I have been a big fan of Hibernate for some time and I have only used Hibernate 2.x in the past. Most recently I jumped right to the cutting edge and have been using Hibernate Annotations on my current project. Even though Hibernate Annotations are only in a beta release, everything worked fairly seamlessly and any issues we had were only minor inconveniences. My conclusion is that it is definitely worth moving to Hibernate Annotations if you are on a project or about to start a project based on Java 5.

There are many great reasons to use Hibernate Annotations and my list includes:

• Reducing your dependencies on XML for configuration files
• Increase the speed of your development loop as annotations become part of your application and you don’t have to worry about copying files into your classpath
• Removes the complexity of ensuring that your code and XML files become out of sync (though XDoclet eases this a little, you still have to make sure the generated files end up in your classpath)
• Modern IDEs (specifically IntelliJ and I think Eclipse) makes adding, changing, and automagic completion of annotation information an easier task that looking up document references.

I have always been pretty impressed by the amount of documentation for Hibernate (it is such a rarity for many open source projects) and the same level of diligence has been applied to the documentation for Hibernate Annotations. The documentation takes you through pretty much the same detail as the normal Hibernate reference and is enough to satisfy most needs. I am sure that we will be seeing another version of Hibernate in Action book coming soon when Hibernate Annotations release their final version.

Caveats for early users of Hibernate Annotations

1. Lagging Tool Support – Like the lag there was (is?) when Java 5 was released, the same could be said for tool support for Hibernate when using annotations. At least of this writing, we had difficulty using the schema export task as it seemed to instantiate the wrong type of Configuration object, but a quick java snippet seemed to fix it for us.
2. Strange Default Behaviours – As I have not really used Hibernate 3 in anger, I’m not sure if this is a Hibernate issue or a Hibernate Annotation issue but nevertheless strange. Annotations such as the field level @Id one does not default to the GeneratorType.AUTO by default.
3. Half Hearted Lucene Integration – I’m beginning to become a really great fan of Lucene and was surprised to see that Hibernate Annotations now had an @Indexed annotation for Lucene support. Unfortunately it seems like what support was half-heartedly added demonstrated by minimal documentation on indexing objects, but not necessarily about retrieving them. Upon closer inspection the index created by the Annotations is useful if you are using a different or custom Lucene Analyzer upon reading it and there is no way of configuring it.

Tips for migrating to Hibernate Annotations

Obviously I have been fairly lucky to be using Hibernate Annotations on a new project. For those that are on an older version there is likely to be more effort in migrating. The documentation seems to imply that the guys have given much though to people migrating from declarative Hibernate mappings and it is good to know that you can mix and match Hibernate Annotations and normal Hibernate configuration files and specify which configuration will override the other (although you cannot use both on the same entity hierarchy). A suggested migration path would involve:

1. Migrate from Hibernate 2.x to Hibernate 3.1
2. Introduce Hibernate Annotations in replacement of configuration files for a few of your domain objects and test that your build and release process continues to operate
3. Continue to replace configuration files for Hibernate Annotations for the rest of your domain.