Documentation

It is fairly easy to use this package with Hibernate. You can use either classic Hibernate mappings (hbm) or Annotations (i.e. JPA)

Hibernate Mapping

Use the type attribute with your property configuration. e.g.:

<property type="org.jadira.usertype.dateandtime.joda.PersistentDateTime" name="dateTime"/>
		

or

<property type="org.jadira.usertype.dateandtime.threetenbp.PersistentDateTime" name="dateTime"/>
		

Hibernate Annotations

Use the @org.hibernate.annotations.Type annotation. e.g.:

@Column
@Type(type="org.jadira.usertype.dateandtime.joda.PersistentLocalDateTime")
private LocalDateTime dateTime;
		

Some of the types require more than one column to be specified, as with PersistentOffsetDateTime:

@Columns(columns={@Column(name="dateTime"),@Column(name="offset")})
@Type(type="org.jadira.usertype.dateandtime.threetenbp.PersistentOffsetDateTime")
private OffsetDateTime startDateTime;
		

Temporal Types

Temporal types supported by Jadira include JSR 310 with Java 8, ThreeTen Backport, Joda Time and the legacy JDK Date and Time types. The support for Java 8 temporal types does not use setObject currently, so it does not require a JDBC 4.2 driver.

Types Qualified by a Zone

Many types have a logical zone associated with them. Jadira makes it possible to configure what zone you want to use when you inflate these types from the database. You do this by setting a parameter on the type as shown below. To configure the zone to use in the database, you no longer use Jadira. Instead use the Hibernate configuration property, hibernate.jdbc.time_zone. Consult the Javadoc for individual types - for most types, Jadira defaults to using the JVM zone in the application. The following gives an example of setting the JVM zone for PersistentDateTime:

@Column
@Type(type="org.jadira.usertype.dateandtime.joda.PersistentDateTime",
	parameters = { @Parameter(name = "javaZone", value = "jvm")})
private DateTime dateTime;
					

Money Types

Money Types typically consist of a currency and amount. Jadira makes it possible to store only the amount to the database with the currency configured using a parameter. For example:

@Column
@Type(type = "org.jadira.usertype.moneyandcurrency.joda.PersistentMoneyAmount",
	parameters = {@org.hibernate.annotations.Parameter(name = "currencyCode", value = "USD")})
private Money moneyAmount;
					

Alternatively, with other types two columns to hold the amount an currency:

@Columns(columns = { @Column(name = "MY_CURRENCY"), @Column(name = "MY_AMOUNT") })
@Type(type = "org.jadira.usertype.moneyandcurrency.joda.PersistentMoneyAmountAndCurrency")
private Money moneyAmount;
					

JDK Enums

Jadira provides PersistentEnum that can map any arbitray enum. The following gives an example:

@Columns(columns = { @Column(name = "MY_CURRENCY"), @Column(name = "MY_AMOUNT") })
@Type(type = "org.jadira.usertype.corejava.PersistentEnum",
	parameters = {@Parameter(name = "enumClass", value = "my.EnumType"),
	{@Parameter(name = "identifierMethod", value = "name"),
	{@Parameter(name = "valueOfMethod", value = "valueOf")})
private EnumType enum;
					

You don't need to specify identifierMethod or valueOfMethod if you are happy with the defaults of name() and valueOf().

Other Types

Jadira aims to provide all the type primitives necessary to bootstrap building a rich, typesafe domain model. For example, it also supports other types, including Country Codes and Libphonenumber. Refer to the Javadoc for each class.

Global Configuration Options

Jadira provides Global Configuration options that can reduce the verbosity of your mapping. For example:

<persistence-unit ...>
	<properties>
		
		...
		
		<!-- Integrator and globalised configuration functionality  -->
					
		<property name="jadira.usertype.autoRegisterUserTypes" value="true" />
		<property name="jadira.usertype.javaZone" value="UTC" />
				
	</properties>
</persistence-unit>
					

These are configured as JPA properties or Hibernate properties. 'jadira.usertype.javaZone' provides defaults for Java (presentation) timezones, saving you from needing to specify these as parameters on your usertypes. 'jadira.usertype.currencyCode' can be used to specify the default currency code to use when persisting unqualified monetary values. 'jadira.usertype.seed' can be used to specify a Hibernate Seed to be used for generating Timestamps used for versioning. Jadira provides two implementations of a seed - DbTimestampSeed which acquires the value from the database and JvmTimestampSeed which uses the local JVM. These types address zoning differences correctly. 'jadira.usertype.autoRegisterUserTypes' is used to autoregister the most commonly used types. This means for any of the autoregistered types you do not need to supply a type annotation. For the full list of supported types, review the subclasses of 'AbstractUserTypeHibernateIntegrator'.

JPA Repositories

Jadira provides typesafe repository implementations (JpaBaseRepository and JpaSearchRepository) for read/write and read-only requirements respectively. Simply provide and use a concrete subclass parameterized with your types - no further implementation is required. These repositories are especially useful when propagating entities across tiers as they detect when merges and persist requests are required, freeing the application developer from these concerns.