A Simple Data Access Layer using Hibernate

A Simple Data-Access Layer using Hibernate

By Mario Aquino, OCI Software Engineer 

November 2003

Introduction

There are a variety of open source tools available today for constructing a data access API that simplify what has been in the past been a complicated and error-prone mechanism.

Before these tools became available, applications resorted to calling JDBC APIs and passing SQL strings to Statement objects to execute data lookup queries. The lookup calls returned ResultSets that an application would use by calling accessor methods matching the data types of the returned columns.

While effective, this approach is fragile because it relies on Strings in application code matching the names of database tables and columns; changing the names of database tables or columns required finding all of their references in the code and changing them. This is problematic, if not inelegant.

A better way to interact with a datastore is to eliminate explicit hand-written references to datastore entities while also providing a simple and intuitive API to retrieve and update data that is backed by a database. Preferably, the alternative should not rely on JDBC Statements, SQL strings, or ResultSets. Instead, a solution could create a natural mapping between Java objects and database entities, one that would require a minimum of hand coding to maintain that mapping without removing any of the data retrieval and control facilities provided in the JDBC APIs.

This article will introduce two tools that radically simplify the data access development process, as well as a lightweight framework built on top of these tools to hide their implementation details from a client application that wishes to leverage the benefits these tools provide.

Hibernate

Hibernate is an open-source object/relational mapping toolkit that relieves the need to make direct use of the JDBC API. Hibernate offers facilities for:

Hibernate also has the ability to generate Java source files to match the structure of a database, as will be discussed in more detail in the next section.

XML files containing configuration data provide Hibernate with details about databases with which it needs to interact. These files contain database connection specifics, connection pooling details, and transaction factory settings, as well as references to other XML files that describe tables in the database. Combined, these files provide substantial configurability, allowing an application to tune the behaviors and performance of its data access layer to a remarkably fine level of granularity.

Code Generators

One of the keys to a flexible architecture is the ability to leverage code generation tools for as much of the data access layer as possible. Hibernate comes with a code generation component that produces Java source files based on object-relational mapping expressed in its configuration XML files. These files map database table columns to Java class fields, matching equivalent datatypes, identifying primary key fields, and specifying relationships (one-to-one, one-to-many, many-to-one, etc.) between entities. Below is an example of a configuration XML file for an "Order" entity:

  1. <hibernate-mapping>
  2.     <class name="com.ociweb.Order" table="order">
  3.         <id name="id" type="long" column="id">
  4.              <generator class="increment" ></generator>
  5.         </id>
  6.         <property name="paymentconfirmed" type="boolean" column="paymentconfirmed" not-null="true"
  7.             length="1"></property>
  8.         <property name="installments" type="short" column="installments" not-null="true" length="2"></property>
  9.  
  10.         <!-- associations -->
  11.         <!-- many-to-one association to Customer -->
  12.         <many-to-one name="customer" class="com.ociweb.Customer" not-null="true">
  13.             <column name="customerid" />
  14.         </many-to-one>   
  15.         <!-- bi-directional one-to-many association to Orderitem -->
  16.         <set name="orderitems" lazy="true" inverse="true" cascade="all-delete-orphan">
  17.             <key>
  18.                 <column name="itemid" />
  19.             </key>
  20.             <one-to-many class="com.ociweb.Orderitem"></one>
  21.         </set>
  22.         <!-- one-to-one association to Deliverysite -->
  23.         <one-to-one 
  24.             name="delivery" 
  25.             class="com.ociweb.Delivery" 
  26.             outer-join="auto" 
  27.             property-ref="order"></one>    
  28.     </class>
  29. </hibernate-mapping>

This sample XML file tells Hibernate to use a class called com.ociweb.Order, which should have three primitive fields:

Additionally, the class will have three fields that represent relationships between the Order and three other entities:

Hibernate does all the work to maintain relationships between tables in your database, using details specified in the configuration XML files.

The XML above also has instructions for Hibernate to:

As well, Hibernate can make use of outer join fetching (allowing retrieval of objects with many-to-one or one-to-one relationships as one object) to reduce the number of roundtrips to and from the database. It is configurability features such as these that make Hibernate very powerful.

Another open-source tool called Middlegen already has the ability to connect to a database server and examine the database metadata to discover table definitions and relationships. As well, Middlegen comes with a plugin for Hibernate that allows it to generate the Hibernate configuration files automatically.

The Middlegen and Hibernate code generation utilities can be run from Ant targets they each supply.

Utilizing code generating tools for a large portion of the data access layer means that the structure and organization of an application's data model can evolve and that the classes that mirror that structure can be regenerated consistently and immediately. Unfortunately, a changing data model does mean that portions of an application that use the data model's API must also be updated to reflect the new changes. This can be managed relatively painlessly either with modern refactoring tools (which are available in several popular IDEs) or through the use of tools to autogenerate other application areas like the View Layer, which would likely be impacted by changes in the Model.

Now that the code generation and data management tools have been introduced, the rest of the article will focus on the construction of a light-weight data access framework that will separate data clients from the tools that provide the persistence layer.

A Service Layer

It is a good idea to construct a layer to separate the rest of an application from Hibernate so that unnecessary dependencies are not created by our data access toolkit. This layer should be responsible for interfacing with the Hibernate data retrieval APIs and managing transactional boundaries.

We should be able to identify an interface pattern to manage access to our domain objects. all will need:

This pattern should hold true for most if not all domain objects that map to entities in the application database. The interface definition below follows this pattern:

  1. public interface DomainObjectMgr {
  2.     public void add(DomainObject obj) throws PeristenceException;
  3.     public void update(DomainObject obj) throws PersistenceException;
  4.     public void delete(DomainObject obj) throws PersistenceException;
  5.     public DomainObject findByPrimaryKey(long id) throws LookupException;
  6.     public Collection findAll() throws LookupException;
  7. }

This interface is used by clients to look up instances of any "DomainObject" (i.e., an interface exists for each domain class). With similar interfaces declared to manage all of the domain objects of an application, the next component we need is a Service Locator to return references to the implementation of these interfaces. To simplify things, we can define the Service Locator interface with a single method that accepts a Class reference for the domain object manager interface that the client needs. The interface definition below demonstrates this:

  1. public interface ServiceLocator {
  2.     public Object getDomainObjectManager(Class objectManagerInterface) throws ServiceLocatorException;
  3. }

The ServiceLocator could be accessible through a Singleton so that clients could make a simple call to get the domain object manager interface they were interested in:

  1. OrderManager mgr = (OrderManager)GlobalServiceLocator.getInstance().
  2.                         getDomainObjectManager(OrderManager.class);
  3. Order order = mgr.findByPrimaryKey(1000L);
  4. order.setCustomer(someCustomerRef);
  5. mgr.update(order);

The code above is a simple and straight-forward example of the use of this service layer. The client code does not need to know about the implementations of the ServiceLocator or the domain object manager (OrderManager above).

Frameworks that make extensive use of interfaces tend to promote ease of testing and the ability to do parallel development. As long as the contracts that an interface provides are well understood, the implementations of interfaces can be mocked-out by their clients until those implementations are completed. Thus the client and the interface implementation are decoupled and can be developed independently. A previous Java News Brief titled "Designing Testability with Mock Objects" focuses on this topic (see the Resources section below for a link).

Each of the operations of the domain object manager's interface can be broken down into independent commands that could be applied generically to all domain objects. Hence an "AddCommand" would be defined to add new domain object records to the data store, the same would be true for "UpdateCommand" and "DeleteCommand". The finder methods can also be made generic. Each appropriate command would be invoked by the implementation class of the domain manager interface. However, rather than create a separate class to implement each domain manager interface, a dynamic proxy can be used to wrap the domain manager interface and invoke the appropriate commands since they all follow the same pattern. The diagram below shows the layout for the interfaces and implementation classes that make up the core of this simple framework.

Figure 1

The Command interface below takes a reference to the method of the domain object manager interface that is being invoked, along with any parameters passed in the invocation, and a reference to a Hibernate Session object. The Hibernate Session interface conveniently provides all of the persistence and query methods that the commands need.

  1. public interface Command {
  2.     Object execute(java.lang.reflect.Method method, Object[] args, net.sf.hibernate.Session session) 
  3.         throws Exception;
  4. }

The ServiceLocatorImpl is mainly responsible for returning a reference to a domain manager given its interface class. All of the interfaces will be implemented by a dynamic proxy that will delegate method invocations to a corresponding command object. So it seems there are three responsibilities that need to be accommodated: providing a means to access each supported command object, validating that the Class objects passed into the getManager() method have methods that follow the domain object manager interface pattern, and creating proxies that will respond to method invocations by delegating to the appropriate commands. The code below demonstrates this.

  1. import java.lang.reflect.InvocationHandler;
  2. import java.lang.reflect.Method;
  3. import java.lang.reflect.Proxy;
  4. import java.util.*;
  5.  
  6. import net.sf.hibernate.Session;
  7. import net.sf.hibernate.HibernateException;
  8. import org.apache.log4j.Logger;
  9. import org.apache.log4j.LogManager;
  10.  
  11. class ServiceLocatorImpl implements ServiceLocator {
  12.     private static final Map COMMANDS = new Hashtable();
  13.     private static final Command FIND_WITH_NAMED_QUERY_COMMAND = 
  14.                                                 new FindWithNamedQueryCommand();
  15.     private List validatedClasses = new Vector();
  16.  
  17.     public ServiceLocatorImpl() {
  18.         COMMANDS.put("add", new AddCommand());
  19.         COMMANDS.put("update", new UpdateCommand());
  20.         COMMANDS.put("remove", new RemoveCommand());
  21.         COMMANDS.put("findByPrimaryKey", new FindByPrimaryKeyCommand());
  22.         COMMANDS.put("findAll", new FindAllCommand());
  23.     }
  24.  
  25.     public Object getDomainObjectManager(Class managerClass) 
  26.         throws ServiceLocatorException {
  27.         validate(managerClass);
  28.         return Proxy.newProxyInstance(managerClass.getClassLoader(), 
  29.                                       new Class[]{managerClass},
  30.                                       new ManagerDelegate());
  31.     }
  32.  
  33.     private void validate(Class managerClass) throws ServiceLocatorException {
  34.         if (!validatedClasses.contains(managerClass)) {
  35.             validateIsInterface(managerClass);
  36.             validateHasDomainObjectMgrAPI(managerClass);
  37.             //cache Class objects that have passed the validity check
  38.             validatedClasses.add(managerClass);
  39.         }
  40.     }
  41.  
  42.     private void validateIsInterface(Class managerClass) 
  43.         throws ServiceLocatorException {
  44.         if (!managerClass.isInterface()) {
  45.             throw exceptionFactory(managerClass, " is not an Interface");
  46.         }
  47.     }
  48.  
  49.     private void validateHasDomainObjectMgrAPI(Class managerClass) 
  50.         throws ServiceLocatorException {
  51.         Method[] methods = managerClass.getMethods();
  52.         List mgrMethods = new ArrayList(methods.length);
  53.         for (int i = 0; i < methods.length; i++) {
  54.             Method method = methods[i];
  55.             mgrMethods.add(method.getName());
  56.         }
  57.         if (!mgrMethods.containsAll(COMMANDS.keySet())) {
  58.             throw exceptionFactory(managerClass,
  59.                     " must contain all of the following methods: 'add'," +
  60.                     "'update', 'remove', 'findByPrimaryKey', 'findAll'");
  61.         }
  62.     }
  63.  
  64.     private ServiceLocatorException exceptionFactory(Class managerClass, 
  65.                                                      String message) {
  66.         return new ServiceLocatorException(
  67.             "The supplied Class object (" + managerClass.getName() + ") " +
  68.             message);
  69.     }
  70.  
  71.     private static class ManagerDelegate implements InvocationHandler {
  72.         private Logger log = LogManager.getLogger(getClass());
  73.  
  74.         public Object invoke(Object proxy, Method method, Object[] args) 
  75.             throws Throwable {
  76.             Command command = resolveCommand(method);
  77.             if (command == null) {
  78.                 throw new UnsupportedOperationException();
  79.             }
  80.             try {
  81.                 return command.execute(method, args, getSession());
  82.             } catch (Exception e) {
  83.                 invalidateSession();
  84.                 throw e;
  85.             }
  86.         }
  87.  
  88.         private Command resolveCommand(Method method) {
  89.             Command result = (Command) COMMANDS.get(method.getName());
  90.             if (result == null && method.getName().startsWith("find")) {
  91.                 //If it is not one of the default commands but it begins 
  92.                 //with 'find', assume it is a finder for named queries
  93.                 result = FIND_WITH_NAMED_QUERY_COMMAND;
  94.             }
  95.             return result;
  96.         }
  97.  
  98.         private Session getSession() throws SessionException {
  99.             Session session = ThreadSessionHolder.get();
  100.  
  101.             if (!session.isConnected()) {
  102.                 try {
  103.                     session.reconnect();
  104.                 } catch (HibernateException he) {
  105.                     throw new SessionException(
  106.                         "Could not reconnect the session", he);
  107.                 }
  108.             }
  109.             return session;
  110.         }
  111.  
  112.         private void invalidateSession() {
  113.             try {
  114.                 ThreadSessionHolder.get().close();
  115.             } catch (HibernateException e) {
  116.                 log.error("Unable to close the session");
  117.             }
  118.             ThreadSessionHolder.set(null);
  119.         }
  120.     }
  121. }

The "validity" checking methods above (validateIsInterface() and validateHasDomainObjectMgrAPI()) only really test that the passed in Class object is an interface that contains all of the methods described in the domain object manager pattern. The signatures of those methods are not also checked, which could be an area for improvement. For simplicity's sake in this article, the name check is good enough.

Another noteworthy aspect of the implementation above appears in the getSession() method of the ManagerDelegate inner class, where a call is made to a ThreadSessionHolder to retrieve a reference to a Hibernate Session object.

As its name implies, the ThreadSessionHolder associates a reference to a Hibernate Session to the currently executing thread. While the Hibernate Session is used to retrieve and update objects that are mapped to database table rows, it also acts as a cache for those persistent objects keeping references to objects it has retrieved. By associating the Session with the current executing thread, objects retrieved through different domain object managers will be able to establish and remove relationships between themselves without having to explicitly share the same Session; since the Session is tied to the thread that all domain object managers are running on, Session sharing happens transparently. A consequence of this design, however, is that the scope of the Session needs to be managed somehow. In a J2EE application, Session scoping can happen at the request level so that each domain object manager invoked during a single request shares a common Session that is closed at the return of a response. For a non-J2EE application, a similar model is possible though it requires a component with the responsibility of defining a "request".

FindWithNamedQuery

The resolveCommand() method in the ManagerDelegate above tries to retrieve a Command object whose name matches that of the invoked Method. If it doesn't find one, it tests whether the name of the invoked Method begins with 'find', and if so returns a command that hasn't yet been discussed, the FindWithNamedQuery command.

This command utilizes Hibernate's named query capability, whose mechanics will be discussed in a later section. The command adds support for arbitrary finder queries which may appear in the domain object manager interface.

The only requirements for these queries is that their methods begin with "find" and return a java.util.Collection reference and that a named query matching the method name appear in the XML configuration file of the domain object whose manager interface contains the finder method.

For example, a finder method could be added to the DomainObjectMgr interface above that found instances of DomainObject by name:

public Collection findDomainObjectByName(String name) throws LookupException;

The Hibernate configuration XML file for DomainObject would need a <query/> element with the name and details of the query in HQL:

  1. <query name="com.ociweb.domain.DomainObjectMgr.findDomainObjectByName"><![CDATA[
  2.     from com.ociweb.bean.DomainObject as domainObject
  3.     where domainObject.name = ?]]>
  4. </query>

The query defined in the mapping file must be named according to the fully qualified class name of the domain manager interface plus the name of the finder method itself ("com.ociweb.domain.DomainObjectMgr.findDomainObjectByName"). Additionally, this query takes a parameter that the finder method in the DomainObjectMgr interface defines as a String. The order and types of parameters declared in the finder method signature must follow the parameters expected by the query definition.

Transactions

As Figure 1 above shows, three of the commands extend from a TransactionalCommand base class. The purpose of this class is to wrap the execution of a command within a transaction. This class follows the Gang of Four Template Method pattern, which starts a transaction at the invocation of its execute() method then calls an abstract method (command()) which must be implemented by its child classes. The TransactionalCommand class appears below.

  1. import net.sf.hibernate.Session;
  2. import net.sf.hibernate.Transaction;
  3. import net.sf.hibernate.HibernateException;
  4.  
  5. abstract class TransactionalCommand implements Command {
  6.  
  7.     public Object execute(java.lang.reflect.Method method, Object[] args, Session session) 
  8.         throws Exception {
  9.         if (args == null || args[0] == null) {
  10.             throw new PersistenceException("Null target record cannot be added, updated, or removed");
  11.         }
  12.         Transaction txn = session.beginTransaction();
  13.         try {
  14.             Object result = command(args, session);
  15.             txn.commit();
  16.             return result;
  17.         } finally {
  18.             if (!txn.wasCommitted()) {
  19.                 txn.rollback();
  20.             }
  21.         }
  22.     }
  23.  
  24.     protected abstract Object command(Object[] args, Session session) 
  25.         throws Exception;
  26. } //end TransactionalCommand

The AddCommand shown below is small and simple, which is a testament to the ease of use of the Hibernate APIs.

  1. import net.sf.hibernate.HibernateException;
  2.  
  3. class AddCommand extends TransactionalCommand {
  4.     protected Object command(Object[] args, net.sf.hibernate.Session session) 
  5.         throws Exception {
  6.         try {
  7.             return session.save(args[0]);
  8.         } catch (HibernateException e) {
  9.             throw new PersistenceException(
  10.                 "Unable to add new object to the datastore", e);
  11.         }
  12.     }
  13. } //end AddCommand

The other two transactional commands (UpdateCommand and RemoveCommand) follow the exact same simple style of the AddCommand.

Flexible Querying

Along with a simple API for retrieving and persisting objects mapped to relational tables, Hibernate also provides a very robust querying API that supports query strings, named queries, and queries built as aggregate expressions. The querying API is exposed through two interfaces, the Query interface and the Criteria, with the former supporting queries passed in as Strings in "Hibernate Query Language" (HQL) syntax (or through the invocation of predefined "named" queries, which will be examined later in this section) and the latter designed for aggregate queries.

Query

The Hibernate Session interface acts as a factory for Query objects, which can be created either by passing a String in HQL syntax (which is similar to SQL, though object-oriented and able to understand inheritance and polymorphism) to the createQuery() method or by calling the getNamedQuery() method and passing it the name of the query that has been defined in one of the configuration XML files for Hibernate. Hibernate Query objects can perform lookups using static values (e.g. from com.ociweb.Customer as customer where customer.name='Als Petstore') as well as parameterized queries (e.g. from com.ociweb.Customer as customer where customer.name=?). In fact, parameterized queries can be stated in two forms, one where the positional question marks ("?") can be replaced with parameter values assigned according to the ordering of the question marks in the query string, or another where named parameters are used instead of the positional questions marks. A "named parameter" query string might look like this: from com.ociweb.Customer as customer where customer.name=:name. The :name parameter would be replaced in a call where the parameter name and the associated value are both passed in (Query.setString(String name, String value)). Advantages of using named parameters are that the ordering of the components in the where clause can change without affecting the query and that parameters can appear multiple times in a query where the values should be the same.

Named queries also relieve an application of hard-coded column names and join specifics, which makes an application resistant to change. As well, relying on named queries defined outside of the application's code means that the application does not have to "know" Hibernate Query Language syntax, further insulating it from the persistence mechanism which can more easily be changed without affecting the client code.

Criteria

The Criteria interface approaches querying by allowing a client to build an aggregation of query clauses. Just as with the Query interface, the Hibernate Session acts as a factory for Criteria, taking a Class reference of the entity class for which a Criteria will be defined and returning an "empty" Criteria. The aggregation happens through the use of the Expression class, which has methods for building discrete comparative expressions (like "greater than", "less than", "like", "between", "equals", "and", "not", etc.) that can be found in regular SQL query strings. Static factory methods on the Expression class return these Expression components, which can be aggregated by the Criteria to form a composite query.

Wrapping the Query APIs

The simple data access layer described in the first half of this article acts to separate the client application from the underlying persistence mechanism. Making the rich query capabilities available to a client application while at the same time avoiding an explicit dependency on Hibernate means that the query APIs need to be wrapped by a delegation layer. This layer need not provide any functionality in itself, other than exposing a simple way to create queries and shielding the client from Session or other Hibernate specific details. Luckily, Hibernate supports externalized queries (via the named query capability), so client applications can make use of this through the wrapping layer to leverage powerful query facilities while leaving Hibernate's query language out of the picture.

Putting It All Together

A review of the components described in this article shows that with an existing database definition, tools can generate both Hibernate XML configuration files that provide a mapping between database entities and Java objects as well as the source code for the Java object classes themselves. Furthermore, a lightweight data access layer can provide a simple and generic means of leveraging the strengths and flexibilities of the Hibernate persistence toolkit without imposing a compile time dependency on Hibernate for the client application. So what has this bought us? A totally reusable persistence framework that makes use of code generation so that an application can evolve over time, introducing new entities and relationships (or adjusting existing ones) with a minimum of hand-coding necessary for support. The framework is also generic enough to be extended so that Hibernate need not be the underlying data storage manager (or perhaps not the only data storage manager). Other O/R mapping or even Java Data Objects (JDO) toolkits could be integrated into the framework in a transparent way to provide services that Hibernate on its own may not.

Conclusion

There are an abundance of tools and technologies that provide solutions to problems that all data-driven applications share, namely accessing and managing a data model. Two of those tools, Hibernate and Middlegen, combine to automatically generate an object representation of an entity model. This article has demonstrated a simple data access framework that leverages the strengths of Hibernate while providing a layer of separation so that an application need not be dependent on its data access toolkit. The combination of code generation and toolkit abstraction boosts an application's ability to quickly evolve and adjust as need warrants and more robust solutions become available.

Resources

Software Engineering Tech Trends (SETT) is a regular publication featuring emerging trends in software engineering.