Webwarp Util Hibernate

General

This module provides abstractions and base classes for easily implemeting entities and Data Access Objects (DAOs) using the Hibernate O/R mapper. In more detail the module includes:

Class Overview

Entity interfaces

The package net.sf.webwarp.util.hibernate.dao contains several base interfaces  for different types of entities:

Types UML
  • ID Type: The ID type interface describes the mapping for an entity with an serializable ID. The class defines a class template parameter where the serializable key type must be passed. 
  • MutationType: This interface describes an entity that traces its creating and (last) updating timestamp and user IDs. Additionally a deleted flag is also present which allows flagging out deleted items (by filters) instead of deleting them physically. Refer to the DAO implementation section later in this document.
    • RecursiveMutationType: This is a special use case that supports a common problem where the DAO needs to update the creation/update fields within a whole object tree. Setting the properties "recursive" means to traverse down all its assocoiated children and to set the appropriate properties where possible.
  • IDMutationType: This is the final interfaces typically used when implementing a concrete mutation type. As for the IDType super class the serializable key class must be passed as a class template paramter.

Entity base classes

The package net.sf.webwarp.util.hibernate.dao.impl contains several base classes for different types of entities that implement the interfaces described above:


Types Implementation Classes
  • AIDTypeImpl: This abstract base type implements an entity which is identified by a simple integer based ID number that typically is generated by the database (alternative mappings are also supported). The class implements the corresponding interface net.sf.webwarp.dao.IDType. Subclasses must override the getID() method for setting the appropriate persistance mapping annotations.
  • AMutationTypeImpl: This abstract base type implements an entity that traces its creating and (last) updating timestamp and user IDs. Additionally a deleted flag is also present which allows flagging out deleted items (by filters) instead of deleting them physically. Refer to the DAO implementation section later in this document. The class implements the corresponding interface net.sf.webwarp.dao.MutationType.
  • AIDMutationTypeImpl: This is the abstract base class typically used when implementing a concrete mutation type. For complex types (e.g. multiple ID properties present), of course, from the super class net.sf.webwarp.dao.impl.AMutationTypeImpl must be inherited from instead of.

DAO interfaces

The package net.sf.webwarp.util.hibernate.dao contains several base interfaces  for different types of data access objects (DAO). Extending from these interfaces allow you the define a complete DAO interface by one single line of code (see the examples later).

DAO Interfaces
  • Preload: The preload class is used when loading data from the DAOs. It can be used for telling the DAO which parts of object tree (that is marked as lazy in hibernate) should be loaded with the given operation. That way the code using the DAO can exactly determine based on the business request what data must be loaded. Alternatively to explicitely defining the data sub trees to be loaded, a preload depth can be specified. All data in the object tree until the given depth then is loaded by the DAO call.
  • BaseHibernateDAO: This is the most simple of all DAO types. All basic DAO operations are available. The DAO is not narrowed to any specific entity type and therefore supports DAO operations on multiple hibernate mapped entities. This DAO type is the most flexible one, but we do not recommend its use if one of the more specified DAO types can be used.
  • BaseMutationEntityDAO: This DAO type "extends" (by mean not inheritance) the basic DAO type, by adding support for mutation types. Since mutation types can be flagged as deleted the corresponding delete methods do not physically delete the entities from the database but setting the deleted flag accordingly. Additionally methods for undeleting and purging (physically delete) items and accessing items depending on its deleted state are provided. Of course a BaseMutationEntityDAO can only handle entities that extend the net.sf.webwarp.dao.MutationType interface.
  • SingleEntityDAO: This DAO type defines a DAO type for one single entity type. By templating with the corresponding entity interface (extending net.sf.webwarp.dao.IDType) and the type of the key field the DAO interface is exactly defined. Refer the eaxmples later for more details.
  • SingleMutationEntityDAO: This DAO is logically the same as the SingleEntityDAO type, though it supports mutation types only and is defining the additional DAO methods available to entities that extends the net.sf.webwarp.dao.MutationType interface.

DAO implementation classes

The package net.sf.webwarp.util.hibernate.dao.impl contains several implementation classes for different types of DAOs implementing the interfaces described above:


DAO implementation classes
  • AbstractBaseHibernateDAOImpl: This abstract base type provides base functionality that is available to all its subclasses and simplifies DAO implementation based on the given technologies a lot. For avoiding name clashes with methods defined by subclasses the base methods are preceded with a '_' character though this is not common sense in most coding style guides.
  • BaseHibernateDAOImpl: This class implements an simple DAO that can be used with any hibernate mapped type. It implements the net.sf.webwarp.dao.BaseHibernateDAO interface. This DAO type is the most flexible one, but we do not recommend its use if one of the more specified DAO types can be used.
  • BaseMutationTypeDAOImpl: This class implements an DAO that can be used with any mutation types (entities extending the net.sf.webwarp.dao.MutationType interface). It implements the net.sf.webwarp.dao.BaseMutationEntityDAO interface.This DAO type is not narrowed to a specific net.sf.webwarp.dao.MutationType class, so we do recommend the using of the SingleMutationEntityDAOImpl class if possible.
  • SingleEntityDAOImpl: This class type implements an DAO that can be used with any ID type (entities extending the net.sf.webwarp.dao.IDType interface). It implements the net.sf.webwarp.dao.SingleEntityDAO interface. This DAO type is narrowed to the specific net.sf.webwarp.dao.IDType instance class by class templating.
  • SingleMutationEntityDAOImpl: This class type implements an DAO that can be used with any mutation type (entities extending the net.sf.webwarp.dao.MutationType interface). It implements the net.sf.webwarp.dao.SingleMutationEntityDAO interface. This DAO type is narrowed to the specific net.sf.webwarp.dao.MutationType instance class by class templating.

Other classes

Package Usage

Creating entities

Choosing the right base interface and base class

For creating entities you must decide which characteristics your entity class owns:
Based on this the following scheme can be defined what type of superclass you shoud use:


Single Property ID (T extends Serializable) Multiple Properties ID
Default Entity Interface:
net.sf.webwarp.util.hibernate.dao.IDType<T>
Class:
net.sf.webwarp.util.hibernate.dao.impl.AIDTypeImpl<T>
Interface:
Any interface.
Class:
Any class.
Mutation Type Entity Interface:
net.sf.webwarp.util.hibernate.dao.IDMutationType<T>
Class:
net.sf.webwarp.util.hibernate.dao.impl.AIDMutationTypeImpl<T>
Interface:
net.sf.webwarp.util.hibernate.dao.MutationType
Class:
net.sf.webwarp.util.hibernate.dao.impl.AMutationTypeImpl

Example Entity 1: Defining a simple entity with an integer key

A simple entity interface using a default integer key therefore can be defined as follows:

import net.sf.webwarp.util.hibernate.dao.IDType; public interface IntegerIDEntity extends IDType<Integer> { } Of Course additional properties can be added as you like. The corresponding entity imeplemtation must be implemented as follows (for a proxied entity). Note that you must override the abstract getId() method since you have to configure the persistence settings for the ID property:

import net.sf.webwarp.util.hibernate.dao.impl.AIDTypeImpl; @Entity @Proxy(proxyClass = IntegerIDEntity.class) public class IntegerIDEntityImpl extends AIDTypeImpl<Integer> { @Override @Id @GeneratedValue(strategy = GenerationType.AUTO) public Integer getId() { return id; } }

Example Entity 2: Defining a simple entity with an string key

A simple entity with String key (a "named" entity) can be defined as simple as before:

import net.sf.webwarp.util.hibernate.dao.IDType; public interface NamedEntity extends IDType<String> { }And the corresponding entity imeplemtation must be implemented analogous. In the sample additionally the table name was explicitely set. Note that you must override the abstract getId() method since you have to configure the persistence settings for the ID property:

import net.sf.webwarp.util.hibernate.dao.impl.AIDTypeImpl;
@Entity(table="NamedEntity") @Proxy(proxyClass = NamedEntity.class) public class NamedEntityImpl extends AIDTypeImpl<String> {
@Override @Id public String getId() { return id; } }

Example Entity 3: Defining a mutation entity with an compund key

A mutation entity with a compund key can be defined as follows:

import net.sf.webwarp.util.hibernate.dao.IDMutationType; public interface ComplexEntity extends IDMutationType<CompundKeyClass> { /** * An additional property. */ String getAdditionalName(); }An the corresponding enbtity class is implemented as follows:

import net.sf.webwarp.util.hibernate.dao.AIDMutationTypeImpl; public class ComplexEntityImpl extends AIDMutationTypeImpl<CompundKeyClass> implements ComplexEntity{ private String additionalProperty; @Override @Id public CompoundKeyClass getId() { return id; }
/** * Get the additional property value. */ @Column(length=20) public String getAdditionalName(){ return additionalName; } public void setAdditionalName(String additionalName){ this.additionalName = additionalName; } }

Creating and Using Data Access Objects (DAOs)

Defining a single entity DAO 

The interface for a corresponding DAO implementation for the above IntegerIDEntity type is defined as follows:

import net.sf.webwarp.util.hibernate.dao.SingleEntityDAO; public interface IntegerIDEntityDAO extends SingleEntityDAO<IDEntity,Integer> { } With a few lines of code more als the corresponding DAO implementation is ready for use::

import net.sf.webwarp.util.hibernate.dao.impl.SingleEntityDAOImpl; public class IntegerIDEntityDAOImpl extends SingleEntityDAOImpl<IntegerIDEntity,Integer> implements IntegerIDEntityDAO{ public IntegerIDEntityDAOImpl(){ super(IntegerIDEntityImpl.class); } }

Manipulating your database

With all the items defined you can manipulate your database (OK, you must first initialize your database, e.g. calling the SchemaCreator from the hibernate framework). The following code snippet shows you some possibilities:

IntegerIDEntityDAO dao = getYourDAOSomehow(); IntegerIDEntity intEntity = new IntegerIDEntityImpl(5); dao.saveOrUpdate(inEntity); IntegerIDEntity searchedEntity = dao.get(5); List<IntegerIDEntity> allItems = dao.findAll(); List<IntegerIDEntity> allItemsOrderedByID = dao.findAll(new String[]{"id"}); dao.delete(searchedEntity); [...]

Configuring Mapped Entities, DAOs and Session Factory

Adding your mapped classes to the session factory

The webwarp util package provides you a Hibernate Session Factory implementation that is capable of collecting automatically the Hibernate classes to be mapped from configuration files available in the classpath. The entities mapped are read out by default from all ressources found under

    classpath:/META-INF/persistentBeans.properties


The file has hereby the following format:

# You're hibernate mapped fully qualified classes must be contained here. # The first non empty, non commented is interpreted as module name. # Module names can be excluded (and thus mapped classes can remapped) # by setting the 'excludedModuleNames' property of your session factory webwarp-util-hibernate-demo IntegerIDEntityImpl NamedEntityImpl ComplexEntityImpl

Configuring all with Spring

A corresponding sample Spring configuration looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:tx="http://www.springframework.org/schema/tx" xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.0.xsd http://www.springframework.org/schema/tx http://www.springframework.org/schema/tx/spring-tx-2.0.xsd">
<bean id="DataSource" class="org.apache.commons.dbcp.BasicDataSource" destroy-method="close">
<property name="driverClassName" value="${jdbc.driverClassName}"/> <property name="url" value="${jdbc-url}" /> <property name="username" value="${jdbc.username}" /> <property name="password" value="${jdbc.password}" />
</bean>
<bean id="SessionFactory" class="ch.orcasys.util.hibernate.WebwarpAnnotationSessionFactoryBean"> <property name="dataSource" ref="DataSource" /> <property name="hibernateProperties"> <props> <prop key="hibernate.dialect">${hibernate.dialect}</prop> <prop key="hibernate.bytecode.use_reflection_optimizer">false</prop> <prop key="hibernate.jdbc.use_streams_for_binary">true</prop> </props> </property> <property name="excludedModuleNames"> <list> <value>module1</value> <value>module2</value> </list> </property> </bean>
<bean id="TxManager" class="org.springframework.orm.hibernate3.HibernateTransactionManager"> <property name="sessionFactory" ref="SessionFactory" /> </bean>
<tx:annotation-driven transaction-manager="TxManager" />
<bean id="IntegerIDEntityDAO" class="IntegerIDEntityDAOImpl" > <property name="sessionFactory" ref="SessionFactory" /> </bean>
<bean id="NamedEntityDAO" class="NamedEntityDAOImpl"> <property name="sessionFactory" ref="SessionFactory" /> </bean>
[...]
</beans>




Webwarp Util