Sunday, June 04, 2006

Hibernate: Setting Up for Development

Before you start coding, there are some requisite steps you must take:
  1. Must have a Sun JDK, with %JAVA_HOME% set to point to the JDK install directory. Additionally, PATH must include a pointer to %JAVA_HOME%\bin. We call this {java}. Using 1.5.0_04.
  2. Must have Apache ANT, with %ANT_HOME% set to point to the ANT install directory. Additionally, PATH must include a pointer to %ANT_HOME%\bin. We call this {ant}, my version is 1.6.5.
Download Hibernate 3.0 from JBoss' SourceForge repository. Extract the compressed file a location, the root of which we will call {hibernate}. Copy the following libraries from {hibernate}\lib to {ant}\lib (to make ANT Hibernate-aware for builds):
  1. antlr-2.7.6rc1.jar
  2. junit-3.8.1.jar
The following are libraries that are needed in Eclipse for development. I have a common archives directory, so I added a new /hibernate folder under it, and will call this {archive-hibernate}. Copy these files from {hibernate}\lib to {archive-hibernate}:
  1. antlr-2.7.6rc1.jar
  2. asm.jar
  3. asm-attrs.jar
  4. cglib-2.1.3.jar
  5. commons-collections-2.1.1.jar
  6. commons-logging-1.0.4.jar
  7. dom4j-1.6.1.jar
  8. hibernate3.jar
  9. jaas.jar
  10. jta.jar
  11. junit-3.8.1.jar
  12. log4j-1.2.11.jar
Prepare your JDBC driver. I connect to a Microsoft SQL Server 2000 database using jTDS. If you will run your builds from the console, copy the jtds-1.2.jar library to {hibernate}\lib. Otherwise, have it available in {archives}\jdbc for reference from an IDE.
Using the Enterprise Manager console, I created my database for use in this project. Let's call it [HIBERNATE]. Since I will connect to it using TCP URLs, you should find out what port mssqlserver listens at; mine is 1433, the default.

At this point, we can open Eclipse (or an IDE of your choice) and create our project. I'll call the project directory {project}. Before coding, we need to reference libraries needed for Hibernate and data access: include all Jars in {archives}\hibernate and {archives}\jdbc in the classpath. Then create the basic directory structure as follows:
  • src = where source files and mapping files will exist
    • package.JavaClass.java (the Java class)
    • JavaClass.hbm.xml (at the same level as the class it will map)
  • src\hibernate.cfg.xml (hibernate configuration)
  • src\log4j.properties (logging - just copy this from {hibernate}\etc as is)
  • lib = where all the libraries referenced above - hibernate and JDBC - are stored. As an alternative, rather than reference the {archive}, you could create a library in Eclipse and include these files therein. You can also include other 3rd party libraries needed by your application.
  • build.xml = the ANT build file.
The basic hibernate.cfg.xml file looks like this (replace block brackets with respective angle brackets):
=====
[?xml version='1.0' encoding='utf-8'?]
[!DOCTYPE hibernate-configuration PUBLIC
"-//Hibernate/Hibernate Configuration DTD 3.0//EN"
"http://hibernate.sourceforge.net/hibernate-configuration-3.0.dtd"]
[hibernate-configuration]
[session-factory]
[!-- Database connection settings --]
[property name="connection.driver_class"]net.sourceforge.jtds.jdbc.Driver[/property]
[property name="connection.url"]
jdbc:jtds:sqlserver://localhost:1433/HIBERNATE;tds=8.0;lastupdatecount=true[/property]
[property name="connection.username"]sa[/property]
[property name="connection.password"]password[/property]
[!-- JDBC connection pool (use the built-in) --]
[property name="connection.pool_size"]1[/property]
[!-- SQL dialect --]
[property name="dialect"]org.hibernate.dialect.SQLServerDialect[/property]
[!-- Enable Hibernate's automatic session context management --]
[property name="current_session_context_class"]thread[/property]
[!-- Disable the second-level cache --]
[property name="cache.provider_class"]org.hibernate.cache.NoCacheProvider[/property]
[!-- Echo all executed SQL to stdout --]
[property name="show_sql"]true[/property]
[!-- Drop and re-create the database schema on startup --]
[property name="hbm2ddl.auto"]update[/property]
[/session-factory]
[/hibernate-configuration]
Basically, this configuration file defines the database connection parameters to the SQL database. Later, we will only need to add references to mapping files when we start developing code.

The next file is the ANT build file, which looks like this (replace block quotes with appropriate angle brackets):
[project name="hibernate-project-name" default="compile"]
[property name="sourcedir" value="${basedir}/src"/]
[property name="targetdir" value="${basedir}/build"/]
[property name="librarydir" value="${basedir}/lib"/]
[path id="libraries"]
[fileset dir="${librarydir}"]
[include name="*.jar"/]
[/fileset]
[/path]
[target name="clean"]
[delete dir="${targetdir}"/]
[mkdir dir="${targetdir}"/]
[/target]
[target name="compile" depends="clean, copy-resources"]
[javac srcdir="${sourcedir}"
destdir="${targetdir}"
classpathref="libraries"/]
[/target]
[target name="copy-resources"]
[copy todir="${targetdir}"]
[fileset dir="${sourcedir}"]
[exclude name="**/*.java"/]
[/fileset]
[/copy]
[/target]
[target name="run" depends="compile"]
[java fork="true" classname="package.MainClass" classpathref="libraries"]
[classpath path="${targetdir}"/]
[/java]
[/target]
[/project]
This file will instruct ANT to clean, compile, copy resources, and run the MainClass. At this point, your project is set up to run. I will discuss the *.hbm.xml file and inserting a reference to it in the hibernate.cfg.xml file in code samples that I may post. Otherwise, the Hibernate Tutorial is the go-to resource to start using right away. It explains in a little bit more detail what everything we have done here means.

No comments: