Na nova Java Persistence Specification, o EntityManager é o serviço central para todas as ações de persistência. Entidades são objetos de Java claros que são alocados como qualquer outro objeto Java. Eles não ficam persistentes explicitamente até seu código interagir com o EntityManager para os fazer persistente. O EntityManager administra o O/R que o mapea entre uma classe de entidade e uma fonte de dados subjacente. O EntityManager provê APIs para criar consultas, buscando objetos, sincronizando objetos, e inserindo objetos no banco de dados. Também pode prover caching e pode administrar a interação entre uma entidade e serviços transacionais em um ambiente Java EE como JTA. O EntityManager é firmemente integrado com Java EE e EJB mas não é limitado a estes ambientes; pode ser usado em programas de Java SE.

Persistence Contexts

Começaremos através de uma introdução das condições do core do JPA. Uma unidade de persistência ou persistence-unit é uma configuração nomeada de classes de entidade. Um contexto de persistência é um gerenciamento de Entidades onde, todo contexto de persistência é associado com uma unidade de persistência. Entendendo o contexto de persistência é a chave para entender o EntityManager. Uma inclusão de entidade ou exclusão de um contexto de persistência, determinarão no resultado de qualquer operações persistentes nisto.

Se o contexto de persistência participa em uma transação, que está na memória, o estado das entidades gerenciadas será sincronizado ao banco de dados. Ainda apesar do papel importante que faz, o contexto de persistência nunca é realmente visível à aplicação. Sempre é acessado indiretamente pelo EntityManager e assumido que estar lá quando nós precisarmos dele.

Persistence Unit

Um EntityManager mapea um conjunto de classes a um banco de dados particular. Este conjunto de classes é chamado de persistence unit (unidade de persistência).

Antes de você poder pensar até mesmo em criar ou consultar entidades com um entity manager, você tem que aprender a empacotar uma unidade de persistência para uso, dentro de um ambiente Java SE ou Java EE.

Uma unidade de persistência está definida em um arquivo chamado persistence.xml. Este arquivo é um descriptor de desenvolvimento exigido no JPA. Um arquivo de persistence.xml pode definir um ou mais unidades de persistência. Este arquivo fica situado no diretório META-INF em:

Ambientes SE, esta pasta fica no classpath da aplicação. Em uma aplicação web, este diretório fica localizado nas pasta WEB-INF\classes\META-INF

Na Listagem 1 temos um exemplo de um arquivo persistence.xml.


<?xml version="1.0" encoding="UTF-8"?>
<persistence version="1.0" xmlns="http://java.sun.com/xml/ns/persistence" xmlns:
xsi="http://www.w3.org/2001/XMLSchema-instance" 
xsi:schemaLocation="http://java.sun.com/xml/ns/persistence 
http://java.sun.com/xml/ns/persistence/persistence_1_0.xsd">
  <persistence-unit name="novoExemploPU" transaction-type="RESOURCE_LOCAL">
    <provider>oracle.toplink.essentials.ejb.cmp3.EntityManagerFactoryProvider
    </provider>
    <class>teste.Empresas</class>
    <class>teste.Cartoes</class>
    <properties>
      <property name="toplink.jdbc.url" value="jdbc:mysql://localhost:3306/devmedia"/>
      <property name="toplink.jdbc.user" value="root"/>
      <property name="toplink.jdbc.driver" value="com.mysql.jdbc.Driver"/>
      <property name="toplink.jdbc.password" value="123456"/>
    </properties>
  </persistence-unit>
</persistence>
Listagem 1. Arquivo persistence.xml

Você deve especificar suas classes de Entidades dentro no arquivo persistence.xml (persistence unit), como mostrado no código.

Vamos analisar como obter acesso de um EntityManager, para poder inserir, atualizar, remover e consultar um bean de entidade no seu bancos de dados. Embora você possa usar uma interface de fábrica em Java EE, esta plataforma provê algumas características adicionais que fazem isto mais fácil e menos árduo de administrar instancias de EntityManager.

EntityManagerFactory

EntityManagers podem ser criado ou podem ser obtidos de um EntityManagerFactory. Em uma aplicação Java SE, você tem que usar um EntityManagerFactory para criar instancias de um EntityManager. Usar o factory não é uma exigência em um ambiente Java EE.

Obtendo um EntityManagerFactory em um ambiente Java SE

Em um ambiente Java SE, a classe javax.persistence.Persistence é responsável por amarrar um EntityManagerFactory, como mostra a Listagem 2.


public class Persistence {
   public static EntityManagerFactory createEntityManagerFactory(
           String unitName
   );
   public static EntityManagerFactory createEntityManagerFactory(
           String unitName,
           java.util.Map
 properties
   );
Listagem 2. Classe javax.persistence.Persistence

A classe javax.persistence.Persistence procura descriptors da distribuição persistence.xml dentro de seu classpath de Java. O parâmetro do unitName que você passa dentro permitirá que a execução da persistencia encontre um EntityManagerFactory que combine o nome dado.


EntityManagerFactory factory = Persistence.createEntityManagerFactory("novoExemploPU");
...
factory.close( );

Em Java EE, obter um EntityManagerFactory pode ser injetado diretamente em um campo ou em um método setter do seu EJBs usando a anotação @javax.persistence.PersistenceUnit, como mostra a Listagem 3.


import javax.persistence.*;
import javax.ejb.*;
 
@Stateless
public MyBean implements MyBusinessInterface {
 
   @PersistenceUnit(unitName="novoExamploPU")
   private EntityManagerFactory factory;
 
   private EntityManagerFactory factory2;
 
   @PersistenceUnit(unitName="novoExemploOutroDB")
   public void setFactory2(EntityManagerFactory f) {
      this.factory2 = f;
   }
Listagem 3. Anotação @javax.persistence.PersistenceUnit

Fizemos uma breve introdução a alguns conceitos dentro do JPA como tecnologia utilizada na camada de persistência.