| = JPA and Enums via @Enumerated |
| :index-group: JPA |
| :jbake-type: page |
| :jbake-status: published |
| |
| It can sometimes be desirable to have a Java `enum` type to represent a particular column in a database. JPA supports converting database data to and from Java `enum` types via the `@javax.persistence.Enumerated` annotation. |
| |
| This example will show basic `@Enumerated` usage in a field of an `@Entity` as well as ``enum``s as the parameter of a `Query`. We'll also see that the actual database representation can be effectively `String` or `int`. |
| |
| == Enum |
| |
| For our example we will leverage the familiar `Movie` entity and add a new field to represent the MPAA.org rating of the movie. This is defined via a simple `enum` that requires no JPA specific annotations. |
| |
| public enum Rating { |
| UNRATED, |
| G, |
| PG, |
| PG13, |
| R, |
| NC17 |
| } |
| |
| == @Enumerated |
| |
| In our `Movie` entity, we add a `rating` field of the enum type `Rating` and annotate it with `@Enumerated(EnumType.STRING)` to declare that its value should be converted from what is effectively a `String` in the database to the `Rating` type. |
| |
| [source,java] |
| ---- |
| @Entity |
| public class Movie { |
| |
| @Id |
| @GeneratedValue |
| private int id; |
| private String director; |
| private String title; |
| private int year; |
| |
| @Enumerated(EnumType.STRING) |
| private Rating rating; |
| |
| public Movie() { |
| } |
| |
| public Movie(String director, String title, int year, Rating rating) { |
| this.director = director; |
| this.title = title; |
| this.year = year; |
| this.rating = rating; |
| } |
| |
| public String getDirector() { |
| return director; |
| } |
| |
| public void setDirector(String director) { |
| this.director = director; |
| } |
| |
| public String getTitle() { |
| return title; |
| } |
| |
| public void setTitle(String title) { |
| this.title = title; |
| } |
| |
| public int getYear() { |
| return year; |
| } |
| |
| public void setYear(int year) { |
| this.year = year; |
| } |
| |
| public Rating getRating() { |
| return rating; |
| } |
| |
| public void setRating(Rating rating) { |
| this.rating = rating; |
| } |
| } |
| ---- |
| |
| The above is enough and we are effectively done. For the sake of completeness we'll show a sample `Query` |
| |
| == Enum in JPQL Query |
| |
| Note the `findByRating` method which creates a `Query` with a `rating` named parameter. The key thing to notice is that the `rating` enum instance itself is passed into the |
| `query.setParameter` method, *not* `rating.name()` or `rating.ordinal()`. |
| |
| Regardless if you use `EnumType.STRING` or `EnumType.ORDINAL`, you still always pass the enum itself in calls to `query.setParameter`. |
| |
| [source,java] |
| ---- |
| @Stateful |
| public class Movies { |
| |
| @PersistenceContext(unitName = "movie-unit", type = PersistenceContextType.EXTENDED) |
| private EntityManager entityManager; |
| |
| public void addMovie(Movie movie) { |
| entityManager.persist(movie); |
| } |
| |
| public void deleteMovie(Movie movie) { |
| entityManager.remove(movie); |
| } |
| |
| public List<Movie> findByRating(Rating rating) { |
| final Query query = entityManager.createQuery("SELECT m FROM Movie as m WHERE m.rating = :rating"); |
| query.setParameter("rating", rating); |
| return query.getResultList(); |
| } |
| |
| public List<Movie> getMovies() throws Exception { |
| Query query = entityManager.createQuery("SELECT m from Movie as m"); |
| return query.getResultList(); |
| } |
| |
| } |
| ---- |
| |
| == EnumType.STRING vs EnumType.ORDINAL |
| |
| It is a matter of style how you would like your `enum` data represented in the database. Either `name()` or `ordinal()` are supported: |
| |
| * `@Enumerated(EnumType.STRING) Rating rating` the value of `rating.name()` is written and read from the corresponding database column; e.g. `G`, `PG`, `PG13` |
| * `@Enumerated(EnumType.ORDINAL) Rating rating` the value of `rating.ordinal()` is written and read from the corresponding database column; e.g. `0`, `1`, `2` |
| |
| The default is `EnumType.ORDINAL` |
| |
| There are advantages and disadvantages to each. |
| |
| === Disadvantage of EnumType.ORDINAL |
| |
| A disadvantage of `EnumType.ORDINAL` is the effect of time and the desire to keep `enums` in a logical order. With `EnumType.ORDINAL` any new enum elements must be added to the |
| *end* of the list or you will accidentally change the meaning of all your records. |
| |
| Let's use our `Rating` enum and see how it would have had to evolve over time to keep up with changes in the MPAA.org ratings system. |
| |
| *1980* |
| |
| public enum Rating { |
| G, |
| PG, |
| R, |
| UNRATED |
| } |
| |
| *1984* PG-13 is added |
| |
| public enum Rating { |
| G, |
| PG, |
| R, |
| UNRATED, |
| PG13 |
| } |
| |
| *1990* NC-17 is added |
| |
| public enum Rating { |
| G, |
| PG, |
| R, |
| UNRATED, |
| PG13, |
| NC17 |
| } |
| |
| If `EnumType.STRING` was used, then the enum could be reordered at anytime and would instead look as we have defined it originally with ratings starting at `G` and increasing in severity to `NC17` and eventually `UNRATED`. With `EnumType.ORDINAL` the logical ordering would not have withstood the test of time as new values were added. |
| |
| If the order of the enum values is significant to your code, avoid `EnumType.ORDINAL` |
| |
| == Unit Testing the JPA @Enumerated |
| |
| [source,java] |
| ---- |
| public class MoviesTest extends TestCase { |
| |
| public void test() throws Exception { |
| |
| final Properties p = new Properties(); |
| p.put("movieDatabase", "new://Resource?type=DataSource"); |
| p.put("movieDatabase.JdbcDriver", "org.hsqldb.jdbcDriver"); |
| p.put("movieDatabase.JdbcUrl", "jdbc:hsqldb:mem:moviedb"); |
| |
| EJBContainer container = EJBContainer.createEJBContainer(p); |
| final Context context = container.getContext(); |
| |
| final Movies movies = (Movies) context.lookup("java:global/jpa-scratch/Movies"); |
| |
| movies.addMovie(new Movie("James Frawley", "The Muppet Movie", 1979, Rating.G)); |
| movies.addMovie(new Movie("Jim Henson", "The Great Muppet Caper", 1981, Rating.G)); |
| movies.addMovie(new Movie("Frank Oz", "The Muppets Take Manhattan", 1984, Rating.G)); |
| movies.addMovie(new Movie("James Bobin", "The Muppets", 2011, Rating.PG)); |
| |
| assertEquals("List.size()", 4, movies.getMovies().size()); |
| |
| assertEquals("List.size()", 3, movies.findByRating(Rating.G).size()); |
| |
| assertEquals("List.size()", 1, movies.findByRating(Rating.PG).size()); |
| |
| assertEquals("List.size()", 0, movies.findByRating(Rating.R).size()); |
| |
| container.close(); |
| } |
| } |
| ---- |
| |
| = Running |
| |
| To run the example via maven: |
| |
| cd jpa-enumerated |
| mvn clean install |
| |
| Which will generate output similar to the following: |
| |
| [source,console] |
| ---- |
| ------------------------------------------------------- |
| T E S T S |
| ------------------------------------------------------- |
| Running org.superbiz.jpa.enums.MoviesTest |
| Apache OpenEJB 4.0.0-beta-2 build: 20120115-08:26 |
| http://tomee.apache.org/ |
| INFO - openejb.home = /Users/dblevins/openejb/examples/jpa-enumerated |
| INFO - openejb.base = /Users/dblevins/openejb/examples/jpa-enumerated |
| INFO - Using 'javax.ejb.embeddable.EJBContainer=true' |
| INFO - Configuring Service(id=Default Security Service, type=SecurityService, provider-id=Default Security Service) |
| INFO - Configuring Service(id=Default Transaction Manager, type=TransactionManager, provider-id=Default Transaction Manager) |
| INFO - Configuring Service(id=movieDatabase, type=Resource, provider-id=Default JDBC Database) |
| INFO - Found EjbModule in classpath: /Users/dblevins/openejb/examples/jpa-enumerated/target/classes |
| INFO - Beginning load: /Users/dblevins/openejb/examples/jpa-enumerated/target/classes |
| INFO - Configuring enterprise application: /Users/dblevins/openejb/examples/jpa-enumerated |
| INFO - Configuring Service(id=Default Stateful Container, type=Container, provider-id=Default Stateful Container) |
| INFO - Auto-creating a container for bean Movies: Container(type=STATEFUL, id=Default Stateful Container) |
| INFO - Configuring Service(id=Default Managed Container, type=Container, provider-id=Default Managed Container) |
| INFO - Auto-creating a container for bean org.superbiz.jpa.enums.MoviesTest: Container(type=MANAGED, id=Default Managed Container) |
| INFO - Configuring PersistenceUnit(name=movie-unit) |
| INFO - Auto-creating a Resource with id 'movieDatabaseNonJta' of type 'DataSource for 'movie-unit'. |
| INFO - Configuring Service(id=movieDatabaseNonJta, type=Resource, provider-id=movieDatabase) |
| INFO - Adjusting PersistenceUnit movie-unit <non-jta-data-source> to Resource ID 'movieDatabaseNonJta' from 'movieDatabaseUnmanaged' |
| INFO - Enterprise application "/Users/dblevins/openejb/examples/jpa-enumerated" loaded. |
| INFO - Assembling app: /Users/dblevins/openejb/examples/jpa-enumerated |
| INFO - PersistenceUnit(name=movie-unit, provider=org.apache.openjpa.persistence.PersistenceProviderImpl) - provider time 406ms |
| INFO - Jndi(name="java:global/jpa-enumerated/Movies!org.superbiz.jpa.enums.Movies") |
| INFO - Jndi(name="java:global/jpa-enumerated/Movies") |
| INFO - Created Ejb(deployment-id=Movies, ejb-name=Movies, container=Default Stateful Container) |
| INFO - Started Ejb(deployment-id=Movies, ejb-name=Movies, container=Default Stateful Container) |
| INFO - Deployed Application(path=/Users/dblevins/openejb/examples/jpa-enumerated) |
| INFO - Undeploying app: /Users/dblevins/openejb/examples/jpa-enumerated |
| INFO - Closing DataSource: movieDatabase |
| INFO - Closing DataSource: movieDatabaseNonJta |
| Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 2.831 sec |
| |
| Results : |
| |
| Tests run: 1, Failures: 0, Errors: 0, Skipped: 0 |
| ---- |
