Envers moves to Hibernate!

I’m happy to announce that Envers is now a module of Hibernate! This means that:

• the code is now in the hibernate-core repository (envers module). There will be no more commits to the old repository.
• issue tracking moved to Hibernate’s JIRA. All open issues from the old JIRA have been moved there. When creating an Envers issue, please select the “envers” component.
• envers is now built using maven2, which replaces the old ant build

The website, documentation and forum so far stay unchanged, but stay tuned for more updates :).

There will be some changes to Envers coming with this move. One of them is renaming of @Versioned to @Audited, to avoid confusion with the @Version annotation used in JPA for optimistic locking. The old @Versioned annotation will become deprecated, and after some time removed completely.

I would like to thank Steve Ebersole for doing the actual move and creating the maven build!

Adam

Adding structure to Seam events

The idea described here is originally by Tomek Szymański. I just enhanced it a little.

Seam events are a very convenient tool to divide your business logic into smaller pieces, and add some new behaviour as necessary. However, they are very unstructured – an event name is just a String that you’ve got to remember. It’s hard to find out what events your application raises, what are the parameters and in what situations the events are actually raised – there’s no place (in code) to document it.

As a remedy, you can create a special package (let’s say events), where, for each event that your application raises, you create an interface corresponding to that event. So, if you raise an event org.myapp.events.MessageCreated, you create a MessageCreated interface in the org.myapp.events package. In the javadoc for this interface, you can describe when the event is raised and what are the parameters.

Furthermore, all components that contain methods, which observe the event, can implement the corresponding event interface (so it will be used as a marker interface). All modern IDEs let you find implementations of an interface, so finding out which methods are observing your event is trivial!

Taking it a step further, the marker interface may also contain a method declaration. An implementation of that method should observe the event. That way, you can make it even easier to provide information about the parameters of the event. For example:

package org.myapp.events;

public interface MessageCreated {
   void handleMessageCreated(Message message, User user);
}

package org.myapp.components;

@Name("sendEmails")
public class SendEmails implements MessageCreated {
   @Observer("org.myapp.events.MessageCreated")
   void handleMessageCreated(Message message, User user) {
      // Send an e-mail to the administrator that there is a new
      // message
   }
}

Finally, what about raising events? If you raise them programmatically, you may also use the interface, instead of the String form of the event name. For example:

public void sendMessage() {
   // ...
   Events.instance().raiseEvent(MessageCreated.class.getName(),
         message, user);
   // ...
}

This has two benefits. Firstly, by finding the usages of the MessageCreated interface, you know where the event is raised. Secondly, it’s refactor-safe: when you decide to rename the event, you just rename or move the interface. Your IDE does the rest for you (unless your IDE is vim ;) ).

Of course, you’ll still need to use the String form of the event’s name in the @Raise annotation and when raising events in pages.xml.

To sum up: creating marker interfaces for events gives you a place to document them, and can provide partial safe refactoring of event names. What are your practicies when using Seam events?

Adam

Envers 1.1.0.GA released

Today Envers 1.1.0.GA has been released. For the impatient: go straight to the downloads! :) This release contains only minor modifications from the last beta version. You can see the release notes for this version here, and combined release notes for all 1.1.0 versions here.

The main emphasis of this release is support for persistent collections. You can now version any relation, collections of “simple” types, maps, etc. All collection mappings defined by JPA are now supported, and most of what Hibernate additionally allows also. One exception is that collections of components won’t yet work, and the second exception is described here.

There are also improvements to the revision-of-entity query. You can now easily retrieve the history of an entity along with the revision metadata (like the date when a revision was commited) using a single query. See here for details.

Both demos have been updated to use the newest version of Envers. The wiki part of the Seam demo is additionally enhanced by adding a set of links (String-s) to each wiki page (of course this set of links is also versioned).

All comments, negative or positive, are as always very welcome on the forum. Thanks to all contributors and forum users, who have been very helpful in finding bugs and designing new features! :)

Enjoy!
Adam

Envers on JDD 08

If you’ll be visting Java Developers’ Day 2008 in Cracow, Poland on Thursday, be sure to stop by and see my presentation of Envers. It will be an introductory talk, in Polish; I’ll post the slides on the website after it.

See you there!
Adam