Você está na página 1de 7

Documentao do WASCE 3.0.

0 > ndice > Contedo > Implementao > Criando Planos de Implementao > JPA
Contedo
Viso Geral
Configurao
Administrao
Implementao
Desenvolvimento
Procura
Funciona com Google Search
Recursos
Mapa do Site
Amostras
Documentao Off-line
Opes de Suporte
IBM developerWorks
Apache Geronimo
Tutoriais do Apache Geronimo
Viso Geral
O arquivo persistence.xml descreve unidades de persistncia. Este o arquivo descritor de implementao para persistncia
que usa Java Persistence API (JPA). Ele usado para declarar o seguinte.
Classes de persistncia gerenciadas.
As classes gerenciadas so, por exemplo, aquelas que usam @Entity, @Embeddable ou
@MappedSuperclass.
Especifique o mapeamento de objeto/relao.
O JPA fornece vrios mecanismos para mapear as classes java para tabelas em um banco de dados relacional.
Informaes de configurao para gerenciadores de entidades e classes factory do gerenciador de entidade.
O arquivo persistence.xml colocado no diretrio META-INF da raiz da unidade de persistncia. As informaes de
mapeamento de objeto/relacional so fornecidas das seguintes formas.
Anotaes nas classes de persistncia gerenciadas
Um ou mais arquivos XML contidos na raiz da unidade de persistncia
Um ou mais arquivos XML fora da raiz da unidade de persistncia no caminho de classe e referidos a partir de
persistence.xml ou de uma combinao deles.
No Java EE, a raiz de uma unidade de persistncia pode ser uma das seguintes
Arquivo EJB-JAR
Diretrio WEB-INF/classes de um arquivo WAR
Um arquivo jar no diretrio WEB-INF/lib de um arquivo WAR
Um arquivo jar na raiz do EAR
Um arquivo jar no diretrio da biblioteca EAR
Um arquivo jar do aplicativo cliente
O local das classes de persistncias gerenciadas pode ser:
Na raiz da unidade de persistncia.
Pode ser especificado pela referncia no persistence.xml nomeando as classes, archives ou arquivos XML de
mapeamento
que so acessveis no caminho de classe do aplicativo.
Algumas combinaes dos mtodos acima.
Pacote
O arquivo persistence.xml colocado no diretrio META-INF da raiz da unidade de persistncia.
Esquema
O esquema de persistence.xml est neste link. O Apache Geronimo usa o OpenJPA como o provedor JPA.
Elementos de Nvel Superior do Esquema
O elemento de nvel superior de persistence.xml <persistence>. As sees acima explicam os subelementos do elemento
<persistence>. O persistence.xml tpico se assemelha ao seguinte:
persistence.xml
<?xml version="1.0" encoding="UTF-8"?>
<persistence xmlns="http://java.sun.com/xml/ns/persistence"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="1.0"
xsi:schemaLocation="http://java.sun.com/xml/ns/persistence
http://java.sun.com/xml/ns/persistence/persistence_1_0.xsd">
...
...
</persistence>
<persistence-unit>
O elemento <persistence> pode consistir de mais de um elemento <persistence-unit>, cada um descrevendo uma unidade
de persistncia. O elemento persistence-unit consiste dos seguintes atributos.
Atributo : name
Documentao do IBM WebSphere Application Se... http://publib.boulder.ibm.com/wasce/V3.0.0/pt_BR/jpa...
1 of 7 15-04-2014 11:04
Esse atributo obrigatrio. O atributo name define o nome da unidade de persistncia. Ele identifica exclusivamente um
contexto de persistncia. Esse nome usado para identificar uma unidade de persistncia referida pelas anotaes
PersistenceContext e PersistenceUnit. Ele tambm referido ao criar um objeto factory do gerenciador de entidades. A
seguinte nota ilustra o uso em um aplicativo.
1. A anotao abaixo insere o objeto EntityManager que corresponde unidade de persistncia Tutorial
na varivel em .
@PersistenceContext(unitName="Tutorial")
private EntityManager em;
2. A anotao abaixo insere o objeto EntityManagerFactory que corresponde unidade de persistncia Account
na varivel emf. A partir de emf, o objeto EntityManager poder ser criado.
@PersistenceUnit(unitName="Account")
private EntityManagerFactory emf;
Atributo : transaction-type
Esse atributo pode ter os seguintes valores.
JTA
RESOURCE_LOCAL
O atributo transaction-type usado para especificar se os gerenciadores de entidades fornecidos pela factory do gerenciador
da unidade de persistncia devem ser gerenciadores de entidades JTA ou gerenciadores de entidades locais de recursos. O valor
desse elemento JTA ou RESOURCE_LOCAL. Um transaction-type de JTA assume que uma origem de dados do JTA ser
fornecida. Ela ser fornecida conforme especificado pelo elemento jta-data-source ou pelo continer. No geral, em ambientes
Java EE, um transaction-type de RESOURCE_LOCAL assume que uma origem de dados no-JTA ser fornecida. Em um
ambiente Java EE, se esse elemento no estiver especificado, o padro ser JTA. Em um ambiente Java SE, se esse elemento
no estiver especificado, um padro de RESOURCE_LOCAL poder ser assumido.
1. A declarao abaixo destina-se a uma unidade de persistncia denominada Account e o tipo de transao JTA.
<persistence-unit name="Account" transaction-type="JTA">
...
...
</persistence-unit>
2. A declarao abaixo destina-se a uma unidade de persistncia denominada Account e o tipo de transao
RESOURCE_LOCAL.
<persistence-unit name="Account" transaction-type="RESOURCE_LOCAL">
...
...
</persistence-unit>
Observe que existem dois tipos de gerenciadores de entidade e contextos de persistncia correspondentes. Eles so o
gerenciador de entidade gerenciado pelo continer e o gerenciador de entidade gerenciado pelo aplicativo.
O gerenciador de entidade gerenciado pelo continer aquele cujo contexto de persistncia gerenciado pelo continer. O
contexto de persistncia propagado junto com a transao ativa. O escopo da persistncia do gerenciador de entidade
gerenciado pelo continer a transao, por padro. O tipo de transao do gerenciador de entidade sempre JTA. O
objeto EntityManager inserido pelo continer para o aplicativo.
O gerenciador de entidade gerenciado pelo aplicativo aquele cujo contexto de persistncia gerenciado pelo aplicativo. O
contexto de persistncia no propagado junto com a transao. O contexto de persistncia ser ativado mesmo depois
que a transao atual for concluda. O tipo de transao do gerenciador de entidade RESOURCE_LOCAL, por padro. O
objeto EntityManager deve ser criado usando o objeto EntityManagerFactory no aplicativo.
<description>
O elemento description fornece informaes descritivas opcionais sobre a unidade de persistncia.
1. O contedo XML abaixo ilustra o uso do elemento.
Documentao do IBM WebSphere Application Se... http://publib.boulder.ibm.com/wasce/V3.0.0/pt_BR/jpa...
2 of 7 15-04-2014 11:04
<persistence-unit name="Account" transaction-type="JTA">
<description>Entities related to bank accounts</description>
...
...
</persistence-unit>
<provider>
O elemento provider especifica o nome da classe javax.persistence.spi.PersistenceProvider do provedor de
persistncia. O elemento provider deve ser especificado quando o aplicativo depende de um provedor de persistncia especfico
que est sendo usado. A classe do provedor fornece EntityManagers para esta unidade de persistncia.
1. O contedo XML abaixo ilustra o uso do elemento.
<persistence-unit name="Account" transaction-type="JTA">
<description>Entities related to bank accounts</description>
<provider>org.apache.openjpa.persistence.PersistenceProviderImpl</provider>
...
...
</persistence-unit>
Para OpenJPA, o valor do provedor org.apache.openjpa.persistence.PersistenceProviderImpl.
<jta-data-source>, <non-jta-data-source>
Nos ambientes Java EE, os elementos jta-data-source e non-jta-data-source so usados para especificar o nome JNDI global da
origem de dados JTA e no-JTA, respectivamente, a ser usado pelo provedor de persistncia. Se nenhum for especificado, o
implementador dever especificar uma origem de dados JTA na implementao ou uma origem de dados JTA dever ser fornecida
pelo continer e um JTA EntityManagerFactory ser criado para corresponder a ela. Esses elementos nomeiam a origem de dados
no ambiente local. O formato/a sintaxe desses nomes e a capacidade de especificar os nomes so especficos do produto. Nos
ambientes Java SE, esses elementos podero ser usados ou as informaes de origem de dados podero ser especificadas por
outros meios; dependendo dos requisitos do provedor.
No servidor Geronimo, os usurios podem implementar origens de dados (conjuntos de conexes do banco de dados) nos
bancos de dados de vrios fornecedores, como DB2, Oracle, MySQL, MS-SQLServer etc,. Ao criar uma origem de dados, os
usurios precisam especificar o nome da origem de dados no plano de implementao. O nome fornecido na origem de
dados precisa ser fornecido nos elementos jta-data-source e non-jta-data-source. O fragmento XML abaixo ilustra o
uso.
<persistence-unit name="Account" transaction-type="JTA">
<description>ContainerManagedJPA</description>
<provider>org.apache.openjpa.persistence.PersistenceProviderImpl</provider>
<jta-data-source>AccountDB2DataSource</jta-data-source>
...
...
</persistence-unit>
O non-jta-datasource deve ser uma origem de dados sem suporte a transaes. Ele pode ser implementado no servidor
Geronimo usando o elemento <no-transaction/> em vez de <local-transaction/> ou <xa-transaction> no plano do
conector, como ilustrado abaixo.
<connector xmlns="http://geronimo.apache.org/xml/ns/j2ee/connector-1.2">
...
...
<resourceadapter>
...
...
<connectionmanager>
<local-transaction/>
<no-transaction/>
<max-size>10</max-size>
<min-size>0</min-size>
<match-one/>
</single-pool>
</connectionmanager>
...
...
</resourceadapter>
...
...
</connector>
<mapping-file>
Documentao do IBM WebSphere Application Se... http://publib.boulder.ibm.com/wasce/V3.0.0/pt_BR/jpa...
3 of 7 15-04-2014 11:04
Um arquivo XML de mapeamento de objeto/relacional contm informaes de mapeamento para as classes listadas nele. Os
arquivos de mapeamento podem ser fornecidos como a seguir.
O arquivo XML de mapeamento de objeto/relacional denominado orm.xml pode ser especificado no diretrio META-INF
da raiz da
unidade de persistncia.
O arquivo XML de mapeamento de objeto/relacional denominado orm.xml pode ser especificado no diretrio META-INF
de qualquer arquivo jar
referido por persistence.xml.
Alm disso, outros arquivos de mapeamento podem ser referidos pelos elementos mapping-file do elemento
persistence-unit
e podem estar presentes em qualquer lugar do caminho de classe.
Um arquivo orm.xml ou outro arquivo de mapeamento est localizado como um recurso pelo provedor de persistncia. Se um
arquivo de mapeamento estiver especificado, as informaes de classes e mapeamento especificadas no arquivo de mapeamento
sero usadas. Se vrios arquivos de mapeamento estiverem especificados (possivelmente incluindo um ou mais arquivos
orm.xml), os mapeamentos resultantes sero obtidos combinando os mapeamentos de todos os arquivos. O resultado ser
indefinido se vrios arquivos de mapeamento (incluindo qualquer arquivo orm.xml) referidos por uma nica unidade de
persistncia contiverem informaes de mapeamento de sobreposio para qualquer classe fornecida. O fragmento XML abaixo
ilustra o uso.
<persistence-unit name="Tutorial" transaction-type="RESOURCE_LOCAL">
<provider>org.apache.openjpa.persistence.PersistenceProviderImpl</provider>
<non-jta-data-source>ProductDS-nonJTA</non-jta-data-source>
<mapping-file>object_mappings.xml</mapping-file>
...
...
</persistence-unit>
O arquivo object_mappings.xml deve estar no caminho de classe do aplicativo.
<jar-file>
Um ou mais arquivos JAR podem ser especificados usando os elementos jar-file em vez dos arquivos de mapeamento
especificados nos elementos mapping-file, ou alm deles. Se especificado, o JPA processar esses arquivos jar como a seguir.
Esses arquivos JAR sero procurados para classes de persistncia gerenciadas e qualquer anotao de metadado de
mapeamento localizada neles ser processada.
Eles sero mapeados usando os padres da anotao de mapeamento definidos pela especificao JPA. Os arquivos JAR
sero especificados em relao raiz da unidade de persistncia.
Uma lista de classes de persistncia gerenciadas tambm pode ser especificada em vez dos arquivos JAR e dos arquivos
de mapeamento, ou alm deles (usando o elemento xml class explicado abaixo). Qualquer anotao de metadados de
mapeamento localizada nessas classes ser processada ou ser mapeada usando os padres da anotao de
mapeamento. O fragmento ML a seguir ilustra o uso.
<persistence-unit name="Tutorial" transaction-type="RESOURCE_LOCAL">
<provider>org.apache.openjpa.persistence.PersistenceProviderImpl</provider>
<jta-data-source>AccountDS</jta-data-source>
<mapping-file>account_mappings.xml</mapping-file>
<jar-file>account-entities.jar</jar-file>
...
...
</persistence-unit>
O account-entities.jar colocado na raiz da unidade de persistncia.
<Class>
As seguintes classes devem ser implcita ou explicitamente denotadas como classes de persistncia gerenciadas para serem
includas em uma unidade de persistncia.
Classes de entidade
Classes que podem ser integradas
Superclasses mapeadas.
O conjunto de classes de persistncia gerenciadas que so mapeadas por uma unidade de persistncia definido usando um ou
mais dos seguintes itens:
Um ou mais arquivos XML de mapeamento de objeto/relacional (explicado na seo mapping-file acima).
Um ou mais arquivos jar que sero procurados para as classes explicadas na seo jar-file acima).
Uma lista explcita de classes (usando o elemento class).
As classes de persistncia gerenciadas anotadas contidas na raiz da unidade de persistncia
(a menos que o elemento exclude-unlisted-classes seja especificado)
Documentao do IBM WebSphere Application Se... http://publib.boulder.ibm.com/wasce/V3.0.0/pt_BR/jpa...
4 of 7 15-04-2014 11:04
No ambiente Java SE, as seguintes regras e recomendaes precisam ser seguidas.
O elemento class usado para listar uma classe de persistncia gerenciada. Uma lista de todas as classes de persistncia
gerenciadas deve ser especificada nos ambientes Java SE para garantir a portabilidade.
Aplicativos Java SE mveis no devem contar com os outros mecanismos descritos aqui para especificar as classes de
persistncia gerenciadas de uma unidade de persistncia.
Provedores de persistncia tambm exigem que o conjunto de classes de entidade que devem ser gerenciadas seja
totalmente enumerado em persistence.xml.
O seguinte procedimento explica como as classes de persistncia gerenciadas so procuradas.
Todas as classes contidas na raiz da unidade de persistncia tambm sero procuradas para classes de persistncia
gerenciadas anotadas e qualquer anotao de metadados de mapeamento localizada nelas ser processada ou elas sero
mapeadas usando os padres da anotao de mapeamento.
Se voc no pretende que as classes de persistncia anotadas contidas na raiz da unidade de persistncia sejam includas
na unidade de persistncia, o elemento exclude-unlisted-classes dever ser usado.
O elemento exclude-unlisted-classes no destina-se para uso nos ambientes Java SE.
O conjunto resultante de entidades gerenciadas pela unidade de persistncia a unio dessas origens, com as anotaes
de metadados de mapeamento (ou padres de anotao) de qualquer classe especfica que esteja sendo sobrescrita pelo
arquivo de informaes de mapeamento XML se houver anotaes ou mapeamentos XML para essa classe.
O nvel mvel mnimo de substituio est no nvel do campo de persistncia ou propriedade.
As classes e/ou jars que so nomeados como parte de uma unidade de persistncia devem estar no caminho de classe.
Consult-las do arquivo persistence.xml no far com que elas sejam colocadas no caminho de classe.
Todas as classes devem estar no caminho de classe para garantir que os gerenciadores de entidades de diferentes
unidades de persistncia que mapeiam a mesma classe estejam acessando uma classe idntica.
O fragmento XML a seguir ilustra o uso do elemento class.
<persistence-unit name="AccountUnit" transaction-type="JTA">
<description>ContainerManagedJPA</description>
<provider>org.apache.openjpa.persistence.PersistenceProviderImpl</provider>
<jta-data-source>AccountDS</jta-data-source>
<class>sample.jpa.Account</class>
<class>sample.jpa.Person</class>
...
...
</persistence-unit>
O sample.jpa.Account e sample.jpa.Person so explicitamente mencionados como classes de persistncia gerenciadas
no persistence.xml.
<exclude-unlisted-classes>
Quando configurada como true, apenas as classes e jars listados sero varridos para classes persistentes. Caso contrrio, o jar
ou diretrio de fechamento tambm sero varridos. Isso no ser aplicvel s unidades de persistncia Java SE. O fragmento
XML a seguir ilustra o uso do elemento exclude-unlisted-classes.
<persistence-unit name="AccountUnit" transaction-type="JTA">
<description>ContainerManagedJPA</description>
<provider>org.apache.openjpa.persistence.PersistenceProviderImpl</provider>
<jta-data-source>AccountDS</jta-data-source>
<jar-file>account-entities.jar</jar-file>
<class>sample.jpa.Account</class>
<class>sample.jpa.Person</class>
<exclude-unlisted-classes>true</exclude-unlisted-classes>
...
...
</persistence-unit>
Apenas account-entities.jar, sample.jpa.Account e sample.jpa.Person so varridos para classes de persistncia
gerenciadas.
<properties>
O elemento properties usado para especificar propriedades especficas do fornecedor que se aplicam unidade de
persistncia e a configurao de fbrica do gerenciador de entidades.
Se um provedor de persistncia no reconhecer as propriedades (diferente daquelas definidas por esta especificao), o
provedor ignorar essas propriedades.
Os fornecedores usaro namespaces do fornecedor para propriedades.
O fragmento XML a seguir ilustra o uso do elemento properties. As propriedades e os valores especificados permitem que o JPA
se conecte ao banco de dados VehicleDB criado no derby integrado do servidor Geronimo.
Documentao do IBM WebSphere Application Se... http://publib.boulder.ibm.com/wasce/V3.0.0/pt_BR/jpa...
5 of 7 15-04-2014 11:04
<persistence-unit name="Inheritence">
<description>Single Table Inheritence example</description>
<provider>org.apache.openjpa.persistence.PersistenceProviderImpl</provider>
<class>com.jpa.RoadVehicle</class>
<class>com.jpa.Car</class>
<class>com.jpa.Coupe</class>
<class>com.jpa.Motorcycle</class>
<class>com.jpa.Roadster</class>
<properties>
<property name="openjpa.ConnectionURL" value="jdbc:derby:VehicleDB" />
<property name="openjpa.ConnectionDriverName" value="org.apache.derby.jdbc.EmbeddedDriver" />
<property name="ConnectionUserName" value="app" />
<property name="openjpa.jdbc.SynchronizeMappings" value="false" />
</properties>
</persistence-unit>
As propriedades acima so especficas para o provedor OpenJPA. O provedor OpenJPA l essas propriedades e cria o
EntityManagerFactory adequado. As propriedades suportadas por OpenJPA esto neste link
Configurao de JPA e Planos de Geronimo
O arquivo persistence.xml pode declarar mais de uma persistence-unit. Uma declarao de persistence-unit em
persistence.xml pode ser substituda nos planos de Geronimo (geronimo-web.xml ou openejb-jar.xml) como a seguir.
Se uma persistence-unit for declarada em persistence.xml, bem como em um plano de Geronimo
(geronimo-web.xml ou openejb-jar.xml), a declarao no plano de Geronimo substituir a declarao
em persistence.xml
O exemplo abaixo ilustra o recurso de substituio no Geronimo.
<?xml version="1.0" encoding="UTF-8"?>
<persistence xmlns="http://java.sun.com/xml/ns/persistence"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="1.0"
xsi:schemaLocation="http://java.sun.com/xml/ns/persistence
http://java.sun.com/xml/ns/persistence/persistence_2_0.xsd">
<persistence-unit name="AccountUnit" transaction-type="JTA">
<description>ContainerManagedJPA</description>
<provider>org.apache.openjpa.persistence.PersistenceProviderImpl</provider>
<jta-data-source>AccountDS</jta-data-source>
<class>sample.jpa.Account</class>
<class>sample.jpa.Person</class>
</persistence-unit>
</persistence>
AccountUnit pode ser substitudo em openejb-jar.xml como a seguir.
<openejb-jar xmlns="http://openejb.apache.org/xml/ns/openejb-jar-2.2"
xmlns:naming="http://geronimo.apache.org/xml/ns/naming-1.2"
xmlns:sec="http://geronimo.apache.org/xml/ns/security-2.0"
xmlns:sys="http://geronimo.apache.org/xml/ns/deployment-1.2">
<sys:environment>
<sys:moduleId>
<sys:groupId>ContainerManagedJPA</sys:groupId>
<sys:artifactId>EJB</sys:artifactId>
<sys:version>1.0</sys:version>
<sys:type>car</sys:type>
</sys:moduleId>
<dependencies>
<dependency>
<groupId>console.dbpool</groupId>
<artifactId>AccountDS1</artifactId>
</dependency>
</dependencies>
</sys:environment>
<persistence xmlns="http://java.sun.com/xml/ns/persistence">
<persistence-unit name="AccountUnit" transaction-type="JTA">
<description>ContainerManagedJPA</description>
<provider>org.apache.openjpa.persistence.PersistenceProviderImpl</provider>
<jta-data-source>AccountDS1</jta-data-source>
<class>sample.jpa.Account</class>
<class>sample.jpa.Person</class>
</persistence-unit>
</persistence>
<enterprise-beans/>
Documentao do IBM WebSphere Application Se... http://publib.boulder.ibm.com/wasce/V3.0.0/pt_BR/jpa...
6 of 7 15-04-2014 11:04
</openejb-jar>
AccountUnit substitudo em openejb-jar.xml para usar a origem de dados JTA AccountDS1. No persistence.xml,
declara-se o uso da origem de dados do JTA, AccountDS.
Similarmente, persistence-unit pode ser substituda em geronimo-web.xml aps a declarao <sys:environment>.
Sobre a IBM Privacidade Contato Termos de Uso Copyright 2005-2011, International Business Machines Corporation.
Documentao do IBM WebSphere Application Se... http://publib.boulder.ibm.com/wasce/V3.0.0/pt_BR/jpa...
7 of 7 15-04-2014 11:04