How to Obtain and Install
Hibernate can be downloaded for free from http://www.hibernate.org/. The core Hibernate distribution includes both Hibernate itself and several ancillary libraries. In addition to the main distribution, we will also make extensive use of the tools available in the Hibernate Extensions library.
Hibernate Distribution
Hibernate is distributed as a single compressed archive. For the remainder of this book, we will assume that you have decompressed the archive inside a folder called C:\devenv\. All screenshots and code in the book will assume that directory as the default installation directory for Hibernate and Hibernate Extensions.
|
On my Windows development system, I install downloaded libraries in a single directory, C:\devenv\. This represents my personal repository of downloaded libraries (and associated documentation, samples, etc.). My development source trees are stored in another directory, C:\devrep\, which is controlled by a version control system (CVS, soon to be converted to Subversion). As libraries are required by projects, I copy the .jar files from the C:\devenv\directory into the appropriate location in C:\devrep\. Therefore, project-specific dependencies are resolved by relative paths, but on occasion interim development is done with references to the C:\devenv\directory. I don't use the C:\Documents and Settings\<username> directory because too many packages are confused by spaces in paths.
On UNIX systems, I generally use ~\devrep\and ~\devenv\.
There's nothing very magical about this strategy, but it does keep my tools and documentation nicely sorted from my development tree. |
Let's explore the Hibernate installation a bit, as shown in Figure 1.5. The bin directory contains a couple of batch scripts for generating schema from a *.hbm.xml file. The doc directory contains a copy of the Hibernate documentation, including both the reference material and the Hibernate javadoc (also available online at http://www.hibernate.org/). The eg directory contains a Hibernate-provided example. The lib directory contains all of the various libraries that Hibernate either requires or can potentially take advantage of. The src directory contains the source for Hibernate itself. The test directory contains a suite of JUnit tests, useful when building or developing Hibernate itself. Similarly, the build.bat and build.xml files are used to generate your own version of Hibernate from source (a batch file to kick off the build, and an Ant script, respectively). The changelog.txt file indicates updates to Hibernate made since the last major revision. The hibernate2.jar file, is, of course, the main Hibernate library. The file hibernate_logo.gif is simply the logo for Hibernate; you might want to put this on your Web site, with a link back to http://www.hibernate.org/. The lgpl.txt file contains the LGPL license for Hibernate, and finally, readme.txt contains a variety of useful information tidbits on Hibernate.
|
"Hibernate is Free Software. The LGPL license is sufficiently flexible to allow the use of Hibernate in both open source and commercial projects. Using Hibernate (by importing Hibernate's public interfaces in your Java code), and extending Hibernate (by subclassing) is considered by the authors of Hibernate to be dynamic linking. Hence our interpretation of the LGPL is that the use of the unmodified Hibernate source or binary does not affect the license of your application code.
If you modify Hibernate and redistribute your modifications, the LGPL applies."
- From the Hibernate documentation, http://hibernate.org/196.html
In other words, if you download the Hibernate source, make modifications, and distribute the resulting binaries, you will need to publish the source for the modifications. If you are merely including the original Hibernate libraries with your application, commercial or otherwise, you are under no obligation to release your source. |
Depending on your application, you'll need to include the main hibernate2.jar file and supporting libraries to your application's CLASSPATH.
The lib directory of Hibernate contains a large number of libraries. Table 1.1 shows a list of the libraries files included with Hibernate 2.1.2, along with a list of URLs for the original library developers and the use of the library. The latest version of Hibernate, 2.1.5, relies on the same JAR files, but in certain cases a later version is included. Generally speaking, it's easiest to simply rely on the versions included with Hibernate, but you may wish to visit the URL below for additional documentation on that particular component.
The precise collection of libraries you'll need will depend on your use of Hibernate. Aside from space, there's no reason not to copy all of the libraries into your application's path (for example, your \WEB-INF\lib\directory for a Web application).
Hibernate Extensions Distribution
In addition to the core Hibernate distribution, you should also download and uncompress the Hibernate Extensions library (as of this writing, version 2.0.2). Figure 1.6 shows the distributions.
You may notice that the Hibernate Extensions distribution really consists of two main components: the Hibern8 IDE and a suite of command-line tools. Hibern8 IDE is really more analogous to a SQL monitor tool, allowing you to interactively query and explore object-results, as shown in Figure 1.7. You can use Hibern8 to interactively build your HQL queries, as shown in Chapter 8.
The various items in the tools directory are used to for mechanically generating files. The utility class2hbm is used to generate an hbm.xml file from compiled .class files. This is useful but not a complete solution, because hand-editing of hbm.xml files is still required; instead this book will be focus on the more complete solution provided by XDoclet, as described in Chapter 3. The utility ddl2hbm allows for import of an existing schema and automatic generation of an hbm.xml file, although this use has been deprecated in favor of a tool called MiddleGen, as will be discussed in Chapter 4. Finally, hbm2java generates Java code for you automatically from an existing hbm.xml file, as will also be discussed in Chapter 2 and Chapter 4.
Configuration
As we have seen, Hibernate is essentially a clump of librariesnot a full application. In the next chapter, we'll show a fully working Hibernate application, with complete instructions on how to set it up and configure it. If you already have a Hibernate-supported database installed and working, you can skip to Chapter 2 and get started with Hibernate. If you don't have a database set up (or aren't sure if it's supported), continue to the next section for instructions and information on how to get started with a Hibernate-supported database.
 |
