= JPA and Enums via @Enumerated
:index-group: JPA
:jbake-type: page
:jbake-status: published

Às vezes pode ser desejável ter um tipo `enum` do Java para representar uma coluna específica em um banco de dados. A JPA oferece suporte à conversão dos dados de um banco de dados para ou a partir de um tipo `enum` do Java por meio da anotação  `@javax.persistence.Enumerated`.

Esse exemplo mostrará o uso básico do `@Enumerated` em um campo de uma `@Entity`, bem como ``enum`` como parâmetro de uma `Query`.  
Também veremos que a representação de um banco de dados real pode ser `String` ou `int`.

== Enum

Para o nosso exemplo, vamos aproveitar a familiar entidade `Movie` e adicionar um novo campo para representar a classificação MPAA.org do filme.  Isso é definido por meio de um `enum` simples que não requer anotações específicas da JPA.

 public enum Rating {
     UNRATED,
     G,
     PG,
     PG13,
     R,
     NC17
 }

== @Enumerated

Em nossa entidade `Movie`, nós adicionamos um campo `rating` do enum do tipo `Rating` e anotamos com `@Enumerated(EnumType.STRING)` para declarar que seu valor deve ser convertido do que é efetivamente uma `String` no banco de dados para o tipo `Rating`.

[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;
    }
}
----

O código acima é suficiente e estará efetivamente feito. Por uma questão de completude, mostraremos um exemplo de uma `Query`

== Enum em uma Query JPQL

Observe o método `findByRating` que cria uma `Query` com um parâmetro denominado `rating`. A principal coisa a notar é que a instância do enum `rating` propriamente dita é passada para o método
 `query.setParameter`, *não* `rating.name()` ou `rating.ordinal()`.

Independentemente se você usar `EnumType.STRING` ou `EnumType.ORDINAL`, você ainda sempre tem que passar o enum propriamente dito em chamadas para `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

É uma questão de estilo como você gostaria que seus dados `enum` representados no banco de dados.  Qualquer um deles `name()` ou `ordinal()` são suportados:

* `@Enumerated(EnumType.STRING) Rating rating` o valor de `rating.name()` é gravado e lido a partir da coluna correspondente no banco de dados; por exemplo `G`, `PG`, `PG13`
* `@Enumerated(EnumType.ORDINAL) Rating rating` o valor de `rating.ordinal()` é gravado e lido a partir da coluna correspondente no banco de dados; por exemplo `0`, `1`, `2`

O padrão é `EnumType.ORDINAL`

Essas são as vantagens e desvantagens de cada.

=== Desvantagem do EnumType.ORDINAL

A desvantagem do `EnumType.ORDINAL` é o efeito do tempo e o desejo de manter `enums` em uma ordem lógica.  Com `EnumType.ORDINAL` quaisquer novos elementos enum devem ser adicionados ao
*final* da lista ou você irá alterar acidentalmente o significado de todos os seus registros.

Vamos usar o nosso enum `Rating` e ver como ele teria que evoluir ao longo do tempo para acompanhar as mudanças no sistema de classificações MPAA.org.

*1980*

 public enum Rating {
     G,
     PG,
     R,
     UNRATED
 }

*1984* PG-13 é adicionado

 public enum Rating {
     G,
     PG,
     R,
     UNRATED,
     PG13
 }

*1990* NC-17 é adicionado

 public enum Rating {
     G,
     PG,
     R,
     UNRATED,
     PG13,
     NC17
 }

Se `EnumType.STRING` foi usado, em seguida, o enum poderia ser reordenado a qualquer momento e, em vez disso, olhar como nós o definimos originalmente com classificações começando em `G` e aumentando em severidade para `NC17` e, eventualmente, `UNRATED`.  Com `EnumType.ORDINAL` a ordenação lógica não teria resistido o teste de tempo como novos valores foram adicionados.

Se a ordem dos valores enum for significativa para seu código, evite `EnumType.ORDINAL`

== Testando Unitariamente a 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();
    }
}
----

= Executando

Para executar o exemplo via maven:

 cd jpa-enumerated
 mvn clean install

Que irá gerar saída semelhante ao seguinte:

[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
----