About

Jadira is the home for Sousan and Chris Pheby's open source projects. These are reusable open source Java modules that provide first class solutions using the most effective current JEE technologies.

Search
Tag Cloud
...
Login
Tuesday
Mar112014

Announcing Jadira 3.1.0.GA

I’ve just released Jadira 3.1.0.GA. Its currently being promoted to Maven Central so may be a few hours before it shows up there.

This release follows nearly a year and half since our last stable release (3.0.0.GA) and eleven candidate releases. It is definitely time for the GA release, with many users tracking the CR releases which now significantly exceed 3.0.0 in usage.

Everyone using 2.0.x and 3.0.x should now be thinking of upgrading.

In 3.1.0 there are significant new features, evolution to existing capabilities and a significant strengthening to the codebase.

Key features in this release include:

Usertype

  • Support for:
    • JSR310 (Java 8)
    • ThreeTen Backport
    • Joda Time
    • Legacy JDK Temporal types
    • Joda Money
    • JDK Enums
    • Libphonenumber (uses Jadira’s cdt – common data types module)
    • ISO Country Codes (uses Jadira’s cdt – common data types module)
  • New Timezone managing algorithm. Especially MySQL users need to pay attention as they now need to set the JDBC connection property 'useLegacyDatetimeCode=false'
  • Global configuration options reduce domain verbosity. These exist for type auto-registration, java and database timezones, default currency codes and sequence generation seeds.
  • Typesafe, plumbing free and multiple-tier friendly JPA repositories.

Documentation has also been improved with (almost) comprehensive Javadoc and an enhanced (if still terse) user guide for the Usertypes modules at http://jadira.sourceforge.net/usertype-userguide.html.

Cloning

  • The first release for a high performance object cloning library with ASM, Reflection, InvokeDynamic and sun.misc.Unsafe based access strategies. Cloning introduces variants on the commons-lang HashCodeBuilder and EqualsBuilder that take advantage of the object access strategies. Cloning can be integrated with Orika to provide a cloning converter as part of a larger transformation.

Bindings

  • Extensible framework for registering and invoking conversions of objects from one class to another

Scanner

  • A multi-threaded library for classpath inspection in the spirit of Scannotation.

I’ll be continuing to add to the documentation for the various moules with successive releases.

Jadira aims to deliver the building blocks for domain driven applications that perform well with minimal code and a rich type safe model. As Jadira moves towards the next release I’ll be working on extending the features with more tooling that supports building rich domains that integrate well with the event driven style.

 As usual, please give feedback via our issue tracker (http://jadira.atlassian.net/) and GitHub (https://github.com/JadiraOrg/jadira/)  or through the mailing list.

 A big vote of thanks to all the users who have provided bug reports, and suggested fixes and new features during the preparation of the release.

Saturday
Jun292013

Eclipse Kepler

Eclipse Kepler is the simultaneous release of Eclipse 4.3 and a large collection of related Eclipse projects. This release is the significant improvement over Eclipse Juno release, and with some small tweaks even some of the (still unsolved) user interface issues can be fully solved and forgotten.

This post updates my previous quick configuration howtos covering Ganymede, Galileo, Helios, Indigo and Juno by documenting the steps to get stock Eclipse up and running with essential Eclipse plugins. The recipe is for Windows - extrapolate as required.

1. Download Eclipse IDE for Java EE (eclipse-jee-kepler-SR2-win32.zip for 32-bit Windows, eclipse-jee-kepler-SR2-win32-x86_64.zip for 64-bit Windows). These can be found via http://www.eclipse.org/downloads/

2. Make a folder for Eclipse somewhere called 'Eclipse', and unzip the Eclipse SDK zip file to the parent folder. I typically create c:\Java\Eclipse and unzip to c:\Java

3. Create a shortcut to Eclipse, for example:

C:\Java\Eclipse\eclipse.exe

4. Configure eclipse.ini, for example, with the following for 32-bit Windows:

-startup
plugins/org.eclipse.equinox.launcher_1.3.0.v20130327-1440.jar
--launcher.library
plugins/org.eclipse.equinox.launcher.win32.win32.x86_1.1.200.v20140116-2212
-product
org.eclipse.epp.package.jee.product
--launcher.defaultAction
openFile
--launcher.XXMaxPermSize
256M
-showsplash
org.eclipse.platform
-clean
-vm
C:/Java/JSE7/jre/bin/server/jvm.dll
--launcher.appendVmargs
-vmargs
-Dosgi.requiredJavaVersion=1.7
-Dhelp.lucene.tokenizer=standard
-server
-Dcom.sun.management.jmxremote
-Declipse.p2.unsignedPolicy=allow
-Xms768m
-Xmx768m
-XX:MaxPermSize=256M
-XX:+UseG1GC
-XX:+TieredCompilation
-XX:+UseCompressedStrings
-XX:+UseCompressedOops

Use the following as an example for 64-bit Windows:

-startup
plugins/org.eclipse.equinox.launcher_1.3.0.v20130327-1440.jar
--launcher.library
plugins/org.eclipse.equinox.launcher.win32.win32.x86_64_1.1.200.v20140116-2212
-product
org.eclipse.epp.package.jee.product
--launcher.defaultAction
openFile
--launcher.XXMaxPermSize
256M
-showsplash
org.eclipse.platform
-clean
-vm
C:/Java/JSE7/jre/bin/server/jvm.dll
--launcher.appendVmargs
-vmargs
--launcher.appendVmargs
-vmargs
-Dosgi.requiredJavaVersion=1.7
-Dhelp.lucene.tokenizer=standard
-server
-Dcom.sun.management.jmxremote
-Declipse.p2.unsignedPolicy=allow
-Xms1536m
-Xmx1536m
-XX:MaxPermSize=256M
-XX:+UseG1GC
-XX:+TieredCompilation
-XX:+UseCompressedStrings
-XX:+UseCompressedOops

Modify the ‘vm’ argument so that it points to your appropriate Java runtime with Eclipse - this should be at least version 7.0 and should be 32-bit or 64-bit as appropriate. Best practice is to point to a JDK rather than a JRE location.

5. Next, search for new features using the Kepler Updates (with only "Show the latest version", "Group Items by Category" and "Contact all update sites during install to find required software" selected). Pick the appropriate platform features - you can safely select everything. Pick the appropriate platform features - you can safely select everything.

Typical selection could be:

  • Collaboration (Commandline interface for Java implementation of Git, Eclipse Git Team Provider, Eclipse Github Integration with task focused interface, Java Implementation of Git, Java Implementation of Git - optional Java 7 libraries, m2e - Maven Integration for Eclipse, m2e - slf4j over logback logging (Optional), Mylyn Builds Connector: Hudson/Jenkins, Mylyn Context Connector: Eclipse IDE, Mylyn Context Connector: Ecore Tools, Mylyn Context Connector: EMF, Mylyn Context Connector: GMF, Mylyn Context Connector: Java Development, Mylyn Context Connector: Team Support, Mylyn Intent, Mylyn Intent - Workspace support, Mylyn Intent Connector: Java, Mylyn Intent Generator: Intent Documentation, Mylyn Task List, Mylyn Task-Focused Interface, Mylyn Tasks Connector: Bugzilla, , Mylyn Tasks Connector: Trac, Mylyn Versions Connector: Git, Mylyn WikiText, Mylyn WikiText: Additional Generators, Task focued interface for Eclipse Git Team Provider)
  • Programming Languages (Code Recommenders Developer Tools)
  • Web XML Java EE and OSGi Development (Dali Java Persistence Tools - JPA Diagram Editor, Dali Java Persistence Tools - JPA Support)

6. After restarting, the following update sites can be used to add essential plugins:

AJDT http://download.eclipse.org/tools/ajdt/43/dev/update (Not AspectJ Development Tools Source or Equinox Weaving SDK)
AJDT AspectJ Configurer http://dist.springsource.org/release/AJDT/configurator/
SvnKit http://eclipse.svnkit.com/1.8.x
SubClipse http://subclipse.tigris.org/update_1.10.x
Log4E http://log4e.jayefem.de/update (note that the free version cannot be installed using the update site)
Eclipse FullScreen http://scharf.gr/eclipse/fullscreen/update/ (Not Experimental)
ByteCode Outline http://andrei.gmxhome.de/eclipse/ (only ByteCode Outline)
RegexUtil http://regex-util.sourceforge.net/update/
then restart

Also, from the Mylyn for Eclipse Kepler update site select all updates except for Mylyn Context Connector: C/C++ Development, Mylyn Reviews Connector: Gerrit, Mylyn Versions Connector: CVS, Mylyn Builds SDK, Mylyn Commons SDK, Mylyn Commons SOAP SDK, Mylyn Context SDK, Mylyn Docs EPUB SDK, Mylyn Docs SDK, Mylyn Reviews SDK, Mylyn Tasks SDK, Mylyn Tasks Tests SDK, Mylyn Versions SDK and Mylyn WikiText SDK).

7. After restarting again, install the following extensions from the Eclipse Marketplace: Maven Integration for Eclipse (Juno and newer), JavaCC Eclipse Plug-in,  EGit - Git Team Provider, GitHub Mylyn Connector, Mylyn WikiText, Spring Tool Suite (STS) for Eclipse Kepler, JBoss Tools (Kepler), Apt M2E Connector, Atlassian Connector for Eclipse, Java 8 support for Eclipse Kepler SR2, Java 8 Facet for Web Tools for Eclipse Kepler SR2, Eclipse Java 8 Support (for Kepler SR2) JDT, PDE 1.0.0, and Java 8 support for m2e for Eclipse Kepler SR2. If there are any conflicts at this stage, resolve them by keeping what you have already installed.

8. Go to "Window / Preferences / Maven / Discovery" and "Open Catalog". Select antlr, buildhelper, m2e connector for org.codehaus.mojo:jaxb2-maven-plugin, m2e-jdt-compiler, m2e-egit, m2e-subclipse (NB. Installation of m2e-subclipse does not appear to be working yet).

9. A couple of plugins are best installed by hand:

Download DBViewer from http://sourceforge.jp/projects/dbviewer/releases/ and copy the Jar to the Eclipse/dropins/plugins subdirectory
Download Tarlog Plugin 1.4.2 from http://code.google.com/p/tarlog-plugins/ (I used tarlog.eclipse.plugins_1.4.2.jar) and copy the Jar to the Eclipse/dropins/plugins subdirectory.

10. Some other Plugins from the Marketplace that you might want to install: QWickie, Apache Directory Studio, TestNG for Eclipse, Bndtools, Checkstyle, PMD, FindBugs Eclipse Plugin

11. If you cannot open Window / Preferences / General / Appearances without an error dialog appearing add to eclipse.ini just before the '-clean' line:

-cssTheme
org.eclipse.e4.ui.css.theme.e4_default

12. If the layout of your toolbar buttons looks poor and you cannot drag and drop them, install Jeeeyul's 'Eclipse 4 Chrome Theme' from the Eclipse Marketplace. Restart then go to Window / Preferences / General / Appearance' and select 'Jeeeyul's themes - Chrome Theme'.  Restart again and the problem should be solved.

13. I prefer the standard Java branding even when I have installed from the JavaEE IDE distribution. To get this packaging, I change -product in eclipse.ini to:

-product
org.eclipse.epp.package.standard.product

Then, from the standard distribution of Eclipse, I unzip the folder eclipse/plugins/org.eclipse.epp.package.standard_2.0.2.20140224-0000 to the equivalent directory in my Eclipse installation. The next Eclipse restart will use the standard branding.

Tuesday
Jun252013

Announcing Jadira Cloning

Why Fast Cloning?

A recent discussion about low-latency design considerations had me considering the applicability of the various tried and tested design patterns to the low-latency context. Can we make use of Domain Driven Design, CQRS, Event Sourcing and other patterns in a low-latency context.

In practice, even high-performance Java is a good fit to these patterns. The same tools that drive standard Java solutions drive high performance solutions. In low latency applications we can exploit design approaches such as consolidating work to specific cores (possibly sharing related work between cores on the same CPU) in order to avoid contention and maximise the usage of memory cache; avoid locking and other sources of contention. Low latency libraries take these approaches to a logical conclusion, also making use of ByteBuffers and the sun.misc.Unsafe class to directly address memory.

In practice, we reserve these techniques to critical sections of applications, and more conventional techniques drive other parts of application build - this is essential ini order to build systems that can be maintained as well as quick. That isn't to say that we don't make use of low overhead libraries to integrate key capabilities. For example, a common issue in Acquire-Parse-Transform-Deliver workload is how to perform the transformation. In the past libraries such as Dozer were popular, but their performance is limited - today a performant alternative is Orika. Similarly Kryo provides an effective, general purpose serialization API. Parsing of large XML documents can deliver good throughput by combination of a StAX pull parser and JAXB. With these kind of approaches we can deliver acceptable performance to producer systems, whilst also achieving excellent maintenance outcomes.

How can a standard POJO domain entity populate an event stream? In future articles, I'll discuss how the domain entity can be rich (rather than anemic) in functionality, but for now, lets consider the scenario that when we manipulate the domain entity, we expect events to be fired. If we want to produce the events, we need to know how the entity has changed, but in the case of a POJO, we may not have this information. The way to preserve this information, is to copy (deep clone) the domain object. Enter Jadira Cloning, which provides fast cloning of almost any object. In (rough) tests on my laptop, Jadira cloning has been able to copy complex objects of around 120 bytes, around 700 000 times per second.

Introducing Jadira Cloning

Jadira Cloning is not the first library for deep cloning in Java. Rits Cloning is a well established library that offers much the same core functions as Jadira Cloning, but delivers around half to one-third of the throughput in the scenarios I tested. To make Jadira fast, a number of steps were taken. First, the introspection model is built once when the 'Cloner' instance is initialised. This reduces the runtime cost of cloning. An initialisation method allows this to be performed at startup, rather than on the first run. Second, the sun.misc.Unsafe class is used when available to perform memory access, with a fall back to a portable strategy when unavailable. For maximum Cloning performance, the server JVM should be used.

Jadira Cloning supports most of the features of Rits Cloning (discarding anonymous parent references is not included), but is designed to be extremely customisable and extensible. Jadira also provides a range of extensibility strategies that creates for a more versatile solution.

Using Cloners

Your basic mode of usage is:

Cloner cloner = new BasicCloner();

This defines a Cloner that uses Unsafe, where available, and a portable cloning strategy otherwise. The PortableCloningStrategy depends on the Objenesis library.

You can also select the strategy explicitly:

Cloner cloner = new BasicCloner(new UnsafeCloningStrategy());

Cloner cloner = new BasicCloner(new PortableCloningStrategy());

This approach makes it easy to customise the cloning behaviour... more on this later.

In addition to BasicCloner, a cut down implementation is provided. MinimalCloner is another implementation of Cloner that  simply hands off to Unsafe, and can be very fast - its most suitable for simple object structures. It is recommended for situations where only basic deep-cloning functionality is required and maximum throughput desirable. It is not always faster or appropriate, so consider your use case and be sure to benchmark. Perform clone with:

cloner.clone(obj);

The other method of Cloner, initialiseFor(Class<?> classes...) allows you to initialise a cloner at startup, rather than runtime.

Cloners are thread-safe and may be used as Singletons.

Customising BasicCloner

There are a variety of ways to customise cloning. The BasicCloner instance can be configured with CloneImplementors which can be implemented to override the normal cloning behaviour for particular classes. These are be enabled by setting useCloneImplementors() as needed. There are a variety of CloneImplementors built in for JDK collections and Calendar types (these have the same coverage as Rit's FastCloners).

CloneImplementor is subclassed by CloneDriver (concrete implementations are BasicCloner and MinimalCloner) and also by Clone strategy, so that are good opportunities for customising the clone strategy during a parse. This is particularly interesting when the @Cloneable annotation is used to customise the behaviour for a particular class.

Immutable and Transient Types

Specific classes can be indicated as being immutable and/or non-cloneable - these classes do not need to be copied during the clone. Cloning of immutables can be disabled or enabled using setCloneImmutables() whilst non-cloneable classes may never be cloned. Setting cloneTransientFields() to false will prevent the cloning of transient fields which will be set to their null (or default primitive) values instead of being cloned.

What about JDK's Cloneable

Using Cloneable is not recommended but there are classes out there that do. BasicCloner can detect classes that implement Cloneable and invoke their clone() method. To enable this function, set useCloneable().

Using Annotations for Customisation

Finally, the operation of the class can be customised using annotations. The @Cloneable annotation can be used to customise the treatment of particular classes being cloned. @Cloner can be used to specify a particular method within a class to be used to fulfil the clone for that specific class. @NonCloneable indicates that a class should not be cloned and the same instance returned. Finally the @Transient annotation can be used on any class field to indicate that the field is transient. In the case of this last annotation, use cloneTransientAnnotatedFields() to enable or disable the capability (by default these fields are not cloned).

@Immutable provides an alternative mechanism for indicating that a class is immutable, as opposed to configuring this directly on BasicCloner. In addition if the Mutability Detector library is on the classpath this will automatically be used to determine immutability for all classes being cloned. If a class is identified as IMMUTABLE or EFFECTIVELY_IMMUTABLE by Mutability Detector it will be treated as immutable.

Use of Recursion

Cloning naturally lends itself to recursion, and it turns out that this is the fastest, and most easily customisable way to traverse an object graph. As you recurse, you need to track what objects you have seen to preserve identity equality (an IdentityHashMap is used for this), but otherwise the process is relatively straightforward.

However, recursion is not suitable for very large object graphs or deeply linked structures (e.g. linked lists) as handling these results in StackOverflowException. Jadira Cloning guards for this eventuality by monitoring the size of the seen object graph, and switching to an iterative strategy if it grows too large. This approach means that even MinimalCloner can handle large graphs without encountering Stack Overflow.

Extra #1: for Objenesis...

The Portable Clone Strategy relies on Objenesis. In addition, for general use of Objenesis, an object construction strategy that can use Unsafe is provided.

Extra #2: for Orika...

For bean mapping with Orika, a mapping strategy that uses Jadira Cloning is provided. This is ideal for objects that simply need to be copied without further modification within your bean mappings. Orika's ASM based implementation means it adds little overhead over direct use of Jadira Cloning.

Get the Code

Find Jadira Cloning at the project site. Please report issues via the mailing list or Jira. Also, the artifacts are in Maven Central:

<dependency>
    <groupId>org.jadira.cloning</groupId>
    <artifactId>cloning</artifactId>
    <version>3.1.0.CR8</version>
</dependency>

Should Cloning be fixed in the JDK?

JDK 8 offers the potential for fixing Cloneable by adding a default clone() implementation to the interface that calls out to a deep cloning library... this won't impact existing implementors, but provides a way to fix what is currently one of the most broken and confusing of the JDKs idioms.

What's Next?

There are announcements coming for other areas of Jadira framework. In the meantime, in this module, I'm starting to think about implementing object diff, patch and merge, which builds nicely on this cloning capability.

Friday
Oct122012

Eclipse Juno

Eclipse Juno (now updated to SR1) is the simultaneous release of Eclipse 4.2 and a large collection of related Eclipse projects. With the release of SR1 some of the main performance issues of the original release have been resolved.

This post updates my previous quick configuration howtos covering Ganymede, Galileo, Helios and Indigo by documenting the steps to get stock Eclipse up and running with essential Eclipse plugins. The recipe is for Windows - extrapolate as required.

1. Download Eclipse IDE for Java Developers (eclipse-jee-juno-SR1-win32.zip for 32-bit Windows, eclipse-jee-juno-SR1-win32-x86_64.zip for 64-bit Windows). These can be found via http://www.eclipse.org/downloads/

2. Make a folder for Eclipse somewhere called 'Eclipse', and unzip the Eclipse SDK zip file to the parent folder. I typically create c:\Java\Eclipse and unzip to c:\Java

3. Create a shortcut to Eclipse, for example:

C:\Java\Eclipse\eclipse.exe

4. Configure eclipse.ini, for example, with the following:

-startup
plugins/org.eclipse.equinox.launcher_1.3.0.v20120522-1813.jar
--launcher.library
plugins/org.eclipse.equinox.launcher.win32.win32.x86_64_1.1.200.v20120522-1813
-product
org.eclipse.epp.package.jee.product
--launcher.defaultAction
openFile
--launcher.XXMaxPermSize
256M
-showsplash
org.eclipse.platform
-clean
-vm
C:/Java/JSE6/jre/bin/server/jvm.dll
-vmargs
-Dosgi.requiredJavaVersion=1.6
-Dhelp.lucene.tokenizer=standard
-server
-Dcom.sun.management.jmxremote
-Declipse.p2.unsignedPolicy=allow
-Xms768m
-Xmx768m
-XX:MaxPermSize=256M
-XX:+UseParallelOldGC
-XX:+DoEscapeAnalysis
-XX:+TieredCompilation
-XX:+OptimizeStringConcat
-XX:+UseCompressedStrings
-XX:+UseCompressedOops

(where the ‘vm’ argument points to your appropriate Java runtime with Eclipse - this should be at least version 6.0 and should be 32-bit or 64-bit as appropriate).

NB. Best practice is to point to a JDK rather than a JRE location.

5. Next, search for new features using the Juno Updates (with "Show the latest version" selected).

Pick the appropriate platform features - you can safely select everything. Pick the appropriate platform features - you can safely select everything.

Typical selection could be Business Intelligence Reporting and Charting (except Eclipse BIRT Example and Eclipse BIRT Source Feature), Collaboration (except Subversive), General Purpose Tools (Local Terminal, Memory Analyzer, Memory Analyzer (Charts), RPM, Swing Designer, SWT Designer, and Window Builder packages), Modeling (UML2 Extender SDK), Programming Languages (JavaScript Development Tools), SOA Development, Testing, Web XML Java EE and OSGi Development (excluding PHP Development Tools (PDT) SDK Feature).

6. After restarting, the following update sites can be used to add AspectJ Developer Tools, SvnKit, QuantumDB, Log4E and some other valuable plugins:

AJDT http://download.eclipse.org/tools/ajdt/42/update (Not AspectJ Development Tools Source)
SvnKit http://eclipse.svnkit.com/1.7.x
SubClipse http://subclipse.tigris.org/update_1.8.x
QuantumDB http://quantum.sourceforge.net/update-site
Log4E http://log4e.jayefem.de/update (note that the free version cannot be installed using the update site)
ERMaster http://ermaster.sourceforge.net/update-site/
then restart

Also, from the Mylyn for Eclipse Juno update site select all updates except Mylyn Builds SDK, Mylyn Commons SDK, Mylyn Context SDK, Mylyn Docs SDK, Mylyn EPUB SDK, Mylyn Reviews SDK, Mylyn Tasks SDK, Mylyn Tasks Tests SDK, Mylyn Versions SDK and Mylyn WikiText SDK).

7. After restarting again, install the following extensions from the Eclipse Marketplace: Maven Integration for Eclipse, QWickie, Atlassian Connector for Eclipse, JavaCC Eclipse Plugin, Apache Directory Studio, TestNG for Eclipse, EGit, GitHub Mylyn Connector, Mylyn WikiText, Bndtools, Checkstyle, PMD, Vex)

8. Install Groovy Eclipse from http://dist.springsource.org/release/GRECLIPSE/e4.2/ and SpringSource Tool Suite for Eclipse Juno from http://dist.springsource.com/release/TOOLS/update/e4.2

9. Install JBoss Tools (Indigo) from http://download.jboss.org/jbosstools/updates/nightly/core/trunk/ (except sources)

10. Go to "Window / Preferences / Maven / Discovery" and "Open Catalog". Select antlr, Axis Tools m2e, buildhelper, CheckStyle M2E, m2e-apt, m2e-jdt-compiler, PMD M2E, Tycho Configurator, m2e-egit, m2e-subclipse

11. Other interesting plugins you might want to consider could include:

LogWatcher http://graysky.sourceforge.net/
Color Editor http://www.gstaff.org/colorEditor/download.html
Scala IDE http://download.scala-ide.org/releases-29/stable/site (Not JDT Weaving for Scala or Scala IDE for Eclipse Source)
Android Development Tools https://dl-ssl.google.com/android/eclipse/

12. A couple of plugins are best installed by hand:

Download Jar Class Finder version 2.1.0 from http://www.alphaworks.ibm.com/tech/jarclassfinder/download and copy the Jar to the Eclipse/dropins/plugins subdirectory.
Download Tarlog Plugin 1.4.2 from http://code.google.com/p/tarlog-plugins/ (I used tarlog.eclipse.plugins_1.4.2.jar) and copy the Jar to the Eclipse/dropins/plugins subdirectory.

https://dl-ssl.google.com/android/eclipse/
Thursday
Jan192012

Release: Jadira Usertype 3.0.0.CR1 with support for Joda Money 0.6

The first candidate build of Jadira Usertype 3.0.0 is now being synchronised to Maven Central. This is quite a big release and represents a large number of significant enhancements for the library.

Change of Naming for Maven Archives

The most immediately visible change is in the names of the Maven archives. Users of 'usertype.jodatime' should now change their dependency to:

        <dependency>
            <groupId>org.jadira.usertype</groupId>
            <artifactId>usertype.core</artifactId>
            <version>3.0.0.CR1</version>
        </dependency>

Similarly the name of the 'jsr310' archive has changed to 'usertype.extended'. Usertype core contains most usertype functionaliy, whilst extended only contains library code that has dependencies that do not exist in Maven Central. Most users will want to use 'usertype.core'. Today you only need to use 'usertype.extended' if you want to use the JSR 310 usertype mappings. The reason for these changes is to accommodate new features within the usertype library.

Support for Joda Money

The most significant new feature is the inclusion of mappings for Joda Money. This library is a precursor for the eventual implementation of JSR 354, so Joda Money users will benefit from a future migration path as they adopt the JSR, just as Joda Time users can fairly readily switch usertype implementations as they adopt JSR 310. The mappings include mappings for both Money and BigMoney types, and support mapping to decimal or integer columns (for integer columns either the major amount (e.g. Dollars) or minor amount (e.g. cents) can be mapped. Single-column mappings allow a currency to be set either for the particular column (using the 'currencyCode' parameter on the column mapping) or SessionFactory wide (using the JPA or Hibernate property 'jadira.usertype.currencyCode'), whilst multicolumn mappings map the amount and currency each to their own columns.

Updates to Joda Time Support

Joda Time support has been upgraded to 2.0 release of the library. With the upgrade support for two new Joda Time datatypes - MonthDay and YearMonth has been added.

Globalised Configuration Options

The Joda Time and JSR 310 mapping have seen the introduction of system wide configuration options. This is particularly useful because you can set the database timezone and JVM default timezone once using a hibernate or JPA property. The two properties that can be used are 'jadira.usertype.javaZone' and 'jadira.usertype.databaseZone'.

A fourth supported property is 'jadira.usertype.seed'. This can be used to indicate which default implementation of Seed will be used for that SessionFactory.

Autoregistration of User Types in Hibernate 4

A final key new feature is the autoregistration of type mappings in Hibernate 4. This feature (which is not enabled by default) coupled with the use of globalised configuration, will allow you to avoid explicitly including type mappings for many of the commonly supported types.

The types that are autoregistered are:

  • PersistentBigMoneyAmount
  • PersistentMoneyAmount
  • PersistentCurrency
  • PersistentCurrencyUnit
  • PersistentDateTime
  • PersistentDurationAsString
  • PersistentInstantAsTimestamp
  • PersistentLocalDate
  • PersistentLocalTime
  • PersistentMonthDayAsString
  • PersistentPeriodAsString
  • PersistentTimeOfDay
  • PersistentYearMonthDay
  • PersistentYears

 To enable this feature, you need to set the JPA or Hibernate property 'jadira.usertype.autoRegisterUserTypes' to 'true'.

Upgrades

Upgrading from Usertype 2.0 should be relatively straightforward - as most new features are not enabled until the relevant property is set. Remember that Usertype 2.0 and later only support Hibernate 4 and onwards.

Upcoming Features

I am looking at a number of future areas for new functionality in Jadira Usertype. These include the previously mentioned addition of support for JAXB Bindings for the existing mapped types. Further planned changes include a refactor of the support for the JDK Date and Calendar classes and the development of some new domain types - and associated mappings - for types for which no standardised types currently exists. At the top of the list of these types just now are PhoneNumber (which will probably make use of Google's excellent libphonenumber) and Address.

You can find more information on the Usertype project at the project website.