One part of their talk was dealing with the specifications concept of the Domain Driven Design book by Eric Evans. Specifications are an abstraction over a statement or requirement you can formulate for an entity. Each of the specifications you can define evaluates to a boolean, so it can be regarded as predicate over the entity. The example Adrian gave in his talk (and also in a blogpost he dropped a few days later) is a soccer player, who can be characterized as “fair player” or as “bonus eligible”.

JPA 2.0 introduces a criteria API, that effectively allows to define queries via a more or less typesafe API. So the typical code you write using this API looks as follows (code originally coined by Adrian):

CriteriaBuilder cb = em.getCriteriaBuilder();
CriteriaQuery<Player> q = cb.createQuery(Player.class);
Root<Player> player = q.from(Player.class);

q.where(/** Build your where clause here **/);

return em.createQuery(q).getResultList();

As you see there’s a few lines of boilerplate code that works with the domain class. The part that actually varies from query to query is the where clause you hand to the q.where(…) method. What Adrian and Mischa now proposed is introducing a Specification<T> interface that simply provides a callback method that gets the CriteriaBuilder, CriteriaQuery<T> and Root<T> and reduces that to a JPA Predicate which can be handed to the q.where(…) method then (code originally coined by Adrian):

public interface Specification<T> {

 Predicate toPredicate(CriteriaBuilder cb,
   CriteryQuery<T> q, Root<T> root);
}

Specifications in Hades

To make this available in Hades we simpy add a method readAll(Specification<T> spec) to GenericDao interface and GenericJpaDao implementation and implement it as follows:

public List<T> readAll(Specification<T> spec) {
  CriteriaBuilder cb = em.getCriteriaBuilder();
  CriteriaQuery<T> q = cb.createQuery(getDomainClass());
  Root<T> player = q.from(getDomainClass());

  q.where(spec.toPredicate(cb, q, root);

  return em.createQuery(q).getResultList();
}

So what this gains you is a possibility to simply add new Specification implementations and thus “extend” the DAO without the need to add finders e.g.

One more thing

The really cool part about the Specifications is, that – as you can concatenate JPA Predicates with and and or – you can do this with some minor effort on the Specifications, too. I added a small class that provides some syntactical sugar to make something like this possible:

playerDao.readBySpecification(
  where(isFair()).and(isEligibleForBonus()));

This probably needs some explaination. First, isFair() and isEligibleForBonus() are static methods on a (for example) PlayerSpecifications class that return a Specification instance creating the JPA Predicate instance. The where(…) method is also a static one on a helper class that pretty much returns itself, implements Specification in turn and and provides the concatenation methods to chain Specifications and build new Specifications on the fly. Thus you can easily implement atomic predicates for the entity and build more complex expression from it – a really cool complement to the finder methods already available in Hades. The feature will be available in upcoming RC3 of Hades 2.0 and can already be used with the current snapshots.

A big thank you to Adrian and Mischa for a huge part of this new feature =).

1. It only works if you call MyDao.save(…) explicitly
2. It only works for the root entity you persist, not transitive ones.

These drawbacks have caused Will Jaynes to open up a ticket over a year ago already and I have been thinking about that issue from time to time, sometimes more deeply, sometimes just remembered it was still open. Finally I came up with a solution that not only fixes the two points mentioned above but also acts as a quite nice example of how powerful Spring as a toolbox can be, especially for framework or library developers. Here’s the story…

The right tool for the job

Actually, implementing auditing with AOP was not the right choice in the first place. Well, it’s not that AOP in general is the wrong hammer for this nail but rather how we applied it. Auditing based on a pointcut targeting a repository method is plain wrong if we deal with OR mappers, period. So I do not consider myself extraordinarily stupid so you and I might wonder what took me down that road.

Entity listeners

The core abstraction for reacting on lifecycle events for entities in JPA are so called entity listeners. You can either annotate the entity itself with annotations like @PrePersist or @PreUpdate or use a dedicated class with annotated methods in case you want to implement common hooks you might want to apply to a common set of classes. You activate those entity listeners by either annotating the entity with @EntityListeners or configure them in your orm.xml. The reason they never seemed suitable for me is that they get instantiated by the JPA provider and thus – by default – lack any means of injecting dependencies into them (the AuditorAware instance knowing who is the current user in our case).

@Configurable

Fortunately Spring offers injecting dependencies into classes created with new by adding an @Configurable to the class to be instantiated. You simply have to get a Spring aspect woven into that class then and activate in your apps XML config and Spring will intercept the instantiation of that class and either autowire dependencies or use a blueprint prototype bean to determine what has to be wired how. (For details see a former blogpost or the reference documentation.)

So let’s recap what we have here: I let the aspect be compiled into my AuditingEntityListener and activate as well as a prototype bean of the listener getting a StubAuditorAware injected in my integration tests config file. Hm, doesn’t work… What’s wrong? Here’s the critical part of the reference doc.

Instances of @Configurable objects created before the aspect has been configured will result in a warning being issued to the log and no configuration of the object taking place. An example might be a bean in the Spring configuration that creates domain objects when it is initialized by Spring. In this case you can use the depends-on bean attribute to manually specify that the bean depends on the configuration aspect.

Okay, it seems the aspect is not yet active when my LocalContainerEntityManagerFactoryBean gets instantiated which in turn instantiates my entity listener. The docs recommend (no pun intended) to emphasize the order of the beans by adding a depends-on attribute to the bean that manually instantiates objects (the EntityManagerFactoryBean in our case). First: what bean to depend on since spring-configured has no id. Ah, it turns out Spring registers the aspect under org.springframework.context.config.internalBeanConfigurerAspect. So I’d essentially need something like this to make sure the EntityManagerFactory already sees the DI aspect:

Well, wait… of course I could document that this was necessary but that would bloat Hades user’s infrastructure configuration, expose Spring internal bean names and make things unnecessary complex.

Spring container hooks – BeanFactoryPostProcessor

Okay, so what we essentially need to do is transparently add a depends-on="org.springframework.context.config.internalBeanConfigurerAspect" to the chosen EntityManagerFactoryBean bean definition. Fortunately we can do this programatically by using one of the Spring container hooks, the BeanFactoryPostProcessor. So I simply implemented a AuditingBeanFactoryPostProcessor that transparently adds the (additional) depends-on to bean definitions that create an EntityManagerFactory. So the benefit here is that we can leave other user defined beans untouched. Let’s take a look on what we have to configure on the Spring side to get things up and running:

As you can see, there’s a lot of boilerplate XML config here. The only thing really custom is the delaration of the MyAuditorAwareImpl. Now guess what? There’s some Spring for that…

Spring namespaces

As you probably already know (as you might have used Hades already) Spring supports the implementation of custom XML namespaces since 2.5. We already implemented the dao-config element in the Hades namespace so why not add one to activate auditing? So here’s what we end up with:

Quite neat, isn’t it? So let’s summarize what we have gained from the plain auditing feature view:

1. We get transparent auditing on all JPA managed entities, whether they are the root entity or a transitive one.
2. No need to call MyDao.save(…) to trigger auditing.

Nice, feature completed ;). Now let’s take another step back an reflect what brought us there:

1. Spring’s ability to inject dependencies into objects instantiated with new through @Configurable and AOP.
2. Prevented custom configuration spread around into other beans thorugh Spring’s BeanFactoryPostProcessor container hook.
3. Reduced the amount of configuration required through a custom namespace to hand an expressive concise configuration language (in our case in form of a single XML element ;) to the user instead of a generic verbose one.

Enough praising here, enjoy auditing with Hades! =)

P.S.: In case you want to take a glance at the sources checkout the commits I’ve done for the feature request.

These days, some kind of back-to-the-basics approach regarding architecture layering is widely accepted as best practices. Thus you don’t want to introduce a layer just because of some merely technical needs. A typical candidate layer for being obsolete is the service layer. Especially in web applications where you pretty much store entities that are equipped with rich behavior themselves the service layer is quite an artificial one that only demarcates transactions but then delegates to the underlying data access layer. Using Hades in such an application you had needed the additional transaction demarcation somewhere as it didn’t deal with transactions itself out of the box. So the only option to get rid of a service layer was to use e.g. @Transactional at a Spring MVC controller e.g. which is rather a sub-optimal solution.

So actually we were quite reluctant to the idea of applying transactions to Hades DAO instances as there were some crucial points to consider:

1. Actually a DAO layer might not be at the right level of abstraction. Usually you define transactions on a more business related method than a plain save(…) or findByUsername(…). So if we enable transactions at DAO methods we have to make sure that they seamlessly can be expanded to more coarse grained methods and the DAOs take part in those transactions.
2. If we apply transactions we don’t want to imply our transaction model to the user’s application. As Spring provides various means to define transactions, we don’t want to take that decision from the developer. So in case she wants to decide for a particular model, she has to be able to do so, no matter what we chose.
3. Although the transactional behavior that we define for CRUD methods might be okay for 90% of the use cases there has to be a way to override the defaults and replace them by some custom one.
4. As Spring 3.0 supports multiple transaction managers via @Transactional we have to make sure we participate in the right transaction depending on in which context the DAO is used.
5. It has to be easy to define transaction configuration for DAO interfaces containing the finder methods.

We decided to use @Transactional annotations at the GenericJpaDao implementation class and activate annotation based transactions for the proxies explicitly through the GenericDaoFactoryBean. This means that the CRUD operations of the DAO instances will be transactional if called standalone or participate in a transaction in case there’s already one running for the current transaction manager (read up details on multiple transaction managers here). So it doesn’t matter if you declare your transactional boundaries via @Transactional, too, or use e.g. XML configuration or even TransactionTemplate. This gets us solutions for issues 1 and 2.

Issue 5 is quite easy to solve as you can simply annotate the finder methods of your DAO interface (or the interface itself) with @Transactional and transactions get applied as you are used to with Spring.

The actual tricky part is issue 3. The main idea here is to simply redeclare the CRUD method originally declared in GenericDao inside your concrete DAO interface and reconfigure transactions as you like. So supposed you want to get rid of the readOnly flag at readByPrimaryKey(…) set to true (as we chose to default the transaction configuration to, as this applies some performance optimizations on the persistence provider as well as the JDBC driver), you can do this as follows:

public interface UserDao extends GenericDao<User, Long> {

  @Override
  @Transactional
  User readByPrimaryKey(Long key);
}

Getting this to work needs some reflection magic as we of course still have to delegate the call to that method to the GenericJpaDao instance but according to the Java Reflection API it of course does only implement GenericDao.readByPrimaryKey(…) and not UserDao.readByPrimaryKey(…). Long story short, we can find out the method that has to be invoked so we can hand this reconfiguration model to the user and gain much flexibility on this side.

Issue 4 is not that interesting as we simply have to configure our internal TransactionInterceptor to lookup the appropriate PlatformTransactionManager instance in a lazy-loading-like fashion but that all happens under the covers and you don’t need to take care of this.

So let me quickly summarize what 2.0.0.RC2 brings you in regard of transactions:

• Transactional CRUD methods (everything declared in GenericDao) with appropriate defaults (readOnly flag set to true on read-only methods) that automatically take part in more coarse grained transactions if necessary
• The ability to use @Transactional for your concrete DAO interfaces
• The ability to reconfigure the transactional behavior of the CRUD methods by simply redeclaring a method inside the concrete DAO interface

Why 1.5?

The first question that might arise is why this release is 1.5 whereas it’s predecessor was 1.1.2. Originally the release was planned as 1.2 but as it introduces some long-ranging features and changes we thought it might be worth indicating that in a larger step of version numbers. As 2.0 is already taken for our JPA 2 upgrade, 1.5 was the choice to go. So what do I mean with “long-ranging”?

Since it’s beginning Hades relied on two major interfaces: GenericDao and Persistable where as especially the latter raised some discussions here and there. Although it is not that of a big deal to implement a 3rd party interface with an entity class it was indeed a hurdle for adoption. So why was it introduced in the first place. GenericDao had the aim to abstract between creation and updates of objects. Although there slight semantic differences this maps to the difference between using EntityManager methods persist(…) and merge(…). To know what to call when save(…) is being called on GenericDao we have to be able to differentiate between a new and an existing entity. As this algorithm might vary from entity to entity, we chose to leave the burdon to decide that to the entity developer by implementing the interface.

Although implementing this interface should not be a big deal actually, we (and the developer community) were not really satisfied with that solutions as the technical infrastructure slightly leaks into the domain abstraction which is somewhat suboptimal kindly speaking. The good news is: as of Hades 1.5 there is no need to implement Persistable anymore. The DAO implementation now uses a reflective approach to lookup the id property of the entity and inspects its value. If it is null, the entity is regarded as new or as already existing otherwise. So that’s the default. If you need to tweak the semantics of new, simply implement Persistable as the algorithm will be simply calling isNew() on you instance then. So in effect, the interface comes into play if explicitly needed and not in any other case.

That’s the big news. Behind that we have a few new features regarding the XML namespace to be used in Spring applications. In case you have multiple EntityManagerFactory beans declared (e.g. in case you work with more than one JPA persistence unit), you can now point the dao-config and dao elements to a specific EMF bean by using entity-manager-factory-ref attribute. Furthermore using exclude-filter and include-filter (probably known from Spring’s context namespace) can be used to tune DAO auto configuration in a more fine grained way. Besides that we have done a general overhaul to the query creation subsystem and now also allow keywords like Between, LessThan and GreaterThan in method names. To round things up we’ve fixed a few minor bugs here and there. For more details read the changelog or the updated reference documentation.

Hades 2.0

Alongside this important step we make another one. JPA 2.0 specification was released a while ago and most existing JPA 1 application wil definately benefit from an upgrade as the new spec version really fills gaps the old one left to workaround for the developers. So what is our approach to the new spec. From a Hades point of view the most intresting part of the new spec is the criteria API as user’s probably will base their custom DAO implementations on it. Furthermore upgrading (Spring) applications demands applications to upgrade to Spring 3.0 and a new major version of the persistence provider of choice we choose to dedicate a 2.0 version of Hades to it.

So the first release candidate builds on top of Spring 3.0.2 as well as Hibernate 3.5, EclipseLink 2.0 as well as OpenJPA 2.0 Beta 3. We will probably wait for our final release until OpenJPA is final, too, but as the majority of users are split between Hibernate and EclipseLink we think that rolling out a release candidate is a good way to get feedback and battle proof the new version. The major change inside Hades 2.0 is that we dropped support of the read-by-example way to access entities. This had to be implemented in a provider specific way so that we could even simplify the codebase in that regard. Furthermore the DAO abstraction is now clearly centered around GenericDao and not blurred with additional interfaces.

So if you can upgrade to Spring 3.0.x and the JPA 2 ready persistence provider already, give Hades 2.0 a try. It should be a drop in replacement in this case. Having that said, it’s probably worth mentioning that even Hades 1.5 can be used with JPA 2.0 but requires more extensive pom configuration on the developer side (as Spring 2.5.6 does not support JPA 2). As you’d end up with a dependency setup similar to the one decalred in 2.0 you’re probably better of just upgrading to Hades 2.0.

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.

After that I will kick of Hades autumn tour on October 27th at this year’s The Server Side Java Symposium in Prague, Czech Republic, which I already mentioned here. The tour will be interrupted by the IBM Rational Software Conference 2009 in Düsseldorf where I will present Skyway Builder, a tool to create Spring based web applications in a model driven way. A key focus of this talk will (as the name of the conference suggests) the integration into IBM Rational, esp. UML to Code and vice versa features. We at Synyx are consulting partner of Skyway Software to care for european customers and users of the community edition of Skyway Builder.

The conference autumn will be closed with a talk at a conference I already really enjoyed last year: Devoxx 2009. I was invited to hold a 45 minute session during the “Tools in Action” track at the University day. I really look forward to all of these talks. If you ocassionally attend one of the events, feel free to say hello and discuss thoughts. See you there!

I just want to announce that I am going to speak about Hades at Devoxx and The Server Side Java Symposium this year. The TSSJS takes place in Prague (Czech Republic) from Oct. 27th to 28th whereas Devoxx will be held between Nov. 16th and  20th in Antwerp (Beligum). I am thrilled by the list of speakers I can share the opportunity to speak with and really look forward to the events. Feel free to say hello and communicate opinions and ideas personally.

In addition to the small promo tour we do in autumn we have released version 0.6 of Hades that mainly frees finder methods from name prefixes entirely. Check the announcement or the reference documentation for details. In the beginning of September there will be a last feature release that will expand the functionality of executing finder queries into executing manipulating queries, too. If you like to check out a stable preview of this version, check it out in our Maven repositories.

German speaking readers might be interested in the article I wrote for JavaMagazin a while ago. You can find a PDF version of that article here. It should also be is also published as online version on the JAXenter website here in a few days.

JavaMagazin 7/09

The June issue of the German JavaMagzin features an article about Hades written by myself. I sketch out issues implementing persistence layers briefly and introduce solutions to these issues using Hades. Furthermore fellow developer Alexander Hanschke introduced Java User Group Mannheim in yet another article, too. Check out the current issue and get your copy.

Beyond that, we at Synyx decided to give the part of our homepage that deals with our OpenSource projects a brush up. Check out http://www.synyx.org to start diggin into the projects, read up our developer’s blogs and keep in touch via the project tracker. Kudos to Philip Reiman who did most of the work.

The build went fine but unfortunately some of my test cases broke when executed under M3. I noticed that things started to get fuzzy with the first test case that was supposed to throw an exception. I have some test cases that look as follows:

@Test(expected=DataAccessException.class)
public void checkDoesNotCascadeIfNotConfigured() {

	// Setup some persistent object graph that is
	// supposed to throw an exception

	userDao.saveAndFlush(user);
}

The key thing to notice here is that I flush the database as the constraint violation I want to expose is only checked at the time the data gets pushed to the database actually. Stepping through the code of Spring testing library in a first level of detail, I realized that the exception is thrown correctly and even detected as the one that is supposed to be thrown. Nevertheless the test method was marked as failed with the exception supposed to be thrown. Furthermore all upcoming tests failed with a duplicate key exception as setting up the test fixture failed right in the beginning. What the heck was going on?

It seemed obvious to me that there would have to be something wrong with the transaction management, so I digged a little further in that direction. Finally I found out this one: in this commit Jürgen Höller added a transactionStatus.flush() during the rollback of a transaction after test execution. This of course raises the exception I wanted to raise a second time but – unfortunately – after the moment the first exception had already been checked to be the expected one. Thus the second exception bubbles up causing the test and the rollback to fail.

As I spoke to Jürgen we found out that the flush was implemented due to a improvement filed in JIRA. Fortunately there is already another ticket that adresses the issue. Waiting for RC1 to see this fixed…

Hades itself seems to be Spring 3 ready already, so if you play around with both of ‘em, I’d be happy to address any issues you face.