public enum Rating { UNRATED, G, PG, PG13, R, NC17 }
JPA and Enums via @Enumerated
À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 @jakarta.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.
@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
.
@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
.
@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 derating.name()
é gravado e lido a partir da coluna correspondente no banco de dados; por exemploG
,PG
,PG13
-
@Enumerated(EnumType.ORDINAL) Rating rating
o valor derating.ordinal()
é gravado e lido a partir da coluna correspondente no banco de dados; por exemplo0
,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
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:
-------------------------------------------------------
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 'jakarta.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