Java Persistence Migration Guide

Hibernate Search

+Index.UN_TOKENISED= renamed +Index.UN_TOKENIZED=

Hibernate Annotations and Hibernate EntityManager 3.2.2 GA

@org.hibernate.annotations.Tables.values() renamed @org.hibernate.annotations.Tables.value()

Hibernate Annotations and Hibernate EntityManager 3.2.0 GA

You can upgrade from the last CR to GA without changing any of your code or mappings.

Hibernate Annotations 3.2.0.CR3

Filters and where condition

When using @Where or @Filter on a collection mapped through an association table, you need to use @WhereJoinTable and @FilterJoinTable respectively. JoinTable will target the association table while the orignal equivalent will apply on the target entity table.

Hibernate EntityManager 3.2.0.CR2

Query

HQL is more powerful and flexible than JPA-QL. JPA-QL mandates select clause

from Animal a

is illegal and should be rewritten

select a from Animal

An exception will be raised otherwise.

Alternatively, you can set hibernate.query.jpaql_strict_compliance to false

Cache

The default second level cache of Hibernate is now NoCache, if you used EhCache as a second level cache please set it up explicitly

hibernate.cache.provider_class org.hibernate.cache.EhCacheProvider

in your persistence.xml file

Exceptions

Various Hibernate exception raises have been change to comply with the specification. Read the JPA / EJB 3.0 JavaDoc for more informations.

Ejb3Configuration

The Ejb3Configuration has slightly changed. Especially createEntityManagerFactory, has been deprecated in favor of ejb3Configuration.configure(...).createEntityManagerFactory(); which is aligned with the Hibernate Configuration object

Hibernate Annotations 3.2.0.CR2

Package level annotations

JPA / EJB 3.0 does not support package level annotations.

The folowwing annotations can no longer be used in package-info.java

javax.persistence.NamedNativeQueries
javax.persistence.NamedNativeQuery
javax.persistence.NamedQueries
javax.persistence.NamedQuery
javax.persistence.SequenceGenerator
javax.persistence.SqlResultSetMapping
javax.persistence.SqlResultSetMappings
javax.persistence.TableGenerator

As a workaround, use their Hibernate annotations equivalent or use a JPA XML deployment descriptor to declare them globally

FlushModeType

FlushModeType has deprecated NEVER. Please use MANUAL instead (same behavior)

@CollectionOfElements

@CollectionOfElements on a map used to use key as the default column name: it is now mapkey

Lucene

Lucene has been upgraded to version 2.0.0

Keyword name is now properly decapitalized, this break existing indexes

The index configuration has been completly revamped. Please refer to the documentation for further details

Hibernate Annotations 3.2.0.CR1

NamingStrategy

The NamingStrategy API has slightly changed, the behavior hasn't though.

@Temporal

@Temporal no longer has default value

Hibernate EntityManager 3.2.0.CR1

Query

Aggregation return type has bee aligned with the EJB3 specification. COUNT returns Long, MAX, MIN return the type of the state-field to which they are applied, AVG returns Double, SUM returns Long when applied to state-fields of integral types (other than BigInteger), Double when applied to state-fields of floating point types; BigInteger when applied to state-fields of type BigInteger; and BigDecimal when applied to state-fields of type BigDecimal.

Exceptions

When accessing a proxied instance which has no counterpart in the database, an EntityNotFoundException is raised (rather than a LazyInitializationException)

Hibernate Annotations 3.1.0 Beta10

allocationSize

To be backward compatible wrt allocationSize, you need to use allocationSize + 1. This is due to an alignment to the spec definition.

Hibernate Core 3.2.0 CR1 fails on allicationSize = 1, this will be fixed in the next version hoiwever.

Hibernate Annotation 3.1beta9

This release of Hibernate Annotations is compatible with the latest EJB 3.0 draft and align with Glassfish implementation. If you have an older application that relies on Hibernate Annotations, and you wish to update, follow these migration guidelines.

Hibernate Core

This version works with Hibernate Core 3.2.0.CR1

@AssociationOverride

You can now use @AssociationOverride in a similar way you use @AttributeOverride but to override @JoinColumn(s), please refer to the reference documentation

@Temporal

To be spec compliant, you must annotate your temporal fields with @Temporal (like java.util.Date etc)

@SqlResultSetMappings

You can now map more than one @SqlResultSetMapping per class using @SqlResultSetMappings

@EntityResult

@EntityResult(String name) has been replaced by @EntityResult(Class entityClass)

Dicriminator

The default discriminator column name is now DTYPE rather than TYPE.

The default discriminator value is now the entity name rather than the fully qualified class name (which means usually the unqualified class name).

Hibernate Validator on collections

@Valid can now be used on Collections, Maps and arrays.

org.hibernate.annotations.Table

@org.hibernate.annotations.Table(name=...) has been replaced by @org.hibernate.annotations.Table(appliesTo=...) to reduce confusion, since @org.hibernate.annotations.Table is not a replacement for @javax.persistence.Table.

Hibernate EntityManager 3.1beta7

Hibernate Core

This version works with Hibernate Core 3.2.0.CR1 and Annotations 3.1beta9

Exception handling and transaction handling

This version align with the specification. Most of the raised exception are now EJB3 standard exceptions (except for LazyInitializationException). Most exceptions mark the current transaction (either JTA or RESOURCE_LOCAL for rollback).

Failure during the commit process in EntityTransaction now executes a rollback.

A JTA transaction rollback, clear the persistence context.

em.getTransaction() call is now disallowed in a JTA entity manager

hibernate.transaction_factory and hibernate.flush_before_completion

hibernate.transaction_factory must not be part of persistence.xml files to have an EJB3 compliant implementation.

hibernate.flush_before_completion will be ignored

JTA Application managed entity manager

JTA Application managed entity manager created outside a JTA transaction must at some point call em.joinTransaction() when an active JTA transaction is active. Otherwise, no change will be synchronized to the database.

EntityManagerFactory API

The API to create an entity manager has changed. All entity managers will be considered as EXTENDED.

em.close()

When calling close() inside a joined transaction, will prevent subsequent calls to the API but will not actually detach managed entity until the transaction completion.

EntityManager.lock(..., LockMode.WRITE)

This mode is now properly implemented

Persistence XML files

Persistence XML files are now validated. They should start with:

<?xml version="1.0" encoding="UTF-8"?>
<!-- example of reference to a cfg.xml file -->
<persistence xmlns="http://java.sun.com/xml/ns/persistence"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_1_0.xsd"
   version="1.0">

Hibernate Annotation 3.1beta8

This release of Hibernate Annotations is compatible with the EJB 3.0 public final draft. If you have an older application that relies on Hibernate Annotations, and you wish to update, follow these migration guidelines.

Mapped superclasses

@EmbeddableSuperclass is replaced by @MappedSuperclass

Access type

The accessType attribute is no longer available in @Entity, @EmbeddableSuperclass, @Embeddable. The access type of a given entity is guessed from the @Id or @EmbeddedId annotation position. If an entity has @Id on a field, the access type will be field and all the annotations will be read on fields. Same for methods. @MappedSuperclass (formerly @EmbeddableSuperclass) and @Embeddable inherit the access type from their owning entity.

Annotating both field and method with @Id for a given entity is forbiddden.

If for some reason you want to mix the access types in a given Entity or between an Entity and its MappedSuperclass/Embeddable, you can use the Hibernate specific @AccessType annotation (please refer to the reference documentation for more information).

Id Generators

@Id no longer contains the generator strategy and name. If you want to use a generator, then add @GeneratedValue next to your @Id annotation

@Id @GeneratedValue is for example the replacement of @Id(generate=GeneratorType.AUTO)

GeneratorType has been renamed GenerationType

@GeneratedIdTable has been merged with @TableGenerator to give a single annotation

@TableGenerator(
    name="myTableGenerator",
    table = "GENERATED_IDS",
    pkColumnName = "key",
    valueColumnName = "hi",
    pkColumnValue="EMP",
    allocationSize=20
)

Non persistent field

transient fields are now treated as if they were annotated with @Transient

Basic types, Temporal data, Lobs and Enums

@Temporal has been introduced as a replacement of @Basic(temporalType)

@Lob no longer has attributes, the lob type (CLOB, BLOB) is guessed. If the underlying type is a String or an array of character then CLOB are used. Othersise BLOB are used.

To LAZY or EAGER a lob, you'll need to use @Basic(fetch=...) instead of @Lob(fetch...)

Serializable type are now persisted to the Hibernate type "serialized" is @Lob is not present.

Enums used to be persisted either as string or as ordinal depending on the underlying database column. This is no longer the case, you can specify the targeted type through @Enumerated. The default is ordinal

@Column / @JoinColumn

the secondaryTable attribute has been renamed table on @Column and @JoinColumn

Join Table

@JoinTable table is replaced by a flatten version: name, catalog, schema, uniqueConstraints.

Secondary tables

@SecondaryTable joins (array of @JoinColumn) is replaced by pkJoinColumns (array of @PrimaryKeyJoinColumn).

Inheritance

@Inheritance has been redisigned a bit. discriminatorType is now held by @DiscriminatorColumn. discriminatorValue is now defined in @DiscriminatorValue.

@Named(Native)Query

@NamedQuery and @NamedNativeQuery have the query attribute instead of queryString

Users are encouraged to use @javax.persistence.Named(Native)Query instead of @org.hibernate.annotations.Named(Native)Query thanks to the hints attribute.

hint	hint key
cacheable	org.hibernate.cacheable
cache region	org.hibernate.cacheRegion
query timeout	org.hibernate.timeout
fetch size	org.hibernate.fetchSize
flush mode	org.hibernate.flushMode
cache mode	org.hibernate.cacheMode
read only	org.hibernate.readOnly
comment	org.hibernate.comment
callable	org.hibernate.callable

Hibernate EntityManager 3.1beta6

par

Files no longer has to follow the .par extension, .jar is enough

persistence.xml

The persistence.xml file structure has changed, please refer to the doc. This include <persistence-unit> and no longer <entity-manager>, name as a persistence-unit attribute rather than a subelement, the transaction-type attribute.

Entity listeners

@EntityListener has been replaced by @EntityListeners.

Entity listeners and callbacks are now inherited from superclasses. You can limit entity listeners inheritance using @ExcludeSuperclassListeners.