Soul Power

Let me announce that as of yesterday Hades ships in its first stable version 1.0. As this of course marks an important milestone let me just briefly give an overview of the features Hades provides. I will start with the very basic features in this post and continue to elaborate on advanced ones in furthers blog posts.

Context

Hades is a library that supports Java developers when implementing persistence layers on top of JPA. Under the covers Hades uses Spring to achieve a lot of it’s functionality. Although there is tight integration with Spring (see bullet points below) that will give Spring users an enhanced development experience there’s no need to have you application based on Spring.

JPA & DAO pattern

JPA eases object persistence a lot. Caveats of version 1.0 are broadly addressed in upcoming 2.0 release. Nevertheless the API could need some bells’n'whistles to align real world development purposes. So the very core of Hades consists of a generic DAO wrapper implementation of JPAs EntityManager that pretty much straightens its API.

Basics – generic DAO instances

Creating instances of this wrapper can be done easily. Suppose you have a JPA entity User with an id type of Long:

EntityManager em = ... // obtain entity manager
GenericDao userDao = GenericJpaDao.create(em,
  User.class);

This gains you basic crud functionality for this entity as well as typed collection access (EntityManager is lacking that) plus sorting and pagination support (e.g. via readAll(Pagable pageable);).

Finder methods

Very seldomly applications stop at only requiring CRUD access to entities. A huge amount of persistence operations resides in executing query methods. With Hades you simply provide an interface extending GenericDao and declare the methods you want to execute queries for:

public interface UserDao extends
  GenericDao<User, Long> {

  User findByUsername(String username);

  List<User> findByLastname(String lastname);
}

To obtain an instance of that DAO you can use GenericDaoFactory as follows:

EntityManager em = ... // obtain EntityManager
GenericDaoFactory factory =
  GenericDaoFactory.create(em);
UserDao userDao = factory.getDao(UserDao.class);

From the method to the query

Of course you’ll immediately ask: “Okay, what queries will be executed for these methods?”. Actually there are 3 ways to define them:

1. Not defining them :) – Hades will the derive the query from the method name on instance creation and validate the querie. Thus, findByUsername(String username) would result in select u from User u where u.username = ?
2. Use JPA named queries – if you align to the naming convention of ${entityName}.${methodName} Hades will use the declared query to be executed. In the case of findByUsername(String username) your query would have to be named User.findByUsername
3. Use @Query annotation – in case you rather don’t want to separate query from DAO interface you can use Hades’ @Query annotation to declare the query directly at the method, e.g. @Query("from User u where u.lastname = ?")

By default these 3 ways are hierarchical, thus an @Query will trump a named query. If none of them can be found Hades will derive the query from the method name. If you need more detailed control over the resolution behaviour you can configure this on the factory.

Spring

Hades uses Spring itself under the hood and thus it seems resonable to provide seamless integration into the framework for users in turn. On a very low level view Hades provides a GenericDaoFactoryBean that pretty much allows the same setup as the code samples showed above. Besides that, the more powerful approach is using the Spring namespace:

<hades:dao-config basePackage="com.acme.**.dao" />

This will cause Hades scanning all dao packages below com.acme for extensions of GenericDao and create the appropriate beans.

Conclusion

The features shown are only the core one’s of what Hades can do for you. The will be follow up posts on query methods in detail, integrating custom data access code, auditing support. If you don’t want to wait for that feel free to skim through the reference documents at http://hades.synyx.org.