Jadira Usertype Integrating Hibernate with Joda Time and JSR 310

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 VersionDateDescription Bugfix (NullPointerException when using Hibernate 3.5) Hibernate 3.6 compatibility UTC DateTime Behaviour Tweak Fix Java 5 Support Published to Maven Central New Types (including Joda Time) 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 ( 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 ( ost.jsp?thread=206350) ost.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

Quality PMD, 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?