examples/jpa-enumerated/README_pt.adoc - tomee - Git at Google

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