Enterprise data is a valuable company asset that is strategic to an organization’s ability to conduct its core business. Consequently, companies go to great lengths to safeguard the integrity and security of such vital corporate resources. Having enterprise data prized so highly and treated so carefully has its implications for development teams:

It is worth considering these points in more detail, as each has an impact on how a development project is conducted.

Object-oriented and relational database technologies represent separate and distinct conceptual paradigms. The term object-relational impedance mismatch, or impedance mismatch, was coined in the early 1990s to formalize the problems endemic to moving between the object and the relational worlds.

The impedance mismatch problem occurs because object and relational techniques each work toward different objectives. Databases rely on the mathematical precision of relational algebra to structure business data in an efficient normalized form. Object-oriented design methods go beyond pure data modeling to define business processes as a collection of collaborating business components that have both state and behavior.

Given the impedance mismatch problem, the question arises, Why are object and relational technologies so frequently used together for the development of enterprise systems? An alternative to the relational database does exist in the form of the object database management system (ODBMS). However, ODBMS technology is taking time to mature and has yet to prove itself at the enterprise level. For this reason, almost all enterprise software uses a relational database.

Relational databases are a mature and proven technology and can trace their origins back to the 1970s when Dr. E. F. Codd, the father of the relational database, was working on defining his famous twelve rules.

Contrast this history with object-oriented technologies such as J2EE, which have only emerged into the mainstream in the past decade. Despite the frustrations the impedance mismatch causes object-oriented practitioners, relational databases are likely to be the standard form of database technology for enterprise software for the foreseeable future. Therefore, it is important to understand the constraints imposed by impedance mismatch and why the problem causes such headaches.

To appreciate the problems, consider the ideal behavior a J2EE architect would like to see from a persistence mechanism. Most well-designed object-oriented systems are constructed around a domain model. The domain model describes the various relationships between each object involved in the problem domain. Typically, the objects and the relationships between them are represented using a UML class diagram.

Ideally, the architect would like object instances from this domain model to be transparently persisted to and from the underlying database, although a good design would see a persistence layer residing between the business objects of the domain and the data store for decoupling purposes.

The keyword here is that of transparency. True persistence transparency enables objects to be transferred between the database and the application without concern for the intricacies of how the state of an object is persisted to the data store.

Unfortunately, impedance mismatch problems make true transparency difficult to achieve if a relational database is the target. Let’s consider some of the reasons this should be the case.

The ability to write code for data access using the JDBC API is a skill most Java developers possess. JDBC enables us to communicate directly with the database, pushing and pulling information to and from the relational world into that of the object-oriented, forming a bridge between the two paradigms.

The strengths of JDBC lie in its popularity, as it is perhaps the most common method of database access for Java applications. By coding to the JDBC API, developers can

Here are some of the main advantages of using a JDBC driver for database access:

JDBC enables the use of SQL as a domain-specific language for simplifying data manipulation with convenient and easily understandable language constructs. With a suitable database driver, the developer has the option of constructing SQL statements within the code and executing them against the database at runtime.

This approach, in addition to being time consuming and error prone, is very sensitive to database change. Changes to table names, column names, or the order of columns within a table require the data access code to be updated. Worse still, differences between data access code and the database schema are only detected at runtime, as embedded SQL statements are not validated at compile time. The careful use of stored procedures is one method of alleviating the impact of the runtime detection issue.

Some of the problems associated with the use of the JDBC API for object persistence include the following:

The next sections look at database access technologies that use JDBC as a base but attempt to avoid some of these pitfalls.

One technology that has grown in maturity and sophistication in recent years is object/relational (O/R) mapping. Mapping tools offer a method of storing an object-oriented domain model transparently to the database without the need to write a line of JDBC data access code or SQL.

The task of persisting an object’s state is handled by the O/R mapping product, which generates the JDBC calls on our behalf. All that is required of the developer is to specify, usually via an XML-based configuration document, the mapping rules for a particular class. Based on the rules in the configuration document, the O/R mapping tool undertakes all data access, leaving the developer free to concentrate on implementing critical business functionality within the application instead of writing boilerplate data access code. Defining the mapping rules can be done by hand but is more commonly generated by the O/R mapping tool.

The benefits of O/R mapping technology include these:

During this chapter, we look at an example of an open source O/R mapping tool. First, let’s look at two Java technologies that build on the services of the JDBC API, but with an O/R mapping approach to object persistence.

Entity beans are a form of O/R mapping technology and are a member of the Enterprise Java-Beans family. Entity beans provide an object-oriented view of business domain model entities held in persistent storage, where persistent storage can be either a database or an existing application. By providing a wrapper around the underlying data, entity beans attempt to simplify the process of data access and retrieval. Entity beans are a core part of the EJB specification and so can be considered the official persistence layer for J2EE applications.

An entity bean is a shareable, in-memory representation of a row in a database table. The combination of being both shareable and in-memory allows entity beans to operate as a caching mechanism for application data. The responsibility of controlling concurrent access to the cached data in the bean and refreshing or writing the cache when needed is the responsibility of the EJB container. The EJB container also safeguards the state of an entity by ensuring it can survive a server crash.

While the EJB container manages the state of an entity bean and ensures support for concurrent access, the mechanism by which the underlying row in the database is accessed and updated is the responsibility of the developer. The decision as to how data access is managed is dictated by two different flavors of entity bean:

Here is a list of some of the main benefits entity beans offer as an object-persistence mechanism:

Although the inclusion of entity beans within the EJB specification would seem to make them the persistence technology of choice, the reaction of developers to the merits of entity beans has been less than favorable. Some of the complaints raised regarding entity beans include these:

The hostile reaction of the Java community to entity beans has seen other technologies spring to the fore. One such technology is Java Data Objects.

Somewhat confusingly, Java also has a second O/R mapping technology that competes with entity beans. Java Data Objects (JDO) is a specification defined under the Java Community Process by JSR-012, Java Data Objects. A second iteration of the JDO technology is currently under review, which is covered by JSR-243.

The JDO specification has a set of objectives similar to O/R mapping products in that the stated aim of the technology is to provide Java developers with a transparent Java-centric view of persistent information residing in a variety of data sources.

The scope of JDO is wider than providing a purely object/relational mapping technology. JDO implementations cover a range of data storage mediums, including object databases and enterprise information systems. In this way, JDO provides an object view of persistent storage regardless of the underlying persistence technology, whether relational, object-based, or otherwise.

Here are some of the main features and benefits JDO technology brings to the Java platform:

Unfortunately, the JDO specification has failed to strike a chord with O/R mapping tools vendors, presumably because products such as CocoBase from Thought Inc. and TopLink from Oracle have already carved themselves a sizeable market niche.

The JDO architecture also faces an uncertain future. The first draft release of the EJB 3.0 specification under JSR-220 announced that the next incarnation of the EJB architecture would provide yet another standard for a Java O/R mapping technology.

Since that time, Sun Microsystems has announced that as both the EJB and JDO specifications are undergoing further revision under the Java Community Process, members of both the JSR-220 and JSR-243 Expert Groups will collaborate to define a single specification for providing transparent Java object persistence. Only time will tell what this move means for the future of JDO and entity beans.

Hibernate is an open source O/R mapping product. Unlike entity beans, which are heavyweight components, Hibernate allows standard Java objects, or POJOs, to be transparently written and retrieved to and from the underlying data store.

As with commercial O/R mapping tools, Hibernate supports enterprise-level capabilities, including transactions, connection pooling, a powerful SQL-like query language, and the ability to declaratively define entity relationships. The tool also integrates with J2EE, making it suitable for both J2SE-based and J2EE-based applications.

Hibernate uses configuration files to hold metadata describing mapping settings and entity relationship information. The Hibernate configuration files are one of the tool’s key strengths. They offer extensive configuration options, making it possible to precisely define the behavior of the persistence framework. Such configuration precision ensures Hibernate can be tuned to deliver a high-performance persistence solution.

Hibernate supports the definition of inheritance, association, and composition relationships types, in addition to the specification of relationships based on Java collections. Hibernate supports most of the leading RDBMS products.

Although Hibernate is open source, it is nevertheless a proprietary API. Unlike JDO, it has not gone through the JSR process and consequent community review. Despite this, the Hibernate development team has arguably eclipsed JDO by providing a robust implementation with a highly detailed level of documentation. Consequently, Hibernate has enjoyed good word of mouth regarding the quality of the product, and developers have been quick to embrace Hibernate as the open source mapping tool of choice. The Hibernate team claims the product is the leading O/R mapping toolkit for Java.

The Hibernate binaries, source, documentation, and examples can be downloaded from http://www.hibernate.org. Hibernate is available under the LGPL license, which allows commercial use. As usual, check with the site for full licensing details.

Over the years, various code generators have emerged that use database metadata to drive the code generation process. Middlegen is one such open source product that has proven popular with developers and complements Hibernate’s persistence capabilities by taking on the chore of generating Hibernate mapping files.

Middlegen uses JDBC to access database metadata and the Velocity engine for code generation. The use of JDBC enables Middlegen to support most of the major RDBMS vendors. Like XDoclet, Middlegen uses an Ant build file for launching the product.

Middlegen uses a plug-in approach for code generation. After Middlegen has determined the database structure, the task of generating code is handed over to those plug-in generators that have been configured with the <middlegen> Ant build task. At the time of writing, plug-ins are available for generating entity beans, JDO classes, and Hibernate mapping files.

The example focuses on generating Hibernate mapping files; however, Middlegen is not constrained to this one persistence technology. The ability to produce code for more than one type of persistence mechanism is vital, as either the architecture or customer requirements may mandate the persistence technology used. The plug-in architecture of Middlegen provides the ability to accommodate such changes.

To download the latest version of Middlegen, along with full documentation and a comprehensive sample application, visit http://boss.bekk.no/boss/middlegen/.

With all the necessary software installed, we can move on to generating the persistence layer. However, before we can look at how code generation techniques can combine with O/R mapping tools to save us time and effort, we need a RDBMS installed and an operational database established with a suitable schema.

The next section covers the setup of the RDBMS and creation of the database schema required for the example.

MySQL is a small, efficient database and is freely available for most platforms. MySQL offers several types of the product, including MySQL Pro, a commercial version intended for use in production systems, and MySQL Standard, which is available free under the GNU Public License (GPL). Both versions of MySQL offer identical functionality, the only differences being in the terms and conditions of the license.

The upcoming example uses version 4.0 of MySQL Standard. MySQL binaries are available for download from http://dev.mysql.com/downloads/mysql/4.0.html.

Comprehensive installation instructions, along with the MySQL manual, can be found at http://dev.mysql.com/doc/mysql/en/Installing.html.

Access to a MySQL database from Java requires the MySQL Connector/J JDBC driver. This is a Type 4 driver, and like MySQL Standard, is free to download. The latest version can be pulled down from http://www.mysql.com/products/connector/j.

From this download, we get mysql-connector-java-3.0.11-stable-bin.jar, which must be placed on the classpath of any Java application requiring access to a MySQL database.

For any additional information regarding MySQL, refer to the main product Web site at http://www.mysql.com.

Once the database has been installed, the next step is to build up a suitable database schema for use in the example.

To generate the persistence layer from the database, we need a suitable schema from which to work. For the example, I have put together an entity-relationship (ER) diagram containing four entities: Customer, Account, Purchase_Order, and Item.

The ER diagram in Figure 7-1 defines the relationships between the entities.

Figure 7-1. Entity-relationship diagram for the Customer schema.

From the ER diagram, the following relationships are apparent:

To save time creating the schema from the diagram, the data modeling features of a modeling tool were used to generate the data definition language (DDL) statements from the ER diagram. The example uses Borland’s Together ControlCenter to produce the DDL.

The final version of the database script is shown in Listing 7-1.

DROP TABLE IF EXISTS Customer;
DROP TABLE IF EXISTS Account;
DROP TABLE IF EXISTS Purchase_Order;
DROP TABLE IF EXISTS Item;
DROP TABLE IF EXISTS Product;

CREATE TABLE Customer
(
  customer_id mediumint(7) NOT NULL,
  name varchar(127),
  PRIMARY KEY (customer_id)
) TYPE=INNODB;

CREATE TABLE Account
(
  account_id mediumint(7) NOT NULL,
  customer_id mediumint(7) NOT NULL,
  balance mediumint(7),
  invoice_period mediumint(7),
  PRIMARY KEY (account_id),
  INDEX customer_idx(customer_id),
  FOREIGN KEY (customer_id) REFERENCES Customer(customer_id)
) TYPE=INNODB;

CREATE TABLE Purchase_Order
(
  order_id mediumint(7) NOT NULL,
  account_id mediumint(7) NOT NULL,
  delivery_date date,
  PRIMARY KEY (order_id),
  INDEX account_idx(account_id),
  FOREIGN KEY (account_id) REFERENCES Account(account_id),
) TYPE=INNODB;

CREATE TABLE Product
(
  product_id mediumint(7) NOT NULL,
  name varchar(127),
  description text,
  PRIMARY KEY (product_id)
) TYPE=INNODB;

CREATE TABLE Item
(
  item_id mediumint(7) NOT NULL,
  order_id mediumint(7) NOT NULL,
  product_id mediumint(7) NOT NULL,
  quantity mediumint(7),
  unit_price mediumint(7),
  PRIMARY KEY (item_id, order_id),
  INDEX order_idx(order_id),
  INDEX product_idx(product_id),
  FOREIGN KEY (order_id) REFERENCES Purchase_Order(order_id),
  FOREIGN KEY (product_id) REFERENCES Product(product_id)
) TYPE=INNODB;

The changes made were around declaring the type of the tables to be InnoDB by adding the line TYPE=INNODB. Without this specification, MySQL discards the relationship information imposed by the foreign key constraints. Another option to changing the scripts would have been to configure MySQL to use InnoDB table types by default.

Looking at the Account table, a relationship is expressed through the customer_id foreign key to the Customer table. It is a MySQL condition that to be able to define a foreign key, an index must exist for the key. Hence, the script declares INDEX customer_idx (customer_id). This creates the index necessary to allow the relationship to be defined between the Account and Customer entities.

To create the database schema, we must first create a database and run the script. Start MySQL using the instructions appropriate for your particular platform—for example, mysqld --console.

MySQL comes with a command-line application for interacting with the database engine. Issue mysql from a command shell to start the application, enter the following commands to create a database called customer, and run the script.

mysql> create database customer;
mysql> use customer
mysql> source customer-mysql.sql

Issuing show tables at the mysql prompt lists the newly created tables for the schema.

With the database established and the schema created, we can now put both Hibernate and Middlegen through their paces.

The Middlegen tool does the hard work of creating the Hibernate mapping documents for us. The Middlegen tool is invoked from an Ant build file, and the <middlegen> task is provided for this purpose. From the example build.xml, we have the following:

<middlegen appname="customer"
           prefsdir="gen_src"
           gui="true"
           databaseurl="jdbc:mysql://localhost/customer"
           driver="org.gjt.mm.mysql.Driver"
           username=""
           password=""
           schema=""
           catalog="">

This task provides Middlegen with the information it requires to use the MySQL JDBC driver to connect to the Customer database through the attributes of databaseurl and driver. The attributes username, password, schema, and catalog provide further connection detail. These attributes are not needed if MySQL is running locally on a Windows platform.

The use of the gui attribute becomes clear shortly but basically tells Middlegen to open its visual configuration tool.

The next step is to tell Middlegen what to generate. Middlegen uses plug-ins for controlling code generation, and we use the Hibernate plug-in, which requires the nested element <hibernate> for configuration:

<hibernate destination="gen_src"
            package="customer.hibernate"
            genXDocletTags="true"
            genIntergratedCompositeKeys="false"/>

The package attribute provides the Hibernate plug-in with Java package information. The next two attributes require a little more description. The genXDocletTags tells the plug-in to generate XDoclet tags in the XML mapping documents. The XDoclet tags are ignored by the mapping documents. However, the Java generation tool later in the process picks up this additional metadata.

Where we have a composite primary key, Hibernate provides the option to generate an external primary key class. The choice of either an external or an internal primary key class is specified with the genIntegratedCompositeKeys attribute. We generate our own keys externally and set this attribute to false.

With this minimal Middlegen configuration complete, we can now invoke the build file and start the tool.

By setting the gui attribute to true, we have informed Middlegen we wish to use the GUI tool to configure the output from the plug-ins. Running the example build file brings up the screen shown in Figure 7-2.

Figure 7-2. The Customer schema in the Middlegen GUI.

The GUI allows us to assist Middlegen in correctly determining the relationships between entities. From the metadata available in the database, Middlegen is unable to infer the type of relationships established by a foreign key constraint.

With the configuration used in our minimal build file, Middlegen assumes all foreign key constraints are modeling one-to-many relationships. Thus, on first opening the GUI, one-to-many relationships are defined between entities where a one-to-one relationship was expected—for example, Customer and Account, Product and Item. Thankfully, the GUI allows this initial interpretation to be corrected. By pressing the <ctrl> key and clicking with the mouse on the relationship, the cardinality of the association can be corrected.

The GUI also enables the output from the Hibernate plug-in to be further fine-tuned. Selecting either an entity or property in the ER diagram displays a configuration dialog for the element in focus. In this way, we can control exactly what is to be generated for the persistence layer. This dialog is shown in the lower pane of Figure 7-2.

When satisfied with all settings, pressing the Generate button on the toolbar causes the Hibernate plug-in to generate mapping documents for each database entity. This process is visible in the console from which Middlegen was launched and provides a visual cue when the generation process has completed.

Let’s assess what Middlegen has produced.

As stated earlier, the output from the <middlegen> task is not Java source but Hibernate XML mapping documents. These documents instruct Hibernate how the mapping between a Java class and a database entity is to be orchestrated. A mapping document is produced for each entity in the Customer schema. Listing 7-3 shows the XML mapping document generated for the Purchase_Order database entity.

<?xml version="1.0"?>
<!DOCTYPE hibernate-mapping PUBLIC
    "-//Hibernate/Hibernate Mapping DTD 2.0//EN"
    "http://hibernate.sourceforge.net/hibernate-mapping-2.0.dtd" >

<hibernate-mapping>
<!--
    Created by the Middlegen Hibernate plugin

    http://boss.bekk.no/boss/middlegen/
    http://hibernate.sourceforge.net/
-->

<class
    name="customer.hibernate.PurchaseOrder"
    table="purchase_order"
>
    <meta attribute="class-description" inherit="false">
       @hibernate.class
        table="purchase_order"
    </meta>

    <id
       name="orderId"
       type="short"
       column="order_id"
    >
       <meta attribute="field-description">
          @hibernate.id
           generator-class="assigned"
           type="short"
           column="order_id"

       </meta>
       <generator class="assigned" />
   </id>

   <property
       name="deliveryDate"
       type="java.sql.Date"
       column="delivery_date"
       length="10"
   >
       <meta attribute="field-description">
          @hibernate.property
           column="delivery_date"
           length="10"
       </meta>
   </property>
 <!-- associations -->
 <!-- bi-directional many-to-one association to Account -->
 <many-to-one
     name="account"
     class="customer.hibernate.Account"
     not-null="true"
 >
     <meta attribute="field-description">
        @hibernate.many-to-one
         not-null="true"
        @hibernate.column name="account_id"
     </meta>
     <column name="account_id" />
 </many-to-one>
 <!-- bi-directional one-to-many association to Item -->
 <set
     name="items"
     lazy="true"
     inverse="true"
 >
     <meta attribute="field-description">
        @hibernate.set
         lazy="true"
         inverse="true"

       @hibernate.collection-key
        column="order_id"

         @hibernate.collection-one-to-many
          class="customer.hibernate.Item"
     </meta>
      <key>
          <column name="order_id" />
      </key>
      <one-to-many
          class="customer.hibernate.Item"
      />
   </set>

</class>
</hibernate-mapping>

In Listing 7-3, it is evident how the configuration is used to map Java types to database types. This ease-of-use configuration is one reason why Hibernate is proving a favorite with developers. Many of the attributes are self-explanatory. For example, the mapping of a class to a table is achieved with the <class> element:

<class name="customer.hibernate.PurchaseOrder"
       table="purchase_order">

Likewise, the <property> element maps properties to columns:

<property
  name="deliveryDate"
  type="java.sql.Date"
  column="delivery_date"
  length="10"/>

The <id> element is similar to that of the <property> element but identifies the property as being a primary key:

<id
  name="orderId"
  type="short"
  column="order_id">
  <generator class="assigned" />
</id>

The <generator> element specifies how the primary key will be produced. A value of assigned indicates that we will supply Hibernate with the key. Alternatively, Hibernate can generate the key on our behalf from a variety of unique key-generation algorithms it provides.

Not all configuration settings are quite so easily understood, and some elements warrant further description. The <meta> element looks a little out of place: it appears to be using Javadoc notation and repeats configuration detail that is already specified in other tags. For example,

<meta attribute="field-description">
  @hibernate.many-to-one
    not-null="true"
  @hibernate.column name="account_id"
</meta>

These are XDoclet tags and are parsed by the XDoclet Hibernate plug-in when encountered in Java source. These tags exist because the genXDocletTags attribute was set for the nested <hibernate> element in the Ant build file. This information is picked up in the next step when Java source is generated from the Hibernate mapping documents. These XDoclet tags are written out to the Java classes that are mapped by the Hibernate XML mapping documents. Using XDoclet, should we wish, we can regenerate the mapping documents from the Java instead of from the database. XDoclet provides developers with the option to adopt an object-driven rather than data-driven generation approach.

Once the Hibernate mapping documents have been produced, we can move to the next stage of the process: generating Java from the mapping information.

Closing the GUI causes the Ant build file to run to completion. Hibernate comes with the hbm2java tool, used to generate Java from mapping documents, and the build file invokes this tool once Middlegen has completed its part of the process. The relevant section of the build.xml file is the <hbm2java> task:

<hbm2java output="gen_src">
  <fileset dir="gen_src">
    <include name="**/*.hbm.xml"/>
  </fileset>
</hbm2java>

This task generates a Java class for each Hibernate mapping document. Listing 7-4 shows an extract from the PurchaseOrder class produced from the PurchaseOrder.hbm.xml mapping file.

/**
 *        @hibernate.class
 *         table="purchase_order"
 *
*/
public class PurchaseOrder implements Serializable {

  /** identifier field */
  private Short orderId;

  /** persistent field */
  private customer.hibernate.Account account;

  /** persistent field */
  private Set items;

  /** full constructor */
  public PurchaseOrder(Short orderId,
                       Date deliveryDate,
                       customer.hibernate.Account account,
                       Set items) {
    this.orderId = orderId;
    this.deliveryDate = deliveryDate;
    this.account = account;
    this.items = items;
  }

  /**
    *            @hibernate.many-to-one
    *             not-null="true"
    *            @hibernate.column name="account_id"
    *
    */
  public customer.hibernate.Account getAccount() {
    return this.account;
  }

  public void setAccount(customer.hibernate.Account account) {
     this.account = account;
  }

  /**
    *             @hibernate.set
    *              lazy="true"
    *              inverse="true"
    *           @hibernate.collection-key
    *            column="order_id"
    *             @hibernate.collection-one-to-many
    *              class="customer.hibernate.Item"
    *
    */
  public Set getItems() {
    return this.items;
  }

  public void setItems(Set items) {
    this.items = items;
  }
  .
  .
  .

 }

Comparing the Hibernate mapping documents with generated Java gives an insight into how O/R mapping is handled by Hibernate. Of note are the embedded XDoclet tags, denoted with the @hibernate namespace. The XDoclet Ant task <hibernatedoclet> can be used to drive the generation of the mapping documents from the Java source if required.

The generation of the persistence layer was initiated from an ER diagram. Despite a few manual changes to the DDL for producing the database schema, the entire persistence layer was constructed by code generators. The result is a set of lightweight Java objects that provide an object view of the database entities.

Reverse engineering the generated Java code into a UML class diagram enables the object relationships to be compared with the original ER diagram. Figure 7-3 shows the UML class diagram for the persistence layer.

Figure 7-3. UML class diagram mapping to Customer database schema.

At the conclusion of the code generation process, we now have a transparent, object-based persistence layer with which to work. Best of all, other than an Ant build file, it wasn’t necessary to write a line of code to produce it.

Set<Item> items;

For more information on entity beans, visit Sun Microsystems’ J2EE site at http://java.sun.com/j2ee.

The latest news and developer information on JDO can be accessed at http://www.jdocentral.com.

For a side-by-side comparison of O/R mapping products, see http://c2.com/cgi-bin/wiki?ObjectRelationalToolComparison.