MADEJA - JPA (Java Persistence API)

JPA (Java Persistence API)

Java Persistence API (JPA) proporciona un modelo de persistencia basado en POJO's para mapear bases de datos relacionales en Java. El Java Persistence API fue desarrollado por el grupo de expertos de EJB 3.0 como parte de JSR 220, aunque su uso no se limita a los componentes software EJB. Tambin puede utilizarse directamente en aplicaciones web y aplicaciones clientes; incluso fuera de la plataforma Java EE, por ejemplo, en aplicaciones Java SE. En su definicin, se han combinado ideas y conceptos de los principales frameworks de persistencia como Hibernate, Toplink y JDO, y de las versiones anteriores de EJB. Todos estos cuentan actualmente con una implementacin JPA. El mapeo objeto/relacional, es decir, la relacin entre entidades Java y tablas de la base de datos, se realiza mediante anotaciones en las propias clases de entidad, por lo que no se requieren ficheros descriptores XML. Tambin pueden definirse transacciones como anotaciones JPA. Java Persistence API consta de tres reas: El Java Persistence API El lenguaje de query El mapeo de los metadatos objeto/relacional A continuacin se muestra un pequeo ndice con la ficha descompuesta: Caractersticas Ventajas e inconvenientes Versiones: No aplica Requisitos e incompatibilidades Interaccin con otros subsistemas o componentes Modo de empleo Enlaces de inters Recomendaciones de uso Aplicaciones de ejemplo

Caractersticas
Una entidad es un objeto de dominio de persistencia. Normalmente, una entidad representa una tabla en el modelo de datos relacional y cada instancia de esta entidad corresponde a un registro en esa tabla. El estado de persistencia de una entidad se representa a travs de campos persistentes o propiedades persistentes. Estos campos o propiedades usan anotaciones para el mapeo de estos objetos en el modelo de base de datos. El estado persistente de una entidad puede ser accesible a travs de variables de instancia a la entidad o bien a travs de las propiedades de estilo de JavaBean. Lo campos o propiedades pueden tener asociados los siguientes tipos Java: Tipos primitivos de Java java.lang.String Otro tipo de objeto serializable, incluyendo:

Page 1 - 02/06/2008 a las 13:21

MADEJA - JPA (Java Persistence API)

Wrappers de tipos primitivos en Java java.math.BigInteger java.math.BigDecimal java.util.Date java.util.Calendar java.sql.Date java.sql.Time java.sql.TimeStamp User-defined serializable types byte Byte char Character Tipos enumerados Otras entidades y/o colecciones de entidades

Las entidades podrn utilizar campos persistentes o propiedades. Si las anotaciones de mapeo se aplican a las instancias de las entidades, la entidad utiliza campos persistentes, En cambio, si se aplican a los mtodos getters de la entidad, se utilizarn propiedades persistentes. Hay que tener en cuenta que no es posible aplicar anotaciones tanto a campos como a propiedades en una misma entidad. Campos persistentes Si la entidad utiliza campos persistentes, los accesos se realizan en tiempo de ejecucin. Aquellos campos que no tienen anotaciones del tipo javax.persistence.Transient o no han sido marcados como Java transitorio sern persistentes para el almacenamiento de datos. Las anotaciones de mapeo objeto/relacin deben aplicarse a los atributos de la instancia. Propiedades persistentes Si la entidad utiliza propiedades persistentes, la entidad debe seguir el mtodo de los convenios de componentes JavaBeans. Las propiedades de JavaBean usan mtodos getters y setters en cuyo nombre va incluido el atributo de la clase al cual hacen referencia. Si el atributo es booleano podr utilizarse isProperty en lugar de getProperty. Por ejemplo, si una entidad Customer, utiliza las propiedades de persistencia, supongamos que tiene un atributo privado denominado firsName, la clase definir los mtodos getFirstName y setFirstName para recuperar y establecer el valor de la variable firstName. Los mtodos para la firma de un valor nico de propiedades son los siguientes.
Tipo getProperty () void setProperty (Tipo tipo)

Tanto los campos persistentes como las propiedades deben utilizar las interfaces de Java independientemente de que la entidad utilice campos o propiedades. Las colecciones posibles son: java.util.Collection java.util.Set java.util.List java.util.Map

Si la entidad utiliza campos persistentes, el tipo en el mtodo anterior debe ser uno de estos tipos de collection. Las variables genricas de estos tipos tambin pueden ser utilizadas. Por ejemplo, si la entidad Customer tiene un atributo que contiene un conjunto de nmeros de tlfno, tendr que tener los siguientes mtodos:
Set<PhoneNumber> getPhoneNumbers() {}

Page 2 - 02/06/2008 a las 13:21

MADEJA - JPA (Java Persistence API)

void setPhoneNumbers(Set<PhoneNumber>) {}

Las anotaciones del mapeo objeto/relacional deben aplicarse a los mtodos getter. El mapeo de las anotaciones no puede aplicarse a los campos o propiedades anotadas como @Transient o marcadas como transient. Clases con claves primarias Una clase con clave primaria debe cumplir los siguientes requerimientos: El modificador de control de acceso de la clase debe ser pblico Las propiedades de la clave primaria deben ser pblicas o protected si se utiliza el acceso a la base de la propiedad. La clase debe tener un constructor pblico por defecto. La clase debe implementar los mtodos hashCode() y equals(Object other) La clase debe ser serializable. Una clave primaria debe representarse y mapearse por campos mltiples o propiedades de la clase de la entidad, o debe representarse y mapearse como una clase embebida. Si la clave primaria est compuesta por varios campos o propiedades, los nombres y tipos de campos de la clave primaria o propiedades en la clave primaria debe coincidir con las de la entidad. Relaciones mltiples de la entidad Hay cuatro tipo de relaciones: uno a uno, uno a muchos, muchos a uno, y muchos a muchos. Uno a uno: Cada entidad se relaciona con una sola instancia de otra entidad. Por ejemplo, al modelo fsico de almacn en el que cada almacn contiene un nico artilugio, StorageBin y Widget, deberan tener una relacin uno a uno. Las relaciones uno a uno utilizan anotaciones javax.persistence.OneToOne. Uno a muchos: Una entidad, puede estar relacionada con varias instancias de otras entidades. Una orden de venta (Order), por ejemplo, puede tener varias partidas (LineItem). En la aplicacin de la orden, La orden (Order) tendr una relacin uno a muchos con las partidas (LineItem). Las relaciones uno a muchos utilizan anotaciones javax.persistence.OneToMany en los campos o propiedades persistentes. Muchos a uno: Mltiples instancias de una entidad pueden estar relacionadas con una sola instancia de otra entidad. Esta multiplicidad es lo contrario a la relacin uno a muchos. En el ejemplo anterior, desde la perspectiva de la orden de venta (LineItem) la relacin con la Orden (Order) es de muchos a uno. Las relaciones muchos a uno utilizan anotaciones javax.persistence.ManyToOne en los campos o propiedades persistentes. Muchos a muchos: En este caso varias instancias de una entidad pueden relacionarse con mltiples instancias de otras entidades. Por ejemplo, cada curso de una universidad tiene muchos estudiantes, y cada estudiante puede tener varios cursos. Por lo tanto, en una solicitud de inscripcin, los cursos y los estudiantes tendran una relacin muchos a muchos. Este tipo de relacin utiliza anotaciones javax.persistence.ManyToMany en los campos o propiedades persistentes. Relaciones y borrado en cascada Existen entidades que utilizan relaciones con dependencias de relaciones de otra entidad. Por ejemplo, una lnea es parte de una orden, y si la orden es eliminada, entonces la lnea tambin debe eliminarse. Esto se llama borrado en cascada. Las relaciones de borrado en cascada se especifican utilizando cascade=REMOVE, elemento que viene en la especificacin de las relaciones @OneToOne y @OneToMany. Por ejemplo:
@OneToMany(cascade=REMOVE, mappedBy=

Page 3 - 02/06/2008 a las 13:21

MADEJA - JPA (Java Persistence API)

"customer") public Set<Order> getOrders() { return orders; }

Entity Manager Las entidades son gestionadas por el Entity Manager. ##ste se representa por instancias javax.persistence.EntityManager. A cada instancia de EntityManager se le asocia con un contexto de persistencia. Un contexto de persistencia define el mbito particular, bajo el cual se crean o se eliminan las instancias de la entidad. El contexto de persistencia Un contexto de persistencia es un conjunto de instancias que existen en un almacn de datos. El interfaz EntityManager define los mtodos que se utilizan para interactuar con el contexto de persistencia. Interfaz EntityManager La API entityManager crea y elimina instancias de entidades persistentes, busca entidades a partir de su clave primaria y permite ejecutar queries. Contenedor de Manager entity Con un contenedor de entidades, una instancia de un EntityManager de un contexto persistente se propaga automticamente por el contenedor de aplicacin a todos los componentes que utilizan la instancia del EntityManager en una sola transaccin Java (JTA). Para obtener una instancia de un EntityManager, basta con incluir la entidad dentro del componente de la aplicacin:
@ PersistenceContext EntityManager em;

Con entity managers por el contrario, el contexto de persistencia no se propaga a los componentes de la aplicacin y el ciclo de vida de las instancias del EntityManager se gestionan por la aplicacin. El administrador de EntityManagers de la aplicacin se usa cuando las aplicaciones necesitan acceso al contexto de persistencia cuando no se propaga con la transaccin JTA a travs de la instancia del EntityManager en una unidad de persistencia particular. En este caso, cada EntityManager crea un nuevo contexto de persistencia.El EntityManager, y sus contextos de persistencia asociados, se crean y se destruyen explcitamente por la aplicacin. Las aplicaciones crean instancias de EntityManager en esos casos mediante el mtodo createEntityManager de javax.persistence.EntityManagerFactory. Para obtener una instancia EntityManager, primero debe obtener una instancia EntityManagerFactory mediante la una anotacin de javax.persistence.PersistenceUnit:

Page 4 - 02/06/2008 a las 13:21

MADEJA - JPA (Java Persistence API)

@ PersistenceUnit EntityManagerFactory emf;

A continuacin, se obtiene un EntityManager de la instancia EntityManagerFactory:

EntityManager em = emf.createEntityManager ();

Se buscan las entidades utilizando el EntityManager. El mtodo EntityManager.find se utiliza para buscar entidades en el almacn de datos a partir de la clave primaria de la entidad.
@ PersistenceContext EntityManager em; public void enterOrder ( int custID, Order newOrder) ( Customer cliente = em.find (Customer.class, custID); cliente.getOrders (). add(newOrder); newOrder.setCustomer (cliente);

Gestin del ciclo de vida de una instancia Entity Las instancias de un entity pueden encontrarse en uno de estos cuatro estados: nuevo, gestionado, trasladado o eliminado. Una nueva instancia no tiene identidad de persistencia e incluso no tiene asociado su contexto de persistencia. Una instancia gestionada tiene una identidad persistente y est asociada con un contexto de persistencia. Una instancia trasladada tiene una identidad persistente y no se encuentra actualmente asociada con un contexto de persistencia. Una instancia eliminada tiene una identidad persistente y se encuentra asociada con un contexto persistente. Se preve el borrado del almacn de datos. Instancias de entidades persistentes Una nueva instancia se gestiona y se actualiza invocando al mtodo persist, o por una operacin de actualizacin en cascada llamada desde una entidad relacionada a travs de las anotaciones cascade=PERSIST o cascade=ALL. Esto significa que el dato de la entidad se almacena en base de datos cuando la transaccin asociada con la operacin persist se completa. Si la entidad ya se encuentra actualizada, la operacin persist se ignora, aunque la operacin persist se ejecutar en cascada con las entidades relacionadas. Si se llama al mtodo persist o al mtodo removed, se convierte en una instancia gestionada. Si la entidad se separa, el mtodo persist elevar una excepcin IllegalArgumentException, o la realizacin del commit fallar.
@PersistenceContext EntityManager em; ... public LineItem createLineItem(Order order, Product product,

int quantity) { LineItem li =

Page 5 - 02/06/2008 a las 13:21

MADEJA - JPA (Java Persistence API)

new LineItem(order, product, quantity); order.getLineItems().add(li); em.persist(li);

return li; }

La operacin persist se propaga a todas las entidades relacionadas con la entidad que tienen el elemento de cascada configurado con ALL o PERSIST
@OneToMany(cascade=ALL, mappedBy= "order") public Collection<LineItem> getLineItems() {

return lineItems; }

Eliminar instancias entity La instancias del entity managed se eliminan invocando al mtodo remove, o por un borrado en cascada invocado desde una entidad relacionada. Si el mtodo remove se invoca desde una entidad nueva, la operacin de borrado se ignora, aunque se borrarn en cascada las entidades relacionadas que tienen configurado su borrado en cascada mediante las anotaciones REMOVE o ALL. Si el mtodo remove se invoca en una entidad en estado trasladada se elevar una excepcin IllegalArgumentException, la transaccin de commit fallar. Si el mtodo remove se invoca desde una entidad ya eliminada, se ignorar. El dato representado por la entidad se eliminar de la base de datos cuando la transaccin se complete, o cuando se realice la operacin de descarga.

public void removeOrder( Integer orderId) {

try { Order order = em.find(Order.class, orderId); em.remove(order); }...

En este ejemplo, todos los LineItem, entidades asociadas con el objeto order, sern eliminados, ya que Order.getLineItems tiene configurado el cascade=ALL en la relacin de anotacin. Sincronizacin entre entidades y base de datos El estado de las entidades persistentes se sincroniza con la base de datos cuando la transaccin con la que la entidad est asociada realice el commit. Para forzar la sincronizacin de la entidad con la base da datos, se invoca el mtodo flush de la entidad. Si la entidad est relacionada con otra, y la relacin es en cascada, los datos de la entidad se sincronizan con la base da datos cuando se llama al mtodo flush. Si la entidad se borra, se llama al mtodo flush, el cual borrar la entidad de la base da datos. Creacin de consultas

Page 6 - 02/06/2008 a las 13:21

MADEJA - JPA (Java Persistence API)

Los mtodos EntityManager.createQuery y EntityManager.createNamedQuery se utilizan para realizar consultas usando lenguaje de consultas. El mtodo createQuery se utiliza para crear queries dinmicas; queries que se definen directamente en la aplicacin dentro de la lgica de negocio.

public List findWithName( String name) { return em.createQuery(

"SELECT c FROM Customer c WHERE c.name LIKE :custName") .setParameter( "custName", name) .setMaxResults(10) .getResultList(); }

El mtodo createNamedQuery se utiliza para crear queries estticas, queries que se definen utilizando el javax.persistence.NamedQuery . La anotacin @NamedQuery especifica el nombre de la consulta que se utilizar con el mtodo createNamedQuery. El elemento de consulta @ NamedQuery es la query.
@NamedQuery( name= "findAllCustomersWithName", query= "SELECT c FROM Customer c WHERE c.name LIKE :custName" )

En este ejemplo se utiliza la anotacin @NamedQuery definida anteriormente.

@PersistenceContext public EntityManager em; ... customers = em.createNamedQuery( "findAllCustomersWithName") .setParameter( "custName", "Smith") .getResultList();

Paso de parmetros en las queries Los parmetros de una consulta son predefinidos utilizando un signo de dos puntos (:). Los parmetros se especifican en una query mediante el mtodo javax.persistence.Query.setParameter (String nombre, Object valor). En el siguiente ejemplo, el parmetro del mtodo findWithName debe definirse como :custName especificado con el mtodo Query.setParameter.

public List findWithName( String name) {

Page 7 - 02/06/2008 a las 13:21

MADEJA - JPA (Java Persistence API)

return em.createQuery(

"SELECT c FROM Customer c WHERE c.name LIKE :custName") .setParameter( "custName", name) .getResultList(); }

El nombre de los parmetros es sensible a maysculas y minsculas, y puede ser utilizado por queries estticas y dinmicas. Posicionamiento de parmetros en las queries Dentro de las queries, los parmetros son predefinidos con un signo de interrogacin (?) seguido del nmero que representa la posicin del parmetro en la query. El mtodo Query.setParameter (Integer posicin, Object, value) se usa para fijar el valor del parmetro. En el siguiente ejemplo, el mtodo findWithName es reescribe para utilizando entrada de parmetros:

public List findWithName( String name) {

return em.createQuery( ##SELECT c FROM Customer c WHERE c.name LIKE ?1##) .setParameter(1, name) .getResultList(); }

La entrada de parmetros comienza enumerndose en la posicin 1. Los parmetros son sensibles a maysculas y minsculas, y pueden utilizarse tanto en queries dinmicas como estticas. Unidades de persistencia La unidad de persistencia define un conjunto de todas las entidades (clases) que son gestionadas por la instancia del EntityManager en una aplicacin. Este conjunto de clases de entidad representa los datos contenidos en un nico almacn de datos. Las unidades de persistencia se definen en el fichero de configuracin persistence.xml. El fichero JAR cuyo directorio META-INF contiene persistence.xml se llama raz de la unidad de persistencia. El mbito de la unidad de persistencia se determina por la raz de la unidad de persistencia. Cada unidad de persistencia debe ser identificada con un nombre nico en el mbito de la unidad de persistencia. Las unidades de persistencia pueden empaquetarse como parte de un WAR o un fichero EJB JAR, o pueden empaquetarse como un archivo JAR que pueda ser incluido en un fichero WAR o EAR. El fichero persistence.xml

Page 8 - 02/06/2008 a las 13:21

MADEJA - JPA (Java Persistence API)

El fichero persistence.xml define una o ms unidades de persistencia:

<persistence> <persistence-unit name= "OrderManagement"> <description>This unit manages orders and customers. It does not rely on any vendor-specific features and can therefore be deployed to any persistence provider. </description> <jta-data-source>jdbc/MyOrderDB</jta-data-source> <jar-file>MyOrderApp.jar</jar-file> <class>com.widgets.Order</class> <class>com.widgets.Customer</class> </persistence-unit> </persistence>

Este archivo define una unidad de persistencia llamada OrderManagement, la cual utiliza jdbc / MyOrderDB. El fichero JAR y los elementos de la clase especifican las clases de persistencia: clases de entidad, clases embebidas y superclases mapeadas. El elemento jar-file especifica los ficheros JAR en los que se encuentran las clases persistentes, mientras que el elemento class indica el nombre de esas clases. El elemento jta-data-source especifica el nombre global JNDI de la fuente de datos que utiliza el contenedor.

Ventajas e inconvenientes
Algunas de las ventajas del Open JPA consisten en que objetos transitorios pueden ser almacenados en forma permanente en una base de datos relacional. Adems, Open JPA pretende hacer ms eficaz el proceso de desarrollo, permitiendo a los desarrolladores enfocarse a resolver los problemas de negocios a los que se enfrentan, en lugar de ocupar su tiempo con el cdigo de infraestructura. El Java Persistence API se basa en las mejores ideas de tecnologas como la persistencia Hibernate, TopLink, y JDO. Los clientes ya no tienen que enfrentarse a las incompatibilidades de modelos no estndar. Adems, la Java Persistence API se puede usar tanto en entornos Java SE, como en Java EE. No obstante, tiene la desventaja de que la implementacin del proveedor se encuentra oculta a la aplicacin lo cual la hace menos flexible.

Requisitos e incompatibilidades
JPA ha sido definida como parte de la especificacin EJB 3.0 de Java EE 5, que supone una simplificacin sobre versiones anteriores, por lo que ya no requiere de un contenedor EJB ni un servidor de aplicaciones Java EE. Esto implica que no podr utilizarse en versiones anteriores de Java.

Interaccin con otros subsistemas o componentes

Muchos de los desarrolladores de Java que han utilizado objetos persistente que proporcionaban los marcos de cdigo abierto o DAO's en lugar de Entinty Beans e Enterprise Beans fue porque eran considerados demasiado pesados y complicados de utilizar. Adems, estos ltimos slo podan utilizarse en servidores de aplicaciones Java EE. Muchas de las caractersticas de la persistencia de otros frameworks se incorporaron a la Java

Page 9 - 02/06/2008 a las 13:21

MADEJA - JPA (Java Persistence API)

Persistence API, y proyectos como Hibernate y TopLink son ahora implementaciones de Java Persistence API (JPA).

Hibernate
La versin 3.2.0 Hibernate desarrolla la especificacin JPA, con lo que ahora es posible desarrollar una capa de acceso a datos compatible con los estndares de Java en hibernate, y desplegarla en cualquier servidor de aplicaciones que soporte las especificaciones JEE5.

TopLink
TopLink es una implementacin del EJB 3.0 JPA (Java Persistence API). Es una versin limitada del propietario del producto, por ejemplo, TopLink no proporciona sincronizacin de la cach entre la agrupacin de las aplicaciones, la poltica de validaciones y la cach de consultas.

EJB
JPA se defini como parte de la especificacin EJB 3.0 que es a su vez parte de la plataforma Java EE 5. No se utiliza un contenedor de EJB's, ni tampoco un servidor de aplicaciones Java EE con el fin de ejecutar aplicaciones que utilizan persistencia.

Modo de empleo (Aplicacin Web)

Los datos compartidos entre los componentes web y las invocaciones de persistencia de una aplicacin se mantienen normalmente en base de datos. Las aplicaciones web utilizan JPA para acceder a esas bases de datos relacionales. Para gestionar la interaccin de las entidades con la JPA, una aplicacin utiliza la interfaz EntityManager. Esta interfaz proporciona mtodos que realizan las funciones comunes de una base de datos, como consulta y actualizacin de la base de datos. El conjunto de entidades que pueden ser gestionadas por un Entity Manager se definen en una unidad de persistencia. ##sta supervisa todas las operaciones de persistencia en la aplicacin. La unidad de persistencia est configurada por un descriptor de archivo llamado persistence.xml. Este fichero tambin define el datasource, el tipo de transacciones utilizadas por la aplicacin, junto con otra informacin adicional. Estos ficheros se deben empaquetar en un .jar y aadirlos a la aplicacin. Para estudiar un caso de uso ms profundamente puede dirigirse a cualquier documento de una de las implementaciones de JPA como puede ser Hibernate .

Enlaces de inters
Java EE 5 Tutorial http://java.sun.com/javaee/5/docs/tutorial/doc/bnbpz.html Wikipedia http://en.wikipedia.org/wiki/Java_Persistence_API

Page 10 - 02/06/2008 a las 13:21

MADEJA - JPA (Java Persistence API)

Recomendaciones de Uso
1. Utilizar un framework de ORM simplifica enormemente la programacin de la lgica de persistencia. Se trata de una idea completamente madura que cada vez se vuelve ms popular. En aplicaciones donde la lgica de negocios trabaja contra un modelo de dominio completamente orientado a objetos la generacin de cdigo se reduce entre un 30% y un 40%. Adems el cdigo generado suele ser mucho ms sencillo y mantenible. 2. Es fundamental conocer bien cmo funcionan las tecnologas que se utilizan ya que dependiendo de cmo se realicen las cosas podr afectar directamente al rendimiento de la aplicacin. Esto no quiere decir que el uso de JPA sea desaconsejable, sino todo lo contrario, proporciona grandes beneficios como es la independencia de la base de datos, bajo acoplamiento entre negocio y persistencia, y un desarrollo rpido. Esto permite centrar los esfuerzos en optimizar las consultas que realmente lo merecen. 3. Para obtener el mejor rendimiento de JPA, es importante entender los parmetros de tunning includos en la implementacin de la JPA. La configuracin de la cach es un parmetro importante de tunning. Ajustar el pool de conexiones tambin es importante para obtener el mejor rendimiento de cualquier implementacin de JPA. 4. Si se utiliza JPA fuera del contenedor EJB, la cach y el pool de conexiones tambin juegan un papel importante en el rendimiento, aunque en este caso se configura el pool en el fichero persistence.xml. 5. Hay otros parmetros que pueden impactar en el rendimiento de JPA. Uno es el statement cache. ##ste se debe especificar explcitamente para algunas bases de datos como Oracle. Adems, la configuracin de la Java Virtual Machine (JVM) puede jugar un rol importante en el ajuste de la persistencia. Para tener informacin detallada del ajuste de la JVM, vase el Java Tuning White Paper. Para la ejecucin de la aplicacin de este tip, las opciones de la JVM las pondremos as:
-server -XX:+AggressiveHeap -Xmx2500m -Xms2500m -Xss128k -XX:+DisableExplicitGC

Aplicacin de ejemplo
Vase el documento de una de las implementaciones de JPA como puede ser Hibernate .

Page 11 - 02/06/2008 a las 13:21