Cheat Sheet: New Features in JPA 2.1

JPA 2.1 introduced 12 new features, like StoreProcedureQueries, Entity Graphs and Attribute Converter, to make your work with the database easier and more efficient.
Download your free New Features in JPA 2.1 cheat sheet now, to get all the information you need to improve your database access.

This 5 page cheat sheet brings you:

- a short description and
- code snippets for each feature,
- links to more detailed articles.

Signup now and get your free New Features in JPA 2.1 cheat sheet and regular blog updates.

I respect your privacy and have ZERO TOLERANCE for spam!

JPA 2.1 - How to implement an Attribute Converter

JPA 2.1 brings several improvements. One of them is the Attribute Converter. It allows the developer to specify methods to convert between the database and the Java representation of an attribute.

What can be converted?

A Converter supports type conversion of all basic attributes defined by entity classes, mapped superclasses, or embeddable classes. The only exceptions are Id attributes, version attributes, relationship attributes and attributes annotated as Temporal or Enumerated.

How to implement a Converter?

A Converter must implement the javax.persistence.AttributeConverter<X, Y> interface, where X is the class of the entity representation and Y the class of the database representation of the attribute. Additionally a Converter has to be annotated with the javax.persistence.Converter annotation.
The following example shows a Converter implementation that can be used to store a java.awt.Color object as a String with the format red|green|blue|alpha in the database. When reading the entity from the database, the String will be used to instantiate a new Color object.

As you can see the implementation is simple and straight forward. You just need to implement one method for each conversion.

How to use a Converter?

There are two options to define the usage of a Converter. The first one is to set autoapply=true at the @Converter annotation of the Converter class. In this case the JPA provider will use this Converter to convert all entity attributes of the given type.
If autoapply is set to false, you need to add the javax.persistence.Convert annotation to all attributes that shall be converted and specify the Converter class. The following code snippet shows an example for this approach:

That is all that needs to be done to implement a simple Attribute Converter. Don't forget to grab your free Cheat Sheet about Attribute Converter and all the other features introduced with JPA 2.1.

If you want to try it yourself, you can use Hibernate 4.3.0.Beta4 which is part of the new Wildfly 8.0.0.Beta1 release.

Looking for more information? Read JPA 2.1 - 12 features every developer should know to get an overview about the features introduced with JPA 2.1 or have a look at the other examples on how to use an Attribute Converter:

Please leave a comment with your idea on how to use an Attribute Converter.
If you enjoyed reading this article and like to learn more about other Java EE features, make sure to subscribe to below or follow me on twitter or google+.


JPA 2.1 Specification
Java Doc javax.persistence


  1. Hi

    Thanks for the article.

    I am using JBoss AS 7.1. I set the "" in persistence.xml. But it looks like the converer is not getting called in my case. Could you please help for the same. If the request comes from tomcat, then the converter is being called but not if the request is from jboss.

    Your help would be highly appreciable


    1. Hi,

      JBoss AS 7.1 supports only JPA 2.0, but type converter are new with JPA 2.1. You need to use Wildfly instead.
      Or have a look at hibernate custom types, if you need to stay with JBoss AS 7.1:


  2. Is there also a way to use the Converter implicitly with a javax.persistence.Query? When I add the Object as a query parameter then I get an Exception.

  3. Yes, that it is possible. Your query parameter needs to be of the same type as the properties of the entity.

    Here is an example;

  4. While conversion between entity type and JDBC type is useful for 90% of all use-cases, it is not useful for special cases where the database type is a non-standard type, like PostgreSQL's JSON type, for instance.

    In jOOQ 3.5, we've introduced a new binding SPI, which helps users interact with JDBC bind values on a JDBC level. I wonder if such a thing is possible in JPA as well?

    1. Hi Lukas,
      interesting question. I will have a look :)

  5. I see it's very similar to FacesConverter :)

  6. Hi Thorben and others,

    I have a project where I need to create many different (70+) enums and hence repeatedly define 70+ AttributeConverters. Even though using Java8, there is no neat way of doing things at compile time.

    Anyone knows if we could define those converters at runtime?


  7. Hi,

    It's possible to convert an object into more than one column, with converters?

    1. Hi,

      unfortunately not :(
      You could use a Hibernate specific CompositeUserType for it, see