Jadira Usertype

Integrating Hibernate with Joda Time and JSR 310

http://usertype.sourceforge.net/

Background

• Hibernate: Object Relational Mapping Framework for Java. At one time a defacto standard, Hibernate is now also the leading implementation of JPA (Java Persistence API)

• Joda Time: Widely used API for Date and Time. Superior to java.util.Date and Calendar for many reasons… thread safety, immutable, distinguishes Date, Time, DateTime and Time Zones effectively

• JSR310: Overhaul of core Java’s date and time APIs based on Joda Time. Scheduled for Java 7

Why Jadira Usertype• JSR310 does not (yet) integrate with JPA so

alternative mechanism is required. Hibernate provides APIs for implementing Usertypes or User-Defined Types

• Existing contributed user type support for Joda Time has not been updated for some time

• JDBC, Hibernate and Joda Time Contrib all (somewhat unexpectedly) modify dates and times when JVM and Database have different timezones – no good at all for correctly storing a Local Date or DateTime with specific zone.

Project Structure

JSR 310 support’s module structure is similar but tests utilise Hibernate 3.6 and JPA2

Timeline

Version Date Description

1.5 07-10-2010Bugfix (NullPointerException when using Hibernate 3.5)

1.4 04-10-2010 Hibernate 3.6 compatibility

1.3.1 13-09-2010 UTC DateTime Behaviour Tweak

1.3 06-09-2010 Fix Java 5 Support

1.2 01-06-2010 Published to Maven Central

1.1 30-04-2010 New Types (including Joda Time)

1.0 22-04-2010 Initial Release (supports JSR 310)

Design Problems

• Various representations of types available (String, milliseconds since 1970, SQL Date, Timestamp etc)

• Representations can be qualified with and without zones and mapped to single or multiple columns

• Addressing the JDBC offsetting problem (http://blog.jadira.co.uk/blog/2010/5/1/javasqldate-types-and-the-offsetting-problem.html)

• Maintenance and testing• New challenges – supporting Hibernate 3.6

Mapping Columns: Column Mapper

• Most behaviour is consolidated into abstract classes that are parameterized by the type they map to…

Mapping Columns: Column Mapper (2)• … yielding lightweight column mapping

implementations

Bringing it all together

The type that uses this column-mapper to persist a Joda LocalTime to the database is even more lightweight.Uses Super Type Tokens (http://www.artima.com/weblogs/viewpost.jsp?thread=206350)

Bringing it all together (2)Multi-column types use n column mappers

Can reuse mappers written for single column mappings

For example: OffsetDateTime is stored as an offset and a LocalDateTime to two columns

QualityPMD, Findbugs, JDepend used for automated metrics capture

Cobertura provides code coverage information…

Unit Tests use DBUnit, embedded H2Database and JPA: Tests verify that the types actually stored in the database are written, stored and read correctly.

JodaTime Contrib unit tests never verified what was stored… the value was offset incorrectly when written and again when read

During testing uncovered and reported some issues in other open source projects:

•JSR 310 Public Draft (relating to formatting of sub-seconds in the Period type)•DBUnit (formatting of milliseconds and nanoseconds in Timestamp types)

Hibernate 3.6 Support

• Problem: Hibernate 3.6 changed its Type API, but its not synced to Maven central

• Solution: Check for presence of Hibernate 3.6 API and use reflection if available; plan to revisit when JBoss start synchronising their releases to Maven Central

Who Uses Jadira Usertype?• Releases 1.0 and 1.1 totalled 100s of downloads;• Since 1.2 distribution is via Maven Central, statistics are not available;• Since April, Joda Time project has recommended Usertype;• Two community reported bugs and fixes received;• Project used by my employer to support business domains in global sales, operations, financing,

integration and web channels;

• Project supports equivalents to all Joda Time Contrib types providing ease of migration;• Wherever possible Usertype’s JodaTime and JSR 310 modules provide equivalent user types

Questions?