Time to install some software

Note: Every "extract the zip file..." line below means extract the zip file directly to the folder.  Do not change the root dir and/or "extract to FILENAME directory."  There may be some repetitive folder names, just ignore them (ex. C:\hibernatetutorial\apps\hsqldb\hsqldb ). If you change the root directory you'll need to manually edit the build.xml, I've provided, to point to the correct application roots.  Additionally, if any of the versions of the software listed below change you'll need to update the build.xml.

Install HSQLDB

Download: hsqldb_1_7_X.zip
File used in this tutorial: hsqldb_1_7_1.zip
URL: http://sourceforge.net/project/showfiles.php?group_id=23316&release_id=117043
Install: Extract the zip file to the hsqldb directory within the apps directory

Install Hibernate

Download: hibernate-2.1.X.zip
File used in this tutorial: hibernate-2.1.3.zip
URL: http://prdownloads.sourceforge.net/hibernate/?sort_by=date&sort=desc
Install: Extract to the hibernate directory inside the apps directory

Install Hibernate extensions

Download: hibernate-extensions-2.1.X.zip
File used in this tutorial: hibernate-extensions-2.1.2.zip
URL: http://prdownloads.sourceforge.net/hibernate/?sort_by=date&sort=desc 
Install: Extract to the hibernate-ext directory inside the apps directory

Install Middlegen

Download: Middlegen-Hibernate-rX.zip
File used in this tutorial: Middlegen-Hibernate-r4.zip
URL: http://prdownloads.sourceforge.net/hibernate/?sort_by=date&sort=desc 
Install: Extract to the middlegen directory inside the apps directory

Open a command prompt to c:\hibernatetutorial2 and type "ant setup-middlegen"

OR if you've decided not to use ANT

Copy the following files:

• C:\hibernatetutorial2\apps\hibernate\lib\commons-lang-1.0.X.jar
  
• C:\hibernatetutorial2\apps\hibernate\hibernate2.jar
  
• C:\hibernatetutorial2\apps\hibernate-ext\tools\lib\jdom.jar
  
• C:\hibernatetutorial2\apps\hibernate-ext\tools\hibernate-tools.jar
  

Copy the following files:

• C:\hibernatetutorial2\middlegen files\middlegen-2.1.jar
• C:\hibernatetutorial2\middlegen files\middlegen-hibernate-plugin-2.1.jar

to the C:\hibernatetutorial2\apps\middlegen\middlegen-lib directory.

Delete the following directories / files:

• C:\hibernatetutorial2\apps\middlegen\build
  
• C:\hibernatetutorial2\apps\middlegen\src
• C:\hibernatetutorial2\apps\middlegen\build.xml
• C:\hibernatetutorial2\apps\middlegen\config\database\hsqldb.xml

• C:\hibernatetutorial2\apps\middlegen\middlegen-lib\middlegen-2.0-vo.jar

• C:\hibernatetutorial2\apps\middlegen\middlegen-lib\middlegen-hibernate-plugin-2.0-vo.jar

Copy the build.xml, provided in the hibernatetutorial2.zip, to C:\hibernatetutorial2\apps\middlegen\.  Additionally, copy the hsqldb.xml to the C:\hibernatetutorial2\apps\middlegen\config\database\hsqldb.xml.
 

Setup the HSQLDB database

Launch the HSQLDB GUI
 

Launch a command prompt to C:\hibernatetutorial2\apps\hsqldb\hsqldb\lib directory.
Launch the HSQLDB GUI by typing "java -cp hsqldb.jar org.hsqldb.util.DatabaseManager"
    Set the type to: HSQL Database Engine Standalone
    Set the URL to: jdbc:hsqldb:../../../../hsqldb/hibernatetutorial2
    Leave the rest of the settings alone
    Click Ok

Two files were just created that make up the hibernatetutorial2 database

• C:\hibernatetutorial2\hsqldb\hibernatetutorial2.properties
  
• C:\hibernatetutorial2\hsqldb\hibernatetutorial2.script
  

Create the PERSONS Table

Paste the following code into the text box next to the execute button

CREATE TABLE PERSONS (
person_id int NOT NULL IDENTITY,
first_name LONGVARCHAR(255) NOT NULL,
last_name LONGVARCHAR(255) NOT NULL,
dob DATE NOT NULL,
ssn LONGVARCHAR(20) NOT NULL,
address_1 LONGVARCHAR(255) NOT NULL,
address_2 LONGVARCHAR(255),
phone LONGVARCHAR(50) NOT NULL,
active bit DEFAULT 'true' NOT NULL
)

Hit execute

Create the EMPLOYEES Table

Paste the following code into the text box next to the execute button

CREATE TABLE EMPLOYEES (
employee_id int NOT NULL PRIMARY KEY,
salary decimal(20,4) NOT NULL,
foreign key (employee_id) references persons (person_id)
)

Create the DEPARTMENTS Table

Paste the following code into the text box next to the execute button

CREATE TABLE DEPARTMENTS (
department_id int NOT NULL IDENTITY,
name LONGVARCHAR(50) NOT NULL,
description LONGVARCHAR(255)
)

Create the EMPLOYEES_DEPARTMENTS Table

Paste the following code into the text box next to the execute button

CREATE TABLE EMPLOYEES_DEPARTMENTS(
employee_id int NOT NULL,
department_id int NOT NULL,
foreign key (employee_id) references employees (employee_id),
foreign key (department_id) references departments (department_id),
primary key(employee_id, department_id)
)

to

<class 
	name="com.warfrog.hibernatetutorial2.hibernate.EmployeeDepartment" 

Inheritance

Setting up Inheritance

Since persons and employees have a one-to-one relationship, we want the generated java classes to have a relationship of Person (superclass) to Employee (subclass). To create the inheritance we're looking for we need to utilize hibernate's <joined-subclass> element. Open then Employee.hbm.xml and change:

<class
...
</class>

to

<joined-subclass
...
</joined-subclass>

Now, hightlight from <joined-subclass> to </joined-subclass> and copy it to your clipboard. Open the Person.hbm.xml and paste the <joined-subclass> information right before the </class> element at the bottom of the Person.hbm.xml.

<PASTE HERE>
</class>
</hibernate-mapping>

We'll also need to remove the <one-to-one> mapping to Person, that Middlegen added to the Employee element. If you don't delete the <one-to-one> mapping it'll cause Hibernate to throw an exception informing you that you haven't supplied a required element, the Person object. Next, find the <id> element of our newly pasted <joined-subclass> element and delete from <id> to </id>. Now paste the following code in it's place:

<key column="employee_id"/>

We've just told hibernate that we want Employee to be a subclass of Person and it should use employee_id as it's id column. We only need to make a few more modifications and we'll be all done with this section. Find the <one-to-one> association inside User.hbm.xml. Below outer-join="auto" add "cascade="delete". This informs hibernate that if we delete a Person object we also want to delete the Employee object associated to it (if there is one). Save the file and exit your editor. Finally, we need to delete the Employee.hbm.xml file, so we don't double generate the Employee class (once from the <joined-subclass> element inside Person.hbm.xml and once from Employee.hbm.xml). We're now done with our inheritance setup, so now lets move on to setting up proper many-to-many relationships.

Note: Once we've run hbm2java you may wish to remove the generated getBrokers() and setBrokers() accessor/mutator methods hbm2java generates. I personally don't like my Parent class having any knowledge of it's subclasses, but that's a personal choice.

Many to Many

Setting up Many to Many associations

Currently, the Employee and Department hbm.xml files Middlegen generated for us both have a one-to-many relationship to the EmployeeDepartment.hbm.xml file. As the relationships are defined now we would have to call code similar to this:

//retrieve the EmployeeDepartment objects
Set employeesDepartments = employee.getEmployeesDepartments();
//now we need to move through the set, retrieve the EmployeeDepartment object
//then each EmployeeDepartment for it's associated Department object.
//now we can work with the Department

While this is usable in an application, it's much cleaner to simply call employee.getDepartments(); and directly receive a Set of Department objects. So, lets get to it.

First, open Person.hbm.xml in your favorite editor and find the <set> element related to EmployeesDepartments (it's inside the Employee </joined-subclass>). Highlight from the comment above the <set> element all the way to the closing </set> element and delete it. Now copy the following code in it's place:

<!-- bi-directional many-to-many association to Department -->
<set name="departments" table="employees_departments" inverse="true" cascade="all">
	<key column="employee_id"/>
	<many-to-many column="department_id" class="com.warfrog.hibernatetutorial2.hibernate.Department"/>
</set>

<!-- bi-directional many-to-many association to Employee -->
<set name="employees" table="employees_departments" cascade="all">
	<key column="department_id"/>
	<many-to-many column="employee_id" class="com.warfrog.hibernatetutorial2.hibernate.Employee"/>
</set>

HBM2JAVA

Generating our Java files

Open a command prompt to you middlegen directory and execute "ant hbm2java". Once the ANT task has completed you should have 4 java files in your gen-src/com/warfrog/hibernatetutorial2/hibernate directory. You should now have a total of 7 files:

Department.hbm.xml
EmployeeDepartment.hbm.xml
Person.hbm.xml
Department.java
Employee.java
EmployeeDepartment.java
Person.java

If you take the time to examine the the java files hbm2java has generated you'll noticed that Employee contains a getDepartments() method, Department contains a getEmployees() method, and the Employee extends Person. At this point you can utilize the afforementioned files to properly insert, update, delete Person, Department, and Employee objects. Below I've provided some sample code on how to insert a new Employee with a new Department associated to it.

try{
	//notice we don't specify the Employee.class below
	Configuration cfg = new Configuration()
		.addClass(Department.class)
		.addClass(Person.class)
		.addClass(EmployeeDepartment.class);
	SessionFactory factory = cfg.buildSessionFactory();

	Session session = factory.openSession();
	Transaction tx = session.beginTransaction();

	//create an employee, take notice that we set both Person and Employee info
	Employee employee = new Employee();
	employee.setActive(new Boolean(true));
	employee.setAddress1("TEST ADDRESS 1");
	employee.setAddress2("TEST ADDRESS 2");
	employee.setDob(new Date());
	employee.setFirstName("TEST_FIRST_NAME");
	employee.setLastName("TEST_LAST_NAME");
	employee.setPhone("18005557500");
	employee.setSalary(new BigDecimal(10000000));
	employee.setSsn("000-00-0000");

	//create a Department
	Department department = new Department();
	department.setName("TEST_DEPARTMENT");
	//not the we've left out Description, which we can do since we marked it's not marked as "NOT NULL"

	//link the department to the employee
	employee.setDepartments(new HashSet());
	employee.getDepartments().add(department);

	//link the employee to the department
	department.setEmployees(new HashSet());
	department.getEmployees().add(employee);

	//now we need to save the objects to the database
	session.save(employee);
	//you could have called this instead since we defined cascade="all"
	//Session.save(department);
	tx.commit();

}catch(Exception e){
	e.printStackTrace();
}

Hibernate: insert into PERSONS (FIRST_NAME, LAST_NAME, DOB, SSN, ADDRESS_1, ADDRESS_2, PHONE, ACTIVE, PERSON_ID) values (?, ?, ?, ?, ?, ?, ?, ?, null)
Hibernate: CALL IDENTITY()
Hibernate: insert into EMPLOYEES (SALARY, employee_id) values (?, ?)
Hibernate: insert into DEPARTMENTS (NAME, DESCRIPTION, DEPARTMENT_ID) values (?, ?, null)
Hibernate: CALL IDENTITY()
Hibernate: insert into employees_departments (department_id, employee_id) values (?, ?)