37 Introduction to the Java Persistence API La Persistencia de Java API provee Javadevelopers de una instalacin de correlacin del objeto

/ instalacin de correlacin relacional para manejar datos relacionales en aplicaciones de Java. La Persistencia de Java consiste en cuatro reas: The Java Persistence API The query language The Java Persistence Criteria API Object/relational mapping metadata Los temas siguientes se dirigen aqu: Entities Entity Inheritance Managing Entities Querying Entities Database Schema Creation Further Information about Persistence 37.1 Entidades Una entidad es un objeto de la esfera de persistencia ligero. Tpicamente, una entidad representa una mesa en una base de datos relacional, y cada caso de la entidad equivale a una fila en esa mesa. El artefacto de programacin primario de una entidad es la clase de la entidad, aunque las entidades puedan usar clases del ayudante. El estado persistente de una entidad se representa a travs de campos persistentes o a travs de propiedades persistentes. Estos campos o propiedades usan anotaciones de correlacin del objeto / anotaciones de correlacin relacionales para trazar un mapa de las entidades y relaciones de la entidad a los datos relacionales en el almacn de datos subyacente. 37.1.1 Requisitos para clases de la entidad Una clase de la entidad debe seguir estos requisitos. La clase se debe anotar con el javax.persistence. Anotacin de la entidad. La clase debe tener un pblico o constructor protegido, sin argumentos. La clase puede tener otros constructores. La clase no se debe declarar final. Ningunos mtodos o variables del caso persistentes se deben declarar finales.

Si un caso de la entidad es pasado por el valor como un objeto separado, tal como a travs del interfaz comercial remoto de la alubia de una sesin, la clase debe poner en prctica el interfaz de Serializable. Entidades puede ampliar tanto entidad como clases de la nulidad, y las clases de la nulidad pueden ampliar clases de la entidad. variables del caso Persistentes se debe declarar privado, protegi, o privado del paquete y directamente slo puede ser tenido acceso por los mtodos de la clase de la entidad. Los clientes deben tener acceso al estado de la entidad a travs de accessor o mtodos comerciales. 37.1.2 Persistent Fields and Properties in Entity Classes Pueden tener acceso a travs del estado persistente de una entidad variables del caso de la entidad o propiedades. Los campos o las propiedades deben ser de los tipos de la lengua de Java siguientes: Java primitive types java.lang.String Other serializable types, including: Wrappers of Java primitive types 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[] Enumerated types Other entities and/or collections of entities Embeddable classes Las entidades pueden usar campos persistentes, propiedades persistentes o una combinacin de ambos. Si las anotaciones de correlacin se aplican a las

variables del caso de la entidad, la entidad usa campos persistentes. Si las anotaciones de correlacin se aplican a los mtodos del comprador de la entidad para propiedades del JavaBeans-estilo, la entidad usa propiedades persistentes. 37.1.2.1 Persistent Fields Si la clase de la entidad usa campos persistentes, las variables del caso de la clase de la entidad de accesos del tiempo de ejecucin de Persistencia directamente. Todos los campos no javax.persistence anotado. Transientor no marcado como Java transientwill persistirse al almacn de datos. Las anotaciones de correlacin del objeto / las anotaciones de correlacin relacionales se deben aplicar a las variables del caso. 37.1.2.2 Persistent Properties Si la entidad usa propiedades persistentes, la entidad debe seguir las convenciones del mtodo de componentes de JavaBeans. Las propiedades del JavaBeans-estilo usan a comprador y mtodos del setter que tpicamente se nombran por los nombres de variable del caso de la clase de la entidad. Para cada propiedad de la propiedad persistente del Tipo del tipo de la entidad, hay un mtodo del comprador getProperty y el mtodo del setter setProperty. Si la propiedad es un Booleano, puede usar es Propertyinstead de getProperty. Por ejemplo, si una entidad del Cliente usa propiedades persistentes y tiene firstName llamado de la variable de un caso privado, la clase define un getFirstNameand setFirstNamemethod para recuperar y poner el estado de la variable firstNameinstance. La firma del mtodo para propiedades persistentes valoradas del modo solo es as: Type getProperty() void setProperty(Type type) Las anotaciones de correlacin del objeto / las anotaciones de correlacin relacionales para propiedades persistentes se deben aplicar a los mtodos del comprador. La correlacin de anotaciones no se puede aplicar a campos o las propiedades anotaron @Transientor marcado pasajero. 37.1.2.3 Using Collections in Entity Fields and Properties

Los campos persistentes valorados a la coleccin y las propiedades deben usar los interfaces de coleccin de Java apoyados sin tener en cuenta si la entidad usa campos persistentes o propiedades. Los interfaces de coleccin siguientes se pueden usar: java.util.Collection java.util.Set java.util.List java.util.Map Si la clase de la entidad usa campos persistentes, el tipo en las firmas del mtodo precedentes debe ser uno de estos tipos de coleccin. Las variantes genricas de estos tipos de coleccin tambin se pueden usar. Por ejemplo, si tiene una propiedad persistente que contiene un juego de nmeros de telfonos, Customerentity tendra los mtodos siguientes: Set<PhoneNumber> getPhoneNumbers() { ... } void setPhoneNumbers(Set<PhoneNumber>) { ... } Si un campo o la propiedad de una entidad consisten en una coleccin de tipos bsicos o clases embeddable, use el javax.persistence. Anotacin de ElementCollection al campo o propiedad. Los dos atributos de @ElementCollectionare targetClassand esfuerzo. El targetClassattribute especifica el nombre de la clase de la clase bsica o embeddable y es opcional si el campo o la propiedad se definen usando medicamentos sin marca del lenguaje de programacin de Java. Fetchattribute opcional es usado para especificar si la coleccin se debera recuperar perezosamente o con impaciencia, usando el javax.persistence. FetchTypeconstants de cualquiera LAZYor IMPACIENTE, respectivamente. En ausencia, la coleccin se traer perezosamente. La entidad siguiente, Persona, tiene un campo persistente, apodos, que es una coleccin de Stringclasses que se ir con impaciencia. El targetClasselement no se requiere, porque usa medicamentos sin marca para definir el campo. @Entity public class Person { ... @ElementCollection(fetch=EAGER) protected Set<String> nickname = new HashSet();

... } Las colecciones de elementos de la entidad y relaciones pueden ser representadas por java.util. Colecciones del mapa. Un Mapconsists de una llave y un valor. Usando Mapelements o relaciones, las reglas siguientes se aplican. El El Mapkey o valor puede ser un tipo del lenguaje de programacin de Java bsico, una clase embeddable o una entidad. Cuando Mapvalue sea una clase embeddable o tipo bsico, use el @ElementCollectionannotation. Cuando Mapvalue sea una entidad, use el @OneToManyor @ManyToManyannotation. Uso Maptype en slo un lado de una relacin bidireccional. Si el tipo clave de Mapis un lenguaje de programacin de Java tipo bsico, use la anotacin javax.persistence. MapKeyColumnto ponen la correlacin de la columna para la llave. En ausencia, el nameattribute de @MapKeyColumnis de la forma RELATIONSHIP-FIELD/PROPERTY-NAME_KEY. Por ejemplo, si el nombre de campo de relacin que se refiere es la imagen, la falta nameattribute es IMAGE_KEY. Si el tipo clave de Mapis una entidad, use el javax.persistence. Anotacin de MapKeyJoinColumn. Si columnas mltiples son necesarias para poner la correlacin, use la anotacin javax.persistence. MapKeyJoinColumnsto incluyen anotaciones @MapKeyJoinColumn mltiples. Si ningn presente de @MapKeyJoinColumnis, el ttulo de la columna de correlacin es por el juego de la falta a RELATIONSHIP-FIELD/PROPERTY-NAME_KEY. Por ejemplo, si el nombre de campo de relacin es el empleado, la falta nameattribute es EMPLOYEE_KEY. Si el lenguaje de programacin de Java los tipos genricos no se usan en el campo de relacin o propiedad, la clase clave se debe explcitamente poner usando el javax.persistence. MapKeyClassannotation. Si Mapkey es la clave primaria o un campo persistente o la propiedad de la entidad que es Mapvalue, use el javax.persistence. MapKeyannotation. El @MapKeyClassand @MapKeyannotations no se puede usar en el mismo campo o propiedad. Si Mapvalue es un lenguaje de programacin de Java tipo bsico o una clase embeddable, trazarn un mapa de ello como una mesa de coleccin en la base

de datos subyacente. Si los tipos genricos no se usan, el @ElementCollectionannotation's targetClassattribute se debe poner al tipo de Mapvalue. Si Mapvalue es una entidad y la parte de un many-many o relacin unidireccional one-many, trazarn un mapa de ello como una mesa de la juntura en la base de datos subyacente. Una relacin one-many unidireccional que usa Mapmay tambin trazarse un mapa usando el @JoinColumnannotation. Si la entidad es la parte de una relacin bidireccional one-to-many/many-toone, trazarn un mapa de ello en la mesa de la entidad que representa el valor del Mapa. Si los tipos genricos no se usan, el targetEntityattribute del @OneToManyand @ManyToMany anotaciones se debe poner al tipo de Mapvalue.

37.1.2.4 Validating Persistent Fields and Properties La Java API para la Validacin de JavaBeans (Validacin de la Alubia) proporciona un mecanismo a validar datos de aplicacin. La Validacin de la alubia se integra en la Java los contenedores de EE, permitiendo la misma lgica de validacin usarse en cualquiera de las gradas de unas coacciones de Validacin de la Alubia de la aplicacin de empresa se pueden aplicar a clases de la entidad persistentes, embeddable clases y superclases trazadas un mapa. En ausencia, el abastecedor de Persistencia realizar automticamente la validacin en campos persistentes entitieswith o propiedades anotadas con coacciones de Validacin de la Alubia inmediatamente despus de PrePersist, PreUpdate y acontecimientos de PreRemovelifecycle. Las coacciones de Validacin de la alubia son anotaciones aplicadas a los campos o las propiedades de las clases del lenguaje de programacin de Java. Alubia Validationprovides un juego de coacciones as como un API para definir customconstraints. Las coacciones de encargo pueden ser combinaciones especficas de las coacciones de la falta, ornew coacciones que no usan las coacciones de la falta. Cada coaccin tiene que ver con al menos una clase validator que valida el valor del campo reprimido o propiedad. Los reveladores

de coaccin de encargo tambin deben proporcionar una clase validator a la coaccin. Las coacciones de Validacin de la alubia se aplican a los campos persistentes o las propiedades de las clases persistentes. Aadiendo coacciones de Validacin de la Alubia, use la misma estrategia de acceso como la clase persistente. Es decir si la clase persistente usa el acceso de campaa, aplique las anotaciones de coaccin de Validacin de la Alubia a los campos de la clase. Si la clase usa el acceso de la propiedad, aplique las coacciones en los mtodos del comprador. Mesa las coacciones incorporadas de la Validacin de Alubia 211lists, definidas en el javax.validation.constraintspackage. Todas las coacciones incorporadas puestas en una lista en Mesa 211have una anotacin correspondiente, ConstraintName. Lista, para agrupar coacciones mltiples del mismo tipo en el mismo campo o propiedad. Por ejemplo, el campo persistente siguiente tiene dos @Patternconstraints: @Pattern.List({ @Pattern(regexp="..."), @Pattern(regexp="...") }) The following entity class, Contact, has Bean Validation constraints applied to its persistent fields. @Entity public class Contact implements Serializable { ... @Id @GeneratedValue(strategy = GenerationType.AUTO) private Long id; @NotNull protected String firstName; @NotNull protected String lastName; @Pattern(regexp="[a-z0-9!#$%&'*+/=?^_`{|}~-]+(?:\\." +"[a-z0-9!#$%&'*+/=?^_`{|}~-]+)*@" +"(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\\.)+[a-z0-9](?:[a-z0-9-]*[a-z0-9])?", message="{invalid.email}") protected String email;

@Pattern(regexp="^\\(?(\\d{3})\\)?[- ]?(\\d{3})[- ]?(\\d{4})$", message="{invalid.phonenumber}") protected String mobilePhone; @Pattern(regexp="^\\(?(\\d{3})\\)?[- ]?(\\d{3})[- ]?(\\d{4})$", message="{invalid.phonenumber}") protected String homePhone; @Temporal(javax.persistence.TemporalType.DATE) @Past protected Date birthday; ... } El @NotNullannotation en el firstNameand lastNamefields especifica que aquellos campos se requieren ahora. Si nuevo Contactinstance se crea donde firstNameor lastNamehave no sido inicializado, la Validacin de la Alubia lanzar un error de validacin. Del mismo modo, si un caso antes creado de Contacthas sido modificado de modo que firstNameor lastNameare nulo, un error de validacin se lanzar. El emailfield tiene un @Patternconstraint aplicado a ello, con una expresin regular complicada que corresponde a la mayor parte de direcciones de correo electrnico vlidas. Si el valor de correo electrnico no corresponde a esta expresin regular, un error de validacin se lanzar. Los homePhoneand mobilePhonefields tienen mismo @Patternconstraints. La expresin regular corresponde a 10 nmeros de telfono del dgito en los Estados Unidos y Canad de la forma (xxx) xxx-xxxx. El birthdayfield se anota con el @Pastconstraint, que asegura que el valor de birthdaymust est en el pasado . 37.1.3 Primary Keys in Entities Cada entidad tiene un identificador del objeto nico. Una entidad del cliente, por ejemplo, podra ser identificada por un nmero del cliente. El identificador nico o clave primaria, permite a clientes localizar un caso de la entidad particular. Cada entidad debe tener una clave primaria. Una entidad puede tener un simple o una clave primaria compuesta. Las claves primarias simples usan el javax.persistence. Idannotation para denotar la propiedad de la clave primaria o campo.

Las claves primarias compuestas se usan cuando una clave primaria consiste en ms de un atributo, que equivale a un juego de propiedades persistentes solas o campos. Las claves primarias compuestas se deben definir en una clase de la clave primaria. Las claves primarias compuestas se denotan usando el javax.persistence. EmbeddedIdand javax.persistence. IdClassannotations. La clave primaria, o la propiedad o el campo de una clave primaria compuesta, debe ser uno de los tipos de la lengua de Java siguientes: Java primitive types Java primitive wrapper types java.lang.String java.util.Date(the temporal type should be DATE) java.sql.Date java.math.BigDecimal java.math.BigInteger Los tipos del punto flotante nunca se deberan usar en claves primarias. Si usa una clave primaria generada, los tipos slo integrales sern porttiles. Una clase de la clave primaria debe cumplir con estos requisitos. El modificador de control de acceso de la clase debe ser pblico. Las propiedades de la clase de la clave primaria debe ser publicor protectedif el acceso basado en la propiedad se usa. La clase debe tener un constructor de la falta pblico. La clase debe poner en prctica el hashCode () e iguala (Objete otro) los mtodos. La clase debe ser serializable. Una clave primaria compuesta se debe representar y trazarse un mapa a campos mltiples o las propiedades de la clase de la entidad o se debe representar y trazarse un mapa como una clase embeddable. Si trazan un mapa de la clase a campos mltiples el orproperties de la clase de la entidad, los nombres y los tipos de los campos de la clave primaria o propiedades en la clase de la clave primaria debe corresponder a aquellos de la clase de la entidad. La clase de la clave primaria siguiente es una llave compuesta, y los orderIdand itemIdfields juntos nicamente identifican una entidad: public final class LineItemKey implements Serializable {

public Integer orderId; public int itemId; public LineItemKey() {} public LineItemKey(Integer orderId, int itemId) { this.orderId = orderId; this.itemId = itemId; } public boolean equals(Object otherOb) { if (this == otherOb) { return true; } if (!(otherOb instanceof LineItemKey)) { return false; } LineItemKey other = (LineItemKey) otherOb; return ( (orderId==null?other.orderId==null:orderId.equals (other.orderId) ) && (itemId == other.itemId) ); } public int hashCode() { return ( (orderId==null?0:orderId.hashCode()) ^ ((int) itemId) ); } public String toString() { return "" + orderId + "-" + itemId; } } 37.1.4 Multiplicity in Entity Relationships

La multiplicidad es de los tipos siguientes: de uno a uno, one-many, many-one, y many-many: de uno a Uno: Cada caso de la entidad isrelated a un caso solo de otra entidad. Por ejemplo, para modelar un depsito fsico en el cual cada recipiente de almacenaje contiene un artefacto solo, StorageBinand Widgetwould tienen una relacin de uno a uno. Las relaciones de uno a uno usan el javax.persistence. OneToOneannotation en la propiedad persistente correspondiente o campo. One-many: Un caso de la entidad se puede relacionar con casos mltiples de las otras entidades. Un pedido de ventas, por ejemplo, puede tener artculos de la lnea mltiples. En la aplicacin de pedido, Orderwould tienen una relacin one-many con LineItem. Las relaciones de One-many usan el javax.persistence. OneToManyannotation en la propiedad persistente correspondiente o campo. Many-one: Casos mltiples de una entidad se pueden relacionar con un caso solo de la otra entidad. Esta multiplicidad es la parte de enfrente de una relacin one-many. En el ejemplo slo mencionado, la relacin a Orderfrom la perspectiva de LineItemis many-one. Las relaciones de Many-one usan el javax.persistence. ManyToOneannotation en la propiedad persistente correspondiente o campo. Many-many: Los casos de la entidad se pueden relacionar con casos mltiples el uno del otro. Por ejemplo, cada curso del colegio tiene muchos estudiantes, y cada estudiante puede tomar varios cursos. Por lo tanto, en una aplicacin de inscripcin, Courseand Studentwould tienen una relacin many-many. Las relaciones de Many-many usan el javax.persistence. ManyToManyannotation en la propiedad persistente correspondiente o campo. 37.1.5 Direction in Entity Relationships La direccin de una relacin puede ser bidireccional o unidireccional. Una relacin bidireccional tiene tanto un lado de posesin como un lado inverso. Una relacin unidireccional tiene slo un lado de posesin. El lado de posesin de una relacin determina cmo el tiempo de ejecucin de Persistencia hace actualizaciones de la relacin en la base de datos. 37.1.5.1 Bidirectional Relationships

En un bidirectionalrelationship, cada entidad tiene un campo de relacin o propiedad que se refiere a la otra entidad. A travs del campo de relacin o propiedad, el cdigo de la clase de la entidad puede tener acceso a su objeto relacionado. Si una entidad tiene un campo relacionado, se dice que la entidad "sabe" sobre su objeto relacionado. Por ejemplo, si Orderknows lo que LineIteminstances tiene y si LineItemknows a qu Orderit pertenece, tienen una relacin bidireccional. Las relaciones bidireccionales deben seguir estas reglas. El lado inverso de una relacin bidireccional se debe referir a su lado de posesin usando el mappedByelement del @OneToOne, @OneToMany, o anotacin @ManyToMany. El mappedByelement designa la propiedad o campo en la entidad que es el dueo de la relacin. El lado de mucho de relaciones bidireccionales many-one no debe definir el mappedByelement. Muchos colindan siempre es el lado de posesin de la relacin. Para relaciones bidireccionales de uno a uno, el lado de posesin equivale al lado que contiene la clave fornea correspondiente. Para relaciones bidireccionales many-many, el uno o el otro lado puede ser el lado de posesin

37.1.5.2 Unidirectional Relationships En un unidirectionalrelationship, slo una entidad tiene un campo de relacin o propiedad que se refiere al otro. Por ejemplo, LineItemwould tienen un campo de relacin que identifica el producto, pero Productwould no tienen un campo de relacin o propiedad para LineItem. En otras palabras, LineItemknows sobre el producto, pero Productdoesn't saben que LineIteminstances mandan a ello. 37.1.5.3 Queries and Relationship Direction La lengua de la pregunta de Persistencia de Java y los Criterios preguntas de API a menudo navegan a travs de relaciones. La direccin de una relacin determina si una pregunta puede navegar de una entidad al otro. Por ejemplo, una pregunta puede navegar de LineItemto que Productbut no puede navegar

en direccin contraria. Para LineItem Orderand, una pregunta podra navegar en ambas direcciones porque estas dos entidades tienen una relacin bidireccional. 37.1.5.4 Cascade Operations and Relationships Las entidades que usan relaciones a menudo tienen dependencias de la existencia de la otra entidad en la relacin. Por ejemplo, un artculo de la lnea es la parte de un pedido; si el pedido se suprime, el artculo de la lnea tambin se debera suprimir. Esto se llama una cascada suprimen la relacin. El javax.persistence. El tipo de CascadeTypeenumerated define las operaciones de cascada que se aplican en el cascadeelement de las anotaciones de relacin. Mesa 371lists las operaciones de cascada para entidades.

quitado se considera un hurfano. Si juego de orphanRemovalis al verdadero, la entidad del artculo de la lnea se suprimir cuando el artculo de la lnea se quite del pedido. The orphanRemovalattribute in @OneToManyand @oneToOnetakes a Boolean value and is by default false. The following example will cascade the remove operation to the orphaned order entity when the customerentity is deleted: @OneToMany(mappedBy="customer", orphanRemoval="true") public List<Order> getOrders() { ... } 37.1.6 Embeddable Classes in Entities Las clases de Embeddable son usadas para representar el estado de una entidad, pero no tienen una identidad persistente de su propio, a diferencia de clases de la entidad. Los casos de una clase embeddable comparten la identidad de la entidad que la posee. Las clases de Embeddable slo existen como el estado de otra entidad. Una entidad puede haber valorado del modo solo o haber valorado a la coleccin atributos de la clase embeddable. Embeddable classes have the same rules as entity classes but are annotated with the javax.persistence.Embeddableannotation instead of @Entity. The following embeddable class, ZipCode, has the fields zipand plusFour: @Embeddable public class ZipCode { String zip; String plusFour; ... } This embeddable class is used by the Addressentity: @Entity public class Address { @Id protected long id String street1; String street2; String city; String province; @Embedded

Cascade delete relationships are specified using the cascade=REMOVEelement specification for @OneToOneand @OneToManyrelationships. For example: @OneToMany(cascade=REMOVE, mappedBy="customer") public Set<Order> getOrders() { return orders; } 37.1.5.5 Orphan Removal in Relationships Cuando una entidad objetivo en la relacin de uno a uno u one-many se quita de la relacin, a menudo es deseable caer en cascada la operacin quitar a la entidad objetivo. Tales entidades objetivo se consideran "hurfanos", y el orphanRemovalattribute puede beused para especificar que las entidades quedadas hurfanas shouldbe quitaron. Por ejemplo, si un pedido tiene muchos artculos de la lnea y uno de ellos se quita del pedido, el artculo de la lnea

ZipCode zipCode; String country; ... } Las entidades que poseen clases embeddable como la parte de su estado persistente pueden anotar el campo o propiedad con el javax.persistence. No se requiere que Embeddedannotation pero hagan as. Las clases de Embeddable pueden usar otras clases embeddable para representar su estado. Tambin pueden contener colecciones ofbasic tipos del lenguaje de programacin de Java u otras clases embeddable. Las clases de Embeddable tambin pueden contener relaciones a otras entidades o colecciones de entidades. Si la clase embeddable tiene tal relacin, la relacin es de la entidad objetivo o la coleccin de entidades a la entidad que posee la clase embeddable 37.2 Entity Inheritance Las entidades apoyan herencia de la clase, asociaciones polimorfas y preguntas polimorfas. Las clases de la entidad pueden ampliar clases de la nulidad, y nonentityclasses puede ampliar clases de la entidad. Las clases de la entidad pueden ser tanto el extracto como el hormign. La aplicacin del ejemplo de la lista demuestra la herencia de la entidad, como descrito en la Herencia de la Entidad en la Aplicacin de la lista. 37.2.1 Abstract Entities Una clase abstracta se puede declarar una entidad decorando la clase con @Entity. Las entidades abstractas parecen a entidades concretas, pero no pueden ser instantiated. Las entidades abstractas se pueden preguntar justo como entidades concretas. Si una entidad abstracta es el objetivo de una pregunta, la pregunta acta sobre todas las subclases concretas de la entidad abstracta: @Entity public abstract class Employee { @Id protected Integer employeeId; ... }

@Entity public class FullTimeEmployee extends Employee { protected Integer salary; ... } @Entity public class PartTimeEmployee extends Employee { protected Float hourlyWage; } 37.2.2 Mapped Superclasses Las entidades pueden heredar de superclases que contienen el estado persistente y la informacin de correlacin, pero no son entidades. Es decir la superclase no se decora con el @Entityannotation y no es trazada un mapa como una entidad por el abastecedor de Persistencia de Java. Estas superclases el ms a menudo se usan cuando tiene el estado y la informacin de correlacin comn para clases de la entidad mltiples. Mapped superclasses are specified by decorating the class with the annotation javax.persistence.MappedSuperclass: @MappedSuperclass public class Employee { @Id protected Integer employeeId; ... } @Entity public class FullTimeEmployee extends Employee { protected Integer salary; ... } @Entity public class PartTimeEmployee extends Employee { protected Float hourlyWage; ... } Las superclases trazadas un mapa no se pueden preguntar y no se pueden usar en operaciones de la Pregunta de EntityManageror. Debe usar subclases de la

entidad de la superclase trazada un mapa en EntityManager o Queryoperations. Las superclases trazadas un mapa no pueden ser objetivos de relaciones de la entidad. Las superclases trazadas un mapa pueden beabstract u hormign. Las superclases trazadas un mapa no tienen mesa correspondiente en datastore subyacente. Las entidades que heredan de superclassdefine trazado un mapa las correlaciones de la mesa. Por ejemplo, en la muestra del cdigo precedente, las mesas subyacentes seran FULLTIMEEMPLOYEEand PARTTIMEEMPLOYEE, pero no hay ningn EMPLOYEEtable. 37.2.3 Non-Entity Superclasses Las entidades pueden tener non-entitysuperclasses, y estas superclases pueden ser el extracto o el hormign. El estado de superclases de la nulidad es no persistente, y cualquier estado heredado de la superclase de la nulidad por la clase anentity es no persistente. Las superclases de la nulidad no se pueden usar en EntityManageror Queryoperations. Cualquier correlacin o anotaciones de relacin en superclases de la nulidad se ignoran. 37.2.4 Entity Inheritance Mapping Strategies Puede configurar cmo el abastecedor de Persistencia de Java traza un mapa de entidades heredadas a datastore subyacente decorando la clase de la raz de la jerarqua con la anotacin javax.persistence. Herencia. Las estrategias de correlacin siguientes son usadas para trazar un mapa de los datos de la entidad a la base de datos subyacente: Una mesa sola por jerarqua de la clase Una mesa por clase de la entidad concreta Una estrategia de la "juntura", por lo cual trazan un mapa de campos o las propiedades que son especficas para una subclase a una mesa diferente que las propiedades fieldsor que son comunes a la clase paternal La estrategia se configura poniendo el strategyelement de @Inheritanceto una de las opciones definidas en el javax.persistence. Tipo de InheritanceTypeenumerated: public enum InheritanceType { SINGLE_TABLE, JOINED, TABLE_PER_CLASS

}; The default strategy, InheritanceType.SINGLE_TABLE, is used if the @Inheritance annotation is not specified on the root class of the entity hierarchy. 37.2.4.1 The Single Table per Class Hierarchy Strategy Con esta estrategia, que equivale a la falta InheritanceType. SINGLE_TABLE, trazan un mapa de todas las clases en la jerarqua a una mesa sola en la base de datos. Esta mesa tiene un discriminador columncontaining un valor que identifica la subclase a la cual el caso representado por la fila pertenece. La columna del discriminador, cuyos elementos se muestran en la Tabla 37-2, se puede especificar usando el javax.persistence. DiscriminatorColumnannotation en la raz de la jerarqua de la clase de la entidad.

The javax.persistence.DiscriminatorTypeenumerated type is used to set the type of the discriminator column in the database by setting the discriminatorTypeelement of @DiscriminatorColumnto one of the defined types. DiscriminatorTypeis defined as: public enum DiscriminatorType { STRING, CHAR, INTEGER };

If @DiscriminatorColumnis not specified on the root of the entity hierarchy and a discriminator column is required, the Persistence provider assumes a default column name of DTYPEand column type of DiscriminatorType.STRING. The javax.persistence.DiscriminatorValueannotation may be used to set the value entered into the discriminator column for each entity in a class hierarchy. You may decorate only concreteentity classes with @DiscriminatorValue. If @DiscriminatorValueis not specified on an entity in a class hierarchy that uses a discriminator column, the Persistence provider will provide a default, implementation-specific value. If the discriminatorTypeelement of @DiscriminatorColumnis DiscriminatorType.STRING, the default value is the name of the entity. This strategy provides good support for polymorphic relationships between entities and queries that cover the entire entity class hierarchy. However, this strategy requires the columns that contain the state of subclasses to be nullable. 37.2.4.2 The Table per Concrete Class Strategy En esta estrategia, que equivale a InheritanceType. TABLE_PER_CLASS, trazan un mapa de cada clase concreta a una mesa separada en la base de datos. Trazan un mapa de todos los campos o las propiedades en la clase, incluso campos heredados o propiedades, a columnas en la mesa de la clase en la base de datos. Esta estrategia proporciona el apoyo pobre a relaciones polimorfas y por lo general requiere SQL UNIONqueries o preguntas de SQL separadas para cada subclase para preguntas que cubren la jerarqua de la clase de la entidad entera El apoyo a esta estrategia es opcional y no puede ser apoyado por toda la Persistencia de Java abastecedores de API. La falta Persistencia de Java abastecedor de API en el Servidor de GlassFish no apoya esta estrategia. 37.2.4.3 The Joined Subclass Strategy En esta estrategia, que equivale a InheritanceType. AFILIADO, la raz de la jerarqua de la clase es representada por una mesa sola, y cada subclase tiene una mesa separada que contiene slo aquellos campos especficos para esa subclase. Es decir la mesa de la subclase no contiene columnas para campos heredados o propiedades. La mesa de la subclase tambin tiene una columna o las columnas que representan su clave primaria, que es una clave fornea a la clave primaria de la mesa de la superclase.

Esta estrategia proporciona el apoyo bueno a relaciones polimorfas, pero requiere que una o varias operaciones de la juntura se realicen subclases de la entidad wheninstantiating. Esto puede causar el rendimiento pobre para jerarquas de la clase extensas. Del mismo modo, las preguntas que cubren la jerarqua de la clase entera requieren operaciones de la juntura entre las mesas de la subclase, causando el rendimiento disminuido. Un poco de Persistencia de Java abastecedores de API, incluso el abastecedor de la falta en GlassFish Servidor, requiera una columna del discriminador que equivale a la entidad de la raz usando la estrategia de la subclase afiliada. Si no usa la creacin de la mesa automtica en su aplicacin, asegrese que la tabla de base de datos se establece correctamente para las faltas de la columna del discriminador, o use el @DiscriminatorColumnannotation para corresponder a su esquema de la base de datos. Para la informacin sobre columnas del discriminador, ver La Mesa Sola por Estrategia de la Jerarqua de la Clase 37.3 Managing Entities Las entidades son manejadas por el gerente de la entidad, que es representado por javax.persistence. EntityManagerinstances. Cada EntityManagerinstance tiene que ver con un contexto de persistencia: un juego de casos de la entidad manejados que existen en un almacn de datos particular. Un contexto de persistencia define el alcance bajo el cual los casos de la entidad particulares se crean, persistieron y quitaron. EntityManagerinterface define los mtodos que son usados para relacionarse con el contexto de persistencia. 37.3.1 The EntityManager Interface EntityManagerAPI crea y quita casos de la entidad persistentes, encuentra entidades por la clave primaria de la entidad y permite que preguntas se dirijan en entidades. 37.3.1.1 Container-Managed Entity Managers Con un gerente de la entidad manejado por el contenedor, el contexto de persistencia de EntityManagerinstance es automticamente propagado por el contenedor a todos los componentes de aplicacin que usan EntityManagerinstance dentro de una transaccin de Java Transaction API (JTA) sola.

Las transacciones de JTA por lo general implican llamadas a travs de componentes de aplicacin. Para completar una transaccin JTA, estos componentes por lo general necesitan el acceso a un contexto de persistencia solo. Esto ocurre cuando EntityManageris inyect en los componentes de aplicacin por medio del javax.persistence. PersistenceContextannotation. El contexto de persistencia automticamente se propaga con la transaccin JTA corriente, y EntityManagerreferences de que trazan un mapa a la misma unidad de persistencia proporciona el acceso al contexto de persistencia dentro de esa transaccin. Propagando automticamente el contexto de persistencia, los componentes de aplicacin no tienen que pasar referencias a EntityManagerinstances el uno al otro a fin de hacer cambios dentro de una transaccin sola. La Java contenedor de EE maneja el lifecycle de gerentes de la entidad manejados por el contenedor. To obtain an EntityManagerinstance, inject the entity manager into the application component: @PersistenceContext EntityManager em; 37.3.1.2 Application-Managed Entity Managers Con un gerente de la entidad manejado por la aplicacin, por otra parte, el contexto de persistencia no se propaga a componentes de aplicacin, y el lifecycle de EntityManagerinstances es manejado por la aplicacin. Los gerentes de la entidad manejados por la aplicacin se usan cuando las aplicaciones tienen que tener acceso a un contexto de persistencia que no se propaga con la transaccin JTA a travs de EntityManagerinstances en una unidad de persistencia particular. En este caso, cada EntityManagercreates un contexto de persistencia nuevo, aislado. EntityManagerand su contexto de persistencia asociado se crean y destruidos explcitamente por la aplicacin. Tambin se usan cuando la inyeccin directa de EntityManagerinstances no se puede hacer porque EntityManagerinstances no estn seguros del hilo. EntityManagerFactoryinstances estn seguros del hilo. Las aplicaciones crean EntityManagerinstances en este caso usando el createEntityManagermethod de javax.persistence. EntityManagerFactory.

Para obtener EntityManagerinstance, primero debe obtener un caso de EntityManagerFactory inyectndolo en el componente de aplicacin por medio del javax.persistence. PersistenceUnitannotation: @PersistenceUnit EntityManagerFactory emf; Then obtain an EntityManagerfrom the EntityManagerFactoryinstance: EntityManager em = emf.createEntityManager(); Application-managed entity managers don't automatically propagate the JTA transaction context. Such applications need to manually gain access to the JTA transaction manager and add transaction demarcation information when performing entity operations. The javax.transaction.UserTransactioninterface defines methods to begin, commit, and roll back transactions. Inject an instance of UserTransactionby creating an instance variable annotated with @Resource: @Resource UserTransaction utx; To begin a transaction, call the UserTransaction.beginmethod. When all the entity operations are complete, call the UserTransaction.commitmethod to commit the transaction. The UserTransaction.rollbackmethod is used to roll back the current transaction. The following example shows how to manage transactions in an application that uses an application-managed entity manager: @PersistenceUnit EntityManagerFactory emf; EntityManager em; @Resource UserTransaction utx; ... em = emf.createEntityManager(); try { utx.begin(); em.persist(SomeEntity); em.merge(AnotherEntity); em.remove(ThirdEntity); utx.commit(); } catch (Exception e) {

utx.rollback(); } 37.3.1.3 Finding Entities Using the EntityManager The EntityManager.findmethod is used to look up entities in the data store by the entity's primary key: @PersistenceContext EntityManager em; public void enterOrder(int custID, Order newOrder) { Customer cust = em.find(Customer.class, custID); cust.getOrders().add(newOrder); newOrder.setCustomer(cust); } 37.3.1.4 Managing an Entity Instance's Lifecycle You manage entity instances by invoking operations on the entity by means of an EntityManagerinstance. Entity instances are in one of four states: new, managed, detached, or removed. New entity instances have no persistent identity and are not yet associated with a persistence context. Managed entity instances have a persistent identity and are associated with a persistence context. Detached entity instances have a persistent identity and are not currently associated with a persistence context. Removed entity instances have a persistent identity, are associated with a persistent context, and are scheduled for removal from the data store. 37.3.1.5 Persisting Entity Instances New entity instances become managed and persistent either by invoking the persistmethod or by a cascading persistoperation invoked from related entities that have the cascade=PERSISTor cascade=ALLelements set in the relationship annotation. This means that the entity's data is stored to the database when the transaction associated with the persistoperation is completed. If the entity is already managed, the persist operation is ignored, although the persistoperation will cascade to related entities that have the cascadeelement set to PERSISTor ALLin the relationship annotation. If persistis called on a removed entity instance, the entity becomes managed. If the entity is detached, either persistwill throw an IllegalArgumentException, or the transaction commit will fail.

@PersistenceContext EntityManager em; ... public LineItem createLineItem(Order order, Product product, int quantity) { LineItem li = new LineItem(order, product, quantity); order.getLineItems().add(li); em.persist(li); return li; } The persistoperation is propagated to all entities related to the calling entity that have the cascadeelement set to ALLor PERSISTin the relationship annotation: @OneToMany(cascade=ALL, mappedBy="order") public Collection<LineItem> getLineItems() { return lineItems; } 37.3.1.6 Removing Entity Instances Managed entity instances are removed by invoking the removemethod or by a cascading removeoperation invoked from related entities that have the cascade=REMOVEor cascade=ALLelements set in the relationship annotation. If the removemethod is invoked on a new entity, the removeoperation is ignored, although removewill cascade to related entities that have the cascadeelement set to REMOVEor ALLin the relationship annotation. If removeis invoked on a detached entity, either removewill throw an IllegalArgumentException, or the transaction commit will fail. If invoked on an already removed entity, removewill be ignored. The entity's data will be removed from the data store when the transaction is completed or as a result of the flushoperation. public void removeOrder(Integer orderId) { try { Order order = em.find(Order.class, orderId); em.remove(order); }... In this example, all LineItementities associatedwith the order are also removed, as Order.getLineItemshas cascade=ALLset in the relationship annotation.

37.3.1.7 Synchronizing Entity Data to the Database The state of persistent entities is synchronized to the database when the transaction with which the entity is associated commits. If a managed entity is in a bidirectional relationship with another managed entity, the data will be persisted, based on the owning side of the relationship. To force synchronization of the managed entity to the data store, invoke the flush method of the EntityManagerinstance. If the entity is related to another entity and the relationship annotation has the cascadeelement set to PERSISTor ALL, the related entity's data will be synchronized with the data store when flushis called. If the entity is removed, calling flushwill remove the entity data from the data store. 37.3.2 Persistence Units A persistence unit defines a set of all entity classes that are managed by EntityManagerinstances in an application. This set of entity classes represents the data contained within a single data store. Persistence units are defined by the persistence.xmlconfiguration file. The following is an example persistence.xmlfile: <persistence> <persistence-unit name="OrderManagement"> <description>This unit manages orders and customers. It does not rely on any vendor-specific features and cantherefore 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> This file defines a persistence unit named OrderManagement, which uses a JTAaware data source: jdbc/MyOrderDB. The jar-fileand classelements specify managed persistence classes: entity classes, embeddable classes, and mapped superclasses. The jar-fileelement specifies JAR files that are visible to the packaged persistence unit that contain managed persistence classes, whereas the classelement explicitly names managed persistence classes.

The jta-data-source(for JTA-aware data sources) and non-jta-data-source(for non-JTA-aware data sources) elements specify the global JNDI name of the data source to be used by the container. The JAR file or directory whose META-INFdirectory contains persistence.xmlis called the root of the persistence unit. The scope of the persistence unit is determined by the persistence unit's root. Each persistence unitmust be identified with a name that is unique to the persistence unit's scope. Persistent units can be packaged as part ofa WAR or EJB JAR file or can be packaged as a JAR file that can then be included in an WAR or EAR file. If you package the persistent unit as a set of classes in an EJB JAR file, persistence.xmlshould be put in the EJB JAR's META-INFdirectory. If you package the persistence unit as a set of classes in a WAR file, persistence.xmlshould be located in the WAR file's WEB-INF/classes/META-INF directory. If you package the persistence unit in a JAR file that will be included in a WAR or EAR file, the JAR file should be located in either The WEB-INF/libdirectory of a WAR The EAR file's library directory

37.4 Querying Entities The Java Persistence API provides the following methods for querying entities. The Java Persistence query language (JPQL) is a simple, string-based language similar to SQL used to query entities and their relationships. See Chapter 39, "The Java Persistence Query Language"for more information. The Criteria API is used to create typesafe queries using Java programming language APIs to query for entities and their relationships. See Chapter 40, "Using the Criteria API to Create Queries"for more information. Both JPQL and the Criteria API have advantages and disadvantages. Just a few lines long, JPQL queries are typically more concise and more readable than Criteria queries. Developers familiar with SQL will find it easy to learn the syntax of JPQL. JPQL named queries can be defined in the entity class using a Java programming language annotation or in the application's deployment descriptor.

JPQL queries are not typesafe, however, and require a cast when retrieving the query result from the entity manager. This means that type-casting errors may not be caught at compile time. JPQL queries don't support open-ended parameters. Criteria queries allow you to define the query in the business tier of the application. Although this is also possible using JPQL dynamic queries, Criteria queries provide better performance because JPQL dynamic queries must be parsed each time they are called. Criteria queries are typesafe and therefore don't require casting, as JPQL queries do. The Criteria API is just another Java programming language API and doesn't require developers to learn the syntax of another query language. Criteria queries are typically more verbose than JPQL queries and require the developer to create several objects and perform operationson those objects before submitting the query to the entity manager. 37.5 Database Schema Creation The persistence provider can be configured toautomatically create the database tables, load data into the tables, and remove the tables during application deployment using standard properties in the applications deployment descriptor. These tasks are typically used during the development phase of a release, not against a production database. <?xml version="1.0" encoding="UTF-8"?> <persistence version="2.1" xmlns="http://xmlns.jcp.org/xml/ns/persistence" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/persistence http://xmlns.jcp.org/xml/ns/persistence/persistence_2_1.xsd"> <persistence-unit name="examplePU" transaction-type="JTA"> <jta-data-source>java:global/ExampleDataSource</jta-data-source> <properties> <property name="javax.persistence.schema-generation.database.action" value="drop-and-create"/> <property name="javax.persistence.schema-generation.create-source" value="script"/> <property name="javax.persistence.schema-generation.create-script-source" value="META-INF/sql/create.sql" /> <property name="javax.persistence.sql-load-script-source" value="META-INF/sql/data.sql" />

<property name="javax.persistence.schema-generation.drop-source" value="script" /> <property name="javax.persistence.schema-generation.drop-script-source" value="META-INF/sql/drop.sql" /> </properties> </persistence-unit> </persistence> This is an example of a persistence.xmldeployment descriptor that specifies that the provider should drop all database artifacts using a provided script, create the artifacts with a provided script, and load data from a provided script when the application is deployed. Database Schema Creation 37.5.1 Configuring an Application to Create or Drop Database Tables The javax.persistence.schema-generation.database.actionproperty is used to specify the action taken by the persistence provider when an application is deployed. If the property is not set, the persitence provider will not create or drop any database artifacts. <property name="javax.persistence.schema-generation.database.action" value="drop-and-create"/> In this example, the persistence provider will delete any remaining database artifacts and then create the artifacts when the application is deployed. By default, the object/relational metadata in the persistence unit is used to create the database artifacts. You may also supply scripts used by the provider to create and delete the database artifacts. The javax.persistence.schemageneration.create-sourceand javax.persistence.schema-generation.dropsourceproperties control how the provider will create or delete the database artifacts. <property name="javax.persistence.schema-generation.create-source" value="script"/> In this example, the persistence providerwill use a script packaged within the application to create the database artifacts. If you specify a script in create-sourceor drop-source, specify the location of the script using the javax.persistence.schema-generation.create-script-sourceor javax.persistence.schema-generation.drop-script-sourceproperty. The location of the script is relative to the root of the persistence unit.

<property name="javax.persistence.schema-generation.create-script-source" value="META-INF/sql/create.sql" /> In the above example, the create-script-sourceis set to a SQL file called create.sqlin the META-INF/sqldirectory relative to root of the persistence unit. 37.5.2 Loading Data Using SQL Scripts If you want to populate the database tableswith data before the application loads, specify the location of a load script in the javax.persistence.sql-loadscript-source property. The location specified in this property is relative to the root of the persistence unit. In this example, the load script is a file called data.sqlin the METAINF/sqldirectory relative to the root of the persistence unit. <property name="javax.persistence.sql-load-script-source" value="META-INF/sql/data.sql" />