Home

- upload.wikimedia.

1. private Money getSalary return this salary private void setSalary Money salary this salary salary 18 2 Common Problems My annotations are ignored This typically occurs when you annotate both the fields and methods properties of the class You must choose either field or property access and be consistent Also when annotating properties you must put the annotation on the get method not the set method Also ensure that you have not defined the same mappings in XML which may be overriding the annotations You may also have a classpath issue such as having an old version of the class on the classpath 5 Chapter 11 on page 25 6 Chapter 10 on page 23 43 Mapping Odd behavior There are many reasons that odd behavior can occur with persistence One common issue that can cause odd behavior is using property access and putting side effects in your get or set methods For this reason it is generally recommended to use field access in mapping i e putting your annotations on your variables not your get methods For example consider public void setPhones List lt Phone gt phones for Phone phone phones phone setOwner this this phones phones This may look innocent but these side effects can have unexpected consequences For example if the relationship was lazy this would have the effect of always instantiating the collection when set from the database It could a
2. 72 Advanced Sequencing public int hashCode return type hashCode owner 23 3 Advanced Sequencing Concurrency and Deadlocks One issue with table sequencing is that the sequence table can become a concurrency bottleneck even causing deadlocks If the sequence ids are allocated in the same transaction as the insert this can cause poor concurrency as the sequence row will be locked for the duration of the transaction preventing any other transaction that needs to allocate a sequence id In some cases the entire sequence table or the table page could be locked causing even transactions allocating other sequences to wait or even deadlock If a large sequence pre allocation size is used this becomes less of an issue because the sequence table is rarely accessed Some JPA providers use a separate non JTA connection to allocate the sequence ids in avoiding or limiting this issue In this case if you use a JTA data source connection it is important to also include a non JTA data source connection in your persistence xml Guaranteeing Sequential Ids Table sequencing also allows for truly sequential ids to be allocated Sequence and identity sequencing are non transactional and typically cache values on the database leading to large gaps in the ids that are allocated Typically this is not an issue and desired to have good performance however if performance and concurrency are less of a concern and true sequential id
3. AVG MAX MIN SUM DISTINCT state_field_path_ expression COUNT DISTINCT identification variable state_field_ path_ expression single_valued_association_path_ expression 46 1 3 Where WHERE employee firstName name AND employee address city LIKE Ott ESCAPE OR employee id IN 1 2 3 AND employee salary 2 gt 40000 where_clause WHERE conditional_ expression conditional expression conditional_term conditional_ expression OR conditional_term conditional_term conditional_factor conditional_term AND conditional_ factor conditional_ factor NOT conditional_ primary conditional_ primary simple_cond_ expression conditional_expression simple _cond_ expression comparison _ expression between_ expression like expression in expression null_comparison_ expression empty _collection_comparison_ expression collection _ member expression exists_ expression between _ expression arithmetic_expression NOT BETWEEN arithmetic_ expression AND arithmetic_ expression string_expression NOT BETWEEN string expression AND string expression datetime_expression NOT BETWEEN datetime_ expression AND datetime_ expression in_ expression state_field_path_ expression NOT IN in_ item in_item subquery in_ item literal input_ parameter like expression string expression NOT LIKE pattern_ value ESCAPE escape_ character null_comparison_ express
4. PHONE table ID TYPE AREA CODE P_ NUMBER OWNER _ID 1 home 613 792 0000 1 2 work 613 896 1234 1 3 work 416 123 4444 2 37 1 2 Example of a JPA 2 0 unidirectional OneToMany relationship annotations OEntity public class Employee Old Column name EMP_ID private long id COneToMany CJoinColumn name OWNER_1D referencedColumnName EMP_ID private List lt Phone gt phones Entity public class Phone Id private long id a OneToMany OneToMany 3 http en wikibooks org wiki Category 3AJava 20Persistence 4 http en wikibooks org wiki Category 3AJava 20Persistence 2FMapping 178 38 ManyToMany A ManyToMany relationship in Java is where the source object has an attribute that stores a collection of target objects and if those target objects had the inverse relationship back to the source object it would also be a ManyToMany relationship All relationships in Java and JPA are unidirectional in that if a source object references a target object there is no guarantee that the target object also has a relationship to the source object This is different than a relational database in which relationships are defined through foreign keys and querying such that the inverse query always exists JPA also defines a OneToMany relationship which is similar to a ManyToMany relationship except that the inverse relationship if it were defined is a ManyToOne relationship The main difference between a OneToMany a
5. James Sutherland Currently working on Oracle TopLink and Eclipse EclipseLink over 12 years of experience in object persistence and ORM Doug Clarke Oracle TopLink and Eclipse EclipseLink over 10 years of experience in the object persistence industry Preface http en wikibooks org wiki User 3AJamesssss http en wikipedia org wiki Oracle 20Corporation http en wikipedia org wiki TopLink http en wikipedia org wiki Eclipse 20Foundation http en wikipedia org wiki EclipseLink http en wikibooks org wiki User 3ADjclarke http en wikipedia org wiki Oracle 20Corporation http en wikipedia org wiki TopLink http en wikipedia org wiki Eclipse 20Foundation http en wikipedia org wiki EclipseLink http en wikibooks org wiki Category 3AJava 20Persistence vosoutkrkuvumH Ro 2 What is Java persistence Persistence in computer science is an adjective describing data that outlives the process that created it Java persistence could be defined as storing anything to any level of persistence using the Java programming language but obviously this would be too broad a definition to cover in a single book That is why this book is more focused on storing Java objects to relational databases In particular using the Java Persistence API JPA There are many ways to make data persist in Java including to name a few JDBC serialization file IO JCA object databases and XML databases Howe
6. 2 persist java lang Object 3 https java sun com javaee 5 docs api javax persistence EntityManager html merge java lang Object 4 https java sun com javaee 5 docs api javax persistence EntityManager html remove java lang Object 5 https java sun com javaee 5 docs api javax persistence EntityManager htmlitfind java lang Class 20java lang Object 6 https java sun com javaee 5 docs api javax persistence EntityManager html persist java lang Object 241 Persisting or flush because the database will only assign the Id on INSERT If the object does not use a generated Id you should normally assign its Id before calling persist The persist operation can only be called within a transaction an exception will be thrown outside of a transaction The persist operation is in place in that the object being persisted will become part of the persistence context The state of the object at the point of the commit of the transaction will be persisted not its state at the point of the persist call persist should normally only be called on new objects It is allowed to be called on existing objects if they are part of the persistence context this is only for the purpose of cascading persist to any possible related new objects If persist is called on an existing object that is not part of the persistence context then an exception may be thrown or it may be attempted to be inserted and a database constraint error may occur or
7. https java sun com javaee 5 docs api javax persistence CascadeType html 129 Relationships private long id OneToOne cascade CascadeType ALL JoinColumn name ADDR_ID private Address address 30 2 2 Example of a cascaded one to one relationship XML lt entity name Employee class org acme Employee access FIELD gt lt attributes gt lt id name id gt lt one to one name address gt lt join column name ADDR_ID gt lt cascade gt lt cascade all gt lt cascade gt lt one to one gt lt attributes gt lt entity gt 30 3 Orphan Removal JPA 2 0 Cascading of the remove operation only occurs when the remove is called on the object This is not normally what is desired on a dependent relationship If the related objects cannot exist without the source then it is normally desired to have them deleted when the source is deleted but also have them deleted when they are no longer referenced from the source JPA 1 0 did not provide an option for this so when a dependent object was removed from the source relationship it had to be explicitly removed from the EntityManager JPA 2 0 provides a orphanRemoval option on the OneToMany and OneToOne annotations and XML Orphan removal will ensure that any object no longer referenced from the relationship is deleted from the database 30 3 1 Example of an orphan removal one to many relationship annotations Entity public class Employee Id p
8. lt entity gt 41 1 4 Example of EntityListener event xml lt entity name Employee class org acme Employee access FIELD gt lt entity listeners gt lt entity listener class org acme EmployeeEventListener gt lt pre persist method name prePersist gt lt pre update method name preUpdate gt lt entity listener gt lt entity listeners gt lt attributes gt lt id name uid gt lt attributes gt lt entity gt 41 1 5 Default Entity Listeners It is also possible to configure a default Entity listener This listener will receive events for all of the Entity classes in the persistence unit Default listeners can only be defined through XML If a default Entity listener is defined and a class wants to define its own listener or does not want the default listener this can be disabled using the ExcludeDefaultListeners annotation or lt exclude default listeners gt XML element Example default Entity listener xml lt xml version 1 0 encoding UTF 8 gt lt entity mappings version 2 0 xmlns http java sun com xml ns persistence orm xmlns xsi http www w3 org 2001 XMLSchema instance xsi schemaLocation http java sun com xml ns persistence orm orm_2_0 xsd gt lt persistence unit metadata gt lt persistence unit defaults gt lt entity listeners gt lt entity listener class org acme ACMEEventListener gt lt pre persist method name prePersist gt lt pre update method name preUpda
9. lt entity name Employee class org acme Employee access FIELD gt Chapter 26 5 on page 96 Chapter 26 6 on page 96 https java sun com javaee 5 docs api javax persistence Embedded html Chapter 26 7 on page 97 oo PR Ww 90 Mapped Superclasses lt attributes gt lt id name id gt lt embedded name period gt lt attributes gt lt entity gt 91 26 Advanced 26 1 Sharing An embeddable object can be shared between multiple classes Consider a Name object that both an Employee and a User contain Both Employee and a User have their own tables with different column names that they desire to store their name in Embeddables support this through allowing each embedded mapping to override the columns used in the embeddable This is done through the AttributeOverride annotation or lt attribute override gt element Note that an embeddable cannot be shared between multiple instances If you desire to share an embeddable object instance then you must make it an independent object with its own table 26 1 1 Example shared embeddable annotations Entity public class Employee Id private long id Embedded AttributeOverrides AttributeOverride name startDate column Column name START_DATE AttributeOverride name endDate column Column name END_DATE private Period employmentPeriod Entity public class User Id private long id Embedded AttributeOverrides
10. Named queries can be defined on any annotated class but are typically defined on the Entity that they query for The name of the named query must be unique for the entire persistence unit they name is not local to the Entity In the orm xml named queries can be defined either on the lt entity mappings gt or on any lt entity gt Named queries are typically parametrized so they can be executed with different parameter values Parameters are defined in JPQL using the lt name gt syntax for named parameters or the syntax for positional parameters A collection of query hints can also be provided to a named query Query hints can be used to optimize or to provide special configuration to a query Query hints are specific to the JPA provider Query hints are defined through the QueryHint annotation or query hint XML element 44 1 1 Example named query annotation NamedQuery name findAllEmployeesInCity query Select emp from Employee emp where emp address city city hints QueryHint name acme jpa batch value emp address public class Employee sre 10 https java sun com javaee 5 docs api javax persistence NamedQuery html 11 https java sun com javaee 5 docs api javax persistence NamedQueries html 12 https java sun com javaee 5 docs api javax persistence EntityManager html createNamedQuery java lang String 13 https java sun com javaee 5 docs api javax persistence Query html 14 https ja
11. ddy 4 TL0G C10 Sox CLOG Sox ISPIIM 292INOS Se jo usado Te9A TUZI ZT VG Ty uoIs 19A Sox TG ANDI Os oar Gz o8ed uo IT I deqo gz o8ed uo QT 199deuo LZ e8ed uo ZI I deyo S v sox sox Sox O S oar 0 Vdr pL10 soA Aur doj osdiog so ur Tosd 9H H pou P VLU SA IOI yon O T Vdr pold 20 Existing Persistence Products eot 2130 q M BIO ETOT SV2Ppe 10 6 Syung ZA ysy SSPTL 0 8 I AI uorye ddy otoyds 2M OUIT U0 199 SIOAIOS uoIye ddy 4 L006 L006 Sok 10G Sok TTOG Sok asealeyYy 9DINOS Se Jo usado TIe9A Ty 0 ETE OTS uors vz TOA ANDI Tg a3ed uo FI 199deyo 67 o8ed uo ET 199deuo 310 snoTdnuegep mmn dgay gg o8ed uo CT soydeyyD PPLIO sox OPOM pureael sten U98SH soA yurydoy sna gt nNeIeAq Snap sox NNeIeg oyoedy gVdf Sox uodo yon o I Vdr pold 21 Or OD Persistence Products Persistence Products Persistence Products 10 http en wikibooks org wiki Category 3AJava 20Persistence 2FPersistence 20Products 11 http en wikibooks org wiki Category 3AJava 20Persistence 22 10 EclipseLink EclipseLink is the open source Eclipse Persistence Services Project from the Eclipse Foundation The product provides an extensible framework that allows Java developers to interact with
12. examples Mapping via JPA Annotations Query a Basics b Future Asychronous query execution c PagingList 1 d Aggregation Group By Save and Delete Transactions Caching Using raw SQL oo ouPrumxm m http www avaje org Chapter 17 on page 37 http en wikibooks org wiki 2FWhy 20Ebean 2F http en wikibooks org wiki 2FExample 20Model 2F http en wikibooks org wiki 2FQuick 20Start 20 20examples 2F http en wikibooks org wiki 2FMapping 20via 20JPA 20Annotations 2F http en wikibooks org wiki 2FQuery 2F http en wikibooks org wiki 2FBasics 2F http en wikibooks org wiki 2FFuture 20 20Asychronous 20query 20execution 2F http en wikibooks org wiki 2FPagingList 2F http en wikibooks org wiki 2FAggregation 20 20Group 20By 2F http en wikibooks org wiki 2FSave 20and 20Delete 2F http en wikibooks org wiki 2FTransactions 2F http en wikibooks org wiki 2FCaching 2F http en wikibooks org wiki 2FUsing 20raw 20SQL 2F 35 17 Mapping 37 18 Mapping The first thing that you need to do to persist something in Java is define how it is to be persisted This is called the mapping process details There have been many different solutions to the mapping process over the years including some object databases that didn t require you map anything but let you persist anything directly Object relational mapping tools that would generate an object mo
13. java sun com xml ns persistence xmlns xsi http www w3 org 2001 XMLSchema instance xsi schemaLocation http java sun com xml ns persistence persistence_1_0 xsd version 1 0 gt lt persistence unit name acme transaction type RESOURCE_LOCAL gt lt EclipseLink gt lt provider gt org eclipse persistence jpa PersistenceProvider lt provider gt lt Hibernate gt lt provider gt org hibernate ejb HibernatePersistence lt provider gt lt TopLink Essentials gt lt provider gt oracle toplink essentials PersistenceProvider lt provider gt lt Apache OpenJPA gt lt provide r gt org apache openjpa persistence PersistenceProviderImpl lt provider gt lt DataNucleus gt lt provider gt org datanucleus jpa PersistenceProviderImpl lt provider gt lt exclude unlisted classes gt false lt exclude unlisted classes gt lt properties gt lt property name eclipselink jdbc driver value org acme db Driver gt lt property name eclipselink jdbc url value jdbc acmedb localhost acme gt lt property name eclipselink jdbc user value wile gt lt property name eclipselink jdbc password value elenberry gt lt properties gt lt persistence unit gt lt persistence gt 43 1 2 Example JPA 2 0 persistence xml file lt xml version 1 0 encoding UTF 8 gt lt persistence xmlns http java sun com xml ns persistence xmlns xsi http www w3 o
14. lished on the MMC site CC BY SA means the Creative Commons Attribution Share Alike 3 0 license published by Creative Commons Corporation a not for profit corporation with a principal place of business in San Francisco California as well as future copyleft versions of that license published by that same organization Incorporate means to publish or republish a Doc ument in whole or in part as part of another Doc ument An MMC is eligible for relicensing if it is licensed under this License and if all works that were first published under this License somewhere other than this MMC and subsequently incorporated in whole or in part into the MMC 1 had no cover texts or invariant sections and 2 were thus incorporated prior to November 1 2008 The operator of an MMC Site may republish an MMC contained in the site under CC BY SA on the same site at any time before August 1 2009 pro vided the MMC is eligible for relicensing ADDEN DUM How to use this License for your documents To use this License in a document you have written include a copy of the License in the document and put the following copyright and license notices just after the title page Copyright C YEAR YOUR NAME Permission is granted to copy distribute and or modify this doc ument under the terms of the GNU Free Documen tation License Version 1 3 or any later version pub lished by the Free Software Foundation with no Invariant Sections
15. trigger when the CREATE TABLE statement is executed Common Problems null is inserted into the database or error on insert This typically occurs because the Id was not configured to use an Generated Value strategy GenerationType IDENTITY Ensure it is configured correctly It could also be that your JPA provider does not support identity sequencing on the database platform that you are using or you have not configured your database platform Most providers require that you set the database platform through a persistence xml property most provider also allow you to customize your own platform if it is not directly supported It may also be that you did not set your primary key column in your table to be an identity type Object s id is not assigned after persist Identity sequencing requires the insert to occur before the id can be assigned so it is not assigned on persist like other types of sequencing You must either call commit on the current transaction or call flush on the EntityManager It may also be that you did not set your primary key column in your table to be an identity type Child s id is not assigned from parent on persist A common issue is that the generated Id is part of a child object s Id through a OneToOne or ManyToOne mapping In this case because JPA requires that the child define a duplicate Basic mapping for the Id its Id will be inserted as null One solution to this is to mark the Column on
16. Moreover your license from a particular copyright holder is reinstated permanently if the copyright holder notifies you of the violation by some reason able means this is the first time you have received notice of violation of this License for any work from that copyright holder and you cure the vi olation prior to 30 days after your receipt of the notice Termination of your rights under this section does not terminate the licenses of parties who have re ceived copies or rights from you under this License If your rights have been terminated and not perma nently reinstated receipt of a copy of some or all of the same material does not give you any rights to use it 10 FUTURE REVISIONS OF THIS LI CENSE The Free Software Foundation may publish new re vised versions of the GNU Free Documentation Li cense from time to time Such new versions will be similar in spirit to the present version but may dif fer in detail to address new problems or concerns See http www gnu org copyleft Each version of the License is given a distinguish ing version number If the Document specifies that a particular numbered version of this License or any later version applies to it you have the op tion of following the terms and conditions either of that specified version or of any later version that has been published not as a draft by the Free Soft ware Foundation If the Document does not specify a version number of this License
17. VARCHAR ES E L_NAME VARCHAR 5 OVWNER_ID NUMBER SALARY NUMBER TYPE VARCHAR 1 FK_OWNER_ID P_NUMBER VARCHAR AREA_CODE VARCHAR Figure 17 JPA 2 0 defines an ElementCollection mapping It is meant to handle several non standard relationship mappings An ElementCollection can be used to define a one to many relationship to an Embeddable object or a Basic value such as a collection of Strings An ElementCollection can also be used in combination with a Map to define relationships where the key can be any type of object and the value is an Embeddable object or a Basic value In JPA a ElementCollection relationship is defined through the ElementCollection annotation or the lt element collection gt element The ElementCollection values are always stored in a separate table The table is defined through the CollectionTable annotation or the lt collection table gt element The 1 Chapter 31 6 on page 148 2 https java sun com javaee 6 docs api javax persistence ElementCollection html 3 https java sun com javaee 6 docs api javax persistence CollectionTable html 187 ElementCollection CollectionTable defines the table s name and JoinColumn or JoinColumns if a composite primary key 40 1 Embedded Collections An ElementCollection mapping can be used to define a collection of Embeddable objects This is not a typical usage of Embeddable objects as the objects are not embedded in the source obje
18. en wikibooks org wiki Category 3AJava 20Persistence 18 http en wikibooks org wiki Category 3AJava 20Persistence 2FMapping 191 41 Advanced Topics 41 1 Events A event is a hook into a system that allows the execution of some code when the event occurs Events can be used to extend integrate debug audit or monitor a system JPA defines several events for the persistent life cycle of Entity objects JPA events are defined through annotations or in the orm xml Any method of a persistent class can be annotated with an event annotation to be called for all instances of that class An event listener can also be configured for a class using the EntityListeners annotation or lt entity listeners gt XML element The specified listener class does not need to implement any interface JPA does not use the Java event model it only needs to annotate its methods with the desired event annotation JPA defines the following events e PostLoad Invoked after an Entity is loaded into the persistence context EntityManager or after a refresh operation e PrePersist Invoked before the persist operation is invoked on an Entity Also invoked on merge for new instances and on cascade of a persist operation The Id of the object may not have been assigned and code be assigned by the event e PostPersist Invoked after a new instance is persisted to the database This occurs during a flush or commit operation after the database INSERT has o
19. getReference API Some JPA products also use the EmbeddedId as a cache key to track an object s identity Because of this it is required depending on JPA product to 4 https java sun com javaee 5 docs api javax persistence EmbeddedId html 67 Advanced implement an equals and hashCode method on the EmbeddedId Ensure that the equals method checks each part of the primary key and correctly uses equals for objects and for primitives Ensure that the hashCode method will return the same value for two equal objects TopLink EclipseLink Do not require the implementation of equals or hashCode in the id class Example embedded id annotation Entity public class Employee EmbeddedId private EmployeePK id Example embedded id XML lt entity name Employee class org acme Employee access FIELD gt lt embedded id class org acme EmployeePK gt lt entity gt lt embeddable name EmployeePK class org acme EmployeePK access FIELD gt lt attributes gt lt basic name employeeld gt lt basic name companyId gt lt basic name departmentId gt lt attributes gt lt embeddable gt Example embedded id class CEmbeddable public class EmployeePK Basic private long employeeld Basic private long companyld Basic private long departmentId public EmployeePK long employeeld long companyld long departmentId ee Bu this employeeld employeeld this companyId
20. https java sun com javaee 6 docs api javax persistence EntityManager html unwrap java lang Class 11 251 Advanced ServerSession getIdentityMapAccessor initializeAllldentityMaps Persisting Persisting kk Java Persistence 12 http en wikibooks org wiki Category 3AJava 20Persistence 2FRuntime 13 http en wikibooks org wiki Category 3AJava 20Persistence 14 http kk wikibooks org wiki Java 20Persistence 252 49 Transactions A transaction is a set of operations that either fail or succeed as a unit Transactions are a fundamental part of persistence A database transaction consists of a set of SQL DML Data Manipulation Language operations that are committed or rolled back as a single unit An object level transaction is one in which a set of changes made to a set of objects are committed to the database as a single unit JPA provides two mechanisms for transactions When used in JEE JPA provides integra tion with JTA Java Transaction API JPA also provides its own EntityTransaction implementation for JSE and for use in a non managed mode in JEE Transactions in JPA are always at the object level this means that all changes made to all persistent objects in the persistence context are part of the transaction 49 1 Resource Local Transactions Resource local transactions are used in JSE or in application managed non managed mode in JEE To use resource local transactions the transaction
21. query hint entities can also be marked to always be read only using the ReadOnly annotation 51 3 Data Cache A data cache caches the object s data not the objects themselves The data is normally a representation of the object s database row The advantage of a data cache is that it is easier to implement as you do not have to worry about relationships object identity or complex memory management The disadvantage of a data cache is that it does not store the data as it is used in the application and does not store relationships This means that on a cache hit the object must still be built from the data and the relationships fetched from the database Some products that support a data cache also support a relationship cache or query cache to allow caching of relationships Hibernate Supports integration with a third party data cache Caching is not enabled by default and a third party caching product such as Ehcache must be used to enable caching 51 3 1 Caching Relationships Some products support a separate cache for caching relationships This is normally required for OneToMany and ManyToMany relationships OneToOne and ManyToOne relationships nor mally do not need to be cached as they reference the object s Id However an inverse OneToOne will require the relationship to be cached as it references the foreign key not primary key Chapter 11 on page 25 Chapter 10 on page 23 Chapter 51 3 1 on page 263 Chapter 5
22. so you may have issues Some JPA providers have built in support for returning values assigned in a trigger or stored procedure back into the object TopLink EclipseLink Provide a ReturningPolicy that allows for any field values including the primary key to be returned from the database after an insert or update This is defined through the CReturnInsert CReturnUpdate annotations or the lt return insert gt lt return update gt XML elements in the eclipselink orm xml 23 5 Primary Keys through Events If the application generates its own id instead of using a JPA GeneratedValue it is sometimes desirable to perform this id generation in a JPA event instead of the application code having to generate and set the id In JPA this can be done through the PrePersist event 23 6 No Primary Key Sometimes your object or table has no primary key The best solution in this case is normally to add a generated id to the object and table If you do not have this option sometimes there is a column or set of columns in the table that make up a unique value You can use this unique set of columns as your id in JPA The JPA Id does not always have to match the database table primary key constraint nor is a primary key or a unique constraint required If your table truly has no unique columns then use all of the columns as the id Typically when this occurs the data is read only so even if the table allows duplicate rows with the same
23. the READ lock check the optimistic version field and the WRITE checks and increments it Example of Using the Lock API Employee employee entityManager find Employee class id employee setSalary employee getManager getSalary 2 entityManager lock employee getManager LockModeType READ Write locking can also be used to provide object level locks If you desire for a change to a dependent object to conflict with any change to the parent object or any other of its dependent objects this can be done through write locking This can also be used to lock relationships when you change a OneToMany or ManyToMany relationship you can also force the parent s version to be incremented Example of Using the Lock API for Cascaded Locks Employee employee entityManager find Employee class id employee getAddress setCity Ottawa entityManager lock employee LockModeType WRITE 27 2 6 No Locking a k a Ostrich Locking Conceptually people may scoff and be alarmed at the thought of no locking but it is probably the most common form of locking in use Some call it Ostrich locking as the strategy is to stick your head in the sand and ignore the issue Most prototypes or small applications frequently do not have the requirement or in most cases the need for locking and handling what to do when a locking contention does occur is beyond the scope of the application so best to just ignore the issue In general it is probably be
24. trary complex foreign keys relationships to be defined among the secondary tables This can be configured through using a DescriptorCustomizer annotation and DescriptorCustomizer class 20 3 Multiple table joins WE FRK_EMPLOYEE 1 ID NUMBER je EMPID NUMBER F NAME VARCHAR TYPE VARCHAR L_NAME VARCHAR CITY VARCHAR SALARY NUMBER STREET VARCHAR STATE VARCHAR COUNTRY VARCHAR P_ CODE VARCHAR Figure 10 11 Chapter 11 on page 25 12 Chapter 10 on page 23 50 Multiple table outer joins Occasionally the data model and object model do not get along very well at all The database could be a legacy model and not fit very well with the new application model or the DBA or object architect may be a little crazy In these cases you may require advanced multiple table joins Examples of these include having two tables related not by their primary or foreign keys but through some constant or computation Consider having an EMPLOYEE table and an ADDRESS table the ADDRESS table has an EMP_ID foreign key to the EMPLOYEE table but there are several address for each employee and only the address with the TYPE of HOME is desired In this case data from both of the tables is desired to be mapped in the Employee object A join expression is required where the foreign key matches and the constant matches Again this scenario could be handled through redesigning the data or object model or through using a view Some
25. user and password JPA has a standard way of setting the DataSource JNDI name but this is mainly used in JEE JPA 2 0 does define standard persistence unit properties for connecting to JDBC in JSE These include javax persistence jdbc driver javax persistence jdbc url javax persistence jdbc user javax persistence jdbc password The JPA application is typically required to be packaged into a persistence unit jar file This is a normal jar that has the persistence xml file in the META INF directory Typically a JPA provider will require something special be done in JSE to enable certain features such as lazy fetching such as static weaving byte code processing of the jar or using a Java agent JVM option In JSE the EntityManager must be closed when your application is done with it The life cycle of the EntityManager is typically per client or per request The https java sun com javaee 5 docs api javax persistence package summary html https java sun com javaee 5 docs api javax persistence EntityManager html https java sun com javaee 5 docs api javax persistence EntityManagerFactory html https java sun com javaee 5 docs api javax persistence Persistence html AUNE 209 Entity Manager EntityManagerFactory can be shared among multiple threads or users but EntityManager should not be shared 43 1 1 Example JPA 1 0 persistence xml file lt xml version 1 0 encoding UTF 8 gt lt persistence xmlns http
26. 2 3 3 4 Relationships Relationships 27 http en wikibooks org wiki Category 3AJava 20Persistence 28 http en wikibooks org wiki Category 3AJava 20Persistence 2FMapping 150 32 OneToOne id long ee _ m firstName String A lastName String L gt id long salary BigDecimal 1 address street String city String province String country String postalCode String y ccs a EMP_ID NUMBER pre neh Sgt ee F_NAME VARCHAR 1 L_NAME VARCHAR PIES sesh Aye SALARY NUMBER COUNTRY VARCHAR ADDRESS_ID NUMBER P CODE VARCHAR Figure 14 A OneToOne relationship in Java is where the source object has an attribute that references another target object and if that target object had the inverse relationship back to the source object it would also be a OneToOne relationship All relationships in Java and JPA are unidirectional in that if a source object references a target object there is no guarantee that the target object also has a relationship to the source object This is different than a relational database in which relationships are defined through foreign keys and querying such that the inverse query always exists JPA also defines a ManyToOne relationship which is similar to a OneToOne relationship except that the inverse relationship if it were defined is a OneToMany relationship The main 1 Chapter 33 2 2 on page 164 151 OneToOne d
27. 2 Stateless SessionBeans 43 2 3 Stateful SessionBeans Runtime Runtime 6 Chapter 41 10 on page 203 7 http en wikibooks org wiki Category 3AJava 20Persistence 8 http en wikibooks org wiki Category 3AJava 20Persistence 2FRuntime 213 44 Querying Querying is a fundamental part of persistence Being able to persist something is not very useful without being able to query it back There are many querying languages and frameworks the most common query language is SQL used in relational databases JPA provides several querying mechanisms e JPQL BNF e Criteria API e Native SQL Queries JPA primarily uses the Java Persistence Querying Language JPQL which is based on the SQL language and evolved from the EJB Query Language EJBQL It basically provides the SQL syntax at the object level instead of at the data level JPQL is similar in syntax to SQL and can be defined through its BNF definition JPA also provides the Criteria API that allows dynamic queries to be easily built using a Java API The Criteria API mirrors the JPQL syntax but provides Java API for each operation function instead of using a separate query language JPA provides querying through the Query interface and the NamedQuery and CNamedNativeQuery annotations and the lt named query gt and lt named native query gt XML elements Other querying languages and frameworks include SQL e EJBQL e JDOQL EQL EclipseLink Query Lang
28. 20Programming 9 http wiki eclipse org EclipseLink 10 http wiki oracle com page TopLink 11 http wiki glassfish java net Wiki jsp page TopLinkEssentials 12 http www hibernate org 37 html 13 http en wikipedia org wiki Java_Persistence_API 14 http wiki java net bin view Javapedia JPA 15 http www freebase com view guid 9202a8c04000641 8000000004666d33 16 http www dmoz org Computers Programming Languages Java Databases_and_Persistence Object_Persistence JPA 279 References amp 55 0 4 Forums Sun EJB Forum JavaRanch ORM Forum Nabble JPA Forum EclipseLink Forum EclipseLink Newsgroup Oracle TopLink Forum Hibernate Forum TopLink Essentials Mailing List Glassfish persistence 55 0 6 Blogs Java Persistence Doug Clarke System out Mike Keith On TopLink Shaun Smith EclipseLink Hibernate Blog 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 http forum java sun com forum jspa forumID 13 55 0 5 Products Oracle TopLink Home EclipseLink Home TopLink Essentials Home Hibernate Home Open JPA Home HiberObjects 55 0 7 Books Pro EJB 3 http saloon javaranch com cgi bin ubb ultimatebb cgi ubb forum amp f 78 http www nabble com JPA 27109 html http www nabble com EclipseLink 26430 html http www eclipse org newsportal thread php group eclipse rt eclipselink http
29. 25 Chapter 10 on page 23 26 Chapter 11 on page 25 27 Chapter 10 on page 23 201 Advanced Topics 41 8 History A common desire in database applications is to maintain a record and history of the database changes This can be used for tracking and auditing purposes or to allow undoing of changes or to keep a record of the system s data over time Many database have auditing functionality that allows some level of tracking changes made to the data Some databases such as Oracle s Flashback feature allow the automatic tracking of history at the row level and even allow querying on past versions of the data It is also possible for an application to maintain its own history through its data model All that is required is to add a START and END timestamp column to the table The current row is then the one in which the END timestamp is null When a row is inserted its START timestamp will be set to the current time When a row is updated instead of updating the row a new row will be inserted with the same id and data but a different START timestamp and the old row will be updated to set its END timestamp to the current time The primary key of the table will need to have the START timestamp added to it History can also be used to avoid deletion Instead of deleting a row the END timestamp can just be set to the current time Another solution is to add a DELETED boolean column to the table and record when a row is deleted The history d
30. 6 Revised Versions of the GNU Lesser General Public License The Free Software Foundation may publish revised and or new versions of the GNU Lesser General Public License from time to time Such new ver sions will be similar in spirit to the present version but may differ in detail to address new problems or concerns Each version is given a distinguishing version num ber If the Library as you received it specifies that a certain numbered version of the GNU Lesser Gen eral Public License or any later version applies to it you have the option of following the terms and conditions either of that published version or of any later version published by the Free Software Foun dation If the Library as you received it does not specify a version number of the GNU Lesser Gen eral Public License you may choose any version of the GNU Lesser General Public License ever pub lished by the Free Software Foundation If the Library as you received it specifies that a proxy can decide whether future versions of the GNU Lesser General Public License shall apply that proxy s public statement of acceptance of any version is permanent authorization for you to choose that version for the Library
31. 7 apply to the code keep intact all notices of the absence of any warranty and give all recipi ents a copy of this License along with the Program You may charge any price or no price for each copy that you convey and you may offer support or war ranty protection for a fee 5 Conveying Modified Source Versions You may convey a work based on the Program or the modifications to produce it from the Program in the form of source code under the terms of sec tion 4 provided that you also meet all of these con ditions a The work must carry prominent notices stating that you modified it and giving a relevant date b The work must carry prominent notices stating that it is released under this License and any con ditions added under section 7 This requirement modifies the requirement in section 4 to keep in tact all notices c You must license the entire work as a whole under this License to anyone who comes into possession of a copy This License will therefore apply along with any applicable section 7 additional terms to the whole of the work and all its parts regardless of how they are packaged This License gives no permission to license the work in any other way but it does not invalidate such per mission if you have separately received it d If the work has interactive user interfaces each must display Appropriate Legal Notices however if the Program has interactive interfaces that do not dis play
32. Appropriate Legal Notices your work need not make them do so A compilation of a covered work with other sepa rate and independent works which are not by their nature extensions of the covered work and which are not combined with it such as to form a larger program in or on a volume of a storage or distri bution medium is called an aggregate if the com pilation and its resulting copyright are not used to limit the access or legal rights of the compilation s users beyond what the individual works permit In clusion of a covered work in an aggregate does not cause this License to apply to the other parts of the aggregate 6 Conveying Non Source Forms You may convey a covered work in object code form under the terms of sections 4 and 5 provided that you also convey the machine readable Correspond ing Source under the terms of this License in one of these ways a Convey the object code in or embodied in a physical product including a physical distribu tion medium accompanied by the Corresponding Source fixed on a durable physical medium custom arily used for software interchange b Convey the object code in or embodied in a physical product including a physical distribution medium accom panied by a written offer valid for at least three years and valid for as long as you offer spare parts or customer support for that product model to give anyone who possesses the object code either 1 a copy of the C
33. Basic annotation or element 9 Chapter 11 on page 25 10 Chapter 10 on page 23 119 Advanced 29 6 Column Definition and Schema Generation There are various attributes on the Column annotation and element for database schema generation If you do not use JPA to generate your schema you can ignore these Many JPA providers do provide the feature of auto generation of the database schema By default the Java types of the object s attributes are mapped to their corresponding database type for the database platform you are using You may require configuring your database platform with your provider such as a persistence xml property to allow schema generation for your database as many database use different type names The columnDefinition attribute of Column can be used to override the default database type used or enhance the type definition with constraints or other such DDL The length scale and precision can also be set to override defaults Since the defaults for the length are just defaults it is normally a good idea to set these to be correct for your data model s expected data to avoid data truncation The unique attribute can be used to define a unique constraint on the column most JPA providers will automatically define primary key and foreign key constraints based on the Id and relationship mappings JPA does not define any options to define an index Some JPA providers may provide extensions for this You can also c
34. Category 3AJava 20Persistence 3 http en wikibooks org wiki Category 3AJava 20Persistence 2FRuntime 259 51 Caching Caching is the most important performance optimization technique There are many things that can be cached in persistence objects data database connections database statements query results meta data relationships to name a few Caching in object persistence normally refers to the caching of objects or their data Caching also influences object identity that is that if you read an object then read the same object again you should get the identical object back same reference JPA 1 0 does not define a shared object cache JPA providers can support a shared object cache or not however most do Caching in JPA is required with in a transaction or within an extended persistence context to preserve object identity but JPA does not require that caching be supported across transactions or persistence contexts JPA 2 0 defines the concept of a shared cache The Cacheable annotation or cacheable XML attribute can be used to enable or disable caching on a class 51 0 1 Example JPA 2 0 Cacheable annotation Entity Cacheable public class Employee The SharedCacheMode enum can also be set in the lt shared cache mode gt XML element in the persistence xml to configure the default cache mode for the entire persistence unit 51 0 2 Example JPA 2 0 SharedCacheMode XML lt persistence unit name ACME gt
35. EE Connector Architec ture 1 6 2009 SDO Service Data Objects 2 1 2006 EJB CMP Enterprise Java Beans Container Managed Persistence 2 1 EJB 2003 Other Persistence Specs Other Persistence Specs 1 Last updated 2010 10 2 http en wikipedia org wiki JDBC 3 http en wikipedia org wiki Java 20Data 200bjects 4 http en wikipedia org wiki Java 20Persistence 20API 5 http en wikipedia org wiki Java 20EE 20Connector 20Architecture 6 http en wikipedia org wiki Service 20Data 200bjects 7 http en wikipedia org wiki EJB http en wikibooks org wiki Category 3AJava 20Persistence 2FWhat 20is 20Java 20persistence 9 http en wikibooks org wiki Category 3AJava 20Persistence 15 8 Why use JPA or ORM This is an intriguing question There are many reasons to use an ORM framework or persistence product and many reasons to use JPA in particular Reasons for ORM e Leverages large persistence library to avoid developing solutions to problems that others have already solved e Avoids low level JDBC and SQL code e Leverages object oriented programming and object model usage e Provides database and schema independence e Most ORM products are free and open source e Many enterprise corporations provide support and services for ORM products e Provides high end performance features such as caching and sophisticated database and query optimizations Reasons for JPA e It is a standard and part of EJ
36. JPA implementations provide extensions to handle this scenarios TopLink EclipseLink Provides a proprietary API for its mapping model DescriptorQueryManager setMultipleTableJoinExpression that allows for arbi trary complex multiple table joins to be defined This can be configured through using a DescriptorCustomizer annotation and DescriptorCustomizer class 20 4 Multiple table outer joins Another perversion of multiple table mapping is to desire to outer join the secondary table This may be desired if the secondary may or may not have a row defined for the object Typically the object should be read only if this is to be attempted as writing to a row that may or may not be there can be tricky This is not directly supported by JPA and it is best to reconsider the data model or object model design if faced with this scenario Again it is possible to map this through a database view where an outer join is used to join the tables in the view Some JPA implementation support using outer joins for multiple tables Hibernate This can be accomplished through using the Hibernate Table annotation and set its optional attribute to true This will configure Hibernate to use an outer join to read the table and will not write to the table if all of the attributes mapping to the table are null TopLink EclipseLink If the database supports usage of outer join syntax in the where clause Oracle Sybase SQL Server then the m
37. Multiple Table Inheritance Joined inheritance is the most logical inheritance solution because it mirrors the object model in the data model In joined inheritance a table is defined for each class in the inheritance hierarchy to store only the local attributes of that class Each table in the hierarchy must also store the object s id primary key which is only defined in the root class All classes in the hierarchy must share the same id attribute A discriminator column is used to determine which class the particular row belongs to each class in the hierarchy defines its own unique discriminator value Some JPA providers support joined inheritance with or without a discriminator column some required the discriminator column and some do not support the discriminator column So joined inheritance does not seem to be fully standardized yet Hibernate A discriminator column on joined inheritance is not supported http opensource atlassian com projects hibernate browse ANN 140 23 8 1 Example joined inheritance tables PROJECT table ID PROJ_ TYPE NAME 1 L Accounting S Legal SMALLPROJECT table ID 2 LARGEPROJECT table ID BUDGET 1 50000 23 8 2 Example joined inheritance annotations Entity Inheritance strategy InheritanceType JOINED DiscriminatorColumn name PROJ_TYPE 27 Chapter 12 on page 27 79 Advanced Table name PROJECT public abstract class Project 4 Id private long id Ent
38. NUMBER NAME VARCHAR EMP_ID NUMBER e NAME VARCHAR 1 1 MGR_ID NUMBER FK_DEP COMPANY_ID DEP_ID FK_MGR COMPANY_ID DEP_ID MGR_ID Figure 11 Composite primary keys are common in legacy database schemas where cascaded keys can sometimes be used This refers to a model where dependent objects key definitions include their parents primary key for example COMPANY s primary key is COMPANY_ID DEPARTMENT s primary key is composed of a COMPANY_ID and a DEP_ID EMPLOYEE s primary key is composed of COMPANY_ID DEP_ID and EMP_ID and so on Although this generally does not match object oriented design principles some DBA s prefer this model Difficulties with the model include the restriction that employees cannot switch departments that foreign key relationships become more complex and that all primary key operations including queries updates and deletes are less efficient However each department has control over its own employee IDs and if needed the database EMPLOYEE table can be partitioned based on the COMPANY_ID or DEP_ID as these are included in every query 65 Advanced Other common usages of composite primary keys include many to many relationships where the join table has additional columns so the table itself is mapped to an object whose primary key consists of the pair of foreign key columns and dependent or aggregate one to many relationships where the child object s primary key consists of its parent s primary k
39. One issue with this is that you normally want to create the EntityManager when there is no active JTA transaction otherwise it will commit as part of that transaction However even if it does commit you can still continue to use it and join a future transaction You do have to avoid using transactional API such as merge or remove until you are ready to commit the transaction joinTransaction is only used with JTA managed EntityManagers JTA transaction type in persistence xml For RESOURCE_LOCAL EntityManagers you can just commit the JPA transaction whenever you desire 50 1 1 Example joinTransaction usage EntityManager em getEntityManagerFactory createEntityManager Employee employee em find Employee class id employee setSalary employee getSalary 1000 UserTransaction transaction UserTransaction new InitialContext lookup java comp UserTransaction transaction begin em joinTransaction transaction commit https java sun com javaee 5 docs api javax persistence EntityManager html joinTransaction 257 Advanced 50 2 Retrying Transactions Handling Commit Failures Sometimes it is desirable to handle persistence errors and recover and retry transactions This normally requires a lot of application knowledge to know what failed what state the system is in and how to fix it Unfortunately JPA does not provide a direct way of handling commit failures or error handling When a tran
40. Requiring preservation of specified reasonable legal notices or author attributions in that material or in the Appropriate Legal Notices displayed by works containing it or c Prohibit ing misrepresentation of the origin of that material or requiring that modified versions of such material be marked in reasonable ways as different from the original version or d Limiting the use for pub licity purposes of names of licensors or authors of the material or e Declining to grant rights under trademark law for use of some trade names trade marks or service marks or f Requiring indem nification of licensors and authors of that material by anyone who conveys the material or modified versions of it with contractual assumptions of lia bility to the recipient for any liability that these contractual assumptions directly impose on those licensors and authors All other non permissive additional terms are con sidered further restrictions within the meaning of section 10 If the Program as you received it or any part of it contains a notice stating that it is gov erned by this License along with a term that is a further restriction you may remove that term If a license document contains a further restriction but permits relicensing or conveying under this License you may add to a covered work material governed by the terms of that license document provided that the further restriction does not survive such relicensin
41. Source The information must suffice to ensure that the continued functioning of the modi fied object code is in no case prevented or interfered with solely because modification has been made If you convey an object code work under this sec tion in or with or specifically for use in a User Product and the conveying occurs as part of a transaction in which the right of possession and use of the User Product is transferred to the re cipient in perpetuity or for a fixed term regard less of how the transaction is characterized the Corresponding Source conveyed under this section must be accompanied by the Installation Informa tion But this requirement does not apply if neither you nor any third party retains the ability to install modified object code on the User Product for ex ample the work has been installed in ROM The requirement to provide Installation Informa tion does not include a requirement to continue to provide support service warranty or updates for a work that has been modified or installed by the re cipient or for the User Product in which it has been modified or installed Access to a network may be denied when the modification itself materially and adversely affects the operation of the network or violates the rules and protocols for communication across the network Corresponding Source conveyed and Installation Information provided in accord with this section must be in a format that is publicly docu
42. Table qualifiers schemas or creators 2 2 2 2 Coon nen 52 21 Identity 55 22 Sequencing 57 22 1 Sequence Strategies 2 2 CH nn nn 57 23 Advanced 65 23 1 Composite Primary Keys nn 65 23 2 Primary Keys through OneToOne and ManyToOne Relationships 69 23 3 Advanced Sequence 73 23 4 Primary Keys through Triggers 2 22 o e 0020220004 74 23 5 Primary Keys through Events o e 0020820004 75 23 6 No Primary Key slo e AE et 75 23 7 Single Table Inheritance o 77 23 8 Joined Multiple Table Inheritance 0 79 24 Advanced 83 24 1 Table Per Class Inheritance 02 00 0000 0004 83 24 2 Mapped Superclasses 2 222 ee ee 84 25 Embeddables 89 26 Advanced 93 26 1 Sharing wou ei wale a BK we bat a ea AE e T 93 26 2 Embedded lds 2 eee ee ee es 94 26 37 Nuls von 22 a eR eh Ee ech ke bo AS 94 26 4 N Stin gg 20s se a ae ee A Bt ee ee Beh ne 95 26 5 Inherit fiee a a ne Aes an oe Sl ae 96 26 6 Relationships ss s ss 62 04 46 sauna na da nr mean be 96 26 1 Collections 2222 02 pie an manner ae na 97 26 8 Querying 2020 De A a A eS aS 98 27 Locking 99 27 1 Optimistic Locking 0 0 0 0 0000 eee ee eee 99 27 2 Advanced o ru 34 24 ee a RE ee ee ee eG 104 28 Basics 111 28 1 Common Problems sa cerem ce ba 20 0002 eee ee ee eee 113 29 Advanced 115 29 1 Temporal Dates Times Timestamps and Calendars 1
43. a JTA DataSource for JPA and your JDBC access to have them share the same global transaction If you are not using JEE or not using JTA then you may be able to access the JDBC connection directly from your JPA provider Some JPA providers provide an API to access a raw JDBC connection from their internal connection pool or from their transaction context In JPA 2 0 this API is somewhat standardized by the unwrap API on EntityManager 24 Chapter 41 4 on page 198 231 Advanced To access a JDBC connection from an EntityManager some JPA 2 0 providers may support java sql Connection connection entityManager unwrap java sql Connection class This connection could then be used for raw JDBC access It normally should not be close when finished as the connection is being used by the EntityManager and will be released when the EntityManager is closed or transaction committed Querying Querying 7 25 http en wikibooks org wiki Category 3AJava 20Persistence 26 http en wikibooks org wiki Category 3AJava 20Persistence 2FRuntime 232 46 JPQL BNF The following defines the structure of the JPQL query language For further examples and usage see Querying or optional repeatable zero or more times mandatory QL_ statement select statement update statement delete statement 46 1 Select Select employee from Employee employee join employee address address where address
44. a cast operation JPA 2 0 may define this so querying on an attribute of a subclass is not obvious This can be done indirectly however if you add a secondary join to the subclass to the query Select e from Employee e join employee projects p LargeProject lproject where p lproject and lproject budget gt 1000000 44 6 6 How to select the first element in a collection To query the employees first project for a particular employee There are a few different ways to do this some using straight JPQL and some using the Query setMaxResuls API If a JPA 2 0 indexed list is used to map the collection then the INDEX function can be used setMaxResults Query query em createQuery Select e projects from Employee e where e id id query setMaxResults 1 Query query em createQuery Select p from Employee e join e projects p where e id id query setMaxResults 1 JPQL Select p from Project p where p id Select MAX p2 id from Employee e join e projects p2 where e id id JPA 2 0 Select p from Employee e join e projects p where e id id and INDEX p 1 44 6 7 How to order by the size of a collection To query all employees ordered by the number of projects There are a few different ways to do this some end up using sub selects in SQL and some use group by Depending on your JPA provider and database you solution may be limited to one or the other Using SIZE function uses sub select in SQL Select e
45. a ee ae re 264 51 5 Query Cache 2 242 0022 hee seek Be Ee awe Ea de 265 16 StalexDataes st cance e Poe ane hed Sate Sad BR ne el ds 265 51 7 Cache Transaction Isolation m mn 271 51 8 Common Problems 2 m nn nn 271 VII Contents 52 Spring 273 592 1 y Persistence x sans a een Paks E a A AD 273 D22 s PAS va en a ee NN 273 53 Databases 275 54 MySQL 277 54 1 Installing s eoe 2 2 fa Re Re Sache de ee a ana Re 277 54 2 Configtration tips e s oo r e tersa Dae ee eee a 277 55 References 279 56 Contributors 281 List of Figures 283 57 Licenses 287 57 1 GNU GENERAL PUBLIC LICENSE 287 57 2 GNU Free Documentation License 0 0 0 0 000004 288 57 3 GNU Lesser General Public License 2 2 2 2 2 m Emm nn 289 1 Preface gt 1 0 1 What is this book about This book is meant to cover Java persistence that is storing stuff in the Java programming language to a persistent storage medium Specifically using the Java Persistence API JPA to store Java objects to relational databases but I would like it to have a somewhat wider scope than just JPA and concentrate more on general persistence patterns and use cases after all JPA is just the newest of many failed Java persistence standards this book should be able to evolve beyond JPA when it is replaced by the next persistence standard I do not want this to be just a regurgitation of the JPA Spec nor a User Manual to using one
46. all of the related objects will need to be traversed and checked if they reference any new objects This can actually lead to n 2 performance issues if you mark all relationships cascade persist and persist a large new graph of objects If you just call persist on the root object this is ok However if you call persist on each object in the graph then you 242 Merge will traverse the entire graph for each object in the graph and this can lead to a major performance issue The JPA spec should probably define persist to only apply to new objects not already part of the persistence context but it requires persist apply to all objects whether new existing or already persisted so can have this issue A second issue is that if you remove an object to have it deleted if you then call persist on the object it will resurrect the object and it will become persistent again This may be desired if it is intentional but the JPA spec also requires this behavior for cascade persist So if you remove an object but forget to remove a reference to it from a cascade persist relationship the remove will be ignored I would recommend only marking relationships that are composite or privately owned as cascade persist 47 2 Merge The EntityManager merge operation is used to merge the changes made to a detached object into the persistence context merge does not directly update the object into the database it merges the changes into the per
47. also notice additional variables when in a debugger but in general debugging will still work as normal 30 1 4 Basics A Basic attribute can also be made LAZY but this is normally a different mechanism than lazy relationships and should normally be avoided unless the attribute is rarely accessed See Basic Attributes Lazy Fetching 30 1 5 Serialization and Detaching A major issue with lazy relationships is ensuring that the relationship is still available after the object has been detached or serialized For most JPA providers after serialization any lazy relationship that was not instantiated will be broken and either throw an error when accessed or return null The naive solution is to make every relationship eager Serialization suffers from the same issue as persistence in that you can very easily serialize your entire database if you have no lazy relationships So lazy relationships are just as necessary for serialization as they are for database access however you need to ensure you have everything you will need after serialization instantiated upfront You may mark only the relationships that you think you will need after serialization as EAGER this will work however there are probably many cases when you do not need these relationships 9 Chapter 29 4 on page 119 127 Relationships A second solution is to access any relationship you will need before returning the object for serialization This has the a
48. be accessible if they were not accessed before the EntityManager was closed Some JPA providers allow LAZY relationships to be accessed after close Example close public Order findOrder long id EntityManager em factory createEntityManager Order order em find Order class id order getOrderLines size em close return order 48 7 Get Delegate The EntityManager getDelegate operation is used to access the JPA provider s EntityManager implementation class in a JEE managed EntityManager A JEE managed EntityManager will be wrapped by a proxy EntityManager by the JEE server that forwards requests to the EntityManager active for the current JTA transaction If a JPA provider 9 https java sun com javaee 5 docs api javax persistence EntityManager html close https java sun com javaee 5 docs api javax persistence EntityManager html getDelegate 250 Unwrap JPA 2 0 specific API is desired the getDelegate API allows the JPA implementation to be accessed to call the API In JEE a managed EntityManager will typically create a new EntityManager per JTA transaction Also the behavior is somewhat undefined outside of a JTA transaction context Outside a JTA transaction context a JEE managed EntityManager may create a new EntityManager per method so getDelegate may return a temporary EntityManager or even null Another way to access the JPA implementation is through the EntityManagerFactory whic
49. be available but could cause a query for each employee for its address This reduces n 1 queries to 1 query Join fetch SELECT e FROM Employee e JOIN FETCH e address Join fetch can also be used on collection relationships SELECT e FROM Employee e JOIN FETCH e address JOIN FETCH e phones Outer joins can be used to avoid null and empty relationships from filtering the results SELECT e FROM Employee e LEFT OUTER JOIN FETCH e address LEFT OUTER JOIN FETCH e phones You can also select multiple objects in a query but note that this does not instantiate the relationship so accessing the relationship could still trigger another query SELECT e a FROM Employee e Address a WHERE e address a 44 6 4 Inverse ManyToMany all employees for a given project To query all employees for a given project where the employee project relationship is a ManyToMany If the relationship is bi directional you could use Select p employees from Project p where p name name If it is uni directional you could use Select e from Employee e Project p where p name name and p member of e projects or Select e from Employee e join employee projects p where p name name 221 Querying 44 6 5 How to simulate casting to a subclass To query all employees who have a large project with a budget greater than 1 000 000 where the employee only has a relationship to Project not to the LargeProject subclass JPA 1 0 JPQL does not define
50. be used for any relationship including OneToMany and ManyToMany Join fetching is one solution to the classic ORM n 1 performance problem The issue is if you select n Employee objects and access each of their addresses in basic ORM including JPA you will get 1 database select for the Employee objects and then n database selects one for each Address object Join fetching solves this issue by only requiring one select and selecting both the Employee and its Address 145 Advanced JPA supports join fetching through JPQL using the JOIN FETCH syntax Example of JPQL Join Fetch SELECT emp FROM Employee emp JOIN FETCH emp address This causes both the Employee and Address data to be selected in a single query 31 3 1 Outer Joins Using the JPQL JOIN FETCH syntax a normal INNER join is performed This has the side effect of filtering any Employee from the result set that did not have an address An OUTER join in SQL is one that does not filter absent rows on the join but instead joins a row of all null values If your relationship allows null or an empty collection for collection relationships then you can use an OUTER join fetch this is done in JPQL using the LEFT syntax Note that OUTER joins can be less efficient on some databases so avoid using an OUTER if it is not required Example of JPQL Outer Join Fetch SELECT emp FROM Employee emp LEFT JOIN FETCH emp address 31 3 2 Mapping Level Join Fetch and EAGER JPA has n
51. because the object has a version that is not null and greater than 0 and the object does not exist But this is probably JPA provider specific some may re insert the object this would occur without locking or throw a different exception If you called persist instead of merge then the object would be re inserted What if my table doesn t have a version column The best solution is probably just to add one Field locking is another solution as well as pessimistic locking in some cases See Field Locking What about relationships See Cascaded Locking 7 Chapter 27 2 9 on page 109 8 Chapter 27 2 4 on page 105 9 Chapter 27 2 3 on page 105 103 Locking Can I use a timestamp See Timestamp Locking Do I need a version in each table for inheritance or multiple tables The short answer is no only in the root table See Multiple Versions 27 2 Advanced 27 2 1 Timestamp Locking Timestamp version locking is supported by JPA and is configured the same as numeric version locking except the attribute type will be a java sql Timestamp or other date time type Be cautious in using timestamp locking as timestamps have different levels of precision in different databases and some database do not store a timestamp s milliseconds or do not store them precisely In general timestamp locking is less efficient than numeric version locking so numeric version locking is recommended Timestamp locking is frequentl
52. both tables such that the secondary table s Id column s are the primary key of the secondary table and a foreign key to the first table If the first table s Id column s are not named the same the CPrimaryKeyJoinColumn or lt primary key join column gt can be used to define the foreign key join condition In a multiple table entity each mapping must define which table the mapping s columns are from This is done using the table attribute of the Column or JoinColumn annotations or XML elements By default the primary table of the class is used so you only need to set the table for secondary tables For inheritance the default table is the primary table of the subclass being mapped 20 1 1 Example mapping annotations for an entity with multiple tables Entity Table name EMPLOYEE SecondaryTable name EMP_DATA pkJoinColumns PrimaryKeyJoinColumn name EMP_ID referencedColumnName ID public class Employee Column name YEAR_OF_SERV table EMP_DATA private int yearsOfService OneToOne JoinColumn name MGR_ID table EMP_DATA referencedColumnName ID private Employee manager 20 1 2 Example mapping XML for an entity with multiple tables lt entity name Employee class org acme Employee access FIELD gt lt table name EMPLOYEE gt lt secondary table name EMP_DATA gt lt primary key join column name EMP_ID referenced column name ID gt lt secondary table gt lt attri
53. cell fax work AREACODE 613 613 416 416 Example of a map key join column relationship annotation Entity public class Employee Old private long id COneToMany mappedBy owner MapKeyJoinColumn name PHONE_TYPE_ID private Map lt PhoneType Phone gt phones Ab Entity public class Phone Old private long id ManyToOne private Employee owner Entity public class PhoneType Old private long id Basic private String type SALARY 50000 60000 NUMBER 792 7777 798 6666 792 9999 798 5595 143 Advanced Example of a map key join column relationship XML lt entity name Employee class org acme Employee access FIELD gt lt attributes gt lt id name id gt lt one to many name phones mapped by owner gt lt map key join column name PHONE_TYPE_ID gt lt one to many gt lt attributes gt lt entity gt lt entity name Phone class org acme Phone access FIELD gt lt attributes gt lt id name id gt lt many to one name owner gt lt attributes gt lt entity gt lt entity name PhoneType class org acme PhoneType access FIELD gt lt attributes gt lt id name id gt lt basic name type gt lt attributes gt lt entity gt Example of a map key class embedded relationship database EMPLOYEE table ID FIRSTNAME LASTNAME SALARY 1 Bob Way 50000 2 Sarah Smith 60000 EMPLOYEE_ PHONE table EMPLOYEE _ ID PHONE _ID TY
54. city city and employee firstName like name order by employee firstName select_ statement select_clause from clause where_clause groupby_clause having_clause orderby_ clause 46 1 1 From FROM Employee employee JOIN FETCH employee address LEFT OUTER JOIN FETCH employee phones JOIN employee manager manager Employee ceo from_clause FROM identification_variable_declaration identification_variable_declaration collection_member_declaration identification_variable_declaration range_variable_declaration join fetch_join Chapter 43 2 3 on page 213 Chapter 46 1 2 on page 234 Chapter 46 2 on page 237 Chapter 46 3 on page 238 Chapter 46 1 2 on page 234 Chapter 46 1 1 on page 233 Chapter 46 1 3 on page 235 Chapter 46 1 5 on page 237 Chapter 46 1 5 on page 237 0 Chapter 46 1 6 on page 237 FOMAONDOBRWNEFE 233 JPQL BNF range_variable_declaration abstract_schema_name AS identification_variable join join_spec join_association_path_expression AS identification_variable fetch_join join_spec FETCH join_association_path_expression association_path_expression collection_valued_path_expression single_valued_association_path_expression join_spec LEFT OUTER INNER JOIN join_association_path_expression join_collection_valued_path_expression join_single_valued_association_path_expression join_collection_valued_path_expression identifica
55. emp where emp address city city query setParameter city Ottawa query setHint acme jpa batch emp address List lt Employee gt employees query getResultList https java sun com javaee 5 docs api javax persistence EntityManager html createQuery java lang String 16 https java sun com javaee 5 docs api javax persistence Query html 217 Querying 44 2 1 Criteria API JPA 2 0 See Criteria APT 44 3 JPQL See JPQL 44 4 Parameters Parameters are defined in JPQL using the syntax i e Select e from Employee e where e id id The parameter values are set on the Query using the Query setParameter API Parameters can also be defined using the mainly for native SQL queries You can also use lt int gt These are positional parameters not named parameters and are set using the Query API Query setParameter The int is the index of the parameter in the SQL Positional parameters start a 1 not 0 Some JPA providers also allow the syntax for native queries For temporal parameters Date Calendar you can also pass the temporal type depending on if you want the Date Time or Timestamp from the value Parameters are normally basic values but you can also reference object s if comparing on their Id i e Select e from Employee e where e address address can take the Address object as a parameter The parameter values are always at the object level when comparing to a m
56. for shared libraries and dynamically linked subprograms that the work is specifically designed to require such as by intimate data communication or control flow between those subprograms and other parts of the work The Corresponding Source need not include any thing that users can regenerate automatically from other parts of the Corresponding Source The Corresponding Source for a work in source code form is that same work 2 Basic Permissions All rights granted under this License are granted for the term of copyright on the Program and are irrevocable provided the stated conditions are met This License explicitly affirms your unlimited per mission to run the unmodified Program The out put from running a covered work is covered by this License only if the output given its content con stitutes a covered work This License acknowledges your rights of fair use or other equivalent as pro vided by copyright law You may make run and propagate covered works that you do not convey without conditions so long as your license otherwise remains in force You may convey covered works to others for the sole purpose of having them make modifications exclusively for you or provide you with facilities for running those works provided that you comply with the terms of this License in conveying all material for which you do not control copyright Those thus making or running the covered works for you must do so exclu sively on your beh
57. from several columns or there is an discriminator but not a one to one mapping from value to class Some JPA providers provide extended support for this Another option is to create a database view that manufactures the discriminator column and then map your hierarchy to this view instead of the table In general the best solution is just to add a discriminator column to the table truth be told ALTER TABLE is your best friend in ORM TopLink EclipseLink Support computing the inheritance discriminator through Java code This can be done through using a DescriptorCustomizer and the ClassDescriptor s InheritancePolicy s setClassExtractor method Hibernate This can be accomplished through using the Hibernate DiscriminatorFormula annotation This allows database specific SQL or func tions to be used to compute the discriminator value Non nullable attributes Subclasses cannot define attributes as not allowing null as the other subclasses must insert null into those columns A workaround to this issue is instead of defining a not null constraint on the column define a table constraint that check the discriminator value and 24 Chapter 11 on page 25 25 Chapter 10 on page 23 26 Chapter 12 on page 27 78 Joined Multiple Table Inheritance the not nullable value In general the best solution is to just live without the constraint odds are you have enough constraints in your life to deal with as it is 23 8 Joined
58. from an entity transaction each party to that transaction who receives a copy of the work also receives whatever licenses to the work the party s predecessor in interest had or could give un der the previous paragraph plus a right to posses sion of the Corresponding Source of the work from the predecessor in interest if the predecessor has it or can get it with reasonable efforts You may not impose any further restrictions on the exercise of the rights granted or affirmed under this License For example you may not impose a license fee royalty or other charge for exercise of rights granted under this License and you may not ini tiate litigation including a cross claim or counter claim in a lawsuit alleging that any patent claim is infringed by making using selling offering for sale or importing the Program or any portion of it 11 Patents A contributor is a copyright holder who autho rizes use under this License of the Program or a work on which the Program is based The work thus licensed is called the contributor s contribu tor version A contributor s essential patent claims are all patent claims owned or controlled by the contribu tor whether already acquired or hereafter acquired that would be infringed by some manner permit ted by this License of making using or selling its contributor version but do not include claims that would be infringed only as a consequence of further modifica
59. graph html 23 Chapter 11 on page 25 24 Chapter 10 on page 23 148 Nested Collections Maps and Matrices In general JPA does not support variable interface or heterogeneous relationships JPA does support relationships to inheritance classes so the easiest workaround is normally to define a common superclass for the related values Another solution is to define virtual attributes using get set methods for each possible implementer and map these separately and mark the heterogeneous get set as transient You could also not map the attribute and instead query for it as required For heterogeneous Basic or Embeddable relationships one solution is to serialize the value to a binary field You could also convert the value to a String representation that you can restore the value from or store the value to two columns one storing the String value and the other the class name or type Some JPA providers have support for interfaces variable relationships and or heterogeneous relationships TopLink EclipseLink Support variable relationships through their VariableOneToOne annotation and XML Mapping to and querying interfaces are also supported through their ClassDescriptor s InterfacePolicy API 31 7 Nested Collections Maps and Matrices It is somewhat common in an object model to have complex collection relationships such as a List of Lists i e a matrix or a Map of Maps or a Map of Lists and so on Unfortunately
60. gt element An embeddable object cannot be directly persisted or queried it can only be persisted or queried in the context of its parent An embeddable object does not have an id or table 1 https java sun com javaee 5 docs api javax persistence Embeddable html 2 Chapter 26 8 on page 98 89 Embeddables The JPA spec does not support embeddable objects having inheritance although some JPA providers may allow this Relationships from embeddable objects are supported in JPA 2 0 Relationships to embeddable objects are defined through the Embedded annotation or lt embedded gt element The JPA 2 0 spec also supports collection relationships to embeddable objects 25 0 5 Example of an Embeddable object annotations Embeddable public class EmploymentPeriod Column name START_DATE private java sql Date startDate Column name END_DATE private java sql Date endDate 25 0 6 Example of an Embeddable object XML lt embeddable class org acme EmploymentPeriod access FIELD gt lt attributes gt lt basic name startDate gt lt column name START_DATE gt lt basic gt lt basic name endDate gt lt column name END_DATE gt lt basic gt lt attributes gt lt embeddable gt 25 0 7 Example of an embedded relationship annotations OEntity public class Employee Old private long id CEmbedded private EmploymentPeriod period 25 0 8 Example of an embedded relationship XML
61. if no constraints are defined it may be possible to have duplicate data inserted persist can only be called on Entity objects not on Embeddable objects or collections or non persistent objects Embeddable objects are automatically persisted as part of their owning Entity Calling persist is not always required If you related a new object to an existing object that is part of the persistence context and the relationship is cascade persist then it will be automatically inserted when the transaction is committed or when the persistence context is flushed Example persist EntityManager em getEntityManager em getTransaction begin Employee employee new Employee employee setFirstName Bob Address address new Address address setCity Ottawa employee setAddress address em persist employee em getTransaction commit 47 1 1 Cascading Persist Calling persist on an object will also cascade the persist operation to across any relation ship that is marked as cascade persist If a relationship is not cascade persist and a related object is new then an exception may be thrown if you do not first call persist on the related object Intuitively you may consider marking every relationship as cascade persist to avoid having to worry about calling persist on every objects but this can also lead to issues One issue with marking all relationships cascade persist is performance On each persist call
62. in connection with specific products or compilations that contain the covered work unless you entered into that arrangement or that patent license was granted prior to 28 March 2007 Nothing in this License shall be construed as ex cluding or limiting any implied license or other de fenses to infringement that may otherwise be avail able to you under applicable patent law 12 No Surrender of Others Freedom Tf conditions are imposed on you whether by court order agreement or otherwise that contradict the conditions of this License they do not excuse you from the conditions of this License If you cannot convey a covered work so as to satisfy simultane ously your obligations under this License and any other pertinent obligations then as a consequence you may not convey it at all For example if you agree to terms that obligate you to collect a roy alty for further conveying from those to whom you convey the Program the only way you could satisfy both those terms and this License would be to re frain entirely from conveying the Program 13 Use with the GNU Affero General Public License 57 2 GNU Free Documentation License Version 1 3 3 November 2008 Copyright O 2000 2001 2002 2007 2008 Free Soft ware Foundation Inc lt http fsf org gt Everyone is permitted to copy and distribute verba tim copies of this license document but changing it is not allowed 0 PREAMBLE The purpose of this License is t
63. insertable updatable false See Target Foreign Keys Primary Key Join Columns Cascade Primary Keys Constraint error on insert This typically occurs because you have incorrectly mapped the foreign key in a OneToOne relationship See Target Foreign Keys Primary Key Join Columns Cascade Primary Keys It can also occur if your JPA provider does not support referential integrity or does not resolve bi directional constraints In this case you may either need to remove the constraint or use EntityManager flush to ensure the order your objects are written in Foreign key value is null Ensure you set the value of the object s OneToOne if the OneToOne is part of a bi directional OneToOne relationship ensure you set OneToOne in both object s JPA does not maintain bi directional relationships for you Also check that you defined the JoinColumn correctly ensure you did not set insertable updatable false or use a PrimaryKeyJoinColumn or mappedBy 16 Chapter 33 1 on page 157 17 Chapter 33 1 on page 157 156 33 Advanced 33 1 Target Foreign Keys Primary Key Join Columns Cascade Primary Keys If a OneToOne relationship uses a target foreign key the foreign key is in the target table not the source table then JPA requires that you define a OneTo0ne mapping in both directions and that the target foreign key mapping use the mappedBy attribute The reason for this is the mapping in the source object only affect
64. is newer than the version value from the object in the cache then the object is refreshed as it is stale otherwise the cache value is returned This option provides optimal caching and avoids stale data on queries However objects returned through find or through relationships 21 Chapter 48 1 on page 247 267 Caching can still be stale Some JPA providers also allow find operation to be configured to first check the database but this general defeats the purpose of caching so you are better off not using a 2nd level cache at all If you want to use a 2nd level cache then you must have some level of tolerance to stale data 51 6 4 JPA 2 0 Cache APIs JPA 2 0 provides a set of standard query hints to allow refreshing or bypassing the cache The query hints are defined on the two enum classes CacheRetrieveMode and Cache StoreMode Query hints e javax persistence cache retrieveMode CacheRetrieveMode e BYPASS Ignore the cache and build the object directly from the database result e USE Allow the query to use the cache If the object data is already in the cache the cached object data will be used e javax persistence cache storeMode CacheStoreMode e BYPASS Do not cache the database results e REFRESH If the object data is already in the cache then refresh replace it with the database results e USE Cache the objects data returned from the query Cache hints example Query query em createQuery Sel
65. iy firstName String managedEmployees lastName String nee id long salary BigDecimal 1 type String number String eee areaCode String manager y 1 EMP_ID NUMBER FK_MANAGER_ID F_NAME VARCHAR se Nine da OWNER JID NUMBER MANAGER_ID NUMBER 1 FK_OWNER_ID TYPE VARCHAR a P_NUMBER VARCHAR AREA_CODE VARCHAR Figure 16 A OneToMany relationship in Java is where the source object has an attribute that stores a collection of target objects and if those target objects had the inverse relationship back to the source object it would be a ManyToOne relationship All relationships in Java and JPA are unidirectional in that if a source object references a target object there is no guarantee that the target object also has a relationship to the source object This is different than a relational database in which relationships are defined through foreign keys and querying such that the inverse query always exists JPA also defines a ManyToMany relationship which is similar to a OneToMany relationship except that the inverse relationship if it were defined is a ManyToMany relationship The main difference between a OneToMany and a ManyToMany relationship in JPA is that a ManyToMany always makes use of a intermediate relational join table to store the relationship where as a OneToMany can either use a join table or a foreign key in target object s table referencing the source object table
66. keys would be much simpler if they were just defined on the entity using a collection of Columns instead of mixing them up with the attribute mapping This would leave you free to map the primary key field in any manner you desired A generic List could be used to pass the primary key to find methods and it would be the JPA provider s responsibility for hashing and comparing the primary key correctly instead of the user s IdClass But perhaps for simple singleton primary key models the JPA model is more straight forward TopLink EclipseLink Allow the primary key to be specified as a list of columns instead of using Id mappings This allows OneToOne and ManyToOne mapping foreign keys to be used as the primary key without requiring a duplicate mapping It also allows the primary key to be defined through any other mapping type This is set through using a DescriptorCustomizer and the ClassDescriptor addPrimaryKeyFieldName API Hibernate Open JPA EclipseLink as of 1 2 Allows the Id annotation to be used on a OneToOne or ManyToOne mapping Example OneToOne id annotation Entity public class Address Id Column name OWNER_ID private long ownerld OneToOne PrimaryKeyJoinColumn name OWNER_ID referencedColumnName EMP_ID private Employee owner public void setOwner Employee owner this owner owner this ownerId owner getId Example OneToOne id XML lt entity name Address class org acm
67. locking will avoid writes occurring on stale data When an optimistic lock exception occurs some JPA providers will automatically refresh or invalidate the object in the cache so if the user or application retries the transaction the next write will succeed Your application could also catch the lock exception and refresh or invalidate the object and potentially retry the transaction if the user does not need to be notified of the lock error be careful doing this though as normally the user should be aware of the lock error Cache invalidation can also be used to decrease the likelyhood of stale data by setting a time to live on the cache The size of the cache can also affect the occurrence of stale data Although returning stale data to a user may be an issue normally returning stale data to a user that just updated the data is a bigger issue This can normally be solved through session infinitely but ensuring the user interacts with the same machine in the cluster for the duration of their session This can also improve cache usage as the same user will typically access the same data It is normally also useful to add a refresh button to the UI this will allow the user to refresh their data if they think their data is stale or they wish to ensure 27 Chapter 11 on page 25 28 Chapter 10 on page 23 269 Caching they have data that is up to date The application can also choose the refresh the objects in places where up to date da
68. lt join column name ADDR_ID gt lt one to one gt 7 Chapter 31 1 on page 139 8 https java sun com javaee 5 docs api javax persistence FetchType html 126 Lazy Fetching lt attributes gt lt entity gt 30 1 3 Magic Lazy fetching normally involves some sort of magic in the JPA provider to transparently fault in the relationships as they are accessed The typical magic for collection relationships is for the JPA provider to set the relationships to its own Collection List Set or Map implementation When any or most method is accessed on this collection proxy it loads the real collection and forwards the method This is why JPA requires that all collection relationships use one of the collection interfaces although some JPA providers support collection implementations too For OneToOne and ManyToOne relationships the magic normally involves some sort of byte code manipulation of the entity class or creation of a subclass This allows the access to the field or get set methods to be intercepted and for the relationships to be first retrieved before allowing access to the value Some JPA providers use different methods such as wrapping the reference in a proxy object although this can have issues with null values and primitive methods To perform the byte code magic normally an agent or post processor is required Ensure that you correctly use your providers agent or post processor otherwise lazy may not work You may
69. mapping The Id used for the object will be derived from the target object s Id If the Id is a single value then the source object s Id is the same as the target object s Id If it is a composite Id then the 71 Advanced IdClass will contain the Basic Id attributes and the target object s Id as the relationship value If the target object also has a composite Id then the source object s IdClass will contain the target object s IdClass Example JPA 2 0 ManyToOne id annotation Entity IdClass PhonePK class public class Phone Id private String type ManyToOne Id JoinColumn name OWNER_ID referencedColumnName EMP_ID private Employee owner getters and setters Example JPA 2 0 ManyToOne id XML lt entity name Address class org acme Address access FIELD gt lt id class class org acme PhonePK gt lt attributes gt lt id name type gt lt many to one name owner id true gt lt join column name OWNER_ID referencedColumnName EMP_ID gt lt many to one gt lt attributes gt lt entity gt Example JPA 2 0 id class public class PhonePK private String type private long owner public PhonePK public PhonePK String type long owner this type type this owner owner public boolean equals Object object if object instanceof PhonePK PhonePK pk PhonePK object return type equals pk type amp amp owner pk owner else return false
70. mechanisms mainly defined though the Inheritance annotation or the lt inheritance gt element There are three inheritance strategies defined from the InheritanceType enum SINGLE_TABLE TABLE_PER_CLASS and JOINED Single table inheritance is the default and table per class is an optional feature of the JPA spec so not all providers may support it JPA also defines a mapped superclass concept defined 21 https java sun com javaee 5 docs api javax persistence Inheritance html 22 https java sun com javaee 5 docs api javax persistence InheritanceType html 76 Single Table Inheritance though the MappedSuperclass annotation or the lt mapped superclass gt element A mapped superclass is not a persistent class but allow common mappings to be define for its subclasses 23 7 Single Table Inheritance Single table inheritance is the simplest and typically the best performing and best solution In single table inheritance a single table is used to store all of the instances of the entire inheritance hierarchy The table will have a column for every attribute of every class in the hierarchy A discriminator column is used to determine which class the particular row belongs to each class in the hierarchy defines its own unique discriminator value 23 7 1 Example single table inheritance table PROJECT table ID PROJ_TYPE NAME BUDGET 1 L Accounting 50000 2 S Legal null 23 7 2 Example single table inheritance annotatio
71. object In JPA 1 0 even if your relationship is cascade REMOVE you still must call remove only the remove of the parent object is cascaded not removal from the collection JPA 2 0 will provide an option for having removes from the collection trigger deletion Some JPA providers support an option for this in JPA 1 0 See Cascading My relationship target is an interface If your relationship field s type is a public interface of your class and only has a single implementer then this is simple to solve you just need to set a targetEntity on your mapping See Target Entity If your interface has multiple implementers then this is more complex JPA does not directly support mapping interfaces One solution is to convert the interface to an abstract class and use inheritance to map it You could also keep the interface create the abstract class and make sure each implementer extends it and set the targetEntity to be the abstract class Another solution is to define virtual attributes using get set methods for each possible implementer and map these separately and mark the interface get set as transient You could also not map the attribute and instead query for it as required See Variable and Heterogeneous Relationships Some JPA providers have support for interfaces and variable relationships TopLink EclipseLink Support variable relationships through their VariableOneToOne annotation and XML Mapping to and
72. of the JPA products but more focused on real world use cases of users and applications trying to make use of JPA or other Java persistence solution and the patterns they evolved and pitfalls they made 1 0 2 Intended Audience This book is intended to be useful for or to anyone learning to or developing Java applications that require persisting data to a database It is mainly intended for Java developers intending to persist Java objects through the Java Persistence API JPA standard to a relational database Please don t just read this book if you re learning or developing with JPA please contribute your experiences to this book 1 0 3 Style This book is meant to be written in a casual manner The goal is avoid sounding dry overly technical or impersonal The book should sound casual like a co worker explaining to you how to use something or a fellow consultant relating their latest engagement to another Please refrain from being overly critical of any product ranting about bugs or marketing your own product or services Preface G 1 0 4 Authors Everyone is encouraged to participate in the ongoing development of this book You do not need to be a Java persistence superstar to contribute many times the best advice information for other users comes from first time users who have not yet been conditioned to think something that may be confusing is obvious List of authors please contribute and sign your name
73. operation for an Entity with a stored procedure or custom SQL Some JPA providers have support for CURSOR OUTPUT parameters TopLink EclipseLink Support stored procedures and stored functions using the NamedStoredProcedureQuery NamedStoredFunctionQuery annotations or XML or the StoredProcedureCall StoredFunctionCall classes Overriding any CRUD opera tion for a class or relationship are also supported using a DescriptorCustomizer and the 17 Chapter 11 on page 25 18 Chapter 10 on page 23 198 Structured Object Relational Data Types DescriptorQueryManager class IN OUT INOUT and CURSOR OUTPUT parameters are supported Example executing a stored procedure on Oracle EntityManager em getEntityManager Query query em createNativeQuery BEGIN VALIDATE_EMP P_EMP_ID gt END query setParameter 1 empld query executeUpdate 41 4 1 PL SQL Stored Procedures In Oracle stored procedures are typically written in Oracle s PL SQL language PL SQL in Oracle supports some additional data types that Oracle does not support through SQL or JDBC These include types such as BOOLEAN TABLE and RECORD Accessing these types or procedures is difficult from Java as these types are not supported by JDBC One workaround is to wrap the PL SQL stored procedures with normal stored procedures that transform the PL SQL types to standard SQL JDBC types such as INT VARRAY Array and OBJECT TYPE Struct Some JPA
74. original publisher of the version it refers to gives permission K For any section Entitled Acknowledgements or Dedications Preserve the Title of the section and preserve in the section all the substance and tone of each of the contributor acknowledgements and or dedications given therein L Preserve all the Invariant Sections of the Document unaltered in their text and in their titles Section numbers or the equivalent are not considered part of the section titles M Delete any section Entitled Endorse ments Such a section may not be included in the Modified Version N Do not retitle any existing section to be Entitled Endorsements or to conflict in title with any Invariant Section O Preserve any Warranty Disclaimers If the Modified Version includes new front matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document you may at your option designate some or all of these sections as invariant To do this add their titles to the list of Invariant Sections in the Modified Version s license notice These titles must be distinct from any other section titles You may add a section Entitled Endorsements provided it contains nothing but endorsements of your Modified Version by various parties for ex ample statements of peer review or that the text has been approved by an organization as the au thoritative definition of a standard You may add a passa
75. page 150 12 Chapter 33 2 on page 161 13 Chapter 35 1 on page 169 14 Chapter 22 1 1 on page 58 15 Chapter 35 1 on page 169 16 Chapter 35 1 on page 169 167 ManyToOne It can also occur if your JPA provider does not support referential integrity or does not resolve bi directional constraints In this case you may either need to remove the constraint or use EntityManager flush to ensure the order your objects are written in Foreign key value is null Ensure you set the value of the object s OneToOne if the OneToOne is part of a bi directional OneToMany relationship ensure you set the object s OneToOne when adding an object to the OneToMany JPA does not maintain bi directional relationships for you Also check that you defined the JoinColumn correctly ensure you did not set insertable updateable false or use a PrimaryKeyJoinColumn 168 35 Advanced 35 1 Target Foreign Keys Primary Key Join Columns Cascade Primary Keys In complex data models it may be required to use a target foreign key or read only JoinColumn in mapping a ManyToOne if the foreign key JoinColumn is shared with other ManyToOne or Basic mappings See Target Foreign Keys Primary Key Join Columns Cascade Primary Keys ManyToOne ManyToOne 1 Chapter 33 1 on page 157 2 http en wikibooks org wiki Category 3AJava 20Persistence 3 http en wikibooks org wiki Category 3AJava 20Persistence 2FMapping 169 36 OneToMany id long
76. part of the data You can partition the data by the data values such as range partitioning value partitioning hash partitioning or even round robin JPA does not define any data partitioning support so you either need to define a different class per partition or use JPA vendor specific functionality TopLink EclipseLink Support both horizontal and vertical data par titioning Hash value range pinned and custom partitioning is supported at the Session Entity and Query level Partitioning is support through the Partitioning HashPartitioning RangePartitioning ValuePartitioning PinnedPartitioning and Partitioned annotations and XML See also e Data Partitioning Scaling the Database Blog 41 13 Data Integration 41 14 NoSQL and EIS legacy XML and non relational data See NoSQL 33 Chapter 11 on page 25 34 Chapter 10 on page 23 35 http java persistence performance blogspot com 2011 05 data partitioning scaling database html 36 http en wikibooks org wiki Java_Persistence 2FNoSQL 204 Multi Tenancy 41 15 Multi Tenancy 41 16 Dynamic Data Advanced Topics 37 http en wikibooks org wiki Category 3AJava 20Persistence 205 42 Runtime Once you have mapped your object model the second step in persistence development is to access and process your objects from your application this is referred to as the runtime usage of persistence Various persistence specification
77. providers have extended support for calling PL SQL stored procedures TopLink EclipseLink Support PL SQL stored procedures and functions us ing the NamedPLSQLStoredProcedureQuery NamedPLSQLStoredFunctionQuery anno tations or XML or the PLSQLStoredProcedureCall PLSQLStoredFunctionCall classes 41 5 Structured Object Relational Data Types Back in the hay day of object oriented databases OODBMS many of the relational database vendors decided to added object oriented concepts to relational data These new hybrid databases were called Object Relational in that they could store both object and relational data These object relational data types were standardized as part of SQL3 and support was added for them from Java in the JDBC 2 0 API Although there was lots of hype around the new forms of data object relational data never caught on much as people seemed to prefer their standard relational data I would not normally recommend using object relational data as relational data is much more standard but if you have really complex data it may be something to investigate Some common object relational database features include e Object types structures e Arrays and array types e Nested tables e Inheritance 19 Chapter 11 on page 25 20 Chapter 10 on page 23 199 Advanced Topics e Object ids OIDs e Refs Databases that support object relational data include e Oracle e DB2 e PostgreSQL The basic model
78. requires special permis sion from their copyright holders but you may in clude translations of some or all Invariant Sections in addition to the original versions of these Invari ant Sections You may include a translation of this License and all the license notices in the Document and any Warranty Disclaimers provided that you also include the original English version of this Li cense and the original versions of those notices and disclaimers In case of a disagreement between the translation and the original version of this License or a notice or disclaimer the original version will prevail If a section in the Document is Entitled Acknowl edgements Dedications or History the re quirement section 4 to Preserve its Title section 1 will typically require changing the actual title 9 TERMINATION You may not copy modify sublicense or distribute the Document except as expressly provided under this License Any attempt otherwise to copy mod ify sublicense or distribute it is void and will automatically terminate your rights under this Li cense However if you cease all violation of this License then your license from a particular copyright holder is reinstated a provisionally unless and until the copyright holder explicitly and finally terminates your license and b permanently if the copyright holder fails to notify you of the violation by some reasonable means prior to 60 days after the ces tion
79. same transaction and clear can be called in between each batch to avoid the persistence context from getting too big Example clear public void processAll0OpenOrders EntityManager em getEntityManager List lt Long gt openOrderIds em createQuery SELECT o id from Order o where o isOpen true em getTransaction begin 8 https java sun com javaee 5 docs api javax persistence EntityManager html clear 249 Advanced try 1 for int batch 0 batch lt openOrderlds size batch 100 4 for int index 0 index lt 100 amp amp batch index lt openOrderlds size index Long id openOrderlds get batch index Order order em find Order class id order process em F em flush em clear J em getTransaction commit catch RuntimeException error if em getTransaction isActive em getTransaction rollback F 48 6 Close The EntityManager close operation is used to release an application managed EntityManager s resources JEE JTA managed EntityManagers cannot be closed as they are managed by the JTA transaction and JEE server The life cycle of an EntityManager can last either a transaction request or a users session Typically the life cycle is per request and the EntityManager is closed at the end of the request The objects obtained from an EntityManager become detached when the EntityManager is closed and any LAZY relationships may no longer
80. server will inject the application with a proxy to an EntityManager and after each JTA transaction a new EntityManager will be created automatically or the EntityManager will be cleared clearing the 1st level cache In an application managed EntityManager the 1st level cache will exist for the duration of the EntityManager This can lead to stale data or even memory leaks and poor performance if the EntityManager is held too long This is why it is generally a good idea to create a new EntityManager per request or per transaction The 1st level cache can also be cleared using the EntityManager clear method or an object can be refreshed using the EntityManager refresh method 51 6 2 2nd Level Cache The 2nd level cache spans transactions and EntityManagers and is not required as part of JPA Most JPA providers support a 2nd level cache but the implementation and semantics vary Some JPA providers default to enabling a 2nd level cache and some do not use a 2nd level cache by default If the application is the only application and server accessing the database there is little issue with the 2nd level cache as it should always be up to date The only issue is with 266 Stale Data DML if the application executes DML directly to the database through native SQL queries JDBC or JPQL UPDATE or DELETE queries JPQL queries should automatically invalidate the 2nd level cache but this may depend on the JPA provider If you use native DM
81. the name of the publisher of the Modified Version as the publisher D Preserve all the copyright notices of the Document E Add an appropriate copyright notice for your modifica tions adjacent to the other copyright notices F Include immediately after the copyright notices a license notice giving the public permission to use the Modified Version under the terms of this Li cense in the form shown in the Addendum below G Preserve in that license notice the full lists of In variant Sections and required Cover Texts given in the Document s license notice H Include an unal tered copy of this License I Preserve the section Entitled History Preserve its Title and add to it an item stating at least the title year new authors and publisher of the Modified Version as given on the Title Page If there is no section Entitled His tory in the Document create one stating the title year authors and publisher of the Document as given on its Title Page then add an item describ ing the Modified Version as stated in the previous sentence J Preserve the network location if any given in the Document for public access to a Trans parent copy of the Document and likewise the net work locations given in the Document for previous versions it was based on These may be placed in the History section You may omit a network lo cation for a work that was published at least four years before the Document itself or if the
82. these types of collections map very poorly to a relational database JPA does not support nested collection relationships and normally it is best to change your object model to avoid them to make persistence and querying easier One solution is to create an object that wraps the nested collection For example if an Employee had a Map of Projects keyed by a String project type and the value a List or Projects To map this a new ProjectType class could be created to store the project type and a OneToMany to Project Example nested collection model original public class Employee private long id private Map lt String List lt Project gt gt projects Example nested collection model modified public class Employee Id GeneratedValue 25 Chapter 11 on page 25 26 Chapter 10 on page 23 149 Advanced private long id COneToMany mappedBy employee MapKey name type private Map lt String ProjectType gt projects public class ProjectType Id GeneratedValue private long id ManyToOne private Employee employee Column name PROJ_TYPE private String type ManyToMany private List lt Project gt projects Example nested collection database EMPLOYEE table ID FIRSTNAME LASTNAME SALARY 1 Bob Way 50000 2 Sarah Smith 60000 PROJECTTYPE table ID EMPLOYEE_ID PROJ_TYPE 1 1 small 2 1 medium 3 2 large PROJECTTYPE_PROJECT table PROJECTTYPE_ID PROJECT_ID 1 1 1 2
83. to be read then it should not be mapped It is best to use direct JDBC to access and stream the LOB in this case In may be possible to map the LOB to a java sql Blob java sql Clob in your object to avoid reading the entire LOB but these require a live connection so may have issues with detached objects 29 3 1 Example of lob annotation Entity public class Employee Basic fetch FetchType LAZY Lob private Image picture 8 https java sun com javaee 5 docs api javax persistence Lob html 118 Lazy Fetching 29 3 2 Example of lob XML lt entity name Employee class org acme Employee access FIELD gt lt attributes gt lt basic name picture fetch LAZY gt lt lob gt lt basic gt lt attributes gt lt entity gt 29 4 Lazy Fetching The fetch attribute can be set on a Basic mapping to use LAZY fetching By default all Basic mappings are EAGER which means the column is selected whenever the object is selected By setting the fetch to LAZY the column will not be selected with the object If the attribute is accessed then the attribute value will be selected in a separate database select Support for LAZY is an optional feature of JPA so some JPA providers may not support it Typically support for lazy on basics will require some form of byte code weaving or dynamic byte code generation which may have issues in certain environments or JVMs or may require preprocessing your application s persisten
84. to rapidly develop a persistent JPA application 1 http en wikipedia org wiki Object Relational_impedance_mismatch 2 https java sun com javaee 5 docs api javax persistence Entity html 3 http java sun com xml ns persistence orm_1_0 xsd 39 Mapping 18 0 1 Example object model managedEmployees manager Figure 5 40 owner id long firstName String lastName String salary BigDecimal teamLeader 1 employmentPeriod startDate Date endDate Date phones 1 address gt id long type String number String areaCode String T id long street String city String province String country String postalCode String id long name String A gt projects TI budget BigDecimal Index 18 0 2 Example data model FK_MANAGER_ID Figure 6 18 0 3 Example of a persistent entity mapping in annotations 1 EMP_ID NUMBER F_NAME VARCHAR L_NAME VARCHAR SALARY NUMBER START_DATE DATE END_DATE DATE ADDRESS_ID NUMBER MANAGER_ID NUMBER FK_EMP_ID E FK_ADDRESS_ID ADDRESS_ID NUMBER STREET VARCHAR CITY VARCHAR PROVINCE VARCHAR COUNTRY VARCHAR 1 P_CODE VARCHAR OVW NER_ID NUMBER FK_OWNER_ID EMP_ID NUMBER PROJ_ID NUMBER TYPE VARCHAR P_NUMBER VARCHAR AREA_CODE VARCHAR FK_PROJ_ID 1 PRO
85. traverse them in queries Also when ordering is used the results will be ordered by class then by the ordering These limitations depend on your JPA provider some JPA provider may have other limitations or not support table per class at all as it is optional in the JPA spec 24 2 Mapped Superclasses Mapped superclass inheritance allows inheritance to be used in the object model when it does not exist in the data model It is similar to table per class inheritance but does not allow querying persisting or relationships to the superclass Its main purpose is to allow mappings information to be inherited by its subclasses The subclasses are responsible for defining the table id and other information and can modify any of the inherited mappings A common usage of a mapped superclass is to define a common PersistentObject for your 84 Mapped Superclasses application to define common behavoir and mappings such as the id and version A mapped superclass normally should be an abstract class A mapped superclass is notan Entity but is instead defined though the MappedSuperclass annotation or the lt mapped superclass gt element 24 2 1 Example mapped superclass tables SMALLPROJECT table ID NAME 2 Legal LARGEPROJECT table ID PROJECT_NAME BUDGET 1 Accounting 50000 24 2 2 Example mapped superclass annotations MappedSuperclass public abstract class Project Id private long id Column name NAME private St
86. type attribute in the persistence xml is set to RESOURCE_LOCAL If resource local transactions are used with a DataSource the lt non jta datasource gt element should be used to reference a server DataSource that has been configure to not be JTA managed Local JPA transactions are defined through the EntityTransaction class It contains basic transaction API including begin commit and rollback Technically in JPA the EntityManager is in a transaction from the point it is created So begin is somewhat redundant Until begin is called certain operations such as persist merge remove cannot be called Queries can still be performed and objects that were queried can be changed although this is somewhat unspecified what will happen to these changes in the JPA spec normally they will be committed however it is best to call begin before making any changes to your objects Normally it is best to create a new EntityManager for each transaction to avoid have stale objects remaining in the persistence context and to allow previously managed objects to garbage collect After a successful commit the EntityManager can continue to be used and all of the managed objects remain managed However it is normally best to close or clear the EntityManager http en wikipedia org wiki Database 20transaction http en wikipedia org wiki Data 20Manipulation 20Language http en wikipedia org wiki Java 20Enterprise 20Edition http en wikipedia org wiki Java
87. used for attributes that need to be converted through a set of database specific get set or allow a specific attribute to avoid side affects in its get set methods This is done through specifying the AccessType annotation or XML attribute on the mapped attribute You may also need to mark the field property as Transient if it has a different attribute name than the mapped attribute JPA allows for a persistence unit default lt access type gt element to be set in persistence unit defaults or entity default in entity mappings 4 https java sun com javaee 5 docs api javax persistence AccessType html 42 Common Problems TopLink EclipseLink Default to using FIELD access If weaving is enabled and field access is used the fields are accessed directly using generated byte code If not using weaving or using property access reflection is used EclipseLink also supports a third access type VIRTUAL which can be used from the ORM XML to map dynamic properties stored in a properties Map 18 1 1 Access type example Entity Access AccessType FIELD public class Employee Id private long id private String firstName private String lastName Transient private Money salary ManyToOne fetch FetchType LAZY private Employee manager CAccess AccessType PROPERTY private BigDecimal getBDSalary return this salary toNumber private void setBDSalary BigDecimal salary this salary new Money salary
88. values the objects will be the same anyway so it does not matter that JPA thinks they are the same object The issue with allowing updates and deletes is that there is no way to uniquely identify the object s row so all of the matching rows will be updated or deleted If your object does not have an id but its table does this is fine Make the object an Embeddable object embeddable objects do not have ids You will need a Entity that contains this Embeddable to persist and query it Identity and Sequencing Identity and Sequencing 16 Chapter 11 on page 25 17 Chapter 10 on page 23 18 https java sun com javaee 5 docs api javax persistence PrePersist html 19 http en wikibooks org wiki Category 3AJava 20Persistence 20 http en wikibooks org wiki Category 3AJava 20Persistence 2FMapping 75 Advanced id long name String budget BigDecimal Figure 12 An example of inheritance SmallProject and LargeProject inherit the properties of their common parent Project Inheritance is a fundamental concept of object oriented programming and Java Relational databases have no concept of inheritance so persisting inheritance in a database can be tricky Because relational databases have no concept of inheritance there is no standard way of implementing inheritance in database so the hardest part of persisting inheritance is choosing how to represent the inheritance in the database JPA defines several inheritance
89. various data services including databases XML and Enterprise Information Systems EIS EclipseLink supports a number of persistence standards including the Java Persistence API JPA Java API for XML Binding JAXB Java Connector Architecture JCA and Service Data Objects SDO EclipseLink is based on the TopLink product which Oracle contributed the source code from to create the EclipseLink project The original contribution was from TopLink s 11g code base and the entire code base feature set was contributed with only EJB 2 CMP and some minor Oracle AS specific integration removed This differs from the TopLink Essentials Glassfish contribution which did not include some key enterprise features The package names were changed and some of the code was moved around The TopLink Mapping Workbench Ul has also been contributed to the project EclipseLink is the intended path forward for persistence for Oracle and TopLink It is intended that the next major release of Oracle TopLink will include EclipseLink as well as the next major release of Oracle AS EclipseLink supports usage in an OSGi environment EclipseLink was announced to be the JPA 2 0 reference implementation and announced to be the JPA provider for Glassfish v3 e EclipseLink Home e EclipseLink Newsgroup EclipseLink Wiki EclipseLink EclipseLink http en wikipedia org wiki EclipseLink Chapter 11 on page 25 http en wikipedia org wiki Dracle 2
90. 0Corporation http en wikipedia org wiki 0SGi http www eclipse org eclipselink http www eclipse org newsportal thread php group eclipse technology eclipselink http wiki eclipse org EclipseLink http en wikibooks org wiki Category 3AJava 20Persistence 2FPersistence 20Products http en wikibooks org wiki Category 3AJava 20Persistence V00 ZDOaOAANNA 23 11 TopLink TopLink is one of the leading Java persistence products and JPA implementations TopLink is produced by Oracle and part of Oracle s OracleAS WebLogic and OC4J servers As of TopLink 11g TopLink bundles the open source project EclipseLink for most of its functionality The TopLink 11g release supports the JPA 1 0 specification TopLink 10 1 3 also supports EJB CMP and is the persistence provider for OracleAS OC4J 10 1 3 for both JPA and EJB CMP TopLink provides advanced object relational mapping functionality beyond the JPA specification as well as providing persistence for object relational data types and Enterprise Information Systems EIS mainframes TopLink includes sophisticated object caching and performance features TopLink provides a Grid extension that integrate with Oracle Coherence TopLink provides object XML mapping support and provides a JAXB implementation and web service integration TopLink provides a Service Data Object SDO implementation TopLink provides a rich user interface through the TopLink Mapping Workbench The Mapping Workbench al
91. 1 5 on page 265 Chapter 12 on page 27 NOD OCB WO 263 Caching For a relationship cache the results normally only store the related object s Id not the object or its data to avoid duplicate and stale data The key of the relationship cache is the source object s Id and the relationship name Sometimes the relationship is cached as part of the data cache if the data cache stores a structure instead of a database row When a cache hit occurs on a relationship the related objects are looked up in the data cache one by one A potential issue with this is that if the related object is not in the data cache it will need to be selected from the database This could result in very poor database performance as the objects can be loaded one by one Some product that support caching relationships also support batching the selects to attempt to alleviate this issue 51 4 Cache Types There are many different caching types The most common is a LRU cache or one that ejects the Least Recently Used objects and maintains a fixed size number of MRU Most Recently Used objects Some cache types include e LRU Keeps X number of recently used objects in the cache e Full Caches everything read forever not always the best idea if the database is large e Soft Uses Java garbage collection hints to release objects from the cache when memory is low e Weak Normally relevant with object caches keeps any objects currently in use in the
92. 15 29 2 AENA o See ap ee a eae ae Bode Dear A AA 117 IV Contents 30 31 32 33 34 35 36 37 29 3 LOBs BLOBs CLOBs and Serialization 29 4 LagysHetching 2 310 Sane 82 Zn ade ea ren wea Pee a ee 29 5 Optionals acia ath oe a ble ate ee eae A ae Sh 29 6 Column Definition and Schema Generation 29 7 Insertable Updatable Read Only Fields Returning 29 8 Conversion ss Shap ee doa we ee Si Pe eK 29 9 Custom Types sua Pe he a ee ae ee AE Relationships 30 1 A Eazy Peteng pia 2 2 a sn AE Se A Dee 302 Cascading u zus ae are Gs PA hs a ke ea ne 30 3 Orphan Removal JPA 2 0 224 oe kee ae he hae a oes 30 4 Target Entity 220200 20 Dae a ee ae ee 30 5 Collections ws rata a Ea ee a eee Sle ba ee A 30 6 Common Problems se 2 de war ts a et ee Advanced 31 1 Advanced Relationships 2 2 2 CE mE nn 31 2 Maps u er a Be A Be ed ae Ee a 31 3 Join Betching usw Se A Be ae ee ge 31 4 Batch Fetching xe kee ae a DE a Be en Be 31 5 Filtering Complex Joins 0 a 31 6 Variable and Heterogeneous Relationships 31 7 Nested Collections Maps and Matrices 200 OneToOne 32 1 Inverse Relationships Target Foreign Keys and Mapped By 32 27 See AlS fe A Bee es Saeed a Bare A 32 3 Common Problems e ses uaa Dete a wu ee ae Advanced 33 1 Target Foreign Keys Primary Key Join Columns Cascade Primary
93. 2001 XMLSchema instance xsi schemaLocation http java sun com xml ns persistence persistence_1_0 xsd version 1 0 gt lt persistence unit name acme transaction type RESOURCE_LOCAL gt lt non jta data source gt amce lt non jta data source gt lt persistence unit gt lt persistence gt 49 1 2 Example resource local transaction EntityManager em createEntityManager em getTransaction begin Employee employee em find Employee class id employee setSalary employee getSalary 1000 em getTransaction commit em close 49 2 JTA Transactions JTA transactions are used in JEE in managed mode EJB To use JTA transactions the transaction type attribute in the persistence xml is set to JTA If JTA transactions are used with a DataSource the lt jta datasource gt element should be used to reference a server DataSource that has been configure to be JTA managed JTA transactions are defined through the JTA UserTransaction class or more likely implicitly defined through SessionBean usage methods In a SessionBean normally each SessionBean method invocation defines a JTA transaction UserTransaction can be 7 Chapter 43 2 on page 211 8 https java sun com javaee 5 docs api javax transaction UserTransaction html 254 JTA Transactions obtained through a JNDI lookup in most application servers or from the EJBContext in EJB 2 0 style SessionBeans JTA transactions can be used in two modes in J
94. 20Transaction 20API http en wikipedia org wiki Java 208Standard 20Edition https java sun com javaee 5 docs api javax persistence EntityTransaction html DORA 0w0NRA 253 Transactions to allow garbage collection and avoid stale data If the commit fails then the managed objects are considered detached and the EntityManager is cleared This means that commit failures cannot be caught and retried if a failure occurs the entire transaction must be performed again The previously managed object may also be left in an inconsistent state meaning some of the objects locking version may have been incremented Commit will also fail if the transaction has been marked for rollback This can occur either explicitly by calling setRollbackOnly or is required to be set if any query or find operation fails This can be an issue as some queries may fail but may not be desired to cause the entire transaction to be rolled back The rollback operation will rollback the database transaction only The managed objects in the persistence context will become detached and the EntityManager is cleared This means any object previously read should no longer be used and is no longer part of the persistence context The changes made to the objects will be left as is the object changes will not be reverted 49 1 1 Example resource local transaction persistence xml lt persistence xmlns http java sun com xml ns persistence xmlns xsi http www w3 org
95. A allows the flush mode for a query to be configured using the FlushModeType enum and the Query setFlushMode API The flush mode is either AUTO the default which means flush before every query execution or COMMIT which means only flush on commit The flush mode can also be set on an EntityManager using the EntityManager setFlushMode API to affect all queries executed with the EntityManager The EntityManager flush API can be called directly on the EntityManager anytime that a flush is desired Some JPA providers also let the flush mode be configured through persistence unit properties or offer alternatives to flushing such as performing the query against the in memory objects TopLink EclipseLink Allow the auto flush to be disabled using the persistence unit property eclipselink persistence context flush mode COMMIT 45 5 Pagination Max First Results A common requirement is to allow the user to page through a large query result Typically a web user is given the first page of n results after a query execution and can click next to go to the next page or previous to go back If you are not concerned about performance or the results are not too big the easiest way to implement this is to query all of the results then access the sub list from the result list to populate your page However you will then have to re query the entire results on every page request One simple solution is to store the query result
96. AttributeOverride name startDate column Column name SDATE AttributeOverride name endDate column Column name EDATE private Period period 1 https java sun com javaee 5 docs api javax persistence AttributeOverride html 93 Advanced 26 1 2 Example shared embeddable XML lt entity name Employee class org acme Employee access FIELD gt lt attributes gt lt id name id gt lt embedded name employmentPeriod gt lt attribute override name startDate gt lt column name START_DATE gt lt attribute override gt lt attribute override name endDate gt lt column name END_DATE gt lt attribute override gt lt embedded gt lt attributes gt lt entity gt lt entity name User class org acme User access FIELD gt lt attributes gt lt id name id gt lt embedded name period gt lt attribute override name startDate gt lt column name SDATE gt lt attribute override gt lt attribute override name endDate gt lt column name EDATE gt lt attribute override gt lt embedded gt lt attributes gt lt entity gt 26 2 Embedded Ids An EmbeddedId is an embeddable object that contains the Id for an entity See Embedded Id 26 3 Nulls An embeddable object s data is contained in several columns in its parent s table Since there is no single field value there is no way to know if a parent s reference to the embeddable is null One could assume th
97. B3 and JEE e Many free and open source products with enterprise level support e Portability across application servers and persistence products avoids vendor lock in e A usable and functional specification e Supports both JEE and JSE ORM can be a hot topic for some people and there are many ORM camps There are those that endorse a particular standard or product There are those that don t believe in ORM or even objects in general and prefer JDBC There are those that still believe that object databases are the way to go Personally I would recommend you use whatever technology you are most comfortable with but if you have never used ORM or JPA perhaps give it a try and see if you like it The below list provides several discussions on why or why not to use JPA and ORM Discussions on JPA and ORM Usage e Why do we need anything other than JDBC Java Ranch e JPA Explained The Server Side 1 http saloon javaranch com cgi bin ubb ultimatebb cgi ubb get_topic amp f 78 amp t 003738 2 http www theserverside com news thread tss thread_id 44526 17 Why use JPA or ORM e JPA vs JDO The Server Side Why use JPA or ORM Why use JPA or ORM A Ww al 1 http www theserverside com news thread tss thread_id 40965 http en wikibooks org wiki Category 3AJava 20Persistence 2FWhat 20is 20Java 20persistence http en wikibooks org wiki Category 3AJava 20Persistence 8 9 Persistence Products There ar
98. Chapter 10 on page 23 bo 66 Composite Primary Keys Example id class XML lt entity name Employee class org acme Employee access FIELD gt lt id class class org acme EmployeePK gt lt attributes gt lt id name employeeld gt lt id name companyld gt lt id name departmentId gt lt attributes gt lt entity gt Example id class public class EmployeePK private long employeeld private long companyld private long departmentld public EmployeePK long employeeld long companyld long departmentId o E this employeeld employeeld this companyld companyld this departmentId departmentld public boolean equals Object object if object instanceof EmployeePK EmployeePK pk EmployeePK object return employeeld pk employeeld amp amp companyld pk companyId amp amp departmentId pk departmentld else return false public int hashCode return employeeId companyId departmentId 23 1 2 Embedded Id An EmbeddedId defines a separate Embeddable Java class to contain the entities primary key It is defined through the EmbeddedId annotation or lt embedded id gt XML element The EmbeddedId s Embeddable class must define each id attribute for the entity using Basic mappings All attributes in the EmbeddedId s Embeddable are assumed to be part of the primary key The Embeddedld is also used as the structure passed to the EntityManager find and
99. E Cascaded the EntityManager remove operation If remove is called on the parent then the child will also be removed This should only be used for dependent relationships Note that only the remove operation is cascaded if you remove a dependent object from a OneToMany collection it will not be deleted JPA requires that you explicitly call remove on it Some JPA providers may support an option to have objects removed from dependent collection deleted JPA 2 0 also defines an option for this MERGE Cascaded the EntityManager merge operation If merge is called on the parent then the child will also be merged This should normally be used for dependent relationships Note that this only effects the cascading of the merge the relationship reference itself will always be merged This can be a major issue if you use transient variables to limit serialization you may need to manually merge or reset transient relationships in this case Some JPA providers provide additional merge operations REFRESH Cascaded the EntityManager refresh operation If refresh is called on the parent then the child will also be refreshed This should normally be used for dependent relationships Be careful enabling this for all relationships as it could cause changes made to other objects to be reset ALL Cascaded all the above operations 30 2 1 Example of a cascaded one to one relationship annotations Entity public class Employee Id 12
100. EE In JEE managed mode such as an EntityManager injected into a SessionBean the EntityManager reference represents a new persistence context for each transaction This means objects read in one transaction become detached after the end of the transaction and should no longer be used or need to be merged into the next transaction In managed mode you never create or close an EntityManager The second mode allows the EntityManager to be application managed normally ob tained from an injected EntityManagerFactory or directly from JPA Persistence This allows the persistence context to survive transaction boundaries and follow the normal EntityManager life cycle similar to resource local If the EntityManager is created in the context of an active JTA transaction it will automatically be part of the JTA transaction and commit rollback with the JTA transaction Otherwise it must join a JTA transaction to commit rollback using EntityManager joinTransaction 49 2 1 Example JTA transaction persistence xml lt persistence xmlns http java sun com xml ns persistence xmlns xsi http www w3 org 2001 XMLSchema instance xsi schemaLocation http java sun com xml ns persistence persistence_1_0 xsd version 1 0 gt lt persistence unit name acme transaction type JTA gt lt jta data source gt amce lt jta data source gt lt persistence unit gt lt persistence gt 49 2 2 Example JTA transaction UserTransaction transaction
101. ET e salary e salary 2 WHERE e address city city update_ statement update_ clause where clause update_clause UPDATE abstract_schema name AS identification_ variable SET update_item update_item 11 Chapter 46 1 3 on page 235 237 JPQL BNF update_ item identification _variable state_field single_valued_ association field new_ value new_ value simple _arithmetic_expression string primary datetime_ primary boolean _ primary enum_ primary simple _entity_expression NULL 46 3 Delete DELETE FROM Employee e WHERE e address city city delete statement delete clause where_ clause delete clause DELETE FROM abstract_schema name AS identification variable 46 4 Literals It is normally best to define data values in a query using parameters using the syntax parameter or JPQL also allows for data values to be in lined in the JPQL query using literals JPQL defines the following syntax for literals String string Select e from Employee e where e name Bob e To define a quote character in a string the quote is double quoted i e Baie D Urf Integer digits Select e from Employee e where e id 1234 Long digitsL Select e from Employee e where e id 1234L Float digits decimaleexponentF Select s from Stat s where s ratio gt 3 14F Double digits decimaleexponentD Select s from Stat s where s r
102. G XCF and JPG Opaque formats include proprietary formats that can be read and edited only by proprietary word processors SGML or XML for which the DTD and or processing tools are not generally available and the machine generated HTML PostScript or Notwithstanding any other provision of this Li cense you have permission to link or combine any covered work with a work licensed under version 3 of the GNU Affero General Public License into a single combined work and to convey the result ing work The terms of this License will continue to apply to the part which is the covered work but the special requirements of the GNU Affero General Public License section 13 concerning interaction through a network will apply to the combination as such 14 Revised Versions of this License The Free Software Foundation may publish revised and or new versions of the GNU General Public Li cense from time to time Such new versions will be similar in spirit to the present version but may dif fer in detail to address new problems or concerns Each version is given a distinguishing version num ber If the Program specifies that a certain num bered version of the GNU General Public License or any later version applies to it you have the option of following the terms and conditions either of that numbered version or of any later version published by the Free Software Foundation If the Program does not specify a version number of the GNU Gen
103. General Public License The Library refers to a covered work governed by this License other than an Application or a Com bined Work as defined below An Application is any work that makes use of an interface provided by the Library but which is not otherwise based on the Library Defining a subclass of a class defined by the Library is deemed a mode of using an interface provided by the Library A Combined Work is a work produced by com bining or linking an Application with the Library The particular version of the Library with which the Combined Work was made is also called the Linked Version The Minimal Corresponding Source for a Com bined Work means the Corresponding Source for the Combined Work excluding any source code for portions of the Combined Work that considered in isolation are based on the Application and not on the Linked Version The Corresponding Application Code for a Com bined Work means the object code and or source code for the Application including any data and utility programs needed for reproducing the Com bined Work from the Application but excluding the System Libraries of the Combined Work 1 Excep tion to Section 3 of the GNU GPL You may convey a covered work under sections 3 and 4 of this License without being bound by sec tion 3 of the GNU GPL 2 Conveying Modified Versions If you modify a copy of the Library and in your modifications a facil
104. INCREMENT The Entity is locked on the database prevents any other transaction from acquiring a PESSIMISTIC_ READ or PESSIMISTIC_ WRITE lock and the Entity will have its optimistic lock version incremented on commit This is unusual as it does both an optimistic and pessimistic lock normally an application would only use one locking model e NONE No lock is acquired this is the default to any find refresh or query operation JPA 2 0 also adds two new standard query hints These can be passed to any Query NamedQuery or find lock or refresh operation e javax persistence lock timeout Number of milliseconds to wait on the lock before giving up and throwing a PessimisticLockException e javax persistence lock scope The valid scopes are defined in PessimisticLockScope either NORMAL or EXTENDED EXTENDED will also lock the object s owned join tables and element collection tables 27 2 9 Serializable Transaction Isolation Serializable transaction isolation guarantees that anything read in the transaction will not be updated by any other user Through using serializable transaction isolation and ensuring the data being edited is read in the same transaction you can achieve pessimistic locking It is important to ensure the objects are refreshed from the database in the transaction as editing cached or potentially stale data defeats the point of locking Serializable transaction isolation can typically be enabled on the da
105. J_ID NUMBER TYPE CHAR NAME VARCHAR BUDGET NUMBER import javax persistence Entity public class Employee eId private private private private private private private long id String firstName String lastName Address address List lt Phone gt phones Employee manager FK_LEADER_ID LEADER_ID NUMBER List lt Employee gt managedEmployees 18 0 4 Example of a persistent entity mapping in XML lt xml version 1 0 encoding UTF 8 gt lt entity mappings version 1 0 xmlns http java sun com xml ns persistence orm xmlns xsi http www w3 org 2001 XMLSchema instance 41 Mapping xsi schemaLocation http java sun com xml ns persistence orm orm_1_0 xsd gt lt description gt The minimal mappings for a persistent entity in XML lt description gt lt entity name Employee class org acme Employee access FIELD gt lt attributes gt lt id name id gt lt attributes gt lt entity gt lt entity mappings gt 18 1 Access Type JPA allows annotations to be placed on either the class field or on the get method for the property This defines the access type of the class which is either FIELD or PROPERTY Either all annotations must be on the fields or all annotations on the get methods but not both unless the CAccessType annotation is used JPA does not define a default access type oddly enough so the default may depend on the JPA provider The default is assu
106. Java Persistence Wikibooks org March 18 2013 On the 28th of April 2012 the contents of the English as well as German Wikibooks and Wikipedia projects were licensed under Creative Commons Attribution ShareAlike 3 0 Unported license An URI to this license is given in the list of figures on page 283 If this document is a derived work from the contents of one of these projects and the content was still licensed by the project under this license at the time of derivation this document has to be licensed under the same a similar or a compatible license as stated in section 4b of the license The list of contributors is included in chapter Contributors on page 281 The licenses GPL LGPL and GFDL are included in chapter Licenses on page 287 since this book and or parts of it may or may not be licensed under one or more of these licenses and thus require inclusion of these licenses The licenses of the figures are given in the list of figures on page 283 This PDF was generated by the IAT X typesetting software The IAIEX source code is included as an attachment source 7z txt in this PDF file To extract the source from the PDF file we recommend the use of http www pdflabs com tools pdftk the pdf toolkit utility or clicking the paper clip attachment symbol on the lower left of your PDF Viewer selecting Save Attachment After extracting it from the PDF file you have to rename it to source 7z To uncompress the resulting archive we recommend the u
107. Keys 33 2 Mapping a OneToOne Using a Join Table Many ToOne SA A E nE ee i 34 2 Common Problems a Sa a nn ai Pe a Bu len Advanced 35 1 Target Foreign Keys Primary Key Join Columns Cascade Primary Keys OneToMany 36 1 Jon Table 3 5 03 2 ru 212 e ee Ae E wee A ua OL SO A A N a ok GN et ar E N 36 3 Common Problems 22 2 CC nn on Advanced 37 1 Undirectional OneToMany No Inverse ManyToOne No Join Table JPA 2U ONEN e hang en ds ar oo cuales Se ad 151 154 155 155 157 157 161 165 167 167 169 169 171 174 176 176 177 Contents 38 39 40 41 42 43 44 45 VI ManyToMany 38 1 Bi directional Many to Many o 38 2 A De a a ee ee ES 38 3 Common Problems 32 2 2 42 eee ke Zul DR ru ie Advanced 39 1 Mapping a Join Table with Additional Columns ElementCollection 40 1 Embedded Collections 22 22 2 CC Emm 40 2 Basic Collections a bocas Comm nen 40 3 See Also na a a a O E a aa a a aaa a a G 40 4 Common Problems aoaaa a a a a a a Advanced Topics AT sBV6nts 29 2258 a ti i a 41 2 VIEWS lt a Inf a A A ee ee Pee PAG 41 3 Interfaces 20 04 tac saa Metts SA ee ot Re ao Yee eS 41 4 Stored Procedures 2 2 ee 41 5 Structured Object Relational Data Types 2 4136 XMIE Data Typis isy oe ep alk ey a ANT A God aR Sh a le ei ER ee RN 41 8 History 2 2 ara oh an eb eho Sole BEIGE os 41 9
108. L queries or JDBC directly you may need to invalidate refresh or clear the objects affected by the DML If there are other applications or other application servers accessing the same database then stale data can become a bigger issue Read only objects and inserting new objects should not be an issue New objects should get picked up by other servers even when using caching as queries typically still access the database It is normally only find operations and relationships that hit the cache Updated and deleted objects by other applications or servers can cause the 2nd level cache to become stale For deleted objects the only issue is with find operations as queries that access the database will not return the deleted objects A find by the object s Id could return the object if it is cached even if it does not exist This could lead to constraint issues if you add relations to this object from other objects or failed updates if you try to update the object Note that these can both occur without caching even with a single application and server accessing the database During a transaction another user of the application could always delete the object being used by another transaction and the second transaction will fail in the same way The difference is the potential for this concurrency issue to occur increases For updated objects any query for the objects can return stale data This can trigger optimistic lock exceptions on
109. License http creativecommons org licenses by sa 3 0 e cc by sa 2 5 Creative Commons Attribution ShareAlike 2 5 License http creativecommons org licenses by sa 2 5 e cc by sa 2 0 Creative Commons Attribution ShareAlike 2 0 License http creativecommons org licenses by sa 2 0 e cc by sa 1 0 Creative Commons Attribution ShareAlike 1 0 License http creativecommons org licenses by sa 1 0 e cc by 2 0 Creative Commons Attribution 2 0 License http creativecommons org licenses by 2 0 e cc by 2 0 Creative Commons Attribution 2 0 License http creativecommons org licenses by 2 0 deed en e cc by 2 5 Creative Commons Attribution 2 5 License http creativecommons org licenses by 2 5 deed en e cc by 3 0 Creative Commons Attribution 3 0 License http creativecommons org licenses by 3 0 deed en e GPL GNU General Public License http www gnu org licenses gpl 2 0 txt e LGPL GNU Lesser General Public License http www gnu org licenses lgpl html e PD This image is in the public domain e ATTR The copyright holder of this file allows anyone to use it for any purpose provided that the copyright holder is properly attributed Redistribution derivative work commercial use and all other use is permitted e EURO This is the common reverse face of a euro coin The copyright on the design of the common face of the euro coins belongs to the European Commission Authorised is reproduction in a format w
110. Logical Deletes 2 22 222 Fe A EZ ALTO Auditing ea a a Se i ke OS Boa ae a das 41 11 Replication 222 2242 22 bake ee Se ee kG Be Ad TD Partitioning pelos aropa Pe Re Re ee re SAS elds AY 13 Data Integration 2 Read a Dre Be AL de ee oe ae Bs 41 14 NoSQL and EIS legacy XML and non relational data 41 15 Multi Tenaney aoe e uo ee a os ee eee nad ne le ea Bes 41 16 Dynamic Data x 5 e suce bo are ek ee I io Runtime Entity Manager 43 1 Java Standard Edition 02 ee eee 43 2 Java Enterprise Edition nn Querying 44 1 Named Queries csi Roa VASE Ah Po RL ns 44 2 Dynamic Queries au 0 2 hock Dag ao Poe cena a A Taye 44 3 JBOE ta oi tier te hae Ae i gh BR ach Rte En Oe eae ee BS 44 4 Parameters 2 an A BHA has ae 44 5 Query Results e ctas ire a a ee 44 6 Common Queries 22 2 2m En Advanced 45 1 Join Fetch and Query Optimization 45 2 Timeouts Fetch Size and other JDBC Optimizations 179 180 181 182 183 183 187 188 189 191 191 207 209 209 211 215 216 217 218 218 219 220 Contents 46 47 48 49 50 51 45 3 Update and Delete Queries 2 2 2m mn m nn 226 A5 A Flush Mode a A ae eR ee re Pe AN 226 45 5 Pagination Max First Results nn a a Se 2 227 45 6 Native SQL Queries nn nn 229 45 7 Stored Procedures 231 45 8 Raw WD BO eh Sets ee dal Ye Se pe hy Soca ad ain wih Seared ae e e
111. Manager gt lt property name entityManagerFactory ref entityManagerFactory gt lt bean gt lt bean id entityManager class org springframework orm jpa support SharedEntityManagerBean gt lt property name entityManagerFactory ref entityManagerFactory gt lt bean gt lt bean id AcmeDao class org acme dao AcmeDao gt lt property name entityManager ref entityManager gt lt bean gt lt beans gt Spring 3 http en wikibooks org wiki Category 3AJava 20Persistence 274 53 Databases 275 54 MySQL Using MySQL with Java Persistence API is quite straightforward as the JDBC driver is available directly from MySQL web site http dev mysql com MySQL Connector J is the official JDBC driver for MySQL and has a good documentation available directly on the web site In this page we will see some aspects of managing MySQL using the Persistence API 54 1 Installing Installation is straightforward and consists in making the jar file downloaded from MySQL web site visible to the JVM It can be already installed if you are using Apache or JBOSS 54 2 Configuration tips You can learn a lot from the documentation on MySQL web site http dev mysql com doc refman 5 0 en connector j reference configuration properties html 54 2 1 Creating the database automatically If you intend to create table and a database automatically you will need to have the correct user rights but also infor
112. NDEX identification variable Allows querying in indexed List mapping s index SELECT e from Employee e join e phones p where INDEX p 1 and p areaCode 613 join_collection_valued_path_expression identification_variable single_valued_ embeddable_object__field collection valued field join_single valued_path_ expression variable single _valued_embeddable_object__field single_valued_ object_ field Allows nested dot notation on joins SELECT p from Employee e join e employeeDetails phones p where e id id select_ item select_ expression AS result_ variable Allows AS option in select SELECT AVG e salary AS s e address city from Employee e group by e address city order by s literal Temporal DATE_LITERAL TIME_LITERAL TIMESTAMP_LITERAL Allows JDBC date time escape syntax SELECT e from Employee e where e startDate gt d 1990 01 01 JPQL BNF JPQL BNF 13 http en wikibooks org wiki Category 3AJava 20Persistence 14 http en wikibooks org wiki Category 3AJava 20Persistence 2FRuntime 240 47 Persisting JPA uses the EntityManager API for runtime usage The EntityManager represents the application session or dialog with the database Each request or each client will use its own EntityManager to access the database The EntityManager also represents a transaction context and in a typical stateless model a new EntityManager is created for each transaction In a stateful mod
113. PE 1 1 home 1 2 cell 2 3 home 2 4 fax PHONE table ID AREACODE NUMBER 1 613 792 7777 2 613 798 6666 3 416 792 9999 4 416 798 5555 Example of a map key class embedded relationship annotation Entity public class Employee 144 Join Fetching Old private long id OneToMany MapKeyClass PhoneType class private Map lt PhoneType Phone gt phones i cate Entity public class Phone Id private long id be Embeddable public class PhoneType Basic private String type Example of a map key class embedded relationship XML lt entity name Employee class org acme Employee access FIELD gt lt attributes gt lt id name id gt lt one to many name phones gt lt map key class gt PhoneType lt map key class gt lt one to many gt lt attributes gt lt entity gt lt entity name Phone class org acme Phone access FIELD gt lt attributes gt lt id name id gt lt many to one name owner gt lt attributes gt lt entity gt lt embeddable name PhoneType class org acme PhoneType access FIELD gt lt attributes gt lt basic name type gt lt attributes gt lt embeddable gt 31 3 Join Fetching Join fetching is a query optimization technique for reading multiple objects in a single database query It involves joining the two object s tables in SQL and selecting both object s data Join fetching is commonly used for OneToOne relationships but also can
114. RISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM INCLUDING BUT NOT LIM ITED TO LOSS OF DATA OR DATA BEING REN DERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES 17 In terpretation of Sections 15 and 16 If the disclaimer of warranty and limitation of lia bility provided above cannot be given local legal ef PDF produced by some word processors for output purposes only The Title Page means for a printed book the title page itself plus such following pages as are needed to hold legibly the material this License requires to appear in the title page For works in formats which do not have any title page as such Title Page means the text near the most promi nent appearance of the work s title preceding the beginning of the body of the text The publisher means any person or entity that distributes copies of the Document to the public A section Entitled XYZ means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language Here XYZ stands for a specific section name mentioned below such as Acknowledgements Dedications En dorsements or History To Preserve the Title of such a section when you modify the Document means that it remains a secti
115. UserTransaction new InitialContext lookup java comp UserTransaction transaction begin EntityManager em getEntityManager Employee employee em find Employee class id employee setSalary employee getSalary 1000 transaction commit https java sun com javaee 5 docs api javax persistence EntityManager html joinTransaction 259 50 Advanced 50 1 Join Transaction The EntityManager joinTransaction API allows an application managed EntityManager to join the active JTA transaction context This allows an EntityManager to be created outside the JTA transaction scope and commit its changes as part of the current transaction This is normally used with a stateful SessionBean or with a JSP or Servlet where an EXTENDED EntityManager is used in a stateful architecture A stateful architecture is one where the server stores information on a client connection until the client s session is over it differs from a stateless architecture where nothing is stored on the server in between client requests each request is processed on its own There are pros and cons with both stateful and stateless architectures One of the advantages with using a stateful architecture and and EXTENDED EntityManager is that you do not have to worry about merging objects You can read your objects in one request let the client modify them and then commit them as part of a new transaction This is where joinTransaction would be used
116. able false updatable false private long companyld ManyToOne fetch FetchType LAZY JoinColumn name COM_ID private Company company ManyToOne fetch FetchType LAZY JoinColumn name DEP_ID PrimaryKeyJoinColumn name COM_ID private Department department ManyToOne fetch FetchType LAZY JoinColumn name MNG_ID PrimaryKeyJoinColumns PrimaryKeyJoinColumn name DEP_ID PrimaryKeyJoinColumn name COM_ID private Employee manager OneToOne fetch FetchType LAZY JoinColumn name ADD_ID PrimaryKeyJoinColumns PrimaryKeyJoinColumn name DEP_ID PrimaryKeyJoinColumn name COM_ID private Address address 33 2 Mapping a OneToOne Using a Join Table In some data models you may have a OneToOne relationship defined through a join table For example consider you had existing EMPLOYEE and ADDRESS tables with no foreign key and wanted to define a OneToOne relationship without changing the existing tables To do this you could define an intermediate table that contained the primary key of both objects This is similar to a ManyToMany relationship but if you add a unique constraint to each foreign key you can enforce that it is OneToOne or even OneToMany JPA defines a join table using the JoinTable annotation and lt join table gt XML element A JoinTable can be used on a ManyToMany or OneToMany mappings but the JPA 1 0 specification is vague whether it can be used on a O
117. abled caching in your JPA configuration or your JPA provider caches by default You can either disable the 2nd level cache in your JPA configuration or refresh the object or invalidate the cache after changing the database directly See Stale Data TopLink EclipseLink Caching is enabled by default To disable caching set the persistence property eclipselink cache shared default to false in your persis tence xml or persistence properties You can also configure this on a per class basis if you want to allow caching in some classes and not in others See EclipseLink FAQ Caching Caching 37 32 Chapter 51 6 on page 265 33 Chapter 11 on page 25 34 Chapter 10 on page 23 35 http wiki eclipse org EclipseLink FAQ How_to_disable_the_shared_cache 3F 36 http en wikibooks org wiki Category 3AJava 20Persistence 37 http en wikibooks org wiki Category 3AJava 20Persistence 2FRuntime 271 52 Spring Spring is an application framework for Java Spring is an IoC container that allows for a different programming model Spring is similar to a JEE server in that it provides a transaction service XML deployment annotation processing byte code weaving and JPA integration 52 1 Persistence Persistence in Spring in normally done through a DAO Data Access Object layer The Spring DAO layer is meant to encapsulate the persistence mechanism so the same application data access API would be given no matter if JDBC JPA o
118. ad a STATUS column in an EMPLOYEE table you could define an Employee and a CurrentEmployee subclass whose discriminator STATUS was ACTIVE and always use CurrentEmployee in the application Similarly you could define an ACMEEmployee subclass that used the TENANT column as its class discriminator of value ACME Another solution is to use database views to filter the data and map the entities to the views These solutions do not work with dynamic filtering where the filter criteria parameters are not know until runtime such as tenant or district Also complex criteria cannot be modeled through inheritance although database views should still work One solution is to always append the criteria to any query such as appending a JPQL string or JPA Criteria in the application code Virtual Private Database VPD support may also provide a solution Some databases such as Oracle support VPD allow context based filtering of rows based on the connected user or proxy certificate Some JPA providers have specific support for filtering data TopLink EclipseLink Support filtering data through their CAdditionalCriteria annotation and XML This allows an arbitrary JPQL fragment to be appended to all queries for the entity The fragment can contain parameters that can be set through persistence unit or context properties at runtime Oracle VPD is also supported include Oracle proxy authentication and isolated data 24 Chapter 11 on page 25
119. ads the object merges the data and commits the transaction w The issues is that the original data was read in step 1 but the lock was not obtained until step 4 so any changes made to the object in between steps 1 and 4 would not result in a conflict This means there is little point to using any locking A key point is that when using database pessimistic locking or database transaction isolation this will always be the case the database locks will only occur in step 4 and any conflicts will not be detected This is the main reason why using database locking does not scale to web applications for the locking to be valid the database transaction must be started at step 1 and not committed until step 4 This means the a live database connection and transaction must be held open while waiting for the web client as well as locks since there is no guarantee that the web client will not sit on the data for hours go to lunch or disappear of the face of the earth holding database resources and locking data for all other users can be very undesirable For optimistic locking the solution is relatively simple the object s version must be sent to the client along with the data or kept in the http session When the user submits the data back the original version must be merged into the object read from the database to ensure that any changes made between step 1 and 4 will be detected Handling optimistic lock exceptions Unfortunately prog
120. after the last time you distribute an Opaque copy directly or through your agents or retailers of that edition to the public It is requested but not required that you con tact the authors of the Document well before redis tributing any large number of copies to give them a chance to provide you with an updated version of the Document 4 MODIFICATIONS You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above provided that you release the Modi fied Version under precisely this License with the Modified Version filling the role of the Document thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it In addition you must do these things in the Modi fied Version A Use in the Title Page and on the covers if any a title distinct from that of the Document and from those of previous versions which should if there were any be listed in the History section of the Document You may use the same title as a previous version if the original publisher of that version gives permission B List on the Title Page as authors one or more persons or entities responsible for authorship of the modifications in the Modified Version together with at least five of the principal authors of the Document all of its principal authors if it has fewer than five unless they release you from this requirement C State on the Title page
121. al independent vendors such as Kodo JDO and several open source implementations but never had much success with the big Java EE vendors Despite the two competing Java persistence standards of EJB CMP and JDO the majority of users continued to prefer proprietary api solutions mainly TopLink which had been http en wikipedia org wiki Java 20Persistence 20API http en wikipedia org wiki EJB http en wikipedia org wiki POJO http en wikipedia org wiki Java 20Data 200bjects Chapter 11 on page 25 oR WN A 11 What is JPA around for some time and had its own POJO API and Hibernate which was a relatively new open source product that also had its own POJO API and was quickly becoming the open source industry standard The TopLink product formerly owned by WebGain was also acquired by Oracle increasing its influence on the Java EE community The EJB CMP backlash was only part of a backlash against all of Java EE which was seen as too complex in general and prompted such products as the Spring container This led the EJB 3 0 specification to have a main goal of reducing the complexity which led the spec committee down the path of JPA JPA was meant to unify the EJB 2 CMP JDO Hibernate and TopLink APIs and products and seems to have been very successful in doing so Currently most of the persistence vendors have released implementations of JPA confirming its adoption by the industry and users These include Hibernate acqui
122. alf under your direction and con trol on terms that prohibit them from making any copies of your copyrighted material outside their relationship with you Conveying under any other circumstances is permit ted solely under the conditions stated below Subli censing is not allowed section 10 makes it unneces sary 3 Protecting Users Legal Rights From Anti Circumvention Law No covered work shall be deemed part of an effec tive technological measure under any applicable law fulfilling obligations under article 11 of the WIPO copyright treaty adopted on 20 December 1996 or similar laws prohibiting or restricting circumven tion of such measures When you convey a covered work you waive any legal power to forbid circumvention of technologi cal measures to the extent such circumvention is ef fected by exercising rights under this License with respect to the covered work and you disclaim any intention to limit operation or modification of the work as a means of enforcing against the work s users your or third parties legal rights to forbid circumvention of technological measures 4 Con veying Verbatim Copies You may convey verbatim copies of the Program s source code as you receive it in any medium pro vided that you conspicuously and appropriately publish on each copy an appropriate copyright no tice keep intact all notices stating that this License and any non permissive terms added in accord with section
123. allowing all of the related objects to be read in a single database query Batch fetching can be used for any type of relationship Batch fetching is one solution to the classic ORM n 1 performance problem The issue is if you select n Employee objects and access each of their addresses in basic ORM including JPA you will get 1 database select for the Employee objects and then n database selects one for each Address object Batch fetching solves this issue by requiring one select for the Employee objects and one select for the Address objects 19 Chapter 31 4 on page 147 147 Advanced Batch fetching is more optimal for reading collection relationships and multiple relationships as it does not require selecting duplicate data as in join fetching JPA does not support batch reading but some JPA providers do TopLink EclipseLink Support a BatchFetch annotation and xml element and a eclipselink batch query hint to enable batch reading Three forms of batch fetching are supported JOIN EXISTS and IN See also e Batch fetching optimizing object graph loading 31 5 Filtering Complex Joins Normally a relationship is based on a foreign key in the database but on occasion it is always based on other conditions Such as Employee having many PhoneNumbers but also a single home phone or one of his phones that has the home type or a collection of active projects or other such condition JPA does not suppo
124. allows you to define Structs or Object types to represent your data the structures can have nested structures arrays of basic data or other structures and refs to other structures You can then store a structure in a normal relational table column or create a special table to store the structures directly Querying is basic SQL with a few extensions to handle traversing the special types JPA does not support object relational data types but some JPA providers may offer some support TopLink EclipseLink Support object relational data types through their Struct Structure Array annotations and XML or their ObjectRelationalDataTypeDescriptor and mapping classes Custom support is also offered for Oracle spatial database JGeometry structures and other structured data types using the StructConverter annotation or XML See also e Complex data stored procedures Blog 41 6 XML Data Types With the advent of XML databases many relational database decided to add enhanced XML support Although it was always possible to store XML in a relational database just using a VARCHAR or CLOB column having the database aware of the XML data does have its advantages The main advantage is databases that offer XML support allow querying of the XML data using XPath or XQuery syntax Some databases also allow the XML data to be stored more efficiently than in Lob storage Databases with XML support include e Oracle XDB DB2 e Postg
125. along with this program If not see lt http www gnu org licenses gt Also add information on how to contact you by elec tronic and paper mail If the program does terminal interaction make it output a short notice like this when it starts in an interactive mode lt program gt Copyright C lt year gt lt name of au thor gt This program comes with ABSOLUTELY NO WARRANTY for details type show w This is free software and you are welcome to redistribute it under certain conditions type show c for details The hypothetical commands show w and show c should show the appropriate parts of the General Public License Of course your program s com mands might be different for a GUI interface you would use an about box You should also get your employer if you work as a programmer or school if any to sign a copyright disclaimer for the program if nec essary For more information on this and how to apply and follow the GNU GPL see lt http www gnu org licenses gt The GNU General Public License does not permit incorporating your program into proprietary pro grams If your program is a subroutine library you may consider it more useful to permit linking pro prietary applications with the library If this is what you want to do use the GNU Lesser General Public License instead of this License But first please read lt http www gnu org philosophy why not lgpl html g
126. an IdClass these duplicate attributes must be kept in synch with the ManyToOne attributes Some JPA providers may allow a ManyToOne to be part of an Id so this may be simpler with some JPA providers To make your life simpler I would recommend adding a generated Id attribute to the association class This will give the object a simpler Id and not require duplicating the Employee and Project ids This same pattern can be used no matter what the additional data in the join table is Another usage is if you have a Map relationship between two objects with a third unrelated object or data representing the Map key The JPA spec requires that the Map key be an attribute of the Map value so the association object pattern can be used to model the relationship If the additional data in the join table is only required on the database and not used in Java such as auditing information it may also be possible to use database triggers to automatically set the data 39 1 1 Example join table association object database EMPLOYEE table ID FIRSTNAME LASTNAME 1 Bob Way 2 Sarah Smith 1 Chapter 23 2 on page 69 183 Advanced PROJ_EMP table EMPLOYEEID PROJECTID IS_PROJECT_ LEAD 1 1 true 1 2 false 2 1 false PROJECT table ID NAME 1 GIS SIG 39 1 2 Example join table association object annotations Entity public class Employee Id private long id OneToMany mappedBy employee private List lt ProjectAssociation
127. anaged by the persistence context and not tracked for changes eclipselink query type Defines the native type of query to use for the query eclipselink sql hint Allows an SQL hint to be included in the SQL for the query eclipselink jdbc bind parameters Specifies if parameter binding should be used or not is used by default Chapter 31 3 on page 145 Chapter 31 4 on page 147 Chapter 10 on page 23 Chapter 11 on page 25 AUNE 225 Advanced 45 3 Update and Delete Queries JPQL also allows for UPDATE and DELETE queries to be executed This is not the recommend or normal way to modify objects in JPA Normally in JPA you first read the object then either modify it directly using its set methods to update it or call the EntityManager remove method to delete it UPDATE and DELETE queries in JPQL are for performing batch updates or deletions There allow a set of objects to be updated or deleted in a single query These queries are useful for performing batch operations or clearing test data UPDATE and DELETE queries have a WHERE the same as SELECT queries and can use the same functions and operations and traverse relationships and make use of sub selects UPDATE and DELETE queries are executed using the Query executeUpdate method and return the row count from the database Note that some caution should be used in execute these queries in an active persistence context as the queries may effect the objects t
128. annotations Entity IdClass EmployeelId class public class Employee Old Column name EMP_ID private long employeeld Old Column name DEP_ID insertable false updatable false private long departmentId Id Column name COM_ID insertable false updatable false private long companyld ManyToOne fetch FetchType LAZY JoinColumn name COM_ID private Company company ManyToOne fetch FetchType LAZY JoinColumns JoinColumn name DEP_ID JoinColumn name COM_ID insertable false updatable false private Department department ManyToOne fetch FetchType LAZY CJoinColumns JoinColumn name MNG_ID JoinColumn name DEP_ID insertable false updatable false JoinColumn name COM_ID insertable false updatable false private Employee manager OneToOne fetch FetchType LAZY JoinColumns JoinColumn name ADD_ID JoinColumn name DEP_ID insertable false updatable false JoinColumn name COM_ID insertable false updatable false private Address address 33 1 2 Example of cascaded primary keys and mixed OneToOne and ManyToOne mapping annotations using PrimaryKeyJoinColumn Entity IdClass EmployeelId class 160 Mapping a OneToOne Using a Join Table public class Employee Old Column name EMP_ID private long employeeld Id a Column name DEP_ID insertable false updatable false private long departmentld Id Column name COM_ID insert
129. any changes made to the database will not be cleared Any object that was read or persisted through the EntityManager is detached meaning any changes made to it will not be tracked and it should no longer be used unless merged into the new persistence context clear can be used similar to a rollback to abandon changes and restart a persistence context If a transaction commit fails or a rollback is performed the persistence context will automatically be cleared clear is similar to closing the EntityManager and creating a new one the main difference being that clear can be called while a transaction is in progress clear can also be used to free the objects and memory consumed by the EntityManager It is important to note that an EntityManager is responsible for tracking and managing all objects read within its persistence context In an application managed EntityManager this includes every objects read since the EntityManager was created including every transaction the EntityManager was used for If a long lived EntityManager is used this is an intrinsic memory leak so calling clear or closing the EntityManager and creating a new one is an important application design consideration For JTA managed EntityManagers the persistence context is automatically cleared across each JTA transaction boundary Clearing is also important on large batch jobs even if they occur in a single transaction The batch job can be slit into smaller batches within the
130. apped attribute for example if comparing a mapped enum the enum value is used not the database value Parameters are always set on the Query no matter what type of query it is JPQL Criteria native SQL NamedQuery Named Parameter Query query em createQuery Select e from Employee e where e name name query setParameter name Bob Smith Positional Parameter Query query em createNativeQuery SELECT FROM EMPLOYEE WHERE NAME query setParameter 1 Bob Smith 17 http en wikibooks org wiki Java 20Persistence 2FCriteria 18 http en wikibooks org wiki Java 20Persistence 2FJPQL 19 https java sun com javaee 5 docs api javax persistence Query html setParameter java lang String 20java lang Object https java sun com javaee 5 docs api javax persistence Query html setParameter int A 20java lang Object 218 Query Results 44 5 Query Results Normally JPA queries return your persistent Entity objects The returned objects will be managed by the persistent context EntityManager and changes made to the objects will be tracked as part of the current transaction In some case more complex queries can be built that just return data instead of Entity objects or even perform update or deletion operations There are three methods to execute a Query each returning different results e Query getResultList e Query getSingleResult oe e Query executeUpdate getResultList retur
131. ar EJB CMP implementations although it continued to recommend its POJO solution 1 http en wikipedia org wiki TopLink 2 http en wikipedia org wiki Dracle 20Corporation 3 Chapter 10 on page 23 25 TopLink TopLink also provided a JDO 1 0 implementation for a few releases but this was eventually deprecated and removed once the JPA specification had been formed Oracle and TopLink have been involved in each of the EJB JDO and EJB3 JPA expert groups and Oracle was the co lead for the EJB3 JPA specification e Oracle TopLink Home e Oracle TopLink Forum e Oracle TopLink Wiki TopLink Resources TopLink Automatic Schema Generation Options TopLink TopLink http www oracle com technology products ias toplink index html http forums oracle com forums forum jspa forumID 48 http wiki oracle com page TopLink http docs sun com app docs doc 819 3672 gbwmk a view http en wikibooks org wiki Category 3AJava 20Persistence 2FPersistence 20Products http en wikibooks org wiki Category 3AJava 20Persistence vovonovr a 26 12 Hibernate Hibernate was an open source project developed by a team of Java software developers around the world led by Gavin King JBoss Inc now part of Red Hat later hired the lead Hibernate developers and worked with them in supporting Hibernate The current version of Hibernate is Version 4 1 x Hibernate provides both a proprietary POJO API and JPA support Hibernate Hiberna
132. ases to achieve great success and standardization Relational databases are characterized by the SQL structured query language standard to query and modify the database their client server architecture and relational table storage structure Relational databases achieved great success because their standardization allowed many different vendors such as Oracle IBM and Sybase to produce interoperable products giving users the flexibility to switch their vendor and avoid vendor lock in to a proprietary solution Their client server architecture allows the client programming language to be decoupled from the server allowing the database server to support interface APIs into multiple different programming languages and clients Although relational databases are relatively old technology they still dominate the industry There have been many attempts to replace the relational model first with object oriented databases then with object relational databases and finally with XML databases but none of the new database models achieved much success and relational databases remain the overwhelmingly dominant database model The main relational databases used today are Oracle MySQL Oracle PostgreSQL DB2 IBM SQL Server Microsoft e Google trend for databases What is a database What is a database 4 http en wikipedia org wiki database http en wikipedia org wiki SQL http en wikipedia org wiki client 2Fserver
133. at if every field value of the embeddable is null then the reference should be null but then there is no way to represent an embeddable with all null values JPA does not allow embeddables to be null but some JPA providers may support this TopLink EclipseLink Support an embedded reference being null This is set through using a DescriptorCustomizer and the Aggregate0bjectMapping setIsNullAllowed API 2 Chapter 23 1 2 on page 67 3 Chapter 11 on page 25 4 Chapter 10 on page 23 94 Nesting 26 4 Nesting A nested embeddable is a relationship to an embeddable object from another embeddable The JPA 1 0 spec only allows Basic relationships in an embeddable object so nested embeddables are not supported however some JPA products may support them Technically there is nothing preventing the CEmdedded annotation being used in an embeddable object so this may just work depending on your JPA provider cross your fingers JPA 2 0 supports nested embeddable objects TopLink EclipseLink Support embedded mappings from embeddables The existing Embedded annotation or lt embedded gt element can be used A workaround to having a nested embeddable and for embeddables in general is to use property access and add get set methods for all of the attributes of the nested embeddable object Example of using properties to define a nested embeddable Embeddable public class EmploymentDetails private EmploymentPeriod per
134. at most closely approximates an absolute waiver of all civil liability in connection with the Program unless a warranty or assumption of liability accompanies a copy of the Program in return for a fee END OF TERMS AND CONDITIONS How to Ap ply These Terms to Your New Programs If you develop a new program and you want it to be of the greatest possible use to the public the best way to achieve this is to make it free software which everyone can redistribute and change under these terms To do so attach the following notices to the pro gram It is safest to attach them to the start of each source file to most effectively state the exclu sion of warranty and each file should have at least the copyright line and a pointer to where the full notice is found lt one line to give the program s name and a brief idea of what it does gt Copyright C lt year gt lt name of author gt This program is free software you can redistribute it and or modify it under the terms of the GNU General Public License as published by the Free Software Foundation either version 3 of the Li cense or at your option any later version This program is distributed in the hope that it will be useful but WITHOUT ANY WAR RANTY without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PAR TICULAR PURPOSE See the GNU General Public License for more details You should have received a copy of the GNU Gen eral Public License
135. ata could either be stored in place in the altered table or the table could be left to only contain the current version of the data and a mirror history table could be added to store the data In the mirror case database triggers could be used to write to the history table For the in place case a database view could be used to give a view of the table as of the current time To query the current data from a history table any query must include the clause where the END is NULL To query as of a point in time the where clause must include where the point in time is between the START and END timestamps JPA does not define any specific history support Oracle flashback can be used with JPA but any queries for historical data will need to use native SQL If a mirror history table is used with triggers JPA can still be used to query to current data A subclass or sibling class could also be mapped to the history table to allow querying of history data If a database view is used the JPA could be used by mapping the Entity to the view If a history table is used JPA could still be used to map to the table and a start and end attribute could be added to the object Queries for the current data could append the current time to the query Relationships are more difficult as JPA requires relationships to be by primary key and historical relationships would not be Some JPA providers have support for history 202 Logical Deletes T
136. atio gt 3 14e32D Boolean TRUE FALSE Select e from Employee e where e active TRUE Date d yyyy mm dd Select e from Employee e where e startDate d 2012 01 03 Time t hh mm ss Select e from Employee e where e startTime t 09 00 00 Timestamp ts yyy mm dd hh mm ss nnnnnnnnn Select e from Employee e where e version ts 2012 01 03 09 00 00 000000001 Enum package class enum Select e from Employee e where e gender org acme Gender MALE null NULL Update Employee e set e manager NULL where e manager manager 12 Chapter 46 1 3 on page 235 238 New in JPA 2 0 46 5 New in JPA 2 0 The following new syntax was added in JPA 2 0 type_discriminator TYPE identification_variable single _valued_object_path_ expression input_ parameter Allows type class of object to be queried SELECT p from Project p where TYPE p in LargeProject SmallProject qualified_ identification variable KEY identification variable VALUE identification_ variable ENTRY identification_ variable Allows selecting on Map keys values and Map Entry SELECT ENTRY e contactInfo from Employee e general_identification_ variable identification variable KEY identification variable VALUE identification_ variable Allows querying on Map keys and values SELECT e from Employee e join e contactInfo c where KEY c Email and VALUE c joe gmail com i
137. base DATE this is just a basic mapping and you should not have any issues ignore Oracle s DATE type that is was a timestamp for now You can also map java sql Time to TIME and java sql Timestamp to TIMESTAMP However if you have a java util Date or java util Calendar in Java and wish to map it to a DATE or TIME you may need to indicate that the JPA provider perform some sort of conversion for this In JPA the Temporal annotation or lt temporal gt element is used to map this You can indicate that just the DATE or TIME portion of the date time value be stored to the database You could also use Temporal to map a java sql Date to a TIMESTAMP field or any other such conversion 29 1 1 Example of temporal annotation Entity public class Employee Basic Temporal DATE private Calendar startDate 29 1 2 Example of temporal XML lt entity name Employee class org acme Employee access FIELD gt 1 https java sun com javaee 5 docs api javax persistence Temporal html 115 Advanced lt attributes gt lt basic name startDate gt lt temporal gt DATE lt temporal gt lt basic gt lt attributes gt lt entity gt 29 1 3 Milliseconds The precision of milliseconds is different for different temporal classes and database types and on different databases The java util Date and Calendar classes support millisec onds The java sql Date and java sql Time classes do not support milliseconds The java sql Time
138. bject or pessimistically locking every possible related object This could be done but would probably be very expensive and more importantly would now raise possible conflicts every time a user checked in so would be entirely useless So in general be careful of being too paranoid such that you sacrifice the usability of your system Other applications accessing same data Any form of locking that is going to work requires that all applications accessing the same data follow the same rules If you use optimistic locking in one application but no locking in another accessing the same data they will still conflict One fake solution is to configure an update trigger to always increment the version value unless incremented in the update This will allow the new application to avoid overwriting the old application s changes but the old application will still be able to overwrite the new application s changes This still may be better than no locking at all and perhaps the old application will eventually go away One common misconception is that if you use pessimistic locking instead of adding a version field you will be ok Again pessimistic locking requires that all applications accessing the same data use the same form of locking The old application can still read data without locking then update the data after the new application reads locks and updates the same data overwriting its changes 102 Optimistic Locking Isn
139. brella and has major providers including IBM WebSphere RedHat JBoss Sun Glassfish BEA WebLogic Oracle AS and many others 3 1 Google Trends e Programming Languages JEE Servers 3 2 See also e Java Programming http en wikipedia org wiki Java 20 28programming 20language 297 20 http en wikipedia org wiki object 20oriented 20 http en wikipedia org wiki Sun 20Microsystems 20 http en wikipedia org wiki C 2B 2B 20 http en wikipedia org wiki Smalltalk 20 http www google com trends q c 23 2C php 2C java 2C ch 2B 2B 2C perl amp ctab 0 amp geo all amp date all amp sort 0 Unfortunately hard to seperate Java island from Java language http www google com trends q websphere 2C tweblogich2C jboss 2Ctglassfish 2C geronimotapache amp ctab 0O amp geo all amp date all amp sort 0 Could not include Oracle because of Oracle database hits http en wikibooks org wiki Java 20Programming RO DAN DoKBRWNYHE o What is Java What is Java What is Java 11 http en wikibooks org wiki Category 3AJava 20Persistence 2FWhat 20is 20Java 20persistence 12 http en wikibooks org wiki Category 3AJava 20Persistence 4 What is a database A database is a program that stores data There are many types of databases flat file hierarchical relational object relational object oriented xml and others The original databases were mainly proprietary and non standardized Relational databases were the first datab
140. butes gt lt basic name yearsOfService gt lt column name YEAR_OF_SERV table EMP_DATA gt lt basic gt 9 https java sun com javaee 5 docs api javax persistence SecondaryTable html 10 https java sun com javaee 5 docs api javax persistence PrimaryKeyJoinColumn html 48 Multiple tables with foreign keys lt one to one name manager gt lt join column name MGR_ID table EMP_DATA referenced column name ID gt lt one to one gt lt attributes gt lt entity gt With the PrimaryKeyJoinColumn the name refers to the foreign key column in the secondary table and the referencedColumnName refers to the primary key column in the first table If you have multiple secondary tables they must always refer to the first table When defining the table s schema typically you will define the join columns in the secondary table as the primary key of the table and a foreign key to the first table Depending how you have defined your foreign key constraints the order of the tables can be important the order will typically match the order that the JPA implementation will insert into the tables so ensure the table order matches your constraint dependencies For relationships to a class that has multiple tables the foreign key join column always maps to the primary table of the target JPA does not allow having a foreign key map to a table other than the target object s primary table Normally this is not an issue as foreign k
141. c and even serialized if not a basic type The column name for the attribute will be defaulted named the same as the attribute name as uppercase Sometimes auto mapping can be unexpected if you have an attribute in your class that you did not intend to have 1 https java sun com javaee 5 docs api javax persistence Basic html 2 Chapter 29 on page 115 111 Basics persisted You must mark any such non persistent fields using the Transient annotation or lt transient gt element Although auto mapping makes rapid prototyping easy you typically reach a point where you want control over your database schema To specify the column name for a basic attribute the Column annotation or lt column gt element is used The column annotation also allows for other information to be specified such as the database type size and some constraints 28 0 10 Example of basic mapping annotations Entity public class Employee Id mappings are also basic mappings eId Column name ID private long id Basic Column name F_NAME private String firstName The Basic is not required in general because it is the default Column name L_NAME private String lastName Any un mapped field will be automatically mapped as basic and column name defaulted private BigDecimal salary Non persistent fields must be marked as transient Transient private EmployeeService service 28 0 11 Example of basic mapping XML lt
142. cache e L1 This refers to the transactional cache that is part of every EntityManager this is not a shared cache e L2 This is a shared cache conceptually stored in the EntityManagerFactory so accessible to all EntityManagers e Data cache The data representing the objects is cached database rows e Object cache The objects are cached directly e Relationship cache The object s relationships are cached e Query cachet The result set from a query is cached e Read only A cache that only stores or only allows read only objects e Read write A cache that can handle insert updates and deletes non read only e Transactional A cache that can handle insert updates and deletes non read only and obeys transactional ACID properties e Clustered Typically refers to a cache that uses JMS JGroups or some other mechanism to broadcast invalidation messages to other servers in the cluster when an object is updated or deleted 8 Chapter 51 6 1 on page 266 9 Chapter 51 6 2 on page 266 10 Chapter 51 3 on page 263 11 Chapter 51 2 on page 262 12 Chapter 51 3 1 on page 263 13 Chapter 51 5 on page 265 14 Chapter 51 6 6 on page 269 264 Query Cache e Replicated Typically refers to a cache that uses JMS JGroups or some other mechanism to broadcast objects to all servers when read into any of the servers cache e Distributed Typically refers to a cache that spreads the cached objects across severa
143. called an aggregate if the copyright re sulting from the compilation is not used to limit the legal rights of the compilation s users beyond what the individual works permit When the Document is included in an aggregate this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document If the Cover Text requirement of section 3 is appli cable to these copies of the Document then if the Document is less than one half of the entire aggre gate the Document s Cover Texts may be placed on covers that bracket the Document within the aggregate or the electronic equivalent of covers if the Document is in electronic form Otherwise they must appear on printed covers that bracket the whole aggregate 8 TRANSLATION 57 3 GNU Lesser General Public License GNU LESSER GENERAL PUBLIC LICENSE Version 3 29 June 2007 Copyright O 2007 Free Software Foundation Inc lt http fsf org gt Everyone is permitted to copy and distribute verba tim copies of this license document but changing it is not allowed This version of the GNU Lesser General Public Li cense incorporates the terms and conditions of ver sion 3 of the GNU General Public License supple mented by the additional permissions listed below 0 Additional Definitions As used herein this License refers to version 3 of the GNU Lesser General Public License and the GNU GPL refers to version 3 of the GNU
144. ccurred but before the transaction is committed It does not occur during the persist operation The Id of the object should be assigned e PreUpdate Invoked before an instance is updated in the database This occurs during a flush or commit operation after the database UPDATE has occurred but before the transaction is committed It does not occur during the merge operation e PostUpdate Invoked after an instance is updated in the database This occurs during a flush or commit operation after the database UPDATE has occurred but before the transaction is committed It does not occur during the merge operation e PreRemove Invoked before the remove operation is invoked on an Entity Also invoked for cascade of a remove operation It is also invoked during a flush or commit for orphanRemoval in JPA 2 0 http download oracle com javaee 6 api javax persistence EntityListeners html http download oracle com javaee 6 api javax persistence PostLoad html http download oracle com javaee 6 api javax persistence PrePersist html http download oracle com javaee 6 api javax persistence PostPersist html http download oracle com javaee 6 api javax persistence PreUpdate html http download oracle com javaee 6 api javax persistence PostUpdate html http download oracle com javaee 6 api javax persistence PreRemove html NOoTR WN FH 193 Advanced Topics e PostRemove Invoked after an instance is deleted from the database This
145. ce Query html setFirstResult int 12 https java sun com javaee 5 docs api javax persistence Query htmlt setMaxResults int 227 Advanced standard SQL for pagination so whether if this is supported depends on your database and your JPA providers support When performing pagination it is also important to order the result If the query does not order the result then each subsequent query could potentially return the results in a different order and give a different page Also if rows are insert deleted in between the queries the results can be slightly different 45 5 1 Example using firstResult maxResults Query query em createQuery Select e from Employee e order by e id query setFirstResult 100 query setMaxResults 200 List lt Employee gt page query getResultList An alternative to using firstResult is to filter the first result in the where clause based on the order by and the value from the previous page 45 5 2 Example using maxResults and order by Query query em createQuery Select e from Employee e where e id gt lastId order by e id query setParameter lastId prevousPage get prevousPage size 1 getId query setMaxResults 100 List lt Employee gt nextPage query getResultList Another alternative is to only query the Ids and store this result in a stateful SessionBean or an http session Then query for the set of Ids for each page 45 5 3 Example using Ids an
146. ce avoid loading the object so some JPA providers may not support it and just perform a normal find operation The object returned by getReference should appear to be a normal object if you access any method or attribute other than its Id it will trigger itself to be refreshed from the database The intention of getReference is that it could be used on an insert or update operation as a stand in for a related object if you only have its Id and want to avoid loading the object Note that getReference does not verify the existence of the object as find does If the object does not exist and you try to use the unfetched object in an insert or update you may get a foreign key constraint violation or if you access the object it may trigger an exception Example getReference EntityManager em getEntityManager Employee manager em getReference managerld Employee employee new Employee em persist employee employee setManager manager em commit 48 4 Flush The EntityManager flush operation can be used the write all changes to the database before the transaction is committed By default JPA does not normally write changes to the database until the transaction is committed This is normally desirable as it avoids database access resources and locks until required It also allows database writes to be ordered and batched for optimal database access and to maintain integrity constraints and avoid deadlocks This means tha
147. ce unit jar Only attributes that are rarely accessed should be marked lazy as accessing the attribute causes a separate database select which can hurt performance This is especially true if a large number of objects is queried The original query will require one database select but if each object s lazy attribute is accessed this will require n database selects which can be a major performance issue Using lazy fetching on basics is similar to the concept of fetch groups Lazy basics is basically support for a single default fetch group Some JPA providers support fetch groups in general which allow more sophisticated control over what attributes are fetched per query TopLink EclipseLink Support lazy basics and fetch groups Fetch groups can be configured through the EclipseLink API using the FetchGroup class 29 5 Optional A Basic attribute can be optional if its value is allowed to be null By default everything is assumed to be optional except for an Id which can not be optional Optional is basically only a hint that applies to database schema generation if the persistence provider is configured to generate the schema It adds a NOT NULL constraint to the column if false Some JPA providers also perform validation of the object for optional attributes and will throw a validation error before writing to the database but this is not required by the JPA specification Optional is defined through the optional attribute of the
148. cking EntityManager API updates Cache APIs Standard Properties Metadata Criteria API JPQL enhancements 6 0 1 Resources JPA 2 0 Spec JPA 2 0 Reference Implementation EclipseLink Eclipse EclipseLink to be JPA 2 0 Reference Implementation JPA 2 0 Examples ONnDo1R WN Hm Chapter 31 2 1 on page 141 Chapter 23 2 2 on page 71 Chapter 26 4 on page 95 Chapter 39 1 2 on page 185 Chapter 37 1 on page 177 Chapter 30 5 4 on page 133 Chapter 31 6 on page 148 Chapter 27 2 7 on page 107 Chapter 46 5 on page 240 Chapter 51 6 4 on page 268 Chapter 43 1 on page 209 Chapter 44 2 1 on page 218 Chapter 46 5 on page 239 http jcp org en jsr detail id 317 http www eclipse org eclipselink http www eclipse org org press release 20080317_Eclipselink php http wiki eclipse org EclipseLink Examples JPA JPA_2 0 13 What is new in JPA 2 0 What is new in JPA 2 018 What is new in JPA 2 01 18 http en wikibooks org wiki Category 3AJava 20Persistence 2FWhat 20is 20Java 20persistence 19 http en wikibooks org wiki Category 3AJava 20Persistence 14 7 Other Persistence Specs There are many specifications related to persistence in Java The following table summarises the latest version of each specification Spec Version Year of Last Re lease JDBC Java DataBase Connectivity 5 0 2010 JDO Java Data Objects 3 0 2010 JPA Java Persistence API 2 0 2009 JCA Java
149. class Employee private EmploymentDetails details Chapter 11 on page 25 Chapter 10 on page 23 Chapter 11 on page 25 Chapter 10 on page 23 Foon o 96 Collections Embedded public EmploymentDetails getEmploymentDetails return details OneToOne public Address getEmploymentAddress return getEmploymentDetails getAddress a public void setEmploymentAddress Address address getEmploymentDetails setAddress address h One special relationship that is sometimes desired in an embeddable is a relationship to its parent JPA does not support this but some JPA providers may Hibernate Supports a Parent annotation in embeddables to define a relationship to its parent A workaround to having a parent relationship from an embeddable is to set the parent in the property set method Example of setting a relationship in an embeddable to its parent Entity public class Employee private EmploymentDetails details Embedded public EmploymentDetails getEmploymentDetails return details public void setEmploymentDetails EmploymentDetails details this details details details setParent this F 26 7 Collections A collection of embeddable objects is similar to a OneToMany except the target objects are embeddables and have no Id This allows for a OneToMany to be defined without a inverse ManyToOne as the parent is responsible for storing the foreign key i
150. class LargeProject extends Project private BigDecimal budget Entity Table name SMALLPROJECT public class SmallProject extends Project 83 Advanced 24 1 3 Example table per class inheritance XML lt entity name Project class org acme Project access FIELD gt lt inheritance strategy TABLE_PER_CLASS gt lt attributes gt lt id name id gt lt attributes gt lt entity gt lt entity name LargeProject class org acme LargeProject access FIELD gt lt table name LARGEPROJECT gt lt entity gt lt entity name SmallProject class org acme SmallProject access FIELD gt lt table name SMALLPROJECT gt lt entity gt 24 1 4 Common Problems Poor query performance The main disadvantage to the table per class model is queries or relationships to the root or branch classes become expensive Querying the root or branch classes require multiple queries or unions One solution is to use single table inheritance instead this is good if the classes have a lot in common but if it is a big hierarchy and the subclasses have little in common this may not be desirable Another solution is to remove the table per class inheritance and instead use a MappedSuperclass but this means that you can no longer query or have relationships to the class Issues with ordering and joins Because table per class inheritance requires multiple queries or unions you cannot join to fetch join or
151. companyld this departmentId departmentld 5 Chapter 11 on page 25 6 Chapter 10 on page 23 68 Primary Keys through OneToOne and ManyToOne Relationships public boolean equals Object object if object instanceof EmployeePK EmployeePK pk EmployeePK object return employeeld pk employeeld amp amp companyld pk companyld amp amp departmentId pk departmentld else return false k public int hashCode return employeeld companyId departmentld 23 2 Primary Keys through OneToOne and ManyToOne Relationships A common model is to have a dependent object share the primary key of its parent In the case of a OneToOne the child s primary key is the same as the parent and in the case of a ManyToOne the child s primary key is composed of the parent s primary key and another locally unique field JPA 1 0 does not allow Id on a OneToOne or ManyToOne but JPA 2 0 does One of the biggest pitfalls when working with composite primary keys comes with the implementation of associations to entity classes whose tables have multi column primary keys using the JoinColumns annotation Many JPA implementations may throw seemingly inconsistent exceptions when not specifying referencedColumnName for every JoinColumn annotation which JPA requires even if all referenced column names are equal to the ones in the referencing table See http download oracle com javaee 5 api javax persistence JoinCo
152. ct s table but stored in a separate collection table This is similar to a OneToMany except the target object is an Embeddable instead of an Entity This allows collections of simple objects to be easily defined without requiring the simple objects to define an Id or ManyToOne inverse mapping ElementCollection can also override the mappings or table for their collection so you can have multiple entities reference the same Embeddable class but have each store their dependent objects in a separate table The limitations of using an ElementCollection instead of a OneToMany is that the target objects cannot be queried persisted merged independently of their parent object They are strictly privately owned dependent objects the same as an Embedded mapping There is no cascade option on an ElementCollection the target objects are always persisted merged removed with their parent ElementCollection still can use a fetch type and defaults to LAZY the same as other collection mappings 40 1 1 Example of an ElementCollection relationship database EMPLOYEE table EMP_ID F_NAME L_NAME SALARY 1 Bob Way 50000 2 Joe Smith 35000 PHONE table OWNER_ID TYPE AREA CODE P_NUMBER 1 home 613 792 0001 1 work 613 494 1234 2 work 416 892 0005 40 1 2 Example of an ElementCollection relationship annotations Entity public class Employee Id Column name EMP_ID 4 https java sun com javaee 5 docs api javax persistence JoinColumn htm
153. d IN Query query em createQuery Select e id from Employee e List lt Long gt ids query getResultList Query pageQuery em createQuery Select e from Employee e where e id in ids pageQuery setParameter ids ids subList 100 200 List lt Employee gt page pageQuery getResultList Pagination can also be used for server processes or batch jobs On the server it is normally used to avoid using too much memory upfront and allow processing each batch one at a time Any of these techniques can be used also some JPA providers support returning a database cursor for the query results that allows scrolling through the results TopLink EclipseLink Support streams and scrollable cursors through the query hints eclipselink cursor scrollable and eclipselink cursor and CursoredStream and ScrollableCursor classes 13 Chapter 11 on page 25 14 Chapter 10 on page 23 228 Native SQL Queries 45 6 Native SQL Queries Typically queries in JPA are defined through JPQL JPQL allows the queries to be defined in terms of the object model instead of the data model Since developers are programming in Java using the object model this is normally more intuitive This also allows for data abstraction and database schema and database platform independence JPQL supports much of the SQL syntax but some aspects of SQL or specific database extensions or functions may not be possible through JPQL so native SQL queries ar
154. d or set methods in the object model that handle both sides of the relationships so the application code does not need to worry about it There are two ways to go about this you can either only add the relationship maintenance code to one side of the relationship and only use the setter from one side such as making the other side protected or add it to both sides and ensure you avoid a infinite loop For example public class Employee private List phones public void addPhone Phone phone this phones add phone if phone getOwner this phone setOwner this public class Phone private Employee owner public void setOwner Employee employee this owner employee if employee getPhones contains this employee getPhones add this E The code is similar for bi directional OneToOne and ManyToMany relationships Some expect the JPA provider to have magic that automatically maintains relationships This was actually part of the EJB CMP 2 specification However the issue is if the objects are detached or serialized to another VM or new objects are related before being managed or the object model is used outside the scope of JPA then the magic is gone and the application is left figuring things out so in general it may be better to add the code to the object model However some JPA providers do have support for automatically maintaining relationships In some cases it is undesirable to in
155. dard defined by a recognized standards body or in the case of interfaces spec ified for a particular programming language one that is widely used among developers working in that language The System Libraries of an executable work in clude anything other than the work as a whole that a is included in the normal form of packag ing a Major Component but which is not part of that Major Component and b serves only to en able use of the work with that Major Component or to implement a Standard Interface for which an implementation is available to the public in source code form A Major Component in this context means a major essential component kernel window system and so on of the specific operating system if any on which the executable work runs or a compiler used to produce the work or an object code interpreter used to run it The Corresponding Source for a work in object code form means all the source code needed to gen erate install and for an executable work run the object code and to modify the work including scripts to control those activities However it does not include the work s System Libraries or general purpose tools or generally available free programs which are used unmodified in performing those ac tivities but which are not part of the work For example Corresponding Source includes interface definition files associated with source files for the work and the source code
156. del for a data model that included the mapping and persistence logic in it ORM products that provided mapping tools to allow the mapping of an existing object model to an existing data model and stored this mapping meta data in flat files database tables XML and finally annotations In JPA mappings can either be stored through Java annotations or in XML files One significant aspect of JPA is that only the minimal amount of mapping is required JPA implementations are required to provide defaults for almost all aspects of mapping an object The minimum requirement to mapping an object in JPA is to define which objects can be persisted This is done through either marking the class with the Entity annotation or adding an lt entity gt tag for the class in the persistence unit s ORM XML file Also the primary key or unique identifier attribute s must be defined for the class This is done through marking one of the class fields or properties get method with the Id annotation or adding an lt id gt tag for the class attribute in the ORM XML file The JPA implementation will default all other mapping information including defaulting the table name column names for all defined fields or properties cardinality and mapping of relationships all SQL and persistence logic for accessing the objects Most JPA imple mentations also provide the option of generating the database tables at runtime so very little work is required by the developer
157. do this then you can use a intermediate join table to store the relationship This is similar to a ManyToMany relationship but if you add a unique constraint to the target foreign key you can enforce that it is OneToMany JPA defines a join table using the JoinTable annotation and lt join table gt XML element A JoinTable can be used on a ManyToMany or OneToMany mappings See also Undirectional OneToMany 36 1 1 Example of a OneToMany using a JoinTable database EMPLOYEE table EMP_ID FIRSTNAME LASTNAME 1 Bob Way 2 Sarah Smith EMP_ PHONE table EMP_ID PHONE_ID 1 1 4 https java sun com javaee 5 docs api javax persistence JoinTable html 5 Chapter 37 1 on page 177 174 Join Table PHONE table ID TYPE AREA CODE P_ NUMBER 1 home 613 792 0000 2 work 613 896 1234 3 work 416 123 4444 36 1 2 Example of a OneToMany using a JoinTable annotation Entity public class Employee Id Column name EMP_ID private long id OneToMany JoinTable name EMP_PHONE joinColumns JoinColumn name EMP_ID referencedColumnName EMP_ID inverseJoinColumns JoinColumn name PHONE_ID referencedColumnName ID unique true private List lt Phone gt phones 36 1 3 Example of a OneToMany using a JoinTable XML lt entity name Employee class org acme Employee access FIELD gt lt attributes gt lt id name id gt lt column name EMP_ID gt lt id gt lt one to many name phon
158. dvantage of being use case specific so different use cases can instantiate different relationships For collection relationships sending size is normally the best way to ensure a lazy relationship is instantiated For OneToOne and ManyToOne rela tionships normally just accessing the relationship is enough i e employee getAddress although for some JPA providers that use proxies you may need to send the object a message i e employee getAddress hashCode A third solution is to use the JPQL JOIN FETCH for the relationship when querying the objects A join fetch will normally ensure the relationship has been instantiated Some caution should be used with join fetch however as it can become inefficient if used on collection relationships especially multiple collection relationships as it requires an n 2 join on the database Some JPA providers may also provide certain query hints or other such serialization options The same issue can occur without serialization if a detached object is accessed after the end of the transaction Some JPA providers allow lazy relationship access after the end of the transaction or after the EntityManager has been closed however some do not If your JPA provider does not then you may require that you ensure you have instantiated all the lazy relationships that you will need before ending the transaction 30 1 6 Eager Join Fetching One common misconception is that EAGER means that the relatio
159. e can be configured with respect to the application s requirements Time of day invalidation allows the cache to be invalidated at a certain time of day typically done in the night this ensures data is never older than a day old This can also be used if it is know that a batch job updates the database a night the invalidation time can be set after this batch job is scheduled to run Data can also be invalidated manually such as using the JPA 2 0 evict O API Most cache implementations support some form of invalidation JPA does not define any configurable invalidation options so this depends on the JPA and cache provider TopLink EclipseLink Provide support for time to live and time of day cache invalidation using the Cache annotation and lt cache gt orm xml element Cache invalidation is also supported through API and can be used in a cluster to invalidate objects changed on other machines 51 6 6 Caching in a Cluster Caching in a clustered environment is difficult because each machine will update the database directly but not update the other machine s caches so each machines cache can become out of date This does not mean that caching cannot be used in a cluster but you must be careful in how it is configured For read only objects caching can still be used For read mostly objects caching can be used but some mechanism should be used to avoid stale data If stale data is only an issue for writes then using optimistic
160. e not the detached object merge is normally called on existing objects but can also be called on new objects If the object is new a new copy of the object will be made and registered with the persistence context the detached object will not be persisted itself merge can only be called on Entity objects not on Embeddable objects or collections or non persistent objects Embeddable objects are automatically merged as part of their owning Entity https java sun com javaee 5 docs api javax persistence EntityManager html merge java lang Object 243 Persisting Example merge EntityManager em createEntityManager Employee detached em find Employee class id em close em createEntityManager em getTransaction begin Employee managed em merge detached em getTransaction commit 47 2 1 Cascading Merge Calling merge on an object will also cascade the merge operation across any relationship that is marked as cascade merge Even if the relationship is not cascade merge the reference will still be merged If the relationship is cascade merge the relationship and each related object will be merged Intuitively you may consider marking every relationship as cascade merge to avoid having to worry about calling merge on every objects but this is normally a bad idea One issue with marking all relationships cascade merge is performance If you have an object with a lot of relationships the
161. e Address access FIELD gt lt attributes gt lt id name ownerId gt Chapter 11 on page 25 Chapter 10 on page 23 Chapter 12 on page 27 Chapter 15 on page 33 Chapter 10 on page 23 Pr oO ON Ro 70 Primary Keys through OneToOne and ManyToOne Relationships lt column name OWNER_ID gt lt id gt lt one to one name owner gt lt primary key join column name OWNER_ID referencedColumnName EMP_ID gt lt one to one gt lt attributes gt lt entity gt Example ManyToOne id annotation Entity IdClass PhonePK class public class Phone Old Column name OWNER_ID private long ownerld Id private String type ManyToOne PrimaryKeyJoinColumn name OWNER_ID referencedColumnName EMP_ID private Employee owner public void setOwner Employee owner this owner owner this ownerId owner getld Example ManyToOne id XML lt entity name Address class org acme Address access FIELD gt lt id class class org acme PhonePK gt lt attributes gt lt id name ownerld gt lt column name OWNER_ID gt lt id gt lt id name type gt lt many to one name owner gt lt primary key join column name OWNER_ID referencedColumnName EMP_ID gt lt many to one gt lt attributes gt lt entity gt 23 2 2 JPA 2 0 Defining an Id for a OneToOne or ManyToOne in JPA 2 0 is much simpler The Id annotation or id XML attribute can be added to a OneToOne or ManyToOne
162. e actual knowledge that but for the patent license your conveying the covered work in a country or your recipient s use of the cov ered work in a country would infringe one or more identifiable patents in that country that you have reason to believe are valid If pursuant to or in connection with a single trans action or arrangement you convey or propagate by procuring conveyance of a covered work and grant a patent license to some of the parties re ceiving the covered work authorizing them to use propagate modify or convey a specific copy of the covered work then the patent license you grant is automatically extended to all recipients of the cov ered work and works based on it A patent license is discriminatory if it does not in clude within the scope of its coverage prohibits the exercise of or is conditioned on the non exercise of one or more of the rights that are specifically granted under this License You may not convey a covered work if you are a party to an arrangement with a third party that is in the business of dis tributing software under which you make payment to the third party based on the extent of your ac tivity of conveying the work and under which the third party grants to any of the parties who would receive the covered work from you a discrimina tory patent license a in connection with copies of the covered work conveyed by you or copies made from those copies or b primarily for and
163. e an Employee class and an Address class which is typically the best solution You should also check with you JPA implementation to see what extensions it supports in this area One way to solve the issue is simply to swap your primary and secondary tables This will result in having the secondary table referencing the primary tables primary key and is within the spec This however will have side effects one being that you now changed the primary key of your object from EMP_ID to ADDRESS_ID and may have other mapping and querying implications If you have more than 2 tables this also may not work Another option is to just use the foreign key column in the PrimaryKeyJoinColumn this will technically be backward and perhaps not supported by the spec but may work for some JPA implementations However this will result in the table insert order not matching the foreign key constraints so the constraints will need to be removed or deferred It is also possible to map the scenario through a database view A view could be defined joining the two tables and the class could be mapped to the view instead of the tables Views are read only on some databases but many also allow writes or allow triggers to be used to handle writes Some JPA implementations provide extensions to handle this scenarios TopLink EclipseLink Provides a proprietary API for its mapping model ClassDescriptor addForeignKeyFieldNameForMultipleTable that allows for arbi
164. e attribute that is not a relationship or a basic type String Number temporal primitive will be serialized to a BLOB field JPA defines the Lob annotation and lt lob gt element on a lt basic gt to define that an attribute maps to a LOB type in the database The annotation is just a hint to the JPA implementation that this attribute will be stored in a LOB as LOBs may need to be persisted specially Sometimes just mapping the LOB as a normal Basic will work fine as well Various databases and JDBC drivers have various limits for LOB sizes Some JDBC drivers have issues beyond 4k 32k or Imeg The Oracle thin JDBC drivers had a 4k limitation in some versions for binding LOB data Oracle provided a workaround for this limitation which some JPA providers support For reading LOBs some JDBC drivers prefer using streams some JPA providers also support this option Typically the entire LOB will be read and written for the attribute For very large LOBs reading the value always or reading the entire value may not be desired The fetch type of the Basic could be set to LAZY to avoid reading a LOB unless accessed Support for LAZY fetching on Basic is optional in JPA so some JPA providers may not support it A workaround which is often a good idea in general given the large performance cost of LOBs is to store the LOB in a separate table and class and define a OneToOne to the LOB object instead of a Basic If the entire LOB is never desired
165. e many persistence products to choose from Most persistence products now support a JPA interface although there still are some exceptions Which product you use depends on your preference but most people would recommend you use the JPA standard whichever product you choose This gives you the flexibility to switch persistence providers or port your application to another server platform which may use a different persistence provider Determining which persistence product to use involves many criteria Valid things to consider include e Which persistence product does your server platform support and integrate with e What is the cost of the product is it free and open source can you purchase enterprise level support and services e Do you have an existing relationship with the company producing the product e Is the product active and does it have a large user base e How does the product perform and scale e Does the product integrate with your database platform e Does the product have active and open forums do questions receive useful responses e Is the product JPA compliant what functionality does the product offer beyond the JPA specification 9 1 Existing Persistence Products The following table summaries existing persistence products 1 Last updated 2013 01 19 Persistence Products STOT Svea BIO 9ZT 21301 M 92 BIO ea ysy Ssse H 9ZT 21301 M BIO ssog f SI9AIOS UO0TJe9
166. e mechanism is one that a uses at run time a copy of the Li brary already present on the user s computer sys tem and b will operate properly with a modified version of the Library that is interface compatible with the Linked Version e Provide Installation Information but only if you would otherwise be re quired to provide such information under section 6 of the GNU GPL and only to the extent that such information is necessary to install and execute a modified version of the Combined Work produced by recombining or relinking the Application with a modified version of the Linked Version If you use option 4d0 the Installation Information must accompany the Minimal Corresponding Source and Corresponding Application Code If you use option 4d1 you must provide the Installation Information in the manner specified by section 6 of the GNU GPL for conveying Corresponding Source this License can be used that proxy s public state ment of acceptance of a version permanently autho rizes you to choose that version for the Document 11 RELICENSING Massive Multiauthor Collaboration Site or MMC Site means any World Wide Web server that publishes copyrightable works and also pro vides prominent facilities for anybody to edit those works A public wiki that anybody can edit is an example of such a server A Massive Multiau thor Collaboration or MMC contained in the site means any set of copyrightable works thus pub
167. e something considered earlier in the development cycle If the application will have concurrent writers to the same objects then a locking strategy is critical so that data corruption can be prevented There are two strategies for preventing concurrent modification of the same object row optimistic and pessimistic locking Tech nically there is a third strategy ostrich locking or no locking which means put your head in the sand and ignore the issue There are various ways to implement both optimistic and pessimistic locking JPA has support for version optimistic locking but some JPA providers support other methods of optimistic locking as well as pessimistic locking Locking and concurrency can be a confusing thing to consider and there are a lot of misconcepts out there Correctly implementing locking in your application typically involves more than setting some JPA or database configuration option although that is all many applications that think they are using locking do Locking may also involve application level changes and ensuring other applications accessing the database also do so correctly for the locking policy being used 27 1 Optimistic Locking Optimistic locking assumes that the data will not be modified between when you read the data until you write the data This is the most common style of locking used and recommended in today s persistence solutions The strategy involves checking that one or more values from
168. e sometimes required Also some developers have more experience with SQL than JPQL so may prefer to use SQL queries Native queries can also be used for calling some types of stored procedures or executing DML or DDL operations Native queries are defined through the NamedNat iveQuery and NamedNativeQueries annotations or lt named native query gt XML element Native queries can also be defined dynamically using the EntityManager createNativeQuery API A native query can be for a query for instances of a class a query for raw data an update or DML or DDL operation or a query for a complex query result If the query is for a class the resultClass attribute of the query must be set If the query result is complex a Result Set Mapping can be used Native queries can be parameterized so they can be executed with different parameter values Parameters are defined in SQL using the syntax for positional parameters JPA does not require native queries support named parameters but some JPA providers may For positional parameter the position starts a 1 not 0 A collection of query hints can also be provided to a native query Query hints can be used to optimize or to provide special configuration to a query Query hints are specific to the JPA provider Query hints are defined through the CQueryHint annotation or query hint XML element Example native named query annotation NamedNativeQuery name findAllEmployeesI
169. e table 28 Chapter 11 on page 25 29 Chapter 10 on page 23 81 Advanced TopLink EclipseLink Support computing the inheritance discriminator through Java code This can be done through using a DescriptorCustomizer and the ClassDescriptor s InheritancePolicy s setClassExtractor method Hibernate This can be accomplished through using the Hibernate DiscriminatorFormula annotation This allows database specific SQL or func tions to be used to compute the discriminator value 30 Chapter 11 on page 25 31 Chapter 10 on page 23 32 Chapter 12 on page 27 82 24 Advanced 24 1 Table Per Class Inheritance Table per class inheritance allows inheritance to be used in the object model when it does not exist in the data model In table per class inheritance a table is defined for each concrete class in the inheritance hierarchy to store all the attributes of that class and all of its superclasses Be cautious using this strategy as it is optional in the JPA spec and querying root or branch classes can be very difficult and inefficient 24 1 1 Example table per class inheritance tables SMALLPROJECT table ID NAME 2 Legal LARGEPROJECT table ID NAME BUDGET 1 Accounting 50000 24 1 2 Example table per class inheritance annotations Entity Inheritance strategy InheritanceType TABLE_PER_CLASS public abstract class Project Id private long id Entity Table name LARGEPROJECT public
170. e the embeddable to be deleted Embeddables cannot be queried directly and are not independent objects as they have no Id 26 8 Querying Embeddable objects cannot be queried directly but they can be queried in the context of their parent Typically it is best to select the parent and access the embeddable from the parent This will ensure the embeddable is registered with the persistence context If the embeddable is selected in a query the resulting objects will be detached and changes will not be tracked Example of querying an embeddable SELECT employee period from Employee employee where employee period endDate param Embeddables 1 Embeddables 14 Chapter 11 on page 25 15 Chapter 10 on page 23 16 Chapter 12 on page 27 17 http en wikibooks org wiki Java 20Persistence 2FDataNucleus 18 http en wikibooks org wiki Category 3AJava 20Persistence 19 http en wikibooks org wiki Category 3AJava 20Persistence 2FMapping 98 27 Locking Locking is perhaps the most ignored persistence consideration Most applications tend to ignore thinking about concurrency issues during development and then smush in a locking mechanism before going into production Considering the large percentage of software projects that fail or are canceled or never achieve a large user base perhaps this is logical However locking and concurrency is a critical or at least a very important issue for most applications so probably should b
171. e the public interface by setting the name of the Entity to be the public interface Some JPA providers allow interfaces to be defined TopLink EclipseLink Support defining and querying on public interfaces using a DescriptorCustomizer and the InterfacePolicy Example public interface alias Entity name Employee public class EmployeeImpl 41 3 2 Interface Types If you have a common interfaces with multiple distinct implementers this can have some issues If you use the interface to define a variable relationship then this is difficult to map JPA has no direct support for interfaces or variable relationships You could change the interface to be a abstract class then use TABLE_PER_CLASS inheritance to map it Otherwise you could split the relationship into multiple relationships one per each implementer or you could just remove the relationship and query for the related objects instead Querying on an interface is also difficult you would need to query on each implementer of the interface and then union the results in memory Some JPA providers have support for mapping interfaces and for variable relationships TopLink EclipseLink Support mapping interfaces using a SessionCustomizer and a RelationalDescriptor and InterfacePolicy Variable relationships can be defined using the VariableOneToOne annotation or XML 13 Chapter 11 on page 25 14 Chapter 10 on page 23 15 Chapter 11 on page 25 16 Chapt
172. e way join table can be mapped using a ManyToMany with a MapKeyJoinColumn for the third foreign key For a ManyToMany the key is always stored in the JoinTable For a OneToMany it is stored in the JoinTable if defined otherwise it is stored in the target Entity s table even though the target Entity does not map this column For an ElementCollection the key is stored in the element s table The MapKeyColumn annotation or lt map key column gt XML element is used to de fine a map relationship where the key is a Basic value the CMapKeyEnumerated and MapKeyTemporal can also be used with this for Enum or Calendar types The MapKeyJoinColumn annotation or lt map key join column gt XML element is used to de fine a map relationship where the key is an Entity value the CMapKeyJoinColumns can also be used with this for composite foreign keys The annotation MapKeyClass or lt map key class gt XML element can be used when the key is an Embeddable or to specify the target class or type if generics are not used Example of a map key column relationship database EMPLOYEE table ID FIRSTNAME LASTNAME SALARY 11 https java sun com javaee 6 docs api javax persistence MapKeyColumn html 12 https java sun com javaee 6 docs api javax persistence MapKeyEnumerated html 13 https java sun com javaee 6 docs api javax persistence MapKeyTemporal html 14 https java sun com javaee 6 docs api javax persistence MapKeyJoinColumn ht
173. ect is of no use The SQL syntax for pessimistic locking is database specific and different databases have different syntax and levels of support so ensure your database properly supports your locking requirements EclipseLink as of 1 2 Supports JPA 2 0 pessimistic locking TopLink EclipseLink Support pessimistic locking through the eclipselink pessimistic lock query hint The main issues with pessimistic locking is they use database resources so require a database transaction and connection to be held open for the duration of the edit This is typically not desirable for interactive web applications Pessimistic locking can also have concurrency issues and cause deadlocks The main advantages of pessimistic locking is that once the lock is obtained it is fairly certain that the edit will be successful This can be desirable in highly concurrent applications where optimistic locking may cause too many optimistic locking errors There are other ways to implement pessimistic locking it could be implemented at the application level or through serializable transaction isolation Application level pessimistic locking can be implemented through adding a locked field to your object Before an edit you must update the field to locked and commit the change Then you can edit the object and set the locked field back to false To avoid conflicts in acquiring the lock you should also use optimistic locking to ensure the lock
174. ect e from Employee e query setHint javax persistence cache storeMode REFRESH JPA 2 0 also provides a Cache interface The Cache interface can be obtained from the EntityManagerFactory using the getCache API The Cache can be used to manually evict invalidate entities in the cache Either a specific entity an entire class or the entire cache can be evicted The Cache can also be checked to see if it contains an entity Some JPA providers may extend the getCache interface to provide additional API TopLink EclipseLink Provide an extended Cache interface JpaCache It provides additional API for invalidation query cache access and clearing Cache evict example Cache cache factory getCache cache evict Employee class id 22 https java sun com javaee 6 docs api javax persistence CacheRetrieveMode html 23 https java sun com javaee 6 docs api javax persistence CacheStoreMode html 24 https java sun com javaee 6 docs api javax persistence Cache html 25 Chapter 11 on page 25 26 Chapter 10 on page 23 268 Stale Data 51 6 5 Cache Invalidation A common way to deal with stale cached data is to use cache invalidation Cache invalidation removes or invalidates data or objects in the cache after a certain amount of time or at a certain time of day Time to live invalidation guarantees that the application will never read cached data that is older than a certain amount of time The amount of the tim
175. egat 23 http en wikibooks org w index php title User Kencyber 24 http en wikibooks org w index php title User Lawgers 25 http en wikibooks org w index php title User Lmdavid 26 http en wikibooks org w index php title User Moutonbreton 27 http en wikibooks org w index php title User Panic2k4 28 http en wikibooks org w index php title User Pengo 29 http en wikibooks org w index php title User QuiteUnusual 30 http en wikibooks org w index php title User Recent_Runes 31 http en wikibooks org w index php title User Sandro roeder 32 http en wikibooks org w index php title User Shaunmsmith 33 http en wikibooks org w index php title User Svendhhh 34 http en wikibooks org w index php title User Tewari deepak 35 http en wikibooks org w index php title User Theshowmecanuck 36 http en wikibooks org w index php title User Tjoneill 37 http en wikibooks org w index php title User Van_der_Hoorn 38 http en wikibooks org w index php title User Vernetto 39 http en wikibooks org w index php title User Vishal423 40 http en wikibooks org w index php title User Webaware 41 http en wikibooks org w index php title User Wutsje 42 http en wikibooks org w index php title User YMS 43 http en wikibooks org w index php title User ZeroOne 282 List of Figures e GFDL Gnu Free Documentation License http www gnu org licenses fdl html e cc by sa 3 0 Creative Commons Attribution ShareAlike 3 0
176. el an EntityManager may match the lifecycle of a client s session The EntityManager provides an API for all required persistence operations These include the following CRUD operations e persist INSERT e merge UPDATE e removet DELETE e find SELECT The EntityManager is an object oriented API so does not map directly onto database SQL or DML operations For example to update an object you just need to read the object and change its state through its set methods and then call commit on the transaction The EntityManager figures out which objects you changed and performs the correct updates to the database there is no explicit update operation in JPA 47 1 Persist The EntityManager persist operation is used to insert a new object into the database persist does not directly insert the object into the database it just registers it as new in the persistence context transaction When the transaction is committed or if the persistence context is flushed then the object will be inserted into the database If the object uses a generated Id the Id will normally be assigned to the object when persist is called so persist can also be used to have an object s Id assigned The one exception is if IDENTITY sequencing is used in this case the Id is only assigned on commit 1 https java sun com javaee 5 docs api javax persistence EntityManager html https java sun com javaee 5 docs api javax persistence EntityManager html
177. el such that your classes do not have relationships to the superclass such as changing the relationship to a subclass or removing the relationship and instead querying for its value by querying each possible subclass and collecting the results in Java Subclass does not want to inherit mappings Sometimes you have a subclass that needs to be mapped differently than its parent or is similar to its parent but does not have one of the fields or uses it very differently Unfortunately it is very difficult not to inherit everything from your parent in JPA you can override a mapping but you cannot remove one or change the type of mapping or the target class If you define your mappings as properties get methods or through XML you may be able to attempt to override or mark the inherited mapping as Transient this may work depending on your JPA provider don t forget to sacrifice a chicken Another solution is to actually fix your inheritance in your object model If you inherit foo from Bar but don t want to inherit it then remove it from Bar if the other subclasses need it either add it to each or create a FooBar subclass of Bar that has the foo and have the other subclasses extend this Some JPA providers may provide ways to be less stringent on inheritance 86 Mapped Superclasses TopLink EclipseLink Allow a subclass remove a mapping redefine a mapping or be entirely independent of its superclass This can be done throu
178. en 231 JPQL BNF 233 AGM Select marma a en een ie er A E O ae YS st et 233 462 VU pd ate ews an ee dae sn ee te ee ae oh eat ae be 237 46 3 Delete ai aa gh be Aas As Bote Bane Riser en decade i een ok 238 AGA APaterals o Bae he Sly ore te wot a ie a A nal A 238 Aba New In JPA 2 0 2 03 A aa oS Beas tea ap eh eed a ee ee ne 239 Persisting 241 AVMs Persist mariaa A A ea tok A Pee E it 241 47 2 Merge ai A Shae ei Baa a Bae cA eas Lee 243 AT REMOVE use 2 E a ne a Bg ed hohe ie AS a SG es 245 Advanced 247 48 1 RETEST A E A en ag AE eh A AREA 247 ASD TOC a Sete Ao ates ee A Gone Bat han alee eRe SE Sa ah E 247 48 3 Get Reference 248 ASA SEUS tints AA Se ap a Rhee A aes eo ee oe Pet ed Ee BS 248 Aso O e di AM piece a e eas Has Bone Bane o ai 249 ASILO CLOSE ros Abe stole eB Big he ee Re ln ys ae Ems oe te aa igs Banh oe 250 ASH Get Delepatery is une Rodel ad DU oe he e te EE ae Pee ek 250 48 8 Unwrap JPA 2 O 22 2 Eee Er ED 251 Transactions 253 49 1 Resource Local Transactions 253 49 2 ITA LAOS ACOSO eek 254 Advanced 257 9001 Join Transaction raro A A ee E A ALS ASIA 257 50 2 Retrying Transactions Handling Commit Failures 258 50 3 Nested Transactions 258 50 4 Transaction Isolation 259 Caching 261 51 1 Object Identity Gods ee eg Kr ea ee A 262 B1 2 Object Cache te a lr AP Bee a a ara Kane 262 51 3 Data Cache tra da aa nn ee ae SE ee de Ge 263 51 4 Cache Types a 2000200 ba 002
179. entify any Invariant Sections then there are none The Cover Texts are certain short passages of text that are listed as Front Cover Texts or Back Cover Texts in the notice that says that the Document is released under this License A Front Cover Text may be at most 5 words and a Back Cover Text may be at most 25 words A Transparent copy of the Document means a machine readable copy represented in a format whose specification is available to the general pub lic that is suitable for revising the document straightforwardly with generic text editors or for images composed of pixels generic paint programs or for drawings some widely available drawing ed itor and that is suitable for input to text format ters or for automatic translation to a variety of for mats suitable for input to text formatters A copy made in an otherwise Transparent file format whose markup or absence of markup has been arranged to thwart or discourage subsequent modification by readers is not Transparent An image format is not Transparent if used for any substantial amount of text A copy that is not Transparent is called Opaque Examples of suitable formats for Transparent copies include plain ASCII without markup Tex info input format LaTeX input format SGML or XML using a publicly available DTD and standard conforming simple HTML PostScript or PDF de signed for human modification Examples of trans parent image formats include PN
180. entity name Employee class org acme Employee access FIELD gt lt attributes gt lt id name id gt lt column name ID gt lt id gt lt basic name firstName gt lt column name F_NAME gt lt basic gt lt basic name lastName gt lt column name L_NAME gt lt basic gt lt transient name service gt lt attributes gt lt entity gt 3 https java sun com javaee 5 docs api javax persistence Transient html 4 https java sun com javaee 5 docs api javax persistence Column html 112 Common Problems 28 1 Common Problems 28 1 1 Translating Values See Conversion 28 1 2 Truncated Data A common issue is that data such as Strings written from the object are truncated when read back from the database This is normally caused by the column length not being large enough to handle the object s data In Java there is no maximum size for a String but in a database VARCHAR field there is a maximum size You must ensure that the length you set in your column when you create the table is large enough to handle any object value For very large Strings CLOBs can be used but in general CLOBs should not be over used as they are less efficient than a VARCHAR If you use JPA to generate your database schema you can set the column length through the Column annotation or element see Column Definition and Schema Generation 28 1 3 How to map timestamp with timezones See Timezones 28 1 4 How t
181. er table e Replication A class s data is replicated to multiple tables e History A class has historical data These are all advanced cases some are handled by the JPA Spec and many are not The following sections investigate each of these scenarios further and include what is supported by the JPA spec what can be done to workaround the issue within the spec and how to use some JPA implementations extensions to handle the scenario 20 1 Multiple tables PLO YEE A l Fk EMP ID 1 ID NUMBER w EMPLID NUMBER F NAME VARCHAR 1 MGR_D NUMBER L_NAME VARCHAR YEAR_OF_SERY NUMBER SALARY NUMBER ADORESS_ID NUMBER Figure 8 Chapter 20 1 on page 47 Chapter 41 7 on page 201 Chapter 23 6 on page 75 Chapter 41 2 on page 196 Chapter 41 4 on page 198 Chapter 41 12 on page 204 Chapter 41 11 on page 203 Chapter 41 8 on page 202 o youtku mHm 47 Advanced Sometimes a class maps to multiple tables This typically occurs on legacy or existing data models where the object model and data model do not match It can also occur in inheritance when subclass data is stored in additional tables Multiple tables may also be used for performance partitioning or security reasons JPA allows multiple tables to be assigned to a single class The SecondaryTable and Secondary Tables annotations or lt secondary table gt elements can be used By default the Id column s are assumed to be in
182. er 10 on page 23 197 Advanced Topics 41 4 Stored Procedures A stored procedure is a procedure or function that resides on the database Stored procedures are typically written in some database specific language that is similar to SQL such as PL SQL on Oracle Some databases such as Oracle also support stored procedures written in Java Stored procedures can be useful to perform batch data processing tasks By writing the task in the database it avoids the cost of sending the data to and from the database client so can operate much more efficiently Stored procedures can also be used to access database specific functionality that can only be accessed on the server Stored procedures can also be used if strict security requirements as required to avoid giving users access to the raw tables or unverified SQL operations Some legacy application have also been written in database procedural languages and need to be integrated with The disadvantages of using stored procedures is they are less flexible than using SQL and require developing and maintaining functionality that is often written in a different language than the application developers may be used to and difficult to develop and debug and typically using a limited procedural programming language There is also a general misconception that using stored procedures will improve performance in that if you put the same SQL the application is executing inside a stored procedure it wil
183. eral Public License you may choose any version ever published by the Free Software Foun dation If the Program specifies that a proxy can decide which future versions of the GNU General Public License can be used that proxy s public statement of acceptance of a version permanently authorizes you to choose that version for the Program Later license versions may give you additional or different permissions However no additional obli gations are imposed on any author or copyright holder as a result of your choosing to follow a later version 15 Disclaimer of Warranty THERE IS NO WARRANTY FOR THE PRO GRAM TO THE EXTENT PERMITTED BY AP PLICABLE LAW EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLD ERS AND OR OTHER PARTIES PROVIDE THE PROGRAM AS IS WITHOUT WARRANTY OF ANY KIND EITHER EXPRESSED OR IMPLIED INCLUDING BUT NOT LIMITED TO THE IM PLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU SHOULD THE PROGRAM PROVE DEFEC TIVE YOU ASSUME THE COST OF ALL NECES SARY SERVICING REPAIR OR CORRECTION 16 Limitation of Liability IN NO EVENT UNLESS REQUIRED BY APPLI CABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER OR ANY OTHER PARTY WHO MODIFIES AND OR CON VEYS THE PROGRAM AS PERMITTED ABOVE BE LIABLE TO YOU FOR DAMAGES IN CLUDING ANY GENERAL SPECIAL INCIDEN TAL OR CONSEQUENTIAL DAMAGES A
184. eratedValue See Mapping a Join Table with Additional Columns 30 5 3 Ordering JPA allows the collection values to be ordered by the database when retrieved This is done through the COrderBy annotation or lt order by gt XML element The value of the OrderBy is a JPQL ORDER BY string The can be an attribute name followed by ASC or DESC for ascending or descending ordering You could also use a path or nested attribute or a for multiple attributes If no OrderBy value is given it is assumed to be the Id of the target object The OrderBy value must be a mapped attribute of the target object If you want to have an ordered List you need to add an index attribute to your target object and an index column to it s table You will also have to ensure you set the index values JPA 2 0 will have extended support for an ordered List using an OrderColumn Note that using an OrderBy does not ensure the collection is ordered in memory You are responsible for adding to the collection in the correct order Java does define a SortedSet 15 Chapter 35 1 on page 169 16 Chapter 37 1 2 on page 178 17 Chapter 39 1 2 on page 185 18 Chapter 39 1 on page 183 19 https java sun com javaee 5 docs api javax persistence OrderBy html 20 Chapter 46 1 6 on page 237 132 Collections interface and TreeSet collection implementation that does maintain an order JPA does not specifically support SortedSet but some JPA providers may allow yo
185. erator annotation 23 4 Primary Keys through Triggers A database table can be defined to have a trigger that automatically assign its primary key Generally this is normally not a good idea although some DBAs may think it is and it is better to use a JPA provider generated sequence id or assign the id in the application The main issue with the id being assigned in a trigger is that the application and object require this value back For non primary key values assigned through triggers it is possible to refresh the object after committing or flushing the object to obtain the values back However this is not possible for the id as the id is required to refresh an object If you have an alternative way to select the id generated by the trigger such as selecting the object s row using another unique field you could issue this SQL select after the insert to obtain the id and set it back in the object You could perform this select in a JPA PostPersist event Some JPA providers may not allow like a query execution during 12 Chapter 11 on page 25 13 Chapter 10 on page 23 14 Chapter 12 on page 27 15 https java sun com javaee 5 docs api javax persistence PostPersist html 74 Primary Keys through Events an event they also may not pick up a change to an object during an event callback so there may be issues with doing this Also some JPA providers may not allow the primary key to be un assigned null when not using a GeneratedValue
186. eritance and instead use a MappedSuperclass but this means that you can no longer query or have relationships to the class 80 Joined Multiple Table Inheritance The poorest performing queries will be those to the root or branch classes Avoiding queries and relationships to the root and branch classes will help to alleviate this burden If you must query the root or branch classes there are two methods that JPA providers use one is to outer join all of the subclass tables the second is to first query the root table then query only the required subclass table directly The first method has the advantage of only requiring one query the second has the advantage of avoiding outer joins which typically have poor performance in databases You may wish to experiment with each to determine which mechanism is more efficient in your application and see if your JPA provider supports that mechanism Typically the multiple query mechanism is more efficient but this generally depends on the speed of your database connection TopLink EclipseLink Support both querying mechanisms The multiple query mechanism is used by default Outer joins can be used instead through using a DescriptorCustomizer and the ClassDescriptor s InheritancePolicy s setShouldOuterJoinSubclasses method Do not have want a table for every subclass Most inheritance hierarchies do not fit with either the joined or the single table inheritance strategy Typically the de
187. es gt lt join table name EMP_PHONE gt lt join column name EMP_ID referenced column name EMP_ID gt lt inverse join column name PHONE_ID referenced column name ID unique true gt lt join table gt lt one to many gt lt attributes gt lt entity gt 175 OneToMany 36 2 See Also Relationships Cascading Lazy Fetching Target Entity Collections Maps Join Fetching Batch Reading Common Problems 4 e ManyToOne e ManyToMany 36 3 Common Problems Object not in collection after refresh See Object corruption 7 176 Chapter 29 9 on page 123 Chapter 30 2 on page 129 Chapter 30 1 on page 126 Chapter 30 4 on page 131 Chapter 30 5 on page 132 Chapter 31 2 on page 140 Chapter 31 3 on page 145 Chapter 31 6 on page 148 Chapter 30 6 on page 135 Chapter 33 2 2 on page 164 Chapter 37 1 2 on page 178 Chapter 31 6 on page 148 37 Advanced 37 1 Undirectional OneToMany No Inverse ManyToOne No Join Table JPA 2 0 ONLY JPA 1 0 does not support a unidirectional OneToMany relationship without a JoinTable JPA 2 0 will have support for a unidirectional OneToMany In JPA 2 0 a CJoinColumn can be used on a OneToMany to define the foreign key some JPA providers may support this already The main issue with an unidirectional OneToMany is that the foreign key is owned by the target object s table so if the target object has no knowledge of this foreign key insert
188. ework org schema beans spring beans 2 0 xsd gt lt bean id entityManagerFactory class org springframework orm jpa LocalContainerEntityManagerFactoryBean gt lt property name persistenceUnitName value acme gt lt property name persistenceUnitManager ref persistenceUnitManager gt lt bean gt lt bean id persistenceUnitManager class org sp ringframework orm jpa persistenceunit DefaultPersistenceUnitManager gt lt property name defaultDataSource ref dataSource gt lt property name dataSources gt lt map gt lt entry gt lt key gt lt value gt jdbc __default lt value gt lt key gt lt ref bean dataSource gt lt entry gt lt entry gt lt key gt lt value gt jdbc jta lt value gt lt key gt lt ref bean dataSource gt lt entry gt lt map gt lt property gt lt property name loadTimeWeaver gt lt bean class org s pringframework instrument classloading InstrumentationLoadTimeWeaver gt lt property gt lt bean gt lt bean id dataSource class org springframework jdbc datasource DriverManagerDataSource gt lt property name driverClassName value oracle jdbc OracleDriver gt lt property name url value jdbc oracle thin localhost 1521 orcl gt lt property name username value scott gt lt property name password value tiger gt lt bean gt lt bean id transactionManager class org springframework orm jpa JpaTransaction
189. ey and a locally unique field There are two methods of declaring a composite primary key in JPA IdClass and Embeddedld 23 1 1 Id Class An IdClass defines a separate Java class to represent the primary key It is defined through the IdClass annotation or lt id class gt XML element The IdClass must define an attribute field property that mirrors each Id attribute in the entity It must have the same attribute name and type When using an IdClass you still require to mark each Id attribute in the entity with Id The main purpose of the IdClass is to be used as the structure passed to the EntityManager findO and getReference API Some JPA products also use the IdClass as a cache key to track an object s identity Because of this it is required depending on JPA product to implement an equals and hashCode method on the IdClass Ensure that the equals method checks each part of the primary key and correctly uses equals for objects and for primitives Ensure that the hashCode method will return the same value for two equal objects TopLink EclipseLink Do not require the implementation of equals or hashCode in the id class Example id class annotation Entity IdClass EmployeePK class public class Employee Id private long employeeld Id private long companyld Old private long departmentld 1 https java sun com javaee 5 docs api javax persistence lIdClass html Chapter 11 on page 25 3
190. eys almost always map to the id primary key of the primary table but in some advanced scenarios this may be an issue Some JPA products allow the column or join column to use the qualified name of the column i e CJoinColumn referenceColumnName EMP_ DATA EMP_NUM to allow this type of relationship Some JPA products may also support this through their own API annotations or XML 20 2 Multiple tables with foreign keys MPLOYE ADORE ID NUMBER ID NUMBER F_NAME VARCHAR CITY VARCHAR L NAME VARCHAR STREET VARCHAR SALARY NUMBER FK_ADDRESS 1 STATE VARCHAR ADDRESS ID NUMBER 1 COUNTRY VARCHAR P CODE VARCHAR Figure 9 Sometimes you may have a secondary table that is referenced through a foreign key from the primary table to the secondary table instead of a foreign key from the secondary table to the primary table You may even have a foreign key between two of the secondary tables Consider having an EMPLOYEE and ADDRESS table where EMPLOYEE refers to ADDRESS through an ADDRESS_ID foreign key and for some strange reason you only want a single Employee class that has the data from both tables The JPA spec does not cover this directly so if you have this scenario the first thing to consider if you have the flexibility is to change your data model to stay within the confines of the spec You could also change your object 49 Advanced model to define a class for each table in this cas
191. field is not updated to true by another user at the same time 27 2 8 JPA 2 0 Locking JPA 2 0 adds support for pessimistic locking as well as other locking options A lock can be acquired using the EntityManager lock API or passing a LockModeType to an EntityManager find or refresh operation or setting the lockMode of a Query or NamedQuery The JPA 2 0 lock modes are defined in the LockModeType enum 20 Chapter 27 2 8 on page 108 21 Chapter 10 on page 23 22 Chapter 11 on page 25 23 Chapter 10 on page 23 24 Chapter 27 2 9 on page 109 95 https java sun com javaee 6 docs api javax persistence EntityManager htmlttlock java lang Object 20javax persistence LockModeType 26 https java sun com javaee 6 docs api javax persistence LockModeType html 108 Advanced e OPTIMISTIC was READ in JPA 1 0 The Entity will have its optimistic lock version checked on commit to ensure no other transaction updated the object e OPTIMISTIC_ FORCE_INCREMENT was WRITE in JPA 1 0 The Entity will have its optimistic lock version incremented on commit to ensure no other transaction updated or READ locked the object e PESSIMISTIC_READ The Entity is locked on the database prevents any other transaction from acquiring a PESSIMISTIC_ WRITE lock e PESSIMISTIC WRITE The Entity is locked on the database prevents any other transaction from acquiring a PESSIMISTIC_ READ or PESSIMISTIC_ WRITE lock e PESSIMISTIC_FORCE_
192. forums oracle com forums forun jspa forumID 48 http forum hibernate org http www nabble com java net glassfish persistence f13455 html http www oracle com technology products ias toplink index html http www eclipse org eclipselink https glassfish dev java net javaee5 persistence http www hibernate org http openjpa apache org http objectgeneration com eclipse http java persistence blogspot com http jroller com mkeith http ontoplink blogspot com http eclipselink blogspot com http blog hibernate org http www amazon com gp product 1590596455 102 2412923 9620152 v glance amp n 283155 280 56 Contributors Edits User Adrignola AllenZh Avicennasis Benjihawaii Bru Chrylis Cinhtau Cowwoc DanielSerodio David shah Dirk H nniger Djaquay Djclarke Dwersin Guruwons Inas66 Izogfif 16 errrrrrerrvne a w O N 1272 Jamesssss 1 Jan derijke DragonxXx James sutherland oo osoutkrumHm ho Ro NNRPRP RP RRP gt e FOO ANDOTKWHYD http http http http http http http http http http http http http http http http http http http http http en en en en en en en en en en en en en en en en en en en en en wikibooks org w index org w index org w index org w index org w index org w
193. from Employee order by SIZE e projects DESC Using SIZE function also selects the size uses group by Select e SIZE e projects from Employee order by SIZE e projects DESC 222 Common Queries Using GROUP BY Select e COUNT p from Employee join e projects p order by COUNT p DESC Using GROUP BY and alias Select e COUNT p as pcount from Employee join e projects p order by pcount DESC 223 45 Advanced 45 1 Join Fetch and Query Optimization There are several ways to optimize queries in JPA The typical query performance issue is that an object is read first then its related objects are read one by one This can be optimized using JOIN FETCH in JPQL otherwise by query hints specific for each JPA provider See e Join Fetching e Batch Fetching 45 2 Timeouts Fetch Size and other JDBC Optimizations There are several JDBC options that can be used when executing a query These JDBC options are not exposed by JPA but some JPA providers may support query hints for them e Fetch size Configures the number of rows to fetch from the database in each page A larger fetch size is more efficient for large queries e Timeout Instructs the database to cancel the query if its execution takes too long EclipseLink TopLink Provide many query hints including eclipselink jdbc fetch size Fetch size eclipselink jdbc timeout Timeout eclipselink read only The objects returned from the query are not m
194. g acme Employee access FIELD gt lt attributes gt lt id name id gt lt one to many name phoneNumbers mapped by owner gt lt map key name type gt lt one to many gt lt attributes gt lt entity gt lt entity name PhoneNumber class org acme PhoneNumber access FIELD gt lt attributes gt lt id name id gt lt basic name type gt 10 https java sun com javaee 5 docs api javax persistence MapKey html 140 Maps lt many to one name owner gt lt attributes gt lt entity gt 31 2 1 Map Key Columns JPA 2 0 JPA 2 0 allows for a Map where the key is not part of the target object to be persisted The Map key can be any of the following e A Basic value stored in the target s table or join table e An Embedded object stored in the target s table or join table A foreign key to another Entity stored in the target s table or join table Map columns can be used for any collection mapping including OneToMany ManyToMany and ElementCollection This allows for great flexibility and complexity in the number of different models that can be mapped The type of mapping used is always determined by the value of the Map not the key So if the key is a Basic but the value is an Entity a OneToMany mapping is still used But if the value is a Basic but the key is an Entity a ElementCollection mapping is used This allows some very sophisticated database schemas to be mapped Such as a thre
195. g an Embedded or composite id relationship not possible Normally it is easiest to either select raw data or a single object with native SQL queries so SqlResultSetMappings can normally be avoided as they are quite complex Also note that even if you select the Employee and its Address with the SQL these are two unrelated objects the employee s address is not set and may trigger a query if accessed unless a cache hit occurs Some JPA providers may provide a query hint to allow join fetching to be used with native SQL queries Example result set mapping annotation NamedNativeQuery name findAllEmployeesInCity query SELECT E A from EMP E ADDRESS A WHERE E EMP_ID A EMP_ID AND A CITY resultSetMapping employee address SqlResultSetMapping name employee address entities EntityResult entityClass Employee class EntityResult entityClass Address class public class Employee 45 7 Stored Procedures See Stored Procedures 45 8 Raw JDBC It can sometimes be required to mix JDBC code with JPA code This may be to access certain JDBC driver specific features or to integrate with another application that uses JDBC instead of JPA If you just require a JDBC connection you could access one from your JEE server s DataSource or connect directly to DriverManager or a third party connection pool If you need a JDBC connection in the same transaction context and your JPA application you could use
196. g inheritance But sometimes reincarnation is desirable When done in two separate transactions this is normally fine first you remove the object then you persist it back This can be more complex if you wish to remove and persist an object with the same Id in the same transaction If you call remove on an object then call persist on the same object it will simply no longer be removed If you call remove on an object then call persist on a different object with the same Id the behavior may depend on your JPA provider and probably will not work If you call flush after calling remove then call persist then the object should be successfully reincarnated Note that it will be a different row the existing row will have been deleted and a new row inserted If you wish the same row to be updated you may need to resort to using a native SQL update query 246 48 Advanced 48 1 Refresh The EntityManager refresh operation is used to refresh an object s state from the database This will revert any non flushed changes made in the current transaction to the object and refresh its state to what is currently defined on the database If a flush has occurred it will refresh to what was flushed Refresh must be called on a managed object so you may first need to find the object with the active EntityManager if you have a non managed instance Refresh will cascade to any relationships marked cascade refresh although it may be done lazily depend
197. g or conveying If you add terms to a covered work in accord with this section you must place in the relevant source files a statement of the additional terms that ap ply to those files or a notice indicating where to find the applicable terms Additional terms permissive or non permissive may be stated in the form of a separately written license or stated as exceptions the above require ments apply either way 8 Termination You may not propagate or modify a covered work except as expressly provided under this License Any attempt otherwise to propagate or modify it is void and will automatically terminate your rights under this License including any patent licenses granted under the third paragraph of section 11 However if you cease all violation of this License then your license from a particular copyright holder is reinstated a provisionally unless and until the copyright holder explicitly and finally terminates your license and b permanently if the copyright holder fails to notify you of the violation by some reasonable means prior to 60 days after the cessa tion Moreover your license from a particular copyright holder is reinstated permanently if the copyright holder notifies you of the violation by some reason able means this is the first time you have received notice of violation of this License for any work from that copyright holder and you cure the vi olation prior to 30 days after your rece
198. ge of up to five words as a Front Cover Text and a passage of up to 25 words as a Back Cover Text to the end of the list of Cover Texts in the Modified Version Only one passage of Front Cover Text and one of Back Cover Text may be added by or through arrangements made by any one entity If the Document already includes a cover text for the same cover previously added by you or by arrangement made by the same entity you are acting on behalf of you may not add an other but you may replace the old one on explicit permission from the previous publisher that added the old one The author s and publisher s of the Document do not by this License give permission to use their names for publicity for or to assert or imply en dorsement of any Modified Version 5 COMBIN ING DOCUMENTS You may combine the Document with other docu ments released under this License under the terms defined in section 4 above for modified versions provided that you include in the combination all of the Invariant Sections of all of the original doc uments unmodified and list them all as Invariant Sections of your combined work in its license no tice and that you preserve all their Warranty Dis claimers The combined work need only contain one copy of this License and multiple identical Invariant Sec tions may be replaced with a single copy If there are multiple Invariant Sections with the same name but different contents make the title of each s
199. ger entityManager factory createEntityManager entityManager close 43 2 Java Enterprise Edition In JEE the EntityManager or EntityManagerFactory can either be looked up in JNDI or injected into a SessionBean To look up the EntityManager in JNDI it must be published in JNDI such as through a lt persistence context ref gt in a SessionBean s ejb jar xml file To inject an EntityManager or EntityManagerFactory the annotation PersistenceContext or PersistenceUnit are used In JEE an EntityManager can either be managed container managed or non managed application managed A managed EntityManager has a different life cycle than an EntityManager managed by the application A managed EntityManager should never be closed and integrates with JTA transactions so local transaction cannot be used Across each JTA transaction boundary all of the entities read or persisted through a managed EntityManager become detached Outside of a JTA transaction a managed EntityManager s behavoir is sometimes odd so typically should be used inside a JTA transaction A non managed EntityManager is one that is created by the application through a EntityManagerFactory or directly from Persistence A non managed EntityManager 211 Entity Manager must be closed and typically does not integrate with JTA but this is possible through the joinTransaction API The entities in a non managed EntityManager do not be come detached after a transaction co
200. gh using a DescriptorCustomizer and removing the ClassDescriptor s mapping or adding a mapping with the same attribute name or removing the InheritancePolicy Inheritance Inheritance 5 oR W bd Chapter 11 on page 25 Chapter 10 on page 23 http en wikibooks org wiki Category 3AJava 20Persistence http en wikibooks org wiki Category 3AJava 20Persistence 2FMapping 87 25 Embeddables _ id long firstName String lastName String salary BigDecimal EMP_ID NUMBER F_NAME VARCHAR L_NAME VARCHAR SALARY NUMBER START_DATE DATE 1 END_DATE DATE ADDRESS_ID NUMBER MANAGER_ID NUMBER employmentPeriod startDate Date endDate Date Figure 13 In an application object model some objects are considered independent and others are considered dependent parts of other objects In UML a relationship to a dependent object is consider an aggregate or composite association In a relational database this kind of relationship could be modeled in two ways the dependent object could have its own table or its data could be embedded in the independent objects table In JPA a relationship where the target object s data is embedded in the source object s table is considered an embedded relationship and the target object is considered an Embeddable object Embeddable objects have different requirements and restrictions than Entity objects and are defined by the Embeddable annotation or lt embeddable
201. gt projects Entity public class Project Old private long id COneToMany mappedBy project private List lt ProjectAssociation gt employees Add an employee to the project Create an association object for the relationship and set its data public void addEmployee Employee employee boolean teamLead ProjectAssociation association new ProjectAssociation association setEmployee employee association setProject this association setEmployeeld employee getId association setProjectId this getId association setIsTeamLead teamLead this employees add association Also add the association object to the employee employee getProjects add association Entity Table name PROJ_EMP IdClass ProjectAssociationld class public class ProjectAssociation Old 184 Mapping a Join Table with Additional Columns private long employeeld Id a private long projectld Column name IS_PROJECT_LEAD private boolean isProjectLead ManyToOne PrimaryKeyJoinColumn name EMPLOYEEID referencedColumnName ID if this JPA model doesn t create a table for the PROJ_EMP entity please comment out the OPrimaryKeyJoinColumn and use the ff JoinColumn name employeeld updatable false insertable false or JoinColumn name employeeld updatable false insertable false referencedColumnName id private Employee employee ManyToOne P
202. gt persistence acme factory lt persistence unit ref name gt lt persistence unit name gt acme lt persistence unit name gt lt persistence unit ref gt lt session gt lt enterprise beans gt lt ejb jar gt Example of looking up an EntityManager in JNDI from a SessionBean InitialContext context new InitialContext properties EntityManager entityManager EntityMan ager context lookup java comp env persistence acme entity manager 5 Chapter 50 1 on page 257 212 Java Enterprise Edition Example of looking up an EntityManagerFactory in JNDI from a SessionBean InitialContext context new InitialContext properties EntityManagerFactory factory EntityMan agerFactory context lookup java comp env persistence acme factory Example of injecting an EntityManager and EntityManagerFactory in a SessionBean Stateless name EmployeeService mappedName acme EmployeeService Remote EmployeeService class public class EmployeeServiceBean implements EmployeeService PersistenceContext unitName acme private EntityManager entityManager PersistenceUnit unitName acme private EntityManagerFactory factory Example of lookup an EJBContext in an Entity Useful for Audit protected EJBContext getContext try InitialContext context new InitialContext return EJBContext context lookup java comp EJBContext catch NamingException e throw new EJBException e 43 2
203. h is typically not wrapped with a proxy but may be in some servers In JPA 2 0 the getDelegate API has been replaced by the unwrap API which is more generic Example getDelegate public void clearCache EntityManager em getEntityManager JpaEntityManager em getDelegate get ServerSession getIdentityMapAccessor initializeAllIdentityMaps 48 8 Unwrap JPA 2 0 The EntityManager unwrap operation is used to access the JPA provider s EntityManager implementation class in a JEE managed EntityManager A JEE man aged EntityManager will be wrapped by a proxy EntityManager by the JEE server that forwards requests to the EntityManager active for the current JTA transaction If a JPA provider specific API is desired the unwrap API allows the JPA implementation to be accessed to call the API In JEE a managed EntityManager will typically create a new EntityManager per JTA transaction Also the behavior is somewhat undefined outside of a JTA transaction context Outside a JTA transaction context a JEE managed EntityManager may create a new EntityManager per method so getDelegate may return a temporary EntityManager or even null Another way to access the JPA implementation is through the EntityManagerFactory which is typically not wrapped with a proxy but may be in some servers Example unwrap public void clearCache EntityManager em getEntityManager em unwrap JpaEntityManager class get
204. h relationships are defined through foreign keys and querying such that the inverse query always exists JPA also defines a OneToOne relationship which is similar to a ManyToOne relationship except that the inverse relationship if it were defined is a OneToOne relationship The main difference between a OneToOne and a ManyToOne relationship in JPA is that a ManyToOne always contains a foreign key from the source object s table to the target object s table where as a OneToOne relationship the foreign key may either be in the source object s table or the target object s table 1 Chapter 31 7 on page 150 165 ManyToOne In JPA a ManyToOne relationship is defined through the ManyToOne annotation or the lt many to one gt element In JPA a ManyToOne relationship is always well almost always required to define a OneToMany relationship the ManyToOne always defines the foreign key JoinColumn and the OneToMany must use a mappedBy to define its inverse ManyToOne Example of a ManyToOne relationship database EMPLOYEE table EMP_ID FIRSTNAME LASTNAME SALARY MANAGER_ID 1 Bob Way 50000 2 2 Sarah Smith 75000 null PHONE table ID TYPE AREA CODE P_ NUMBER OWNER_ID 1 home 613 792 0000 1 2 work 613 896 1234 1 3 work 416 123 4444 2 34 0 3 Example of a ManyToOne relationship annotations Entity public class Phone Old private long id ManyToOne fetch FetchType LAZY JoinColumn name OWNER_ID private Emplo
205. h second for about 100 years If you instead use a long this would be a 64 bit number which is 9 223 372 036 854 775 808 different ids or one id each millisecond for about 300 000 000 years which is pretty safe I would recommend using a long vs an int however as I have seen int ids run out on large databases before what happens is they become negative until they wrap around to 0 and start getting constraint errors 23 3 2 Customizing JPA supports three different strategies for generating ids however there are many other methods Normally the JPA strategies are sufficient so you would only use a different method in a legacy situation Sometimes the application has an application specific strategy for generating ids such as prefixing ids with the country code or branch number There are several ways to integrate a customize ids generation strategy the simplest is just define the id as a normal id and have the application assign the id value when the object is created Some JPA products provide additional sequencing and id generation options and configura tion hooks TopLink EclipseLink Several additional sequencing options are provided A UnaryTableSequence allows a single column table to be used A QuerySequence al lows for custom SQL or stored procedures to be used An API also exists to allow a user to supply their own code for allocating ids Hibernate A GUID id generation options is provided through the GenericGen
206. has a OneToOne or other such mapping to an entity The JPA 1 0 spec only allows Basic mappings in an embeddable object so relationships from embeddables are not supported however some JPA products may support them Technically there is nothing preventing the OneToOne annotation or other relationships from being used in an embeddable object so this may just work depending on your JPA provider cross your fingers JPA 2 0 supports all relationship types from an embeddable object TopLink EclipseLink Support relationship mappings from embeddables The existing relationship annotations or XML elements can be used Relationships to embeddable objects from entities other than the embeddable s parent are typically not a good idea as an embeddable is a private dependent part of its parent Generally relationships should be to the embeddable s parent not the embeddable Otherwise it would normally be a good idea to make the embeddable an independent entity with its own table If an embeddable has a bi directional relationship such as a OneToMany that requires an inverse ManyToOne the inverse relationship should be to the embeddable s parent A workaround to having a relationship from an embeddable is to define the relationship in the embeddable s parent and define property get set methods for the relationship that set the relationship into the embeddable Example of setting a relationship in an embeddable from its parent Entity public
207. hat have already been registered in the EntityManager Normally it is a good idea to clear the EntityManager after executing the query or to execute the query in a new EntityManager or transaction 45 3 1 Example update query UPDATE Employee e SET e salary e salary 1000 WHERE e address city city 45 3 2 Example delete query DELETE FROM Employee e WHERE e address city city 45 4 Flush Mode Within a transaction context in JPA changes made to the managed objects are normally not flushed written to the database until commit So if a query were executed against the database directly it would not see the changes made within the transaction as these changes are only made in memory within the Java This can cause issues if new objects have been persisted or objects have been removed or changed as the application may expect the query to return these results Because of this JPA requires that the JPA provider performs a flush of all changes to the database before any query operation This however can cause issues if the application is not expecting that a flush as a side effect of a query operation If the application changes are not yet in a state to be flushed a flush may not be desired Flushing also can be expensive and causes the database transaction and database locks are other resources to be held for the duration of the transaction which can effect performance and concurrency 226 Pagination Max First Results JP
208. he link name can also be a table qualifier In JPA a table qualifier can be set on a table through the schema or catalog attribute Generally it does not matter which attribute is used as both just result in prefixing the table name Technically you could even include the full name schema table as the table s name and it would work The benefit of setting the prefix in the schema or catalog is a default table qualifier can be set for the entire persistence unit also not setting the real table name may impact native SQL queries If all of your tables require the same table qualifier you can set the default in the orm xml 20 6 1 Example mapping annotations for an entity with a qualified table Entity Table name EMPLOYEE schema ACME public class Employee 20 6 2 Example mapping XML for default entire persistence unit table qualifier lt entity mappings gt lt persistence unit metadata gt 52 Table qualifiers schemas or creators lt persistence unit defaults gt lt schema name ACME gt lt persistence unit defaults gt lt persistence unit metadata gt lt entity mappings gt 20 6 3 Example mapping XML for default orm file table qualifier lt entity mappings gt lt schema name ACME gt lt entity mappings gt Tables 18 Tables 1 18 http en wikibooks org wiki Category 3AJava 20Persistence 19 http en wikibooks org wiki Category 3AJava 20Persistence 2FMapping 53 21 Iden
209. he rights Therefore you have certain re sponsibilities if you distribute copies of the soft ware or if you modify it responsibilities to respect the freedom of others For example if you distribute copies of such a pro gram whether gratis or for a fee you must pass on to the recipients the same freedoms that you re ceived You must make sure that they too receive or can get the source code And you must show them these terms so they know their rights Developers that use the GNU GPL protect your rights with two steps 1 assert copyright on the software and 2 offer you this License giving you legal permission to copy distribute and or modify it For the developers and authors protection the GPL clearly explains that there is no warranty for this free software For both users and authors sake the GPL requires that modified versions be marked as changed so that their problems will not be attributed erroneously to authors of previous versions Some devices are designed to deny users access to install or run modified versions of the software in side them although the manufacturer can do so This is fundamentally incompatible with the aim of protecting users freedom to change the software The systematic pattern of such abuse occurs in the area of products for individuals to use which is precisely where it is most unacceptable Therefore we have designed this version of the GPL to pro hibit the prac
210. hen map each column in the view to your object s attributes Views are normally read only so object s mapping to views are normally also read only In most databases views can also be updatable depending on how complex to query is that they encapsulate Even for complex queries database triggers can normally be used to update into the view Views can often be used in JPA to workaround mapping limitations For example if a table join is not supported by JPA or a database function is desired to be called to transform data this can normally be done inside a view so JPA can just map to the simplified data Using views does require database expertise and the definition of views can be database dependent 10 http download oracle com javaee 6 api javax persistence ExcludeSuperclassListeners html 11 Chapter 11 on page 25 12 Chapter 10 on page 23 196 Interfaces 41 3 Interfaces Interfaces can be used for two main purposes in a model The first is as a public interface that defines the public API for the class The second is as a common type that allows multiple distinct implementers 41 3 1 Public Interfaces If you have a public interface in JPA you just need to map the implementation class and are fine for the most part One issue is that you need to use the implementation class for queries as JPA does not know about the interface For JPQL the default alias is also the implementation class but you could redefine this to b
211. http en wikipedia org wiki Dracle 20Corporation http en wikipedia org wiki IBM http en wikipedia org wiki Sybase http en wikipedia org wiki Dracle 20database http en wikipedia org wiki MySQL http en wikipedia org wiki PostgreSQL http en wikipedia org wiki DB2 http en wikipedia org wiki Microsoft 20SQL 20Server http www google com trends q oracle 2C sybase 2C sql server 2C mysq1 2C db24ctab O amp geo allkdate all amp sort 0 http en wikibooks org wiki Category 3AJava 20Persistence 2FWhat 20is 20Java 20persistence http en wikibooks org wiki Category 3AJava 20Persistence ONnoKR WNP o Ro m bo m Bw 5 What is JPA The Java Persistence Architecture API JPA is a Java specification for accessing persisting and managing data between Java objects classes and a relational database JPA was defined as part of the EJB 3 0 specification as a replacement for the EJB 2 CMP Entity Beans specification JPA is now considered the standard industry approach for Object to Relational Mapping ORM in the Java Industry JPA itself is just a specification not a product it cannot perform persistence or anything else by itself JPA is just a set of interfaces and requires an implementation There are open source and commercial JPA implementations to choose from and any Java EE 5 application server should provide support for its use JPA also requires a database to persist to JPA allows POJO Plain Old Java Ob
212. i e MALE FEMALE For translating Enum types to values other than the integer or String name such as character constants see Translating Values 29 2 1 Example of enumerated annotation public enum Gender MALE FEMALE Entity public class Employee Basic Enumerated EnumType STRING private Gender gender 29 2 2 Example of enumerated XML lt entity name Employee class org acme Employee access FIELD gt lt attributes gt lt basic name gender gt lt enumerated gt STRING lt enumerated gt lt basic gt Chapter 11 on page 25 Chapter 10 on page 23 http old nabble com MySQL 27s datetime and time zones td21006801 html https java sun com java 5 docs api java lang Enum html https java sun com javaee 5 docs api javax persistence Enumerated html Chapter 29 1 4 on page 116 Nook wb 117 Advanced lt attributes gt lt entity gt 29 3 LOBs BLOBs CLOBs and Serialization A LOB is a Large OBject such as a BLOB Binary LOB or a CLOB Character LOB It is a database type that can store a large binary or string value as the normal VARCHAR or VARBINARY types typically have size limitations A LOB is often stored as a locator in the database table with the actual data stored outside of the table In Java a CLOB will normally map to a String and a BLOB will normally map to a byte although a BLOB may also represent some serialized object By default in JPA any Serializabl
213. ided you inform other peers where the object code and Corresponding Source of the work are be ing offered to the general public at no charge under subsection 6d A separable portion of the object code whose source code is excluded from the Corresponding Source as a System Library need not be included in conveying the object code work A User Product is either 1 a consumer prod uct which means any tangible personal property which is normally used for personal family or household purposes or 2 anything designed or sold for incorporation into a dwelling In deter mining whether a product is a consumer product doubtful cases shall be resolved in favor of cover age For a particular product received by a par ticular user normally used refers to a typical or common use of that class of product regardless of the status of the particular user or of the way in which the particular user actually uses or expects or is expected to use the product A product is a consumer product regardless of whether the prod uct has substantial commercial industrial or non consumer uses unless such uses represent the only significant mode of use of the product User Product authorization Installation Information for a means any methods procedures keys or other information required to install and execute modified versions of a covered work in that User Product from a modified version of its Corre sponding
214. ied Pro gram or a work based on the Program To propagate a work means to do anything with it that without permission would make you directly or secondarily liable for infringement under appli cable copyright law except executing it on a com puter or modifying a private copy Propagation in cludes copying distribution with or without mod ification making available to the public and in some countries other activities as well To convey a work means any kind of propagation that enables other parties to make or receive copies Mere interaction with a user through a computer network with no transfer of a copy is not convey ing An interactive user interface displays Appropriate Legal Notices to the extent that it includes a con venient and prominently visible feature that 1 dis plays an appropriate copyright notice and 2 tells the user that there is no warranty for the work ex cept to the extent that warranties are provided that licensees may convey the work under this Li cense and how to view a copy of this License If the interface presents a list of user commands or options such as a menu a prominent item in the list meets this criterion 1 Source Code The source code for a work means the preferred form of the work for making modifications to it Object code means any non source form of a work A Standard Interface means an interface that ei ther is an official stan
215. ifference between a OneToOne and a ManyToOne relationship in JPA is that a ManyToOne always contains a foreign key from the source object s table to the target object s table where as a OneToOne relationship the foreign key may either be in the source object s table or the target object s table If the foreign key is in the target object s table JPA requires that the relationship be bi directional must be defined in both objects and the source object must use the mappedBy attribute to define the mapping In JPA a OneToOne relationship is defined through the OneToOne annotation or the lt one to one gt element A OneToOne relationship typically requires a JoinColumn or CJoinColumns if a composite primary key Example of a OneToOne relationship database EMPLOYEE table EMP_ID FIRSTNAME LASTNAME SALARY ADDRESS_ ID 1 Bob Way 50000 6 2 Sarah Smith 60000 7 ADDRESS table 2 https java sun com javaee 5 docs api javax persistence OneToOne html 3 https java sun com javaee 5 docs api javax persistence JoinColumn html 4 https java sun com javaee 5 docs api javax persistence JoinColumns html 152 Nested Collections Maps and Matrices SACHSI SZLHCM adop d epeue epeue AULNNOD NO NO HONIAOYdA OJUOJOL EMENO ALID 15 TEN GG 15 JUE LT LATULS L 9 dI SS4YaAV 153 OneToOne 32 0 1 Example of a OneToOne relationship annotations Entity public class Employee Id Column name EMP_ID priva
216. imal with Postgresql JPA maps salary to a table column of type NU MERIC 38 0 You can adjust scale and precision for BigDecimal within the Column annotation Column precision 8 scale 2 private BigDecimal salary 29 7 Insertable Updatable Read Only Fields Returning The Column annotation and XML element defines insertable and updatable options These allow for this column or foreign key field to be omitted from the SQL INSERT or UPDATE statement These can be used if constraints on the table prevent insert or update operations They can also be used if multiple attributes map to the same database column such as with a foreign key field through a ManyToOne and Id or Basic mapping Setting both insertable and updatable to false effectively mark the attribute as read only insertable and updatable can also be used in the database table defaults or auto assigns values to the column on insert or update Be careful in doing this though as this means that the object s values will be out of synch with the database unless it is refreshed For IDENTITY or auto assigned id columns a GeneratedValue should normally be used instead of setting insertable to false Some JPA providers also support returning auto assigned fields values from the database after insert or update operations The cost of refreshing or returning fields back into the object can effect performance so it is normally better to initialize field values in the object model no
217. in the database The following table summarizes the basic types and the database types they map to Java type Database type String char char VARCHAR CHAR VARCHAR2 CLOB TEXT Number BigDecimal BigInteger Inte NUMERIC NUMBER INT LONG ger Double Long Float Short Byte FLOAT DOUBLE int long float double short byte NUMERIC NUMBER INT LONG FLOAT DOUBLE bytel VARBINARY BINARY BLOB boolean Boolean BOOLEAN BIT SMALLINT INT NUMBER java util Date TIMESTAMP DATE DATETIME java sql Date DATE TIMESTAMP DATETIME java sql Time TIME TIMESTAMP DATETIME java sql Timestamp TIMESTAMP DATETIME DATE java util Calendar TIMESTAMP DATETIME DATE java lang Enum NUMERIC VARCHAR CHAR java util Serializable VARBINARY BINARY BLOB In JPA a basic attribute is mapped through the Basic annotation or the lt basic gt element The types and conversions supported depend on the JPA implementation and database platform Some JPA implementations may support conversion between many different data types or additional types or have extended type conversion support see the advanced section for more details Any basic attribute using a type that does not map directly to a database type can be serialized to a binary database type The easiest way to map a basic attribute in JPA is to do nothing Any attributes that have no other annotations and do not reference other entities will be automatically mapped as basi
218. in the other fields Field locking can also be used on legacy schemas where you cannot add a version column or to integrate with other applications accessing the same data which are not using optimistic locking note if the other applications are not also using field locking you can only detect conflicts in one direction There are several types of field locking e All fields compared in the update This can lead to a very big where clause but will detect any conflicts e Selected fields compared in the update This is useful if conflicts in only certain fields are desired e Changed fields compared in the update This is useful if only changes to the same fields are considered to be conflicts If your JPA provider does not support field locking it is difficult to simulate as it requires changes to the update SQL Your JPA provider may allow overriding the update SQL in which case A11 or Selected field locking may be possible if you have access to the original values but Changed field locking is more difficult because the update must be dynamic Another way to simulate field locking is to flush you changes then refresh the object using a separate EntityManager and connection and compare the current values with your original object When using field locking it is important to keep the original object that was read If you read the object in one transaction and send it to a client then update in another you are not really locki
219. inColumns JoinColumn name PROJ_ID referencedColumnName ID private List lt Project gt projects 38 0 5 Example of a ManyToMany relationship XML lt entity name Employee class org acme Employee access FIELD gt lt attributes gt lt id name id gt lt column name EMP_ID gt lt id gt lt many to many name projects gt lt join table name EMP_PROJ gt lt join column name EMP_ID referenced column name ID gt lt inverse join column name PROJ_ID referenced column name ID gt lt join table gt lt many to many gt lt attributes gt lt entity gt 38 1 Bi directional Many to Many Although a ManyToMany relationship is always bi directional on the database the object model can choose if it will be mapped in both directions and in which direction it will be mapped in If you choose to map the relationship in both directions then one direction must be defined as the owner and the other must use the mappedBy attribute to define its mapping This also avoids having to duplicate the JoinTable information in both places 180 See Also If the mappedBy is not used then the persistence provider will assume there are two independent relationships and you will end up getting duplicate rows inserted into the join table If you have a conceptual bi directional relationship but have two different join tables in the database then you must not use the mappedBy as you need to maintain two independent
220. index org w index org w index org w index org w index org w index org w index org w index org w index org w index org w index org w index org w index org w index org w index org w index wikibooks wikibooks wikibooks wikibooks wikibooks wikibooks wikibooks wikibooks wikibooks wikibooks wikibooks wikibooks wikibooks wikibooks wikibooks wikibooks wikibooks wikibooks wikibooks wikibooks php title User php title User php title User php title User php title User php title User php title User php title User php title User php title User php title User php title User php title User php title User php title User php title User php title User php title User php title User php title User php title User Adrignola AllenZh Avicennasis Benjihawaii Bru Chrylis Cinhtau Cowwoc DanielSerodio David shah Dirk_H C3 BCnniger Djaquay Djclarke DragonxXx Dwersin Guruwons Inas66 Izogfif James sutherland Jamesssss Jan derijke 281 Contributors 1 Jomegat 1 Kencyber 1 Lawgers 8 Lmdavid 1 Moutonbreton 1 Panic2k4 7 1 Pengo 2 QuiteUnusual 1 Recent Runes 8 Sandro roeder 1 Shaunmsmith 7 Svendhhh 3 Tewari deepak 4 2 Theshowmecanuck 1 Tjoneill 1 Van der Hoorn 3 Vernetto 2 Vishal423 1 Webaware 1 Wutsje 1 YMS 1 ZeroOne 22 http en wikibooks org w index php title User Jom
221. ing and updating the value is difficult In a unidirectional OneToMany the source object take ownership of the foreign key field and is responsible for updating its value The target object in a unidirectional OneToMany is an independent object so it should not rely on the foreign key in any way i e the foreign key cannot be part of its primary key nor generally have a not null constraint on it You can model a collection of objects where the target has no foreign key mapped but uses it as its primary key or has no primary key using a Embeddable collection mapping see Embeddable Collections If your JPA provider does not support unidirectional OneToMany relationships then you will need to either add a back reference ManyToOne or a JoinTable In general it is best to use a JoinTable if you truly want to model a unidirectional OneToMany on the database There are some creative workarounds to defining a unidirectional OneToMany One is to map it using a JoinTable but make the target table the JoinTable This will cause an extra join but work for the most part for reads writes of course will not work correctly so this is only a read only solution and a hacky one at that 37 1 1 Example of a JPA 2 0 unidirectional OneToMany relationship database EMPLOYEE table EMP_ID FIRSTNAME LASTNAME 1 Bob Way 2 Sarah Smith 1 https java sun com javaee 5 docs api javax persistence JoinColumn html 2 Chapter 26 7 on page 97 177 Advanced
222. ing on your fetch type so you may need to access the relationship to trigger the refresh refresh can only be called on Entity objects not on Embeddable objects or collections or non persistent objects Embeddable objects are automatically refreshed as part of their owning Entity Refresh can be used to revert changes or if your JPA provider supports caching it can be used to refresh stale cached data Sometimes it is desirable to have a Query or find operation refresh the results Unfortunately JPA 1 0 does not define how this can be done Some JPA providers offer query hints to allow refreshing to be enabled on a query TopLink EclipseLink Define a query hint eclipselink refresh to allow refreshing to be enabled on a query JPA 2 0 defines a set of standard query hints for refeshing see JPA 2 0 Cache APIs Example refresh EntityManager em getEntityManager em refresh employee 48 2 Lock See Read and Write Locking https java sun com javaee 5 docs api javax persistence EntityManager html refresh java lang Object Chapter 11 on page 25 Chapter 10 on page 23 Chapter 51 6 4 on page 268 Chapter 27 2 5 on page 106 oR WN e 247 Advanced 48 3 Get Reference The EntityManager getReference operation is used to obtain a handle to an object without requiring it to be loaded It is similar to the find operation but may return a proxy or unfetched object JPA does not require that getReferen
223. ints Tables also have other artifacts such as indexes partitions and triggers A typical mapping of a persist class will map the class to a single table In JPA this is defined through the Table annotation or lt table gt XML element If no table annotation is present the JPA implementation will auto assign a table for the class The JPA default table name is the name of the class minus the package with the first letter capitalized Each attribute of the class will be stored in a column in the table 19 0 1 Example mapping annotations for an entity with a single table Entity Table name EMPLOYEE public class Employee 19 0 2 Example mapping XML for an entity with a single table lt entity name Employee class org acme Employee access FIELD gt lt table name EMPLOYEE gt lt entity gt 2 https java sun com javaee 5 docs api javax persistence Table html 46 20 Advanced Although in the ideal case each class would map to a single table this is not always possible Other scenarios include e Multiple tables One class maps to 2 or multiple tables e Sharing tables 2 or multiple classes are stored in the same table e Inheritance A class is involved in inheritance and has an inherited and local table e Views A class maps to a view e Stored procedures A class maps to a set of stored procedures e Partitioning Some instances of a class map to one table and other instances to anoth
224. iod private int yearsOfService private boolean fullTime public EmploymentDetails this period new EmploymentPeriod Transient public EmploymentPeriod getEmploymentPeriod return period Basic public Date getStartDate return getEmploymentPeriod getStartDate J public void setStartDate Date startDate getEmploymentPeriod setStartDate startDate Basic public Date getEndDate return getEmploymentPeriod getEndDate H public void setEndDate Date endDate getEmploymentPeriod setEndDate endDate 5 Chapter 11 on page 25 6 Chapter 10 on page 23 95 Advanced 26 5 Inheritance Embeddable inheritance is when one embeddable class subclasses another embeddable class The JPA spec does not allow inheritance in embeddable objects however some JPA products may support this Technically there is nothing preventing the DiscriminatorColumn annotation being used in an embeddable object so this may just work depending on your JPA provider cross your fingers Inheritance in embeddables is always single table as an embeddable must live within its parent s table Generally attempting to mix inheritance between embeddables and entities is not a good idea but may work in some cases TopLink EclipseLink Support inheritance with embeddables This is set through using a DescriptorCustomizer and the InheritancePolicy 26 6 Relationships A relationship is when an embeddable
225. ion single_valued_path_expression input_ parameter IS NOT NULL empty_ collection_comparison_ expression collection_valued_ path_ expression IS NOT EMPTY collection_mmember_ expression entity_ expression NOT MEMBER OF collection_ valued_ path_ expression exists_expression NOT EXISTS subquery all_or_any_ expression ALL ANY SOME subquery comparison_expression string expression comparison_operator string _ expression all_or_any_ expression boolean_expression lt gt boolean_expression all_or_ any_ expression enum_ expression lt gt enum_expression all_or_any_ expression datetime_expression comparison_operator datetime expression all_or_any_ expression entity_expression lt gt entity_expression all_or_any_ expression arithmetic_ expression comparison_operator arithmetic_expression all_or_any_ expression 235 JPQL BNF comparison_operator gt gt lt lt lt gt arithmetic_ expression simple _arithmetic_ expression subquery simple _arithmetic_ expression arithmetic_term simple _arithmetic_ expression arithmetic_term arithmetic_term arithmetic_ factor arithmetic_term arithmetic_ factor arithmetic_ factor arithmetic_ primary arithmetic_ primary state_field_path_expression numeric_literal simple_ arithmetic_ expression input_ parameter func
226. ion has no effect on the state of the parent transaction The parent transaction is still uncommitted However the parent transaction can now see any modifications made by the child transaction Those modifications of course are still hidden to all other transactions until the parent also commits Likewise aborting the nested transaction has no effect on the state of the parent transaction The only result of the abort is that neither the parent nor any other transactions will see any of the database modifications performed under the protection of the nested transaction If the parent transaction commits or aborts while it has active children the child transactions are resolved in the same way as the parent That is if the parent aborts then the child transactions abort as well If the parent commits then whatever modifications have been performed by the child transactions are also committed The locks held by a nested transaction are not released when that transaction commits Rather they are now held by the parent transaction until such a time as that parent commits Any database modifications performed by the nested transaction are not visible outside of the larger encompassing transaction until such a time as that parent transaction is committed The depth of the nesting that you can achieve with nested transaction is limited only by memory 50 4 Transaction Isolation Transactions Transactions 2 http en wikibooks org wiki
227. ional or non transactional In a transactional cache the changes from a transaction are committed to the cache as a single atomic unit This means the objects data are first locked in the cache preventing other threads users from accessing the objects data then updated in the cache then the locks are released Ideally the locks are obtained before committing the database transaction to ensure consistency with the database In a non transactional cache the objects data are updated one by one without any locking This means there will be a brief period where the data in the cache is not consistent with the database This may or may not be an issue and is a complex issue to think about and discuss and gets into the issue of locking and the application s isolation requirements Optimistic locking is another important consideration in cache isolation If optimistic locking is used the cache should avoid replacing new data with older data This is important when reading and when updating the cache Some JPA providers may allow for configuration of their cache isolation or different caches may define different levels of isolation Although the defaults should normally be used it can be important to understand how the usage of caching is affecting your transaction isolation as well as your performance and concurrency 51 8 Common Problems I can t see changes made directly on the database or from another server This means you have either en
228. ips and have dependent objects So determining when an object has changed and needs to update its version can be more difficult than determining when a row has changed JPA does define that when any of the object s tables changes the version is updated However it is less clear on relationships If Basic Embedded or a foreign key relationship OneToOne ManyToOne changes the version will be updated But what about OneToMany ManyToMany and a target foreign key OneToOne For changes to these relationships the update to the version may depend on the JPA provider What about changes made to dependent objects JPA does not have a cascade option for locking and has no direct concept of dependent objects so this is not an option Some JPA providers may support this One way to simulate this is to use write locking JPA defines the EntityManager lock API You can define a version only in your root parent objects and when a child or relationship is changed you can call the lock API with the parent to cause a WRITE lock This will cause the parent version to be updated You may also be able to automate this through persistence events Usage of cascaded locking depends on your application If in your application you consider one user updating one dependent part of an object and another user updating another part of the object to be a locking contention then this is what you want If your application does not consider this to be a problem the
229. ipt of the notice Termination of your rights under this section does not terminate the licenses of parties who have re ceived copies or rights from you under this License If your rights have been terminated and not perma nently reinstated you do not qualify to receive new licenses for the same material under section 10 9 Acceptance Not Required for Having Copies You are not required to accept this License in or der to receive or run a copy of the Program Ancil lary propagation of a covered work occurring solely as a consequence of using peer to peer transmission to receive a copy likewise does not require accep tance However nothing other than this License grants you permission to propagate or modify any covered work These actions infringe copyright if you do not accept this License Therefore by mod ifying or propagating a covered work you indicate your acceptance of this License to do so 10 Auto matic Licensing of Downstream Recipients Each time you convey a covered work the recipient automatically receives a license from the original licensors to run modify and propagate that work subject to this License You are not responsible for enforcing compliance by third parties with this License An entity transaction is a transaction transfer ring control of an organization or substantially all assets of one or subdividing an organization or merging organizations If propagation of a cov ered work results
230. istributed Caching A distributed cache is one where the cache is distributed across each of the machines in the cluster Each object will only live on one or a set number of the machines This avoids stale data because when the cache is accessed or updated the object is always retrieved from the same location so is always up to date The draw back to this solution is that cache access now potentially requires a network access This solution works best when the machines in the cluster are connected together on the same high speed network and when the database machine is not as well connected or is under load A distributed cache reduces database access so allows the application to be scaled to a larger cluster without the database becoming a bottleneck Some distributed cache providers also provide a local cache and offer cache coordination between the caches TopLink Supports integration with the Oracle Coherence distributed cache 29 Chapter 11 on page 25 30 Chapter 10 on page 23 31 Chapter 11 on page 25 270 Cache Transaction Isolation 51 7 Cache Transaction Isolation When caching is used the consistency and isolation of the cache becomes as important as the database transaction isolation For basic cache isolation it is important that changes are not committed into the cache until after the database transaction has been committed otherwise uncommitted data could be accessed by other users Caches can be either transact
231. ithout relief drawings paintings films provided they are not detrimental to the image of the euro e LFK Lizenz Freie Kunst http artlibre org licence lal de e CFR Copyright free use 283 List of Figures e EPL Eclipse Public License http www eclipse org org documents epl v10 php Copies of the GPL the LGPL as well as a GFDL are included in chapter Licenses Please note that images in the public domain do not require attribution You may click on the image numbers in the following table to open the webpage of the images in your webbrower 44 Chapter 57 on page 287 284 List of Figures 1 PD 2 3 4 Her Pegship LGPL 5 PD 6 PD 7 Jamesssss PD 8 Jamesssss 7 PD 9 Jamesssss PD 10 Jamesssss I PD 11 Jamesssss PD 12 PD 13 PD 14 Jamesssss PD 15 Jamesssss PD 16 Jamesssss PD 17 PD 18 19 20 Traced by User Stannered original by David Vignoni LGPL 21 wnr Ot OT OT OT OT A http en wikibooks org wiki User 3APegship http en wikibooks org wiki User 3AJamesssss http en wikibooks org wiki User 3AJamesssss http en wikibooks org wiki User 3AJamesssss http en wikibooks org wiki User 3AJamesssss http en wikibooks org wiki User 3AJamesssss http en wikibooks org wiki User 3AJamesssss http en wikibooks org wiki User 3AJamesssss http en wikibooks org wiki User 3AJamesssss http e
232. ity DiscriminatorValue L Table name LARGEPROJECT public class LargeProject extends Project private BigDecimal budget Entity DiscriminatorValue S Table name SMALLPROJECT public class SmallProject extends Project 4 23 8 3 Example joined inheritance XML lt entity name Project class org acme Project access FIELD gt lt table name PROJECT gt lt inheritance strategy JOINED gt lt discriminator column name PROJ_TYPE gt lt attributes gt lt id name id gt lt attributes gt lt entity gt lt entity name LargeProject class org acme LargeProject access FIELD gt lt table name LARGEPROJECT gt lt discriminator value gt L lt discriminator value gt lt entity gt lt entity name SmallProject class org acme SmallProject access FIELD gt lt table name SMALLPROJECT gt lt discriminator value gt S lt discriminator value gt lt entity gt 23 8 4 Common Problems Poor query performance The main disadvantage to the joined model is that to query any class join queries are required Querying the root or branch classes is even more difficult as either multiple queries are required or outer joins or unions are required One solution is to use single table inheritance instead this is good if the classes have a lot in common but if it is a big hierarchy and the subclasses have little in common this may not be desirable Another solution is to remove the inh
233. ity refers to a function or data to be supplied by an Application that uses the fa cility other than as an argument passed when the facility is invoked then you may convey a copy of the modified version under this License provided that you make a good faith effort to ensure that in the event an Ap plication does not supply the function or data the facility still operates and performs whatever part of its purpose remains meaningful or b under the GNU GPL with none of the additional permis sions of this License applicable to that copy 3 Object Code Incorporating Material from Li brary Header Files The object code form of an Application may incor porate material from a header file that is part of the Library You may convey such object code un der terms of your choice provided that if the in corporated material is not limited to numerical pa rameters data structure layouts and accessors or small macros inline functions and templates ten or fewer lines in length you do both of the follow ing a Give prominent notice with each copy of the object code that the Library is used in it and that the Library and its use are covered by this License b Accompany the object code with a copy of the GNU GPL and this license document Translation is considered a kind of modification so you may distribute translations of the Document under the terms of section 4 Replacing Invariant Sections with translations
234. jects to be easily persisted without requiring the classes to implement any interfaces or methods as the EJB 2 CMP specification required JPA allows an object s object relational mappings to be defined through standard annotations or XML defining how the Java class maps to a relational database table JPA also defines a runtime EntityManager API for processing queries and transaction on the objects against the database JPA defines an object level query language JPQL to allow querying of the objects from the database JPA is the latest of several Java persistence specifications The first was the OMG persistence service Java binding which was never very successful I m not sure of any commercial products supporting it Next came EJB 1 0 CMP Entity Beans which was very successful in being adopted by the big Java EE providers BEA IBM but there was a backlash against the spec by some users who thought the spec requirements on the Entity Beans overly complex and overhead and performance poor EJB 2 0 CMP tried to reduce some of the complexity of Entity Beans through introducing local interfaces but the majority of the complexity remained EJB 2 0 also lacked portability in that the deployment descriptors defining the object relational mapping were not specified and were all proprietary This backlash in part led to the creation of another Java persistence specification JDO Java Data Objects JDO obtained somewhat of a cult following of sever
235. k Support query cache enabled through the query hint eclipselink query results cache Several configuration options including invali dation are supported 51 6 Stale Data The main issue with caching anything is the possibility of the cache version getting out of synch with the original This is referred to as stale or out of synch data For read only data this is not an issue but for data that changes in frequently or frequently this can be a major issue There are many techniques for dealing with stale data and out of synch data 15 Chapter 51 6 6 on page 270 16 Chapter 11 on page 25 17 Chapter 10 on page 23 18 Chapter 11 on page 25 19 Chapter 11 on page 25 20 Chapter 10 on page 23 265 Caching 51 6 1 1st Level Cache Caching the object s state for the duration of a transaction or request is normally not an issue This is normally called a 1st level cache or the EntityManager cache and is required by JPA for proper transaction semantics If you read the same object twice you must get the identical object with the same in memory changes The only issues occur with querying and DML For queries that access the database the query may not reflect the un written state of the objects For example you have persisted a new object but JPA has not yet inserted this object in the database as it generally only writes to the database on the commit of the transaction So your query will not return this new object as it is queryi
236. l 5 https java sun com javaee 5 docs api javax persistence JoinColumns html 188 Basic Collections private long id ElementCollection CollectionTable name PHONE joinColumns JoinColumn name OWNER_ID private List lt Phone gt phones Embeddable public class Phone private String type private String areaCode Column name P_NUMBER private String number 40 1 3 Example of an ElementCollection relationship XML lt entity name Employee class org acme Employee access FIELD gt lt attributes gt lt id name id gt lt column name EMP_ID gt lt id gt lt element collection name phones gt lt collection table name PHONE gt lt join column name OWNER_ID gt lt collection table gt lt element collection gt lt attributes gt lt entity gt lt embeddable name Phone class org acme Phone access FIELD gt lt attributes gt lt basic name number gt lt column name P_NUMBER gt lt basic gt lt attributes gt lt embeddable gt 40 2 Basic Collections An ElementCollection mapping can be used to define a collection of Basic objects The Basic values are stored in a separate collection table This is similar to a OneToMany except the target is a Basic value instead of an Entity This allows collections of simple values to be easily defined without requiring defining a class for the value There is no cascade option on an ElementCollection the target object
237. l servers in a cluster and can look up an object in another server s cache TopLink EclipseLink Support an L1 and L2 object cache LRU Soft Full and Weak cache types are supported A query cache is supported The object cache is read write and always transactional Support for cache coordination through RMI and JMS is provided for clustering The TopLink product includes a Grid component that integrates with Oracle Coherence to provide a distributed cache 51 5 Query Cache A query cache caches query results instead of objects Object caches cache the object by its Id so are generally not very useful for queries that are not by Id Some object caches support secondary indexes but even indexed caches are not very useful for queries that can return multiple objects as you always need to access the database to ensure you have all of the objects This is where query caches are useful instead of storing objects by Id the query results are cached The cache key is based on the query name and parameters So if you have a NamedQuery that is commonly executed you can cache its results and only need to execute the query the first time The main issue with query caches as with caching in general is stale data Query caches normally interact with an object cache to ensure the objects are at least as up to date as in the object cache Query caches also typically have invalidation options similar to object caches TopLink EclipseLin
238. l somehow become faster This is a false and normally the opposite is true as stored procedures restrict the dynamic ability of the persistence layer to optimize data retrieval Stored procedures only improve performance when they use more optimal SQL than the application typically when they perform an entire task on the database To achieve optimal performance from SQL generated in an application you must use prepared statements otherwise the database will have to create a new execution plan each time you submit a query JPA does not have any direct support for stored procedures Some types of stored procedures can be executed in JPA through using native queries Native queries in JPA allow any SQL that returns nothing or returns a database result set to be executed The syntax to execute a stored procedure depends on the database JPA does not support stored procedures that use OUTPUT or INOUT parameters Some databases such as DB2 Sybase and SQL Server allow for stored procedures to return result sets Oracle does not allow results sets to be returned only OUTPUT parameters but does define a CURSOR type that can be returned as an OUTPUT parameter Oracle also supports stored functions that can return a single value A stored function can normally be executed using a native SQL query by selecting the function value from the Oracle DUAL table Some JPA providers have extended support for stored procedures some also support overriding any CRUD
239. l support Some custom database types include e TIMESTAMPTZ TIMESTAMPLTZ Oracle TIMESTAMP WITH TIMEZONE Postgres e XMLTYPE Oracle XML DB2 14 Chapter 29 1 on page 115 15 Chapter 11 on page 25 16 Chapter 10 on page 23 122 Custom Types e NCHAR NVARCHAR NCLOB Oracle e Struct STRUCT Oracle e Array VARRAY Oracle BINARY_INTEGER DEC INT NATURAL NATURALN BOOLEAN Oracle e POSITIVE POSITIVEN SIGNTYPE PLS_ INTEGER Oracle e RECORD TABLE Oracle e SDO_ GEOMETRY Oracle e LOBs Oracle thin driver To handle persistence to custom database types either custom hooks are required in your JPA provider or you need to mix raw JDBC code with your JPA objects Some JPA provider provide custom support for many custom database types some also provide custom hooks for adding your own JDBC code to support a custom database type TopLink EclipseLink Support several custom database types including TIMES TAMPTZ TIMESTAMPLTZ XMLTYPE NCHAR NVARCHAR NCLOB object relational Struct and Array types PLSQL types SDO_ GEOMETRY and LOBs Basic Attributes Basic Attributes 17 Chapter 11 on page 25 18 Chapter 10 on page 23 19 http en wikibooks org wiki Category 3AJava 20Persistence 20 http en wikibooks org wiki Category 3AJava 20Persistence 2FMapping 123 30 Relationships A relationship is a reference from one object to another In Java relationships are defined through
240. lationship If each Employee has 3 Phone objects in its phoneNumbers collection the join will require to bring back n 3 rows As there are 3 phone rows for each employee row the employee row will be duplicated 3 times So you are reading more data than if you have selected the objects in n 1 queries Normally the fact that your executing fewer queries makes up for the fact that you may be reading duplicate data but if you consider joining multiple collection relationships you can start to get back j duplicate data which can start to become an issue Even with ManyToOne relationships you can be selecting duplicate data Consider join fetching an Employee s manager if all or most employee s have the same manager you will end up select this manager s data many times in this case you would be better off not using join fetch and allowing a single query for the manager If you start join fetching every relationship you can start to get some pretty huge joins This can sometimes be an issue for the database especially with huge outer joins One alternative solution to join fetch that does not suffer from duplicate data is using Batch Fetching 31 4 Batch Fetching Batch fetching is a query optimization technique for reading multiple related objects in a finite set of database queries It involves executing the query for the root objects as normal But for the related objects the original query is joined with the query for the related objects
241. lows for graphical mapping of an object model to a data model as allows for generation of a data model from an object model and generation of an object model from a data model and auto mapping of an existing object and data model The TopLink Mapping Workbench functionality is also integrated with Oracle s JDeveloper IDE TopLink contributed part of its source code to become the JPA 1 0 reference implementation under the Sun java net Glassfish project This open source product is called TopLink Essentials and despite a different package name oracle toplink essentials it is basically a branch of the source code of the TopLink product with some advanced functionality stripped out TopLink contributed practically its entire source code to the Eclipse Foundation EclipseLink product This is an open source product currently in incubation that represents the path forward for TopLink The package name is different org eclipse persistence but the source code it basically a branch of the TopLink 11g release Oracle also contributed its Mapping Workbench source code to the project The TopLink Mapping Workbench developers also were major contributors to the Eclipse Dali project for JPA support TopLink was first developed in Smalltalk and ported to Java in the 90 s and has over 15 years worth of object persistence solutions TopLink originally provided a proprietary POJO persistence API when EJB was first released TopLink provided one of the most popul
242. lso have consequences with certain JPA implementations for persisting merging and other operations causing duplicate inserts missed updates or a corrupt object model I have also seen simply incorrect property methods such as a get method that always returns a new object or a copy or set methods that don t actually set the value In general if you are going to use property access ensure your property methods are free of side effects Perhaps even use different property methods than your application uses Mapping Mapping 7 http en wikibooks org wiki Category 3AJava 20Persistence 8 http en wikibooks org wiki Category 3AJava 20Persistence 2FMapping 44 19 Tables D NUMBER F_MAME VARCHAR L NAME VARCHAR SALARY NUMBER MANAGE ID NUMBER ADDRESS_ID NUMBER m a Figure 7 A table is the basic persist structure of a relational database A table contains a list of columns which define the table s structure and a list of rows that define the table s data Each column has a specific type and generally size The standard set of relational types are limited to basic types including numeric character date time and binary although most modern databases have additional types and typing systems Tables can also have constraints that define the rules which restrict the row data such as primary key foreign 1 http en wikipedia org wiki Table 20 28database 29 45 Tables key and unique constra
243. lt shared cache mode gt NONE lt shared cache mode gt lt persistence unit gt There are two types of caching You can cache the objects themselves including all of their structure and relationships or you can cache their database row data Both provide a benefit however just caching the row data is missing a huge part of the caching benefit as the retrieval of each relationship typically involves a database query and the bulk of the cost of reading an object is spent in retrieving its relationships 1 https java sun com javaee 6 docs api javax persistence Cacheable html 2 http download oracle com javaee 6 api javax persistence SharedCacheMode html 261 Caching 51 1 Object Identity Object identity in Java means if two variables x y refer to the same logical object then x y returns true Meaning that both reference the same thing both a pointer to the same memory location In JPA object identity is maintained within a transaction and normally within the same EntityManager The exception is in a JEE managed EntityManager object identity is only maintained inside of a transaction So the following is true in JPA Employee employeel entityManager find Employee class 123 Employee employee2 entityManager find Employee class 123 assert employeel employee2 This holds true no matter how the object is accessed Employee employeel entityManager find Employee class 123 Employee employee2 em
244. lumns html 23 2 1 JPA 1 0 Unfortunately JPA 1 0 does not handle this model well and things become complicated so to make your life a little easier you may consider defining a generated unique id for the child JPA 1 0 requires that all Id mappings be Basic mappings so if your Id comes from a foreign key column through a OneToOne or ManyToOne mapping you must also define a Basic Id mapping for the foreign key column The reason for this is in part that the Id must be a simple object for identity and caching purposes and for use in the IdClass or the EntityManager find API Because you now have two mappings for the same foreign key column you must define which one will be written to the database it must be the Basic one so the OneToOne or ManyToOne foreign key must be defined to be read only This is done through setting the JoinColumn attributes insertable and updatable to false or by using the PrimaryKeyJoinColumn instead of the JoinColumn A side effect of having two mappings for the same column is that you now have to keep the two in synch This is typically done through having the set method for the OneToOne 69 Advanced attribute also set the Basic attribute value to the target object s id This can become very complicated if the target object s primary key is a GeneratedValue in this case you must ensure that the target object s id has been assigned before relating the two objects Some times I think that JPA primary
245. m getEntityManager em getTransaction begin Employee employee em find Employee class id em remove employee em getTransaction commit 47 3 1 Cascading Remove Calling remove on an object will also cascade the remove operation across any relationship that is marked as cascade remove Note that cascade remove only effects the remove call If you have a relationship that is cascade remove and remove an object from the collection or dereference an object it will not be removed You must explicitly call remove on the object to have it deleted Some JPA providers provide an extension to provide this behavior and in JPA 2 0 there will be an orphanRemoval option on OneToMany and OneToOne mappings to provide this 47 3 2 Reincarnation Normally an object that has been removed stays removed but in some cases you may need to bring the object back to life This normally occurs with natural ids not generated ones https java sun com javaee 5 docs api javax persistence EntityManager html remove java lang Object 245 Persisting where a new object would always get an new id Generally the desire to reincarnate an object occurs from a bad object model design normally the desire to change the class type of an object which cannot be done in Java so a new object must be created Normally the best solution is to change your object model to have your object hold a type object which defines its type instead of usin
246. m so in general are not recommended In JPA there is no annotation or element for identity sequencing as there is no additional information to specify Only the GeneratedValue s strategy needs to be set to IDENTITY Example identity annotation Entity public class Employee Old GeneratedValue strategy GenerationType IDENTITY private long id Example identity XML lt entity name Employee class org acme Employee access FIELD gt lt attributes gt lt id name id gt lt generated value strategy IDENTITY gt lt id gt lt attributes gt lt entity gt 61 Sequencing PostgreSQL Serial Columns Sequence objects are database constructs can be instantiated as distinct objects as needed They provide incremental values when their next method is called Note that the increments can be values greater than one for example incremented by two s three s etc An on insert trigger can be constructed for each table that calls a sequence object created for that specific table primary key asking for the next value and inserting it into the table with the new record Identity datatypes in products like MySQL or SQL Server are encapsulated types that do the same thing without requiring the set up of triggers and sequences although PostgreSQL at least has automated much of this with its Serial and Big Serial pseudo datatypes these actually create an int bigint column and run a macro creating the sequence and on insert
247. m the Persistence APT about the name of the Database you want to create For example with TopLink if you used lt property name toplink ddl generation value create tables gt in the property xml you will be likely need to create a new database To create the database NewDB automatically you need to give the following URL to the jdbc connection lt property name toplink jdbc url valu e jdbc mysql localhost 3306 NewDB createDatabaselfNotExist true gt If not the persistence API will complain that the database does not exist 277 55 References 55 0 2 Resources 55 0 3 Wikis EJB 3 0 JPA 1 0 Spec JPA 2 0 Spec JPA 1 0 EclipseLink Wiki Ora ORM XML Schema JPA 1 0 Persistence XML cle TopLink Wiki 0 Glass Schema JPA 1 0 JavaDoc JPQL BNF JPA fish TopLink Essentials 2 0 Reference Implementation Development Java Wikil Hibernate Wiki Programming JPA on Wikipedia JPA on Javapedia JPA on freebase JPA on DMOZ Open Directory 1 http jcp org aboutJava communityprocess final jsr220 index html 2 http jcp org en jsr detail id 317 3 http java sun com xml ns persistence orm_1_0 xsd 4 http java sun com xml ns persistence persistence_1_0 xsd 5 https java sun com javaee 5 docs api javax persistence package summary html 6 http en wikibooks org wiki 2FJPQL 20BNF 7 http wiki eclipse org EclipseLink Development JPA 8 http en wikibooks org wiki Java
248. mapping See also Target Foreign Keys Primary Key Join Columns Cascade Primary Keys The following gives an example of what the inverse address relationship would look like 5 Chapter 33 1 on page 157 6 Chapter 33 1 on page 157 154 See Also 32 1 1 Example of an inverse OneToOne relationship annotations Entity public class Address Id private long id OneToOne fetch FetchType LAZY mappedBy address private Employee owner 32 1 2 Example of an inverse OneToOne relationship XML lt entity name Address class org acme Address access FIELD gt lt attributes gt lt id name id gt lt one to one name owner fetch LAZY mapped by address gt lt attributes gt lt entity gt 32 2 See Also e Relationships e Cascading Lazy Fetching Target Entity e Join Fetching e Batch Reading e Common Problems e ManyToOne 3 32 3 Common Problems Foreign key is also part of the primary key See Primary Keys through OneToOne Relationships 7 Chapter 29 9 on page 123 8 Chapter 30 2 on page 129 9 Chapter 30 1 on page 126 10 Chapter 30 4 on page 131 11 Chapter 31 3 on page 145 12 Chapter 31 6 on page 148 13 Chapter 30 6 on page 135 14 Chapter 33 2 2 on page 164 15 Chapter 23 2 on page 69 155 OneToOne Foreign key is also mapped as a basic If you use the same field in two different mappings you typically require to make one of them read only using
249. mary key See No Primary Key 3 Chapter 23 6 on page 75 56 22 Sequencing An object id can either be a natural id or a generated id A natural id is one that occurs in the object and has some meaning in the application Examples of natural ids include user ids email addresses phone numbers and social insurance numbers A generated id is one that is generated by the system A sequence number in JPA is a sequential id generated by the JPA implementation and automatically assigned to new objects The benefits of using sequence numbers are that they are guaranteed to be unique allow all other data of the object to change are efficient values for querying and indexes and can be efficiently assigned The main issue with natural ids is that everything always changes at some point even a person s social insurance number can change Natural ids can also make querying foreign keys and indexing less efficient in the database In JPA an Id can be easily assigned a generated sequence number through the CGeneratedValue annotation or lt generated value gt element 22 0 6 Example generated id annotation Entity public class Employee Id GeneratedValue private long id 22 0 7 Example generated id XML lt entity name Employee class org acme Employee access FIELD gt lt attributes gt lt id name id gt lt generated value gt lt id gt lt attributes gt lt entity gt 22 1 Sequence Strategies There are
250. mbeddables 7 3 40 4 Common Problems Primary keys in CollectionTable The JPA 2 0 specification does not provide a way to define the Id in the Embeddable However to delete or update a element of the ElementCollection mapping some unique key is normally required Otherwise on every update the JPA provider would need to delete everything from the CollectionTable for the Entity and then insert the values back So the JPA provider will most likely assume that the combination of all of the fields in the Embeddable are unique in combination with the foreign key JoinColumn s This however could be inefficient or just not feasible if the Embeddable is big or complex Some JPA providers may allow the Id to be specified in the Embeddable to resolve this issue Note in this case the Id only needs to be unique for the collection not the table as the foreign key is included Some may also allow the unique option on the CollectionTable to be used for this Otherwise if your Embeddable is complex you may consider making it an Entity and use a OneToMany instead ElementCollection ElementCollection 6 Chapter 29 9 on page 123 7 Chapter 30 1 on page 126 8 Chapter 30 4 on page 131 9 Chapter 30 5 on page 132 10 Chapter 31 2 on page 140 11 Chapter 31 3 on page 145 12 Chapter 31 6 on page 148 13 Chapter 30 6 on page 135 14 Chapter 33 2 2 on page 164 15 Chapter 37 1 2 on page 178 16 Chapter 24 2 4 on page 87 17 http
251. med to occur based on where the Id annotation is placed if placed on a field then the class is using FIELD access if placed on a get method then the class is using PROPERTY access The access type can also be defined through XML on the lt entity gt element The access type can be configured using the AccessType annotation or access type XML attribute For FIELD access the class field value will be accessed directly to store and load the value from the database This is normally done either through reflection or through generated byte code but depends on the JPA provider and configuration The field can be private or any other access type FIELD is normally safer as it avoids any unwanted side affect code that may occur in the application get set methods For PROPERTY access the class get and set methods will be used to store and load the value from the database This is normally done either through reflection or through generated byte code but depends on the JPA provider and configuration PROPERTY has the advantage of allowing the application to perform conversion of the database value when storing it in the object The user should be careful to not put any side affects in the get set methods that could interfere with persistence JPA 2 0 allows the access type to also be set on a specific field or get method This allows for the class to use one default access mechanism but for one attribute to use a different access type This can be
252. mented and with an implementation available to the public in source code form and must require no special password or key for unpacking reading or copying 7 Additional Terms Additional permissions are terms that supplement the terms of this License by making exceptions from one or more of its conditions Additional permis sions that are applicable to the entire Program shall be treated as though they were included in this License to the extent that they are valid un der applicable law If additional permissions apply only to part of the Program that part may be used separately under those permissions but the entire Program remains governed by this License without regard to the additional permissions When you convey a copy of a covered work you may at your option remove any additional permissions from that copy or from any part of it Additional permissions may be written to require their own re moval in certain cases when you modify the work You may place additional permissions on material added by you to a covered work for which you have or can give appropriate copyright permission Notwithstanding any other provision of this Li cense for material you add to a covered work you may if authorized by the copyright holders of that material supplement the terms of this License with terms a Disclaiming warranty or limiting liability dif ferently from the terms of sections 15 and 16 of this License or b
253. ml 15 https java sun com javaee 6 docs api javax persistence MapKeyJoinColumns html 16 https java sun com javaee 6 docs api javax persistence MapKeyClass html 141 Advanced 1 Bob Way 2 Sarah Smith PHONE table ID OWNER_ ID PHONE TYPE AREACODE 1 1 home 613 2 1 cell 613 3 2 home 416 4 2 fax 416 Example of a map key column relationship annotation Entity public class Employee Id private long id COneToMany mappedBy owner MapKeyColumn name PHONE_TYPE private Map lt String Phone gt phones Aas Entity public class Phone Old private long id ManyToOne private Employee owner Example of a map key column relationship XML lt entity name Employee class org acme Employee access FIELD gt lt attributes gt lt id name id gt lt one to many name phones mapped by owner gt lt map key column name PHONE_TYPE gt lt one to many gt lt attributes gt lt entity gt lt entity name Phone class org acme Phone access FIELD gt lt attributes gt lt id name id gt lt many to one name owner gt lt attributes gt lt entity gt Example of a map key join column relationship database EMPLOYEE table 142 50000 60000 NUMBER 792 7777 798 6666 792 9999 798 5999 Maps ID FIRSTNAME 1 Bob 2 Sarah PHONE table ID OWNER_ ID 1 1 2 1 3 2 4 2 PHONETYPE table ID rom m LASTNAME Way Smith PHONE_TYPE_ID 1 2 1 3 TYPE home
254. mple arithmetic_ expression TRIM trim_ specification trim character FROM string primary LOWER string_ primary UPPER string_ primary trim_ specification LEADING TRAILING BOTH 236 Update 46 1 5 Group By GROUP BY employee address country employee address city HAVING COUNT employee id gt 500 egroupby_clause GROUP BY groupby_ item groupby_item groupby_ item single_valued_path_expression identification variable having_clause HAVING conditional_ expression 46 1 6 Order By ORDER BY employee address country employee address city DESC orderby_ clause ORDER BY orderby_item orderby_item orderby_ item state_field_path_expression ASC DESC 46 1 7 Subquery WHERE employee salary SELECT MAX wellPaid salary FROM Employee wellPaid subquery simple _ select _clause subquery_from_ clause where _clause groupby_clause having clause subquery_from_clause FROM subselect_identification_variable_declaration subselect_ identification _variable_ declarationp subselect_ identification variable declaration identification _variable_declaration association_path_ expression AS identification variable collection_member_ declaration simple_select_clause SELECT DISTINCT simple_ select expression simple_select_expression single _valued_path_ expression aggregate_ expression identification variable 46 2 Update UPDATE Employee e S
255. mpletes and can continue to be used in subsequent transactions 43 2 1 Example JEE JPA persistence xml file lt xml version 1 0 encoding UTF 8 gt lt persistence xmlns http java sun com xml ns persistence xmlns xsi http www w3 org 2001 XMLSchema instance xsi schemaLocation http java sun com xml ns persistence persistence_1_0 xsd version 1 0 gt lt persistence unit name acme transaction type JTA gt lt jta data source gt jdbc ACMEDataSource lt jta data source gt lt persistence unit gt lt persistence gt Example SessionBean ejb jar xml file with persistence context lt xml version 1 0 encoding UTF 8 gt lt ejb jar xmlns http java sun com xml ns javaee xmlns xsi http www w3 org 2001 XMLSchema instance xsi schemaLocation http java sun com xml ns javaee http java sun com xml ns javaee ejb jar_3_0 xsd version 3 0 gt lt enterprise beans gt lt session gt lt ejb name gt EmployeeService lt ejb name gt lt business remote gt org acme EmployeeService lt business remote gt lt ejb class gt org acme EmployeeServiceBean lt ejb class gt lt session type gt Stateless lt session type gt lt persistence context ref gt lt persistence context re f name gt persistence acme entity manager lt persistence context ref name gt lt persistence unit name gt acme lt persistence unit name gt lt persistence context ref gt lt persistence unit ref gt lt persisten ce unit ref name
256. n each merge call can require to traverse a large graph of objects Another issues arises if your detached object is corrupt in some way For example say you have an Employee who has a manager but that manager has a different copy of the detached Employee object as its managedEmployee This may cause the same object to be merged twice or at least may not be consistent which object will be merged so you may not get the changes you expect merged The same is true if you didn t change an object at all but some other user did if merge cascades to this unchanged object it will revert the other user s changes or throw an OptimisticLockException depending on your locking policy This is normally not desirable I would recommend only marking relationships that are composite or privately owned as cascade merge 47 2 2 Transient Variables Another issue with merge is transient variables Since merge is normally used with object serialization if a relationship was marked as transient Java transient not JPA transient then the detached object will contain null and null will be merged into the object even though it is not desired This will occur even if the relationship was not cascade merge as merge always merges the references to related objects Normally transient is required when using serialization to avoid serializing the entire database when only a single or small set of objects are required One solution is to avoid marking anything t
257. n the target object s table JPA 1 0 did not support collections of embeddable objects but some JPA providers support this JPA 2 0 does support collections of embeddable objects through the ElementCollection mapping See ElementCollection EclipseLink as of 1 2 Supports the JPA 2 0 ElementCollection mapping 11 Chapter 12 on page 27 12 Chapter 39 1 2 on page 185 13 Chapter 10 on page 23 97 Advanced TopLink EclipseLink Support collections of embeddables This is set through using a DescriptorCustomizer and the AggregateCollectionMapping Hibernate Supports collections of embeddables through the Collection0fElements annotation DataNucleus Supports the JPA 2 0 ElementCollection mapping Typically the primary key of the target table will be composed of the parent s primary key and some unique field in the embeddable object The embeddable should have a unique field within its parent s collection but does not need to be unique for the entire class It could still have a unique id and still use sequencing or if it has no unique fields its id could be composed of all of its fields The embeddable collection object will be different than a typical embeddable object as it will not be stored in the parent s table but in its own table Embeddables are strictly privately owned objects deletion of the parent will cause deletion of the embeddables and removal from the embeddable collection should caus
258. n wikibooks org wiki User 3AStannered 285 57 Licenses 57 1 GNU GENERAL PUBLIC LICENSE Version 3 29 June 2007 Copyright O 2007 Free Software Foundation Inc lt http fsf org gt Everyone is permitted to copy and distribute verba tim copies of this license document but changing it is not allowed Preamble The GNU General Public License is a free copyleft license for software and other kinds of works The licenses for most software and other practi cal works are designed to take away your freedom to share and change the works By contrast the GNU General Public License is intended to guaran tee your freedom to share and change all versions of a program to make sure it remains free software for all its users We the Free Software Foundation use the GNU General Public License for most of our software it applies also to any other work released this way by its authors You can apply it to your programs too When we speak of free software we are referring to freedom not price Our General Public Li censes are designed to make sure that you have the freedom to distribute copies of free software and charge for them if you wish that you receive source code or can get it if you want it that you can change the software or use pieces of it in new free programs and that you know you can do these things To protect your rights we need to prevent others from denying you these rights or asking you to sur render t
259. n you do not want cascaded locking One of the advantages of cascaded locking is you have fewer version fields to maintain and only the update to the root object needs to check the version This can make a difference in optimizations such as batch writing as the dependent objects may not be able to be batched if they have their own version that must be checked TopLink EclipseLink Support cascaded locking through their OptimisticLocking and PrivateOwned annotations and XML 27 2 4 Field Locking If you do not have a version field in your table optimistic field locking is another solution Field locking involves comparing certain fields in the object when updating If those fields have changed then the update will fail JPA does not support field locking but some JPA providers do support it Field locking can also be used when a finer level of locking is desired For example if one user changes the object s name and another changes the objects address you may desire for these updates to not conflict and only desire optimistic lock errors when users change the 12 Chapter 27 2 5 on page 106 13 https java sun com javaee 5 docs api javax persistence EntityManager html lock java lang Object 20javax persistence LockModeType 14 Chapter 11 on page 25 15 Chapter 10 on page 23 105 Locking same fields You may also only be concerned about conflicts in changes to certain fields and not desire lock errors from conflicts
260. nCity query SELECT E from EMP E ADDRESS A WHERE E EMP_ID A EMP_ID AND A CITY resultClass Employee class public class Employee N BP 15 https java sun com javaee 5 docs api javax persistence NamedNativeQuery html 16 https java sun com javaee 5 docs api javax persistence NamedNativeQueries html 17 https java sun com javaee 5 docs api javax persistence EntityManager html createNativeQuery java lang String 18 Chapter 45 6 1 on page 230 19 https java sun com javaee 5 docs api javax persistence QueryHint html 229 Advanced Example native named query XML lt entity mappings gt lt entity name Employee class org acme Employee access FIELD gt lt named native query name findAllEmployeesInCity result class org acme Employee gt lt query gt SELECT E from EMP E ADDRESS A WHERE E EMP_ID A EMP_ID AND A CITY lt query gt lt named native query gt lt attributes gt lt id name id gt lt attributes gt lt entity gt lt entity mappings gt Example native named query execution EntityManager em getEntityManager Query query em createNamedQuery findAllEmployeesInCity query setParameter 1 Ottawa List lt Employee gt employees query getResultList Example dynamic native query execution EntityManager em getEntityManager Query query em createNativeQuery SELECT E from EMP E ADDRESS A WHERE E EMP_ID A EMP_ID AND A CITY Employee cla
261. n_ item literal single_valued_input_ parameter Allows collection parameters for IN SELECT e from Employee e where e id in param functions_returning_ strings CONCAT string_ primary string_ primary string_ primary Allows CONCAT with multiple arguments SELECT e from Employee e where CONCAT e address street e address city e address province address SUBSTRING string_primary simple_arithmetic_expression simple_arithmetic_ expression Allows SUBSTRING with single argument SELECT e from Employee e where SUBSTRING e name 3 Mac case _ expression general_case_expression simple_case_ expression coalesce_ expression nullif_expression general_case_expression CASE when_clause when_clause ELSE scalar_expression END when_clause WHEN conditional_expression THEN scalar_ expression simple_case_expression CASE case_operand simple_when_clause simple_ when_clause ELSE scalar_expression END case_operand state_field_path_expression type_discriminator simple_when_clause WHEN scalar_expression THEN scalar_ expression coalesce_ expression COALESCE scalar_ expression scalar_expression nullif_expression NULLIF scalar_ expression scalar_ expression 239 JPQL BNF Allows CASE COALESCE and NULLIF functions SELECT e name CASE WHEN e salary gt 100000 THEN 1 WHEN e salary lt 100000 THEN 2 ELSE O END from Employee e functions _returning_numerics I
262. nal columns in join table See Mapping a Join Table with Additional Columns Duplicate rows inserted into the join table If you have a bidirectional ManyToMany relationship you must use mappedBy on one side of the relationship otherwise it will be assumed to be two difference relationships and you will get duplicate rows inserted into the join table 15 Chapter 31 6 on page 148 16 Chapter 39 1 on page 183 182 39 Advanced 39 1 Mapping a Join Table with Additional Columns A frequent problem is that two classes have a ManyToMany relationship but the relational join table has additional data For example if Employee has a ManyToMany with Project but the PROJ_EMP join table also has an IS_PROJECT_LEAD column In this case the best solution is to create a class that models the join table So a ProjectAssociation class would be created It would have a ManyToOne to Employee and Project and attributes for the additional data Employee and Project would have a OneToMany to the ProjectAssociation Some JPA providers also provide additional support for mapping to join tables with additional data Unfortunately mapping this type of model becomes more complicated in JPA because it requires a composite primary key The association object s Id is composed of the Employee and Project ids The JPA 1 0 spec does not allow an Id to be used on a ManyToOne so the association class must have two duplicate attributes to also store the ids and use
263. nd a ManyToMany relationship in JPA is that a ManyToMany always makes use of a intermediate relational join table to store the relationship where as a OneToMany can either use a join table or a foreign key in target object s table referencing the source object table s primary key In JPA a ManyToMany relationship is defined through the ManyToMany annotation or the lt many to many gt element All ManyToMany relationships require a JoinTable The JoinTable is defined using the JoinTable annotation and lt join table gt XML element The JoinTable defines a foreign key to the source object s primary key joinColumns and a foreign key to the target object s primary key inverseJoinColumns Normally the primary key of the JoinTable is the combination of both foreign keys 38 0 3 Example of a ManyToMany relationship database EMPLOYEE table ID FIRSTNAME LASTNAME 1 Bob Way 2 Sarah Smith EMP_PROJ table EMP_ID PROJ_ID 1 1 1 2 1 Chapter 35 1 on page 169 2 https java sun com javaee 5 docs api javax persistence ManyToMany html 3 https java sun com javaee 5 docs api javax persistence JoinTable html 179 Many ToMany PROJECT table ID NAME 1 GIS SIG 38 0 4 Example of a ManyToMany relationship annotations Entity public class Employee Old Column name ID private long id ManyToMany CJoinTable name EMP_PROJ joinColumns JoinColumn name EMP_ID referencedColumnName ID inverseJo
264. ne setOwner this public class Phone private Employee owner public void setOwner Employee employee 3 Chapter 33 2 2 on page 164 173 OneToMany this owner employee if employee getPhones contains this employee getPhones add this Some expect the JPA provider to have magic that automatically maintains relationships This was actually part of the EJB CMP 2 specification However the issue is if the objects are detached or serialized to another VM or new objects are related before being managed or the object model is used outside the scope of JPA then the magic is gone and the application is left figuring things out so in general it may be better to add the code to the object model However some JPA providers do have support for automatically maintaining relationships In some cases it is undesirable to instantiate a large collection when adding a child object One solution is to not map the bi directional relationship and instead query for it as required Also some JPA providers optimize their lazy collection objects to handle this case so you can still add to the collection without instantiating it 36 1 Join Table A common mismatch between objects and relational tables is that a OneToMany does not require a back reference in Java but requires a back reference foreign key in the database Normally it is best to define the ManyToOne back reference in Java if you cannot or don t want to
265. ne to many name phones target entity org acme Phone mapped by owner gt lt attributes gt lt entity gt lt entity name Phone class org acme Phone access FIELD gt lt attributes gt lt id name id gt lt many to one name owner fetch LAZY gt lt join column name OWNER_ID gt lt many to one gt lt attributes gt lt entity gt Note this OneToMany mapping requires an inverse ManyToOne mapping to be complete see ManyToOne 36 0 4 Getters and Setters As the relationship is bi directional so as the application updates one side of the relationship the other side should also get updated and be in synch In JPA as in Java in general it is the responsibility of the application or the object model to maintain relationships If your application adds to one side of a relationship then it must add to the other side This can be resolved through add or set methods in the object model that handle both sides of the relationships so the application code does not need to worry about it There are two ways to go about this you can either only add the relationship maintenance code to one side of the relationship and only use the setter from one side such as making the other side protected or add it to both sides and ensure you avoid a infinite loop For example public class Employee private List phones public void addPhone Phone phone this phones add phone if phone getOwner this pho
266. neToOne The JoinTable documentation does not state that it can be used in a OneToOne but the XML schema for lt one to one gt does allow a nested lt join table gt element Some JPA providers may support this and others may not If your JPA provider does not support this you can workaround the issue by instead defining a OneToMany or ManyToMany relationship and just define a get set method that returns sets the first element on the collection 2 https java sun com javaee 5 docs api javax persistence JoinTable html 161 Advanced Example of a OneToOne using a JoinTable database EMPLOYEE table EMP_ID FIRSTNAME LASTNAME SALARY 1 Bob Way 50000 2 Sarah Smith 60000 EMP_ADD table EMP_ID ADDR_ID 1 6 2 7 ADDRESS table 162 Mapping a One ToOne Using a Join Table SACHSI SZLHCM adop d epeue epeue AULNNOD NO NO HONIAOYdA OJUOJOL EMENO ALID 15 TEN GG 15 JUE LT LATULS L 9 dI SS4YaAV 163 Advanced 33 2 1 Example of a OneToOne using a JoinTable OneToOne fetch FetchType LAZY CJoinTable name EMP_ADD joinColumns JoinColumn name EMP_ID referencedColumnName EMP_ID inverseJoinColumns JoinColumn name ADDR_ID referencedColumnName ADDRESS_ID private Address address 33 2 2 Example of simulating a OneToOne using a OneToMany JoinTable COneToMany CJoinTable name EMP_ADD joinColumns JoinColumn name EMP_ID referencedColumnName EMP_ID inverseJ
267. ng Any changes made between the read and write will not be detected You must keep the original object read managed in an EntityManager for your locking to have any effect TopLink EclipseLink Support field locking through their OptimisticLocking annotation and XML 27 2 5 Read and Write Locking It is sometimes desirable to lock something that you did not change Normally this is done when making a change to one object that is based on the state of another object and you wish to ensure that the other object represents the current state of the database at the point of the commit This is what serializable transaction isolation gives you but optimistic read and write locking allow this requirement to be met declaratively and optimistically and without deadlock concurrency and open transaction issues JPA supports read and write locks through the EntityManager lock API The LockModeType argument can either be READ or WRITE A READ lock will ensure that 16 Chapter 11 on page 25 17 Chapter 10 on page 23 18 https java sun com javaee 5 docs api javax persistence EntityManager htmlttlock java lang Object 20javax persistence LockModeType 19 https java sun com javaee 5 docs api javax persistence LockModeType html 106 Advanced the state of the object does not change on commit A WRITE lock will ensure that this transaction conflicts with any other transaction changing or locking the object Essentially
268. ng the INCREMENT on the database sequence object to the sequence preallocation size In JPA the CSequenceGenerator annotation or lt sequence generator gt element is used to define a sequence object The SequenceGenerator defines a sequenceName for the name of the database sequence object and an allocationSize for the sequence preallocation size or sequence object INCREMENT Example sequence generator annotation Entity public class Employee Id GeneratedValue strategy GenerationType SEQUENCE generator EMP_SEQ SequenceGenerator name EMP_SEQ sequenceName EMP_SEQ allocationSize 100 private long id Example sequence generator XML lt entity name Employee class org acme Employee access FIELD gt lt attributes gt lt id name id gt lt generated value strategy SEQUENCE generator EMP_SEQ gt lt sequence generator name EMP_SEQ sequence name EMP_SEQ allocation size 100 gt lt id gt lt attributes gt lt entity gt Common Problems Error when allocating a sequence number Errors such as sequence not found can occur if you do not have a SEQUENCE object defined in your database Ensure you create the sequence object or let your JPA provider create your schema for you most JPA providers support schema creation When creating your sequence object ensure the sequence s INCREMENT matches your SequenceGenerator s allocationSize The DDL to create a sequence object depends on the databa
269. ng the database not the 1st level cache This is normally solved in JPA by the user first calling flush or the flushMode automatically triggering a flush The default flushMode on an EntityManager or Query is to trigger a flush but this can be disabled if a write to the database before every query is not desired normally it isn t as it can be expensive and lead to poor concurrency Some JPA providers also support conforming the database query results with the object changes in memory which can be used to get consistent data without triggering a flush This can work for simple queries but for complex queries this typically gets very complex to impossible Applications normally query data at the start of a request before they start making changes or don t query for objects they have already found so this is normally not an issue If you bypass JPA and execute DML directly on the database either through native SQL queries JDBC or JPQL UPDATE or DELETE queries then the database can be out of synch with the 1st level cache If you had accessed objects before executing the DML they will have the old state and not include the changes Depending on what you are doing this may be ok otherwise you may want to refresh the affected objects from the database The 1st level or EntityManager cache can also span transaction boundaries in JPA A JTA managed EntityManager will only exist for the duration of the JTA transac tion in JEE Typically the JEE
270. no Front Cover Texts and no Back Cover Texts A copy of the license is included in the section entitled GNU Free Documentation License If you have Invariant Sections Front Cover Texts and Back Cover Texts replace the with Texts line with this with the Invariant Sections being LIST THEIR TI TLES with the Front Cover Texts being LIST and with the Back Cover Texts being LIST If you have Invariant Sections without Cover Texts or some other combination of the three merge those two alternatives to suit the situation If your document contains nontrivial examples of program code we recommend releasing these exam ples in parallel under your choice of free software license such as the GNU General Public License to permit their use in free software 5 Combined Libraries You may place library facilities that are a work based on the Library side by side in a single library together with other library facilities that are not Applications and are not covered by this License and convey such a combined library under terms of your choice if you do both of the following a Accompany the combined library with a copy of the same work based on the Library uncombined with any other library facilities conveyed under the terms of this License b Give prominent no tice with the combined library that part of it is a work based on the Library and explaining where to find the accompanying uncombined form of the same work
271. not have a SEQUENCE table defined in your database or its schema does not match what you have configured or what your JPA provider is expecting by default Ensure you create the sequence table correctly or configure your TableGenerator to match the table that you created or let your JPA provider create you tables for you most JPA provider support schema creation You may also get an error such as sequence not found this means you did not create a row in the table for your sequence You must insert an initial row in the sequence table for your sequence with the initial id i e INSERT INTO SEQUENCE_TABLE SEQ_NAME SEQ_COUNT VALUES EMP_SEQ 0 or let your JPA provider create your schema for you Deadlock or poor concurrency in the sequence table See concurrency issues 22 1 2 Sequence objects Sequence objects use special database objects to generate ids Sequence objects are only supported in some databases such as Oracle DB2 and Postgres Usually a SEQUENCE object has a name an INCREMENT and other database object settings Each time the lt sequence gt NEXTVAL is selected the sequence is incremented by the INCREMENT Sequence objects provide the optimal sequencing option as they are the most efficient and have the best concurrency however they are the least portable as most databases do 6 Chapter 23 3 on page 73 59 Sequencing not support them Sequence objects support sequence preallocation through setti
272. ns Entity Inheritance CDiscriminatorColumn name PROJ_TYPE Table name PROJECT public abstract class Project Id private long id Entity DiscriminatorValue L public class LargeProject extends Project private BigDecimal budget Entity DiscriminatorValue S public class SmallProject extends Project 23 7 3 Example single table inheritance XML lt entity name Project class org acme Project access FIELD gt 23 https java sun com javaee 5 docs api javax persistence MappedSuperclass html 77 Advanced lt table name PROJECT gt lt inheritance gt lt discriminator column name PROJ_TYPE gt lt attributes gt lt id name id gt lt attributes gt lt entity gt lt entity name LargeProject class org acme LargeProject access FIELD gt lt discriminator value gt L lt discriminator value gt lt entity gt lt entity name SmallProject class org acme SmallProject access FIELD gt lt discriminator value gt S lt discriminator value gt lt entity gt 23 7 4 Common Problems No class discriminator column If you are mapping to an existing database schema your table may not have a class discriminator column Some JPA providers do not require a class discriminator when using a joined inheritance strategy so this may be one solution Otherwise you need some way to determine the class for a row Sometimes the inherited value can be computed
273. ns a List of the results This is normally a List of Entity objects but could also be a list of data or arrays JPQL SQL Result SELECT e FROM Employee e This returns a List lt Employee gt List of Employee objects The objects will be managed SELECT e firstName FROM Employee e This returns a List lt String gt List of String values The data is not managed SELECT e firstName e lastName This returns a List lt Object String FROM Employee e String gt List of object arrays each with two String values The data is not managed SELECT e e address FROM Employee This returns a List lt Object Employee e Address gt List of object arrays each with an Employee and Address objects The objects will be managed SELECT EMP_ID F_NAME L_NAME FROM This returns a EMP List lt Object BigDecimal String String gt List of object arrays each with the row data The data is not managed getSingleResult returns the results This is normally an Entity objects but could also be data or an object array If the query returns nothing an exception is thrown This is unfortunate as typically just returning null would be desired Some JPA providers may have an option to return null instead of throwing an exception if nothing is returned Also if the query returns more than a single row and exception is also thrown This is also unfortunate as typically just returning the first result is desired Some JPA providers may have an
274. ns stated herein The Document below refers to any such manual or work Any member of the public is a li censee and is addressed as you You accept the license if you copy modify or distribute the work in a way requiring permission under copyright law A Modified Version of the Document means any work containing the Document or a portion of it ei ther copied verbatim or with modifications and or translated into another language A Secondary Section is a named appendix or a front matter section of the Document that deals ex clusively with the relationship of the publishers or authors of the Document to the Document s overall subject or to related matters and contains noth ing that could fall directly within that overall sub ject Thus if the Document is in part a textbook of mathematics a Secondary Section may not ex plain any mathematics The relationship could be a matter of historical connection with the subject or with related matters or of legal commercial philosophical ethical or political position regard ing them The Invariant Sections are certain Secondary Sec tions whose titles are designated as being those of Invariant Sections in the notice that says that the Document is released under this License If a sec tion does not fit the above definition of Secondary then it is not allowed to be designated as Invariant The Document may contain zero Invariant Sections If the Document does not id
275. nship XML lt entity name Employee class org acme Employee access FIELD gt lt attributes gt lt id name id gt lt one to many name phones target entity org acme Phone gt lt join column name OWNER_ID gt lt one to many gt lt attributes gt lt entity gt 131 Relationships 30 5 Collections Collection mappings include OneToMany ManyToMany and in JPA 2 0 ElementCollec tion 7 JPA requires that the type of the collection field or get set methods be one of the Java collection interfaces Collection List Set or Map 30 5 1 Collection Implementations Your field should not be of a collection implementation type such as ArrayList Some JPA providers may support using collection implementations many support EAGER collection relationships to use the implementation class You can set any implementation as the instance value of the collection but when reading an object from the database if it is LAZY the JPA provider will normally put in a special LAZY collection 30 5 2 Duplicates A List in Java supports duplicate entries and a Set does not In the database duplicates are generally not supported Technically it could be possible if a JoinTable is used but JPA does not require duplicates to be supported and most providers do not If you require duplicate support you may need to create an object that represents and maps to the join table This object would still require a unique Id such as a Gen
276. nship should be join fetched i e retrieved in the same SQL SELECT statement as the source object Some JPA providers do implement eager this way However just because something is desired to be loaded does not mean that it should be join fetched Consider Employee Phone a Phone s employee reference is made EAGER as the employee is almost always loaded before the phone However when loading the phone you do not want to join the employee the employee has already been read and is already in the cache or persistence context Also just because you want two collection relationships loaded does not mean you want them join fetch which would result in a very inefficient join that would return n 2 data Join fetching is something that JPA currently only provides through JPQL which is normally the correct place for it as each use case has different relationship requirements Some JPA providers also provider a join fetch option at the mapping level to always join fetch a relationship but this is normally not the same thing as EAGER Join fetching is not normally the most efficient way to load a relationship anyway normally batch reading a relationship is much more efficient when supported by your JPA provider See Join Fetching See Batch Reading 10 Chapter 31 3 on page 145 11 Chapter 31 4 on page 147 128 Cascading 30 2 Cascading Relationship mappings have a cascade option that allows the relationship to be cascaded for common
277. nsure you have the agent configured correctly Some JPA providers perform dynamic subclass generation so do not require an agent Example agent java javaagent eclipselink jar Some JPA providers also provide static weaving instead or in addition to dynamic weaving For static weaving some preprocessor must be run on your JPA classes When running in JEE lazy should normally work as the class loader hook is required by the EJB specification However some JEE providers may not support this so static weaving may be required Also ensure that you are not accessing the relationship when you shouldn t be For example if you use property access and in your set method access the related lazy value this will cause it to be loaded Fither remove the set method side effects or use field access 22 Chapter 30 1 on page 126 23 Chapter 31 6 on page 148 24 Chapter 31 3 on page 145 25 Chapter 31 4 on page 147 136 Common Problems Broken relationships after serialization If your relationship is marked as lazy then if it has not been instantiated before the object is serialized then it may not get serialized This may cause an error or return null if it is accessed after deserialization See Serialization and Detaching Dependent object removed from OneToMany collection is not deleted When you remove an object from a collection if you also want the object deleted from the database you must call remove on the
278. nversion is required when obtaining a cache hit With JPA the EntityManager must still copy the objects to and from the cache as it must maintain its transaction isolation but that is all that is required The objects do not need to be re built and the relationships are already available 262 Data Cache With an object cache transient data may also be cached This may occur automatically or may require some effort If transient data is not desired you may also need to clear the data when the object gets cached Some JPA products allow read only queries to access the object cache directly Some products only allow object caching of read only data Obtaining a cache hit on read only data is extremely efficient as the object does not need to be copied other than the look up no work is required It is possible to create your own object cache for your read only data by loading objects from JPA into your own object cache or JCache implementation The main issue which is always the main issue in caching in general is how to handle updates and stale cached data but if the data is read only this may not be an issue TopLink EclipseLink Support an object cache The object cache is on by default but can be globally or selectively enabled or configured per class The persistence unit property eclipselink cache shared default can be set to false to disable the cache Read only queries are supported through the eclipselink read only
279. o make a manual textbook or other functional and useful document free in the sense of freedom to assure everyone the effective freedom to copy and redistribute it with or without modifying it either commercially or noncommercially Secondarily this License pre serves for the author and publisher a way to get credit for their work while not being considered responsible for modifications made by others This License is a kind of copyleft which means that derivative works of the document must them selves be free in the same sense It complements the GNU General Public License which is a copy left license designed for free software We have designed this License in order to use it for manuals for free software because free software needs free documentation a free program should come with manuals providing the same freedoms that the software does But this License is not lim ited to software manuals it can be used for any tex tual work regardless of subject matter or whether it is published as a printed book We recommend this License principally for works whose purpose is instruction or reference 1 APPLICABILITY AND DEFINITIONS This License applies to any manual or other work in any medium that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License Such a notice grants a world wide royalty free license unlimited in dura tion to use that work under the conditio
280. o map XML data types See Custom Types 28 1 5 How to map Struct and Array types See Custom Types 28 1 6 How to map custom database types See Custom Types Chapter 29 8 on page 122 Chapter 29 6 on page 120 Chapter 29 1 4 on page 116 Chapter 29 9 on page 122 Chapter 29 9 on page 122 Chapter 29 9 on page 122 F COND OH o 113 Basics 28 1 7 How to exclude fields from INSERT or UPDATE statements or default values in triggers See Insertable Updatable 11 Chapter 29 7 on page 121 114 29 Advanced 29 1 Temporal Dates Times Timestamps and Calendars Dates times and timestamps are common types both in the database and in Java so in theory mappings these types should be simple right Well sometimes this is the case and just a normal Basic mapping can be used however sometimes it becomes more complex Some databases do not have DATE and TIME types only TIMESTAMP fields however some do have separate types and some just have DATE and TIMESTAMP Originally in Java 1 0 Java only had a java util Date type which was both a date time and milliseconds In Java 1 1 this was expanded to support the common database types with java sql Date java sql Time and java sql Timestamp then to support internationalization Java cre ated the java util Calendar type and virtually deprecated almost all of the methods the old date types which JDBC still uses If you map a Java java sql Date type to a data
281. o way to specify that a join fetch always be used for a relationship Normally it is better to specify the join fetch at the query level as some use cases may require the related objects and other use cases may not JPA does support an EAGER option on mappings but this means that the relationship will be loaded not that it will be joined It may be desirable to mark all relationships as EAGER as everything is desired to be loaded but join fetching everything in one huge select could result in a inefficient overly complex or invalid join on the database Some JPA providers do interpret EAGER as join fetch so this may work on some JPA providers Some JPA providers support a separate option for always join fetching a relationship TopLink EclipseLink Support a JoinFetch annotation and XML on a mapping to define that the relationship always be join fetched 17 Chapter 11 on page 25 18 Chapter 10 on page 23 146 Batch Fetching 31 3 3 Nested Joins JPA 1 0 does not allow nested join fetches in JPQL although this may be supported by some JPA providers You can join fetch multiple relationships but not nested relationships Example of Multiple JPQL Join Fetch SELECT emp FROM Employee emp LEFT JOIN FETCH emp address LEFT JOIN FETCH emp phoneNumbers 31 3 4 Duplicate Data and Huge Joins One issue with join fetching is that duplicate data can be returned For example consider join fetching an Employee s phoneNumbers re
282. object references pointers from a source object to the target object Technically in Java there is no difference between a relationship to another object and a relationship to a data attribute such as a String or Date primitives are different as both are pointers however logically and for the sake of persistence data attributes are considered part of the object and references to other persistent objects are considered relationships In a relational database relationships are defined through foreign keys The source row contains the primary key of the target row to define the relationship and sometimes the inverse A query must be performed to read the target objects of the relationship using the foreign key and primary key information In Java if a relationship is to a collection of other objects a Collection or array type is used in Java to hold the contents of the relationship In a relational database collection relations are either defined by the target objects having a foreign key back to the source object s primary key or by having an intermediate join table to store the relationship both objects primary keys All relationships in Java and JPA are unidirectional in that if a source object references a target object there is no guarantee that the target object also has a relationship to the source object This is different than a relational database in which relationships are defined through foreign keys and querying such tha
283. occurs during a flush or commit operation after the database DELETE has occurred but before the transaction is committed It does not occur during the remove operation 41 1 1 Example of Entity event annotations Entity public class Employee Id private String uid Basic private Calendar lastUpdated PrePersist public void prePersist this uid UIDGenerator newUUI this lastUpdated Calendar getInstance PreUpdate public void preUpdate this lastUpdated Calendar getInstance 41 1 2 Example of EntityListener event annotations Entity EventListeners EmployeeEventListener class public class Employee Old private String uid Basic private Calendar lastUpdated public class EmployeeEventListener PrePersist public void prePersist Object object Employee employee Employee object employee setUID UIDGenerator newUUI employee setLastUpdated Calendar getInstance PreUpdate public void preUpdate Object object Employee employee Employee object employee setLastUpdated Calendar getInstance 8 http download oracle com javaee 6 api javax persistence PostRemove html 194 Events 41 1 3 Example of Entity event xml lt entity name Employee class org acme Employee access FIELD gt lt pre persist method name prePersist gt lt pre update method name preUpdate gt lt attributes gt lt id name uid gt lt attributes gt
284. oinColumns JoinColumn name ADDR_ID referencedColumnName ADDRESS_ID private List lt Address gt addresses public Address getAddress if this addresses isEmpty return null return this addresses get 0 public void setAddress Address address if this addresses isEmpty this addresses add address else this addresses set 1 address OneToOne OneToOne 3 http en wikibooks org wiki Category 3AJava 20Persistence 4 http en wikibooks org wiki Category 3AJava 20Persistence 2FMapping 164 34 ManyToOne id long iy firstName String se managedEmployees lastName String nee id long salary BigDecimal 1 type String number String eee areaCode String manager y 1 EMP_ID NUMBER FK_MANAGER_ID F_NAME VARCHAR se Nine da OWNER JID NUMBER MANAGER_ID NUMBER 1 FK_OWNER_ID TYPE VARCHAR a P_NUMBER VARCHAR AREA_CODE VARCHAR Figure 15 A ManyToOne relationship in Java is where the source object has an attribute that references another target object and if that target object had the inverse relationship back to the source object it would be a OneToMany relationship All relationships in Java and JPA are unidirectional in that if a source object references a target object there is no guarantee that the target object also has a relationship to the source object This is different than a relational database in whic
285. ompany uses a normal ManyToOne with a foreign key but its relationship to department uses a ManyToOne with a foreign key but the COM_ID uses insertable updatable false or PrimaryKeyJoinColumn because it is actually mapped through the company relationship The Employee s relationship to its address then uses a normal foreign key for ADD_ID but a target foreign key for COM_ID DEP_ID and EMP_ID This may work in some JPA providers others may require different configuration or not support this type of data model 1 https java sun com javaee 5 docs api javax persistence PrimaryKeyJoinColumn html 157 Advanced Example of cascaded primary keys database COMPANY table COM_ID 1 2 DEPARTMENT table COM_ID 1 1 2 2 EMPLOYEE table 158 NAME ACME Wikimedia DEP_ID DOr bw NAME Billing Research Accounting Research Target Foreign Keys Primary Key Join Columns Cascade Primary Keys Y NN A NA dr ady mu mu mu mu dI DNN HU SEM 90 Surf 90 uyor ke yereg TuS of sem qog HINVN Y N TN A AI dINd mA NN TN d ddd aD TN N dI WOO 159 Advanced ADDRESS table COM_ID DEP_ID ADD_ID ADDRESS 1 1 1 17 Bank Ottawa ONT 1 1 2 22 Main Ottawa ONT 1 2 1 255 Main Toronto ONT 1 2 2 12 Main Winnipeg MAN 2 1 1 72 Riverside Winnipeg MAN 2 2 1 82 Riverside Winnipeg MAN 33 1 1 Example of cascaded primary keys and mixed OneToOne and ManyToOne mapping
286. on Entitled XYZ ac cording to this definition The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document These Warranty Dis claimers are considered to be included by reference in this License but only as regards disclaiming war ranties any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License 2 VERBATIM COPY ING You may copy and distribute the Document in any medium either commercially or noncommercially provided that this License the copyright notices and the license notice saying this License applies to the Document are reproduced in all copies and that you add no other conditions whatsoever to those of this License You may not use technical mea sures to obstruct or control the reading or further copying of the copies you make or distribute How ever you may accept compensation in exchange for copies If you distribute a large enough number of copies you must also follow the conditions in sec tion 3 You may also lend copies under the same condi tions stated above and you may publicly display copies 3 COPYING IN QUANTITY If you publish printed copies or copies in media that commonly have printed covers of the Doc ument numbering more than 100 and the Doc ument s license notice requires Cover Texts you fect according to their terms reviewing courts shall apply local law th
287. ooks org wiki Category 3AJava 20Persistence 2FWhat 20is 20Java 20persistence http en wikibooks org wiki Category 3AJava 20Persistence FOANDOTKRWNEH e N m O 3 What is Java Java is an object oriented programming language first released by Sun Microsystems in 1995 It blended concepts from existing languages such as C and Smalltalk into a new programming language It achieved its success over the many rival languages of the day because it was associated with this newish thing called the Internet in allowing Java applets to be embedded in web pages and run using Netscape Its other main reason for success was unlike many of its competitors it was open free and not embedded with a integrated development environment IDE Java also included the source code to its class library This enabled Java to be adopted by many different companies producing their own Java development environments but sharing the same language this open model fostered the growth in the Java language and continues today with the open sourcing of Java Java quickly moved from allowing developers to build dinky applets to being the standard server side language running much of the Internet today The Enterprise Edition JEE of Java was defined to provide an open model for server application to be written and portable across any compliant JEE platform provider The JEE standard is basically a basket of other Java specifications brought together under one um
288. opLink EclipseLink Support Oracle flashback querying as well as appli cation specific history Historical queries can be defined using the query hint eclipselink history as of or Expression queries Automatic tracking of history is also supported using the HistoryPolicy API that supports maintaining and querying a mirror history table 41 9 Logical Deletes 41 10 Auditing See Auditing and Security 41 11 Replication Data replication can be used to backup data for fault tolerance and fail over or for load balancing and scaling the database For replication changes are written to multiple databases either by the application JPA provider or database back end For fail over if one of the databases goes down the other can be used without loss of data or application downtime For load balancing read requests can be load balanced across the replicated databases to reduce the load on each database and improve the scalability of the application Most enterprise database support some form of automatic backup or replication Clustered database such as Oracle RAC also allow for load balancing fail over and high availability If your database supports replication or clustering then it is normally transparent to JPA A specialize DataSource such as Oracle UCP or WebLogic GridLink may need to be used to handle load balancing and fail over JPA does not define any specific support for data replication but some JPA provider pro
289. operations cascade is normally used to model dependent relationships such as Order gt OrderLine Cascading the orderLines relationship allows for the Order s gt OrderLines to be persisted removed merged along with their parent The following operations can be cascaded as defined in the CascadeType enum PERSIST Cascaded the EntityManager persist operation If persist is called on the parent and the child is also new it will also be persisted If it is existing nothing will occur although calling persist on an existing object will still cascade the persist operation to its dependents If you persist an object and it is related to a new object and the relationship does not cascade persist then an exception will occur This may require that you first call persist on the related object before relating it to the parent General it may seem odd or be desirable to always cascade the persist operation if a new object is related to another object then it should probably be persisted There is most likely not a major issue with always cascading persist on every relationship although it may have an impact on performance Calling persist on a related object is not required on commit any related object whose relationship is cascade persist will automatically be persisted The advantage of calling persist up front is that any generated ids will unless using identity be assigned and the prePersist event will be raised REMOV
290. option to return the first result instead of throwing an exception otherwise you need to call getResultList and get the first element 21 https java sun com javaee 5 docs api javax persistence Query html getResultList 22 https java sun com javaee 5 docs api javax persistence Query html getSingleResult 23 https java sun com javaee 5 docs api javax persistence Query html executeUpdate 219 Querying JPQL SQL SELECT e FROM Employee e SELECT e firstName FROM Employee e SELECT e firstName e lastName FROM Employee e SELECT e e address FROM Employee e SELECT EMP_ID F_NAME L_NAME FROM EMP Result This returns an Employee The object will be managed This returns a String The data is not managed This returns an Object String String object array with two String values The data is not managed This returns an Object Employee Address object array with an Em ployee and Address object The objects will be managed This returns an Object BigDecimal String String object array with the row data The data is not managed executeUpdate returns the database row count This can be used for UPDATE DELETE JPQL queries or any native SQL DML or DDL query that does not return a result 44 6 Common Queries 44 6 1 Joining querying on a OneToMany relationship To query all employees with a phone number in 613 area code a join is used JPQL SELECT e FROM Employee e JOIN e phoneNumbers
291. orresponding Source for all the software in the product that is covered by this Li cense on a durable physical medium customarily used for software interchange for a price no more than your reasonable cost of physically performing this conveying of source or 2 access to copy the Corresponding Source from a network server at no charge c Convey individual copies of the object code with a copy of the written offer to provide the Corresponding Source This alternative is al lowed only occasionally and noncommercially and only if you received the object code with such an of fer in accord with subsection 6b d Convey the object code by offering access from a designated place gratis or for a charge and offer equivalent access to the Corresponding Source in the same way through the same place at no further charge You need not require recipients to copy the Correspond ing Source along with the object code If the place to copy the object code is a network server the Cor responding Source may be on a different server op erated by you or a third party that supports equiv alent copying facilities provided you maintain clear directions next to the object code saying where to find the Corresponding Source Regardless of what server hosts the Corresponding Source you remain obligated to ensure that it is available for as long as needed to satisfy these requirements e Con vey the object code using peer to peer transmission prov
292. p where p areaCode 613 Criteria CriteriaBuilder cb em getCriteriaBuilder CriteriaQuery lt Employee gt query cb createQuery Employee class Root lt Employee gt employee query from Employee class Join lt PhoneNumber gt phone employee join phoneNumbers query where cb equal phone get areaCode 613 44 6 2 Subselect querying all of a ManyToMany relationship To query all employees whose projects are all in trouble a subselect with a double negation is used JPQL SELECT e FROM Employee e JOIN e projects p where NOT EXISTS SELECT t from Project t where p t AND t status lt gt In trouble Criteria 220 Common Queries CriteriaBuilder cb em getCriteriaBuilder CriteriaQuery lt Employee gt query cb createQuery Employee class Root lt Employee gt employee query from Employee class Join lt Project gt project employee join projects Subquery lt Project gt subquery query subquery Project class Root lt Project gt subProject query from Project class subquery where cb and cb equal project subProject cb equal subProject get status In trouble query where cb not cb exists subquery 44 6 3 Join fetch read both employee and address in same query To query all employees and their address a join fetch is used This selects both the employee and address data in the same query If the join fetch was not used the employee address would still
293. ple of a collection order column database EMPLOYEE table 21 https java sun com javaee 6 docs api javax persistence OrderColumn html 133 Relationships ID FIRSTNAME LASTNAME SALARY 1 Bob Way 50000 2 Sarah Smith 60000 EMPLOYEE_ PHONE table EMPLOYEE_ID PHONE_ID INDEX 1 1 0 1 3 1 2 2 0 2 4 1 PHONE table ID AREACODE NUMBER 1 613 792 7777 2 416 798 6666 3 613 792 9999 4 416 798 5555 Example of a collection order column annotation Entity public class Employee eId private long id OneToMany COrderColumn name INDEX private List lt Phone gt phones Example of a collection order column XML lt entity name Employee class org acme Employee access FIELD gt lt attributes gt lt id name id gt lt one to many name phones gt lt order column name INDEX gt lt one to many gt lt attributes gt lt entity gt 134 Common Problems 30 6 Common Problems Object corruption one side of the relationship is not updated after updating the other side A common problem with bi directional relationships is the application updates one side of the relationship but the other side does not get updated and becomes out of sync In JPA as in Java in general it is the responsibility of the application or the object model to maintain relationships If your application adds to one side of a relationship then it must add to the other side This is commonly resolved through ad
294. ployeel getManagedEmployees get 0 getManager assert employeel employee2 In JPA object identity is not maintained across EntityManagers Each EntityManager maintains its own persistence context and its own transactional state of its objects So the following is true in JPA EntityManager entityManageri factory createEntityManager EntityManager entityManager2 factory createEntityManager Employee employeel entityManager1 find Employee class 123 Employee employee2 entityManager2 find Employee class 123 assert employeel employee2 Object identity is normally a good thing as it avoids having your application manage multiple copies of objects and avoids the application changing one copy but not the other The reason different EntityManagers or transactions in JEE don t maintain object identity is that each transaction must isolate its changes from other users of the system This is also normally a good thing however it does require the application to be aware of copies detached objects and merging Some JPA products may have a concept of read only objects in which object identity may be maintained across EntityManagers through a shared object cache 51 2 Object Cache An object cache is where the Java objects entities are themselves cached The advantage of an object cache is that the data is cached in the same format that it is used in Java Everything is stored at the object level and no co
295. querying interfaces are also supported through their ClassDescriptor s InterfacePolicy API 26 Chapter 30 1 5 on page 127 27 Chapter 30 2 on page 129 28 Chapter 30 4 on page 131 29 Chapter 31 6 on page 148 30 Chapter 11 on page 25 31 Chapter 10 on page 23 137 31 Advanced 31 1 Advanced Relationships 31 1 1 JPA 2 0 Relationship Enhancements ElementCollection A Collection or Map of Embeddable or Basic values Map Columns A OneToMany or ManyToMany or ElementCollection that has a Basic Embeddable or Entity key not part of the target object Order Columns A OneToMany or ManyToMany or ElementCollection can now have a OrderColumn that defines the order of the collection when a List is used Unidirectional OneToMany A OneToMany no longer requires the ManyToOne inverse relationship to be defined 31 1 2 Other Types of Relationships Variable OneToOne ManyToOne A reference to an interface or common unmapped inheritance class that has multiple distinct implementors Variable OneToMany ManyToMany A Collection or Map of heterogeneous objects that share an interface or common unmapped inheritance class that has multiple distinct implementers Nested collection relationships such as an array of arrays List of Lists or Map of Maps or other such combinations Object Relational Data Type Relationships stored in the database using STRUCT VARRAY REF or NESTEDTABLE types XML relationships Relationships
296. r a native API were used Spring also defines a transaction manager implementation that is similar to JTA Spring also supports transactional annotations and beans similar to SessionBeans 52 2 JPA Spring has specific support for JPA and can emulate some of the functionality of a JEE container with respect to JPA Spring allows a JPA persistence unit to be deployed in container managed mode If the spring agent is used to start the JVM Spring can de ploy a JPA persistence unit with weaving similar to a JEE server Spring can also pass a Spring DataSource and integrate its transaction service with JPA Spring allows the PersistenceUnit and PersistenceContext annotations to be used in any Spring bean class to have an EntityManager or EntityManagerFactory injected Spring supports a managed transactional EntityManager similar to JEE where the EntityManager binds itself as a new persistence context to each new transaction and commits as part of the transaction Spring supports both JTA integration and its own transaction manager 52 2 1 Example Spring JPA Deployment lt xml version 1 0 encoding UTF 8 gt lt beans xmlns http www springframework org schema beans xmlns xsi http www w3 org 2001 XMLSchema instance xsi schemaLocation http www springframework org schema beans 1 http en wikipedia org wiki Spring_Framework 2 http en wikipedia org wiki Inversion_of_Control 273 Spring http www springfram
297. rammers can frequently be too clever for their own good The first issue that comes up when using optimistic locking is what to do when an OptimisticLockException occurs The typical response of the friendly neighborhood super programmer is to automatically handle the exception They will just create a new transaction refresh the object to reset its version and merge the data back into the object and re commit it Presto problem solved or is it This actually defeats the whole point of locking in the first place If this is what you desire you may as well use no locking Unfortunately the OptimisticLockException should rarely be automatically handled and you really need to bother the user about the issue You should report the conflict to the user and either say your sorry but an edit conflict occurred and they are going to have to redo their work or in the best case refresh the object and present the user with the current data and the data that they submitted and help them merge the two if appropriate Some automated merge tools will compare the two conflicting versions of the data and if none of the individual fields conflict then the data will just be automatically merged without the user s aid This is what most software version control systems do Unfortunately the user is typically better able to decide when something is a conflict than the program just because two versions of the java file did not change the same line of code does no
298. ransient and instead use LAZY relationships in JPA to limit what is serialized lazy relationships that have not been accessed will normally not be serialized Another solution is to manually merge in your own code 244 Remove Some JPA providers provide extended merge operations such as allowing a shallow merge or deep merge or merging without merging references 47 3 Remove The EntityManager remove operation is used to delete an object from the database remove does not directly delete the object from the database it marks the object to be deleted in the persistence context transaction When the transaction is committed or if the persistence context is flushed then the object will be deleted from the database The remove operation can only be called within a transaction an exception will be thrown outside of a transaction The remove operation must be called on a managed object not on a detached object Generally you must first find the object before removing it although it is possible to call EntityManager getReference on the object s Id and call remove on the reference Depending on how you JPA provider optimizes getReference and remove it may not require reading the object from the database remove can only be called on Entity objects not on Embeddable objects or collections or non persistent objects Embeddable objects are automatically removed as part of their owning Entity Example remove EntityManager e
299. reSQL JPA has no extended support for XML data although it is possible to store an XML String into the database just mapped as a Basic Some JPA provider may offer extended XML data support Such as query extensions or allow mapping an XML DOM 21 Chapter 11 on page 25 22 Chapter 10 on page 23 23 http ronaldoblanc blogspot com 2011 11 jpa eclipselink e stored procedures com html 200 Filters If you wish to map the XML data into objects you could make use of the JAXB specification You may even be able to integrate this with your JPA objects TopLink EclipseLink Support Oracle XDB XMLType columns using their DirectToXMLTypeMapping XMLTypes can be mapped either as String or as an XML DOM Document Query extensions are provided for XPath queries within Expression queries EclipseLink also includes a JAXB implementation for object XML mapping 41 7 Filters Some times it is desirable to filter some of the contents of a table from all queries This is normally because the table is shared either by multiple types applications tenants or districts and the JPA application is only interested in a subset of the rows It may also be that the table includes historical or archive rows that should be ignored by the JPA application JPA does not provide any specific support for filtering data but there are some options available Inheritance can be used to include a type check on the rows for a class For example if you h
300. reate your own indexes through native queries 29 6 1 Example of column annotations Entity public class Employee Id Column name ID private long id CColumn name SSN unique true optional false private long ssn Column name F_NAME length 100 private String firstName Column name L_NAME length 200 private String lastName Column name SALARY scale 10 precision 2 private BigDecimal salary CColumn name S_TIME columnDefinition TIMESTAMPTZ private Calendar startTime CColumn name E_TIME columnDefinition TIMESTAMPTZ private Calendar endTime 29 6 2 Example of column XML lt entity name Employee class org acme Employee access FIELD gt lt attributes gt lt id name id gt lt column name ID gt lt id gt lt basic name ssn gt 11 https java sun com javaee 5 docs api javax persistence Column html 120 Insertable Updatable Read Only Fields Returning lt column name SSN unique true optional false gt lt basic gt lt basic name firstName gt lt column name F_NAME length 100 gt lt basic gt lt basic name lastName gt lt column name L_NAME length 200 gt lt basic gt lt basic name startTime gt lt column name S_TIME columnDefinition TIMESTAMPTZ gt lt basic gt lt basic name endTime gt lt column name E_TIME columnDefinition TIMESTAMPTZ gt lt basic gt lt attributes gt lt entity gt If using BigDec
301. red by JBoss acquired by Red Hat TopLink acquired by Oracle and Kodo JDO acquired by BEA acquired by Oracle Other products that have added support for JPA include Cocobase owned by Thought Inc and JPOX EJB JPA Spec e JPA ORM XML Schema e JPA Persistence XML Schema e JPA JavaDoc JPQL BNF What is JPA What is JPA 6 Chapter 12 on page 27 7 http jcp org about Java communityprocess final jsr220 index html 8 http java sun com xml ns persistence orm_1_0 xsd 9 http java sun com xml ns persistence persistence_1_0 xsd 10 https java sun com javaee 5 docs api javax persistence package summary html 11 Chapter 45 8 on page 232 12 http en wikibooks org wiki Category 3AJava 20Persistence 2FWhat 20is 20Java 20persistence 13 http en wikibooks org wiki Category 3AJava 20Persistence 12 6 What is new in JPA 2 0 The JPA 2 0 specification adds several enhancements to the JPA 1 0 specification including Extended Map support Support for maintaining a key column for a Basic Embeddable or Entity key value in any collection relationship using a Map Derived Identifiers Nested embedding New collection mappings Support for collections of Basic or Embeddable types Undirectional OneToMany Ordered List mappings Support for maintaining an index column in any collection relationship using a List Orphan removal Automatic deletion of objects removed from relationships Pessimistic Lo
302. rg 2001 XMLSchema instance xsi schemaLocation http java sun com xml ns persistence persistence_2_0 xsd version 2 0 gt lt persistence unit name acme transaction type RESOURCE_LOCAL gt lt EclipseLink gt lt provider gt org eclipse persistence jpa PersistenceProvider lt provider gt lt Hibernate gt 210 the Java Enterprise Edition lt provider gt org hibernate ejb HibernatePersistence lt provider gt lt TopLink Essentials gt lt provider gt oracle toplink essentials PersistenceProvider lt provider gt lt Apache OpenJPA gt lt provide r gt org apache openjpa persistence PersistenceProviderImpl lt provider gt lt DataNucleus gt lt provider gt org datanucleus jpa PersistenceProviderImpl lt provider gt lt exclude unlisted classes gt false lt exclude unlisted classes gt lt properties gt lt property name javax persistence jdbc driver value org acme db Driver gt lt property name javax persistence jdbc url value jdbc acmedb localhost acme gt lt property name javax persistence jdbc user value wile gt lt property name javax persistence jdbc password value elenberry gt lt properties gt lt persistence unit gt lt persistence gt 43 1 3 Example of accessing an EntityManager from an Entity ManagerFactory EntityManagerFactory factory Persistence createEntityManagerFactory acme EntityMana
303. rimaryKeyJoinColumn name PROJECTID referencedColumnName ID the same goes here if this JPA model doesn t create a table for the PROJ_EMP entity please comment out the OPrimaryKeyJoinColumn and use the ff JoinColumn name projectId updatable false insertable false or JoinColumn name projectId updatable false insertable false referencedColumnName id private Project project public class ProjectAssociationId implements Serializable private long employeeld private long projectld public int hashCode return int employeeId projectId public boolean equals Object object if object instanceof ProjectAssociationld ProjectAssociationld otherId ProjectAssociationId object return otherld employeeld this employeeld amp amp otherId projectId this projectld return false H e Ifthe given examples won t suit your expectations try the solution indicated in this link http giannigar wordpress com 2009 09 04 mapping a many to many join table with extra col ManyToMany ManyToMany 2 http en wikibooks org wiki Category 3AJava 20Persistence 3 http en wikibooks org wiki Category 3AJava 20Persistence 2FMapping 185 40 ElementCollection a Emplo yee id long e firstName String z lastName String iana type String salary BigDecimal 1 number String areaCode String Fiss LOYEE EMP_ID NUMBER F_NAME
304. ring name Entity Table name LARGEPROJECT AttributeOverride name name column Column name PROJECT_NAME public class LargeProject extends Project private BigDecimal budget Entity Table SMALLPROJECT public class SmallProject extends Project 24 2 3 Example mapped superclass XML lt mapped superclass class org acme Project access FIELD gt lt attributes gt lt id name id gt lt basic name name gt lt column name NAME gt lt basic gt 1 https java sun com javaee 5 docs api javax persistence MappedSuperclass html 85 Advanced lt attributes gt lt mapped superclass gt lt entity name LargeProject class org acme LargeProject access FIELD gt lt table name LARGEPROJECT gt lt attribute override gt lt column name NAME gt lt attribute override gt lt entity gt lt entity name SmallProject class org acme SmallProject access FIELD gt lt table name SMALLPROJECT gt lt entity gt 24 2 4 Common Problems Cannot query persist or have relationships The main disadvantage of mapped superclasses is that they cannot be queried or persisted You also cannot have a relationship to a mapped superclass If you require any of these then you must use another inheritance model such as table per class which is virtually identical to a mapped superclass except it may not have these limitations Another alternative is to change your mod
305. rivate long id OneToMany orphanRemoval true cascade CascadeType ALL private List lt PhoneNumbers gt phones 13 https java sun com javaee 6 docs api javax persistence OneToMany html 14 https java sun com javaee 6 docs api javax persistence OneToMany html 130 Target Entity 30 3 2 Example of an orphan removal one to many relationship XML lt entity name Employee class org acme Employee access FIELD gt lt attributes gt lt id name id gt lt one to many name phones orphan removal true gt lt cascade gt lt cascade all gt lt cascade gt lt one to many gt lt attributes gt lt entity gt 30 4 Target Entity Relationship mappings have a targetEntity attribute that allows the reference class target of the relationship to be specified This is normally not required to be set as it is defaulted from the field type get method return type or collection s generic type This can also be used if your field uses a public interface type for example field is interface Address but the mapping needs to be to implementation class AddressImpl Another usage is if your field is a superclass type but you want to map the relationship to a subclass 30 4 1 Example of a target entity relationship annotations Entity public class Employee eId private long id COneToMany targetEntity Phone class JoinColumn name OWNER_ID private List phones 30 4 2 Example of a target entity relatio
306. rt mapping these types of relationships as it only supports mappings defined by foreign keys not based on other columns constant values or functions Some JPA providers may support this Workarounds include mapping the foreign key part of the relationship then filtering the results in your get set methods of your object You could also query for the results instead of defining a relationship TopLink EclipseLink Support filtering and complex relationships through several mechanisms You can use a DescriptorCustomizer to define a selectionCriteria on any mapping using the Expression criteria API This allows for any condition to be applied including constants functions or complex joins You can also use a DescriptorCustomizer to define the SQL or define a StoredProcedureCall for the mapping s selectionQuery 31 6 Variable and Heterogeneous Relationships It is sometimes desirable to define a relationship where the type of the relationship can be one of several unrelated heterogeneous values This could either be a OneToOne Many ToOne OneToMany or Many ToMany relationship The related values may share a common interface or may share nothing in common other than subclassing Object It is also possible to conceive of a relationship that could also be any Basic value or even an Embeddable 20 Chapter 11 on page 25 21 Chapter 10 on page 23 99 http java persistence performance blogspot com 2010 08 batch fetching optimizing object
307. s are always persisted merged removed with their parent ElementCollection still can use a fetch type and defaults to LAZY the same as other collection mappings 189 ElementCollection 40 2 1 Example of an ElementCollection relationship to a basic value database EMPLOYEE table EMP_ID F_NAME L_ NAME SALARY 1 Bob Way 50000 2 Joe Smith 35000 PHONE table OWNER_ID PHONE_NUMBER 1 613 792 0001 1 613 494 1234 2 416 892 0005 40 2 2 Example of a ElementCollection relationship to a basic value annotations Entity public class Employee Id Column name EMP_ID private long id ElementCollection CollectionTable name PHONE joinColumns JoinColumn name OWNER_ID Column name PHONE_NUMBER private List lt String gt phones 40 2 3 Example of a ElementCollection relationship to a basic value XML lt entity name Employee class org acme Employee access FIELD gt lt attributes gt lt id name id gt lt column name EMP_ID gt lt id gt lt element collection name phones gt lt column name PHONE_NUMBER gt lt collection table name PHONE gt lt join column name OWNER_ID gt lt collection table gt lt element collection gt lt attributes gt lt entity gt 190 See Also 40 3 See Also e Relationships e Lazy Fetching e Target Entity e Collections e Maps e Join Fetching e Batch Reading e Common Problems e OneToMany ManyToMany e E
308. s are desired then a table sequence can be used By setting the allocationSize of the sequence to 1 and ensuring the sequence ids are allocated in the same transaction of the insert you can guarantee sequence ids without gaps but generally it is much better to live with the gaps and have good performance 23 3 1 Running Out of Numbers One paranoid delusional fear that programmers frequently have is running out of sequence numbers Since most sequence strategies just keep incrementing a number it is unavoidable that you will eventually run out However as long a large enough numeric precision is used to store the sequence id this is not an issue For example if you stored your id in a NUMBER 5 column this would allow 99 999 different ids which on most systems would eventually run out However if you store your id in a NUMBER 10 column which is more typical this would store 9 999 999 999 ids or one id each second for about 300 years longer than most databases exist But perhaps your system will process a lot of data and hopefully be around a very long time If you store your id in a NUMBER 20 this would be 99 999 999 999 999 999 999 ids or one id each millisecond for about 3 000 000 000 years which is pretty safe 73 Advanced But you also need to store this id in Java If you store the id in a Java int this would be a 32 bit number which is 4 294 967 296 different ids well actually 2 147 483 648 positive ids or one id eac
309. s assumed to be in the local time zone and is stored and retrieved from the database with that assumption If you then read that same Calendar on another computer in another time zone the question is if you will have the same Calendar or will you have the Calendar of what the original time would have been in the new time zone It depends on if the Calendar is stored as the GMT time or the local time and if the time zone was stored in the database Some databases support time zones but most database types do not store the time zone Oracle has two special types for timestamps with time zones TIMESTAMPTZ time zone is stored and TIMESTAMPLTZ local time zone is used Some JPA providers may have extended support for storing Calendar objects and time zones 116 Enums TopLink EclipseLink Support the Oracle TIMESTAMPTZ and TIMESTAMPLTZ types using the TypeConverter annotation and XML Forum Posts e Investigation of storing timezones in MySQL 29 2 Enums Java Enums are typically used as constants in an object model For example an Employee may have a gender of enum type Gender MALE FEMALE By default in JPA an attribute of type Enum will be stored as a Basic to the database using the integer Enum values as codes i e 0 1 JPA also defines an Enumerated annotation and lt enumerated gt element on a lt basic gt to define an Enum attribute This can be used to store the Enum as the STRING value of its name
310. s have had various runtime models The most common model is to have a runtime API a runtime API typically will define API for connecting to a data source querying and transactions 207 43 Entity Manager JPA provides a runtime API defined by the javax persistence package The main runtime class is the EntityManager class The EntityManager provides API for creating queries accessing transactions and finding persisting merging and deleting objects The JPA API can be used in any Java environment including JSE and JEE An EntityManager can be created through an EntityManagerFactory or can be injected into an instance variable in an EJB SessionBean or can be looked up in JNDI in a JEE server JPA is used differently in Java Standard Edition JSE versus Java Enterprise Edition JEE 43 1 Java Standard Edition In JSE an EntityManager is accessed from the JPA Persistence class through the createEntityManagerFactory API The persistent unit name is passed to the createEntityManagerFactory this is the name given in the persistence unit s persistence xml file All JSE JPA applications must define a persistence xml file The file defines the persistence unit including the name classes orm files datasource vendor specific properties JPA 1 0 does not define a standard way of specifying how to connect to the database in JSE Each JPA provider defines their own persistence properties for setting the JDBC driver manager class URL
311. s in a stateful SessionBean or an http session This means the initial query make take a while but paging will be fast Some JPA providers also support the caching of query results so you can cache the results in your JPA providers cache and just re execute the query to obtain the cached results If the query result is quite large then another solution may be required JPA provides the Query API setFirstResult setMaxResults to allow paging through a large query result The maxResults can also be used as a safeguard to avoid letting users execute queries that return too many objects How these query properties are implemented depends on the JPA provider and database JDBC allows the maxResults to be set and most JDBC drivers support this so it will normally work for most JPA providers and most databases Support for firstResult can be less guaranteed to be efficient as it normally requires database specific SQL There is no al https java sun com javaee 5 docs api javax persistence FlushModeType html https java sun com javaee 5 docs api javax persistence Query html t setFlushMode javax persistence FlushModeType https java sun com javaee 5 docs api javax persistence EntityManager html setFlushMode javax persistence FlushModeType 8 https java sun com javaee 5 docs api javax persistence EntityManager htmlitflush Chapter 11 on page 25 10 Chapter 10 on page 23 11 https java sun com javaee 5 docs api javax persisten
312. s primary key If the OneToMany uses a foreign key in the 1 Chapter 37 1 2 on page 178 171 OneToMany target object s table JPA requires that the relationship be bi directional inverse ManyToOne relationship must be defined in the target object and the source object must use the mappedBy attribute to define the mapping In JPA a OneToMany relationship is defined through the OneToMany annotation or the lt one to many gt element 36 0 1 Example of a OneToMany relationship database EMPLOYEE table EMP_ID FIRSTNAME LASTNAME SALARY MANAGER_ID 1 Bob Way 50000 2 2 Sarah Smith 75000 null PHONE table ID TYPE AREA CODE P_ NUMBER OWNER _ID 1 home 613 792 0000 1 2 work 613 896 1234 1 3 work 416 123 4444 2 36 0 2 Example of a OneToMany relationship and inverse ManyToOne annotations Entity public class Employee Old Column name EMP_ID private long id COneToMany mappedBy owner private List lt Phone gt phones OEntity public class Phone Old private long id ManyToOne fetch FetchType LAZY JoinColumn name OWNER_ID private Employee owner 2 https java sun com javaee 5 docs api javax persistence OneToMany html 172 Target Foreign Keys Primary Key Join Columns Cascade Primary Keys 36 0 3 Example of a OneToMany relationship and inverse Many ToOne XML lt entity name Employee class org acme Employee access FIELD gt lt attributes gt lt id name id gt lt o
313. s the row the JPA writes to the source table if the foreign key is in the target table JPA has no easy way to write this field There are other ways around this problem however In JPA the JoinColumn defines an insertable and updatable attribute these can be used to instruct the JPA provider that the foreign key is actually in the target object s table With these enabled JPA will not write anything to the source table most JPA providers will also infer that the foreign key constraint is in the target table to preserve referential integrity on insertion JPA also defines the PrimaryKeyJoinColumn that can be used to define the same thing You still must map the foreign key in the target object in some fashion though but could just use a Basic mapping to do this Some JPA providers may support an option for a unidirectional OneToOne mapping for target foreign keys Target foreign keys can be tricky to understand so you might want to read this section twice They can get even more complex though If you have a data model that cascades primary keys then you can end up with a single OneToOne that has both a logical foreign key but has some fields in it that are logically target foreign keys For example consider Company Department Employee Company s id is COM_ID Department s id is a composite primary key of COM_ID and DEPT_ID and Employee s id is a composite primary key of COM_ID DEP_ID and EMP_ID So for an Employee its relationship to c
314. saction commit fails the transaction is automatically rolled back and the persistence context cleared and all managed objects detached Not only is there no way to handle a commit failure but if any error occurs in an query before the commit the transaction will be marked for rollback so there is no real way to handle any error This is because any query could potentially change the state of the database so JPA does not know if the database is in an invalid or inconsistent state so must rollback the transaction As well if the commit fails the state of the objects registered in the persistence context may also be inconsistent such as partially committed objects having their optimistic lock versions incremented so the persistence context is cleared to avoid further errors Some JPA providers may provide extended API to allow handling commit failures or handling errors on queries There are some methods to generically handle commit failures and other errors Error handling in general is normally easier when using RESOURCE_LOCAL transactions and not when using JTA transactions One method of error handling is to call merge for each managed object after the commit fails into a new EntityManager then try to commit the new EntityManager One issue may be that any ids that were assigned or optimistic lock versions that were assigned or incremented may need to be reset Also if the original EntityManager was EXTENDED any objects that were in u
315. se for Oracle it is CREATE SEQUENCE EMP_SEQ INCREMENT BY 100 START WITH 100 7 https java sun com javaee 5 docs api javax persistence SequenceGenerator html 60 Sequence Strategies Invalid duplicate or negative sequence numbers This can occur if your sequence object s INCREMENT does not match your allocationSize This results in the JPA provider thinking it got back more sequences than it really did and ends up duplicating values or with negative numbers This can also occur on some JPA providers if your sequence object s STARTS WITH is 0 instead of a value equal or greater to the allocationSize 22 1 3 Identity sequencing Identity sequencing uses special IDENTITY columns in the database to allow the database to automatically assign an id to the object when its row is inserted Identity columns are supported in many databases such as MySQL DB2 SQL Server Sybase and PostgreSQL Oracle does not support IDENTITY columns but its is possible to simulate them using sequence objects and triggers Although identity sequencing seems like the easiest method to assign an id they have several issues One is that since the id is not assigned by the database until the row is inserted the id cannot be obtained in the object until after commit or after a flush call Identity sequencing also does not allow for sequence preallocation so can require a select for each object that is inserted potentially causing a major performance proble
316. se of http www 7 zip org The ATEX source itself was generated by a program written by Dirk H nniger which is freely available under an open source license from http de wikibooks org wiki Benutzer Dirk_Huenniger wb2paf This distribution also contains a configured version of the pdflatex compiler with all necessary packages and fonts needed to compile the ATEX source included in this PDF file Contents 10 11 12 13 14 15 16 17 18 19 Preface What is Java persistence What is Java 3 1 Google Trends 2 4222 0 At tie 3 2 Seeralso 0 0 0 000200 aa i a a What is a database What is JPA What is new in JPA 2 0 Other Persistence Specs Why use JPA or ORM Persistence Products 9 1 Existing Persistence Products EclipseLink TopLink Hibernate TopLink Essentials Kodo Open JPA Ebean LOA Index ok ore ee a tees ty Aah i Pe A Mapping Mapping 18 1 Access Type certo oe a eg ae G 18 2 Common Problems Tables 11 13 15 17 19 19 23 25 27 29 31 33 35 35 37 39 42 43 45 III Contents 20 Advanced 47 20 1 Multiple tables r es G00 aaa 2 8er Br a ala a 47 20 2 Multiple tables with foreign keys o e 49 20 3 Multiple table joins e e 50 20 4 Multiple table outer joins 2 2 22 on o o 51 20 5 Tables with special characters and mixed case 52 20 6
317. se would still become detached and need to be reset Another more involved method to error handling is to always work with a non transactional EntityManager When it s time to commit a new EntityManager is created the non transactional objects are merged into it and the new EntityManager is committed If the commit fails only the state of the new EntityManager may be inconsistent the original EntityManager will be unaffected This can allow the problem to be corrected and the EntityManager re merged into another new EntityManager If the commit is successful any commit changes can be merged back into the original EntityManager which can then continue to be used as normal This solution requires a fair bit of overhead so should only be used if error handling is really required and the JPA provider provides no alternatives 50 3 Nested Transactions JPA and JTA do not support nested transactions A nested transaction is used to provide a transactional guarantee for a subset of operations performed within the scope of a larger transaction Doing this allows you to commit and abort the subset of operations independently of the larger transaction The rules to the usage of a nested transaction are as follows 258 Transaction Isolation While the nested child transaction is active the parent transaction may not perform any operations other than to commit or abort or to create more child transactions Committing a nested transact
318. several strategies for generating unique ids Some strategies are database agnostic and others make use of built in databases support 1 https java sun com javaee 5 docs api javax persistence GeneratedValue html 57 Sequencing JPA provides support for several strategies for id generation defined through the GenerationType enum values TABLE SEQUENCE and IDENTITY The choice of which sequence strategy to use is important as it affects performance concur rency and portability 22 1 1 Table sequencing Table sequencing uses a table in the database to generate unique ids The table has two columns one stores the name of the sequence the other stores the last id value that was assigned There is a row in the sequence table for each sequence object Each time a new id is required the row for that sequence is incremented and the new id value is passed back to the application to be assigned to an object This is just one example of a sequence table schema for other table sequencing schemas see Customizing Table sequencing is the most portable solution because it just uses a regular database table so unlike sequence and identity can be used on any database Table sequencing also provides good performance because it allows for sequence pre allocation which is extremely important to insert performance but can have potential concurrency issues In JPA the TableGenerator annotation or lt table generator gt element is used
319. sired strategy is somewhere in between having joined tables in some subclasses and not in others Unfortunately JPA does not directly support this One workaround is to map your inheritance hierarchy as single table but them add the additional tables in the subclasses either through defining a Table or SecondaryTable in each subclass as required Depending on your JPA provider this may work don t forget to sacrifice the chicken If it does not work then you may need to use a JPA provider specific solution if one exists for your provider otherwise live within the constraints of having either a single table or one per subclass You could also change your inheritance hierarchy so it matches your data model so if the subclass does not have a table then collapse its class into its superclass No class discriminator column If you are mapping to an existing database schema your table may not have a class discriminator column Some JPA providers do not require a class discriminator when using a joined inheritance strategy so this may be one solution Otherwise you need some way to determine the class for a row Sometimes the inherited value can be computed from several columns or there is an discriminator but not a one to one mapping from value to class Some JPA providers provide extended support for this Another option is to create a database view that manufactures the discriminator column and then map your hierarchy to this view instead of th
320. sistence context transaction When the transaction is committed or if the persistence context is flushed then the object will be updated in the database Normally merge is not required although it is frequently misused To update an object you simply need to read it then change its state through its set methods then commit the transaction The EntityManager will figure out everything that has been changed and update the database merge is only required when you have a detached copy of a persistence object A detached object is one that was read through a different EntityManager or in a different transaction in a JEE managed EntityManager or one that was cloned or serialized A common case is a stateless SessionBean where the object is read in one transaction then updated in another transaction Since the update is processed in a different transaction with a different EntityManager it must first be merged The merge operation will look up find the managed object for the detached object and copy each of the detached objects attributes that changed into the managed object as well as cascading any related objects marked as cascade merge The merge operation can only be called within a transaction an exception will be thrown outside of a transaction The merge operation is not in place in that the object being merged will never become part of the persistence context Any further changes must be made to the managed object returned by the merg
321. ss query setParameter 1 Ottawa List lt Employee gt employees query getResultList 45 6 1 Result Set Mapping When a native SQL query returns objects the SQL must ensure it returns the correct data to build the resultClass using the correct column names as specified in the mappings If the SQL is more complex and returns different column names or returns data for multiple objects then a SqlResultSetMapping must be used SqlResultSetMapping is a fairly complex annotation containing an array of EntityResult and ColumnResult This allows multiple Entity objects in combina tion with raw data to be returned The EntityResult contains an array of CFieldResult which can be used to map the alias name used in the SQL to the column name required by the mapping This is required if you need to return two different instances of the same class or if the SQL needs to alias the columns differently for some reason Note that in the FieldResult the name is the name of the attribute in the object not the column name in 20 https java sun com javaee 5 docs api javax persistence SqlResultSetMapping html 21 https java sun com javaee 5 docs api javax persistence EntityResult html 22 https java sun com javaee 5 docs api javax persistence ColumnResult html 23 https java sun com javaee 5 docs api javax persistence FieldResult html 230 Stored Procedures the mapping This seems odd because this would make mappin
322. st in JPA to enable optimistic locking always as it is fairly simple to do as least in concept but what does occur on a conflict without any form of locking Essentially it is last in wins so if two users edit the same object at the same time the last one to commit will have their changes reflected in the database This is true at least for users editing the same fields but if two users edit different fields in the same object it depends on the JPA implementation Some JPA providers only update exactly the fields that were changed where as other update all fields in the object So in one case the first user s changes would be overridden but in the second they would not 27 2 7 Pessimistic Locking Pessimistic locking means acquiring a lock on the object before you begin to edit the object to ensure that no other users are editing the object Pessimistic locking is typically implemented through using database row locks such as through the SELECT FOR 107 Locking UPDATE SQL syntax The data is read and locked the changes are made and the transaction is committed releasing the locks JPA 1 0 did not support pessimistic locking but some JPA 1 0 providers do JPA 2 0 supports pessimistic locking It is also possible to use JPA native SQL queries to issue SELECT FOR UPDATE and use pessimistic locking When using pessimistic locking you must ensure that the object is refreshed when it is locked locking a potentially stale obj
323. stamp class supports nanoseconds On many databases the TIMESTAMP type supports milliseconds On Oracle prior to Oracle 9 there was only a DATE type which was a date and a time but had no milliseconds Oracle 9 added a TIMESTAMP type that has milliseconds and nanoseconds and now treats the old DATE type as only a date so be careful using it as a timestamp MySQL has DATE TIME and DATETIME types DB2 has a DATE TIME and TIMESTAMP types the TIMESTAMP supports microseconds Sybase and SQL Server just have a DATETIME type which has milliseconds but at least on some versions has precision issues it seems to store an estimate of the milliseconds not the exact value If you use timestamp version locking you need to be very careful of your milliseconds precision Ensure your database supports milliseconds precisely otherwise you may have issues especially if the value is assigned in Java then differs what gets stored on the database which will cause the next update to fail for the same object In general 1 would not recommend using a timestamp and as primary key or for version locking There are too many database compatibility issues as well as the obvious issue of not supporting two operations in the same millisecond 29 1 4 Timezones Temporals become a lot more complex when you start to consider time zones international ization eras locals day light savings time etc In Java only Calendar supports time zones Normally a Calendar i
324. stantiate a large collection when adding a child object One solution is to not map the bi directional relationship and instead query for it as required 135 Relationships Also some JPA providers optimize their lazy collection objects to handle this case so you can still add to the collection without instantiating it Poor performance excessive queries This most common issue leading to poor performance is the usage of EAGER relationships This requires the related objects to be read when the source objects are read So for example reading the president of the company with EAGER managedEmployees will cause every Employee in the company to be read The solution is to always make all relationships LAZY By default OneToMany and ManyToMany are LAZY but OneToOne and ManyToOne are not so make sure you configure them to be See Lazy Fetching Sometimes you have LAZY configured but it does not work see Lazy is not working Another common problems is the n 1 issue For example consider that you read all Employee objects then access their Address Since each Address is accessed separately this will cause n 1 queries which can be a major performance problem This can be solved through Join Fetching and Batch Reading Lazy is not working Lazy OneToOne and ManyToOne relationships typically require some form of weaving or byte code generation Normally when running in JSE an agent option is required to allow the byte code weaving so e
325. stored as XML documents CmornNIoaw kwnr Chapter 39 1 2 on page 185 Chapter 31 2 1 on page 141 Chapter 30 5 4 on page 133 Chapter 37 1 on page 177 Chapter 31 6 on page 148 Chapter 31 6 on page 148 Chapter 31 7 on page 149 Chapter 41 5 on page 199 Chapter 41 6 on page 200 139 Advanced 31 2 Maps Java defines the Map interface to represent collections whose values are indexed on a key There are several Map implementations the most common is HashMap but also Hashtable and TreeMap JPA allows a Map to be used for any collection mapping including OneToMany ManyToMany and ElementCollection JPA requires that the Map interface be used as the attribute type although some JPA providers may also support using Map implementations In JPA 1 0 the map key must be a mapped attribute of the collection values The MapKey annotation or lt map key gt XML element is used to define a map relationship If the MapKey is not specified it defaults to the target object s Id Example of a map key relationship annotation Entity public class Employee Id private long id OneToMany mappedBy owner MapKey name type private Map lt String PhoneNumber gt phoneNumbers Br Entity public class PhoneNumber Id private long id Basic private String type Either home work or fax ManyToOne private Employee owner Example of a map key relationship XML lt entity name Employee class or
326. t must enclose the copies in covers that carry clearly and legibly all these Cover Texts Front Cover Texts on the front cover and Back Cover Texts on the back cover Both covers must also clearly and legibly identify you as the publisher of these copies The front cover must present the full title with all words of the title equally prominent and visible You may add other material on the covers in addition Copying with changes limited to the covers as long as they preserve the title of the Doc ument and satisfy these conditions can be treated as verbatim copying in other respects If the required texts for either cover are too volu minous to fit legibly you should put the first ones listed as many as fit reasonably on the actual cover and continue the rest onto adjacent pages If you publish or distribute Opaque copies of the Document numbering more than 100 you must ei ther include a machine readable Transparent copy along with each Opaque copy or state in or with each Opaque copy a computer network location from which the general network using public has access to download using public standard network protocols a complete Transparent copy of the Doc ument free of added material If you use the lat ter option you must take reasonably prudent steps when you begin distribution of Opaque copies in quantity to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year
327. t database transaction isolation all I need Possibly but most likely not Most databases default to read committed transaction isolation This means that you will never see uncommitted data but this does not prevent concurrent transactions from overwriting the same data Transaction A reads row x Transaction B reads row x Transaction A writes row x Transaction B writes row x and overwrites A s changes 5 Both commit successfully Rw NR This is the case with read committed but with serializable this conflict would not occur With serializable either Transaction B would lock on the select for B and wait perhaps a long time until Transaction A commits In some databases Transaction A may not wait but would fail on commit However even with serializable isolation the typical web application would still have a conflict This is because each server request operates in a different database transaction The web client reads the data in one transaction then updates it in another transaction So optimistic locking is really the only viable locking option for the typical web application Even if the read and write occurs in the same transaction serializable is normally not the solution because of concurrency implications and deadlock potential See Serializable Transaction Isolation What happens if I merge an object that was deleted by another user What should happen is the merge should trigger an OptimisticLockException
328. t in the database TopLink EclipseLink Support returning insert and update values back into the object using the ReturnInsert and ReturnUpdate annotations and XML elements 12 Chapter 11 on page 25 13 Chapter 10 on page 23 121 Advanced 29 8 Conversion A common problem in storing values to the database is that the value desired in Java differs from the value used in the database Common examples include using a boolean in Java and a 0 1 ora T F in the database Other examples are using a String in Java and a DATE in the database One way to accomplish this is to translate the data through property get set methods Entity public class Employee private boolean isActive Transient public boolean getIsActive return isActive public void setIsActive boolean isActive this isActive isActive Basic private String getIsActiveValue if isActive return T else return F F private void setIsActiveValue String isActive this isActive T equals isActive Also for translating date times see Temporals As well some JPA providers have support for this TopLink EclipseLink Support translation using the Convert CConverter 0bjectTypeConverter and TypeConverter annotations and XML 29 9 Custom Types JPA defines support for most common database types however some databases and JDBC driver have additional types that may require additiona
329. t mean there was no conflict the first user could have deleted a method that the other user added 101 Locking a method to reference and several other possible issues that cause the typically nightly build to break every so often Paranoid Delusionment Locking can prevent most concurrency issues but be careful of going overboard in over analyzing to death every possible hypothetical occurrence Sometimes in an concurrent application or any software application bad stuff can happen Users are pretty used to this by now and I don t think anyone out there thinks computers are perfect A good example is a source code control system Allowing users to overwrite each other changes is a bad thing so most systems avoid this through versioning the source files If a user submits changes to a file that originated from a older version than the current version the source code control system will raise a conflict and make the user merge the two files This is essentially optimistic locking But what if one user removes or renames a method in one file then another user adds a new method or call in another file to that old method No source code control system that I know of will detect this issue it is a conflict and will cause the build to break The solution to this is to start locking or checking the lock on every file in the system or at least every possible related file Similar to using optimistic read locking on every possible related o
330. t the inverse query always exists 30 0 1 JPA Relationship Types e OneToOne A unique reference from one object to another inverse of a OneToOne e ManyToOne A reference from one object to another inverse of a OneToMany e OneToMany A Collection or Map of objects inverse of a ManyToOne e ManyToMany A Collection or Map of objects inverse of a ManyToMany e Embedded A reference to a object that shares the same table of the parent e ElementCollection JPA 2 0 a Collection or Map of Basic or Embedable objects stored in a separate table This covers the majority of types of relationships that exist in most object models Each type of relationship also covers multiple different implementations such as OneToMany Chapter 31 7 on page 150 Chapter 33 2 2 on page 164 Chapter 35 1 on page 169 Chapter 37 1 2 on page 178 Chapter 24 2 4 on page 87 Chapter 39 1 2 on page 185 oOokWNnr 125 Relationships allowing either a join table or foreign key in the target and collection mappings also allow Collection types and Map types There are also other possible complex relationship types see Advanced Relationships 30 1 Lazy Fetching The cost of retrieving and building an object s relationships far exceeds the cost of selecting the object This is especially true for relationships such as manager or managedEmployees such that if any employee were selected it would trigger the loading of every employee through
331. t when you call persist merge or remove the database DML INSERT UPDATE DELETE is not executed until commit or until a flush is triggered Flush has several usages e Flush changes before a query execution to enable the query to return new objects and changes made in the persistence unit e Insert persisted objects to ensure their Ids are assigned and accessible to the application if using IDENTITY sequencing e Write all changes to the database to allow error handling of any database errors useful when using JTA or SessionBeans To flush and clear a batch for batch processing in a single transaction e Avoid constraint errors or reincarnate an object https java sun com javaee 5 docs api javax persistence EntityManager html getReference java lang Class 20java lang Object https java sun com javaee 5 docs api javax persistence EntityManager html flush ND 248 Clear Example flush public long createOrder Order order throws ACMEException EntityManager em getEntityManager em persist order try em flush catch PersistenceException exception throw new ACMEException exception return order getld 48 5 Clear The EntityManager clear operation can be used to clear the persistence context This will clear all objects read changed persisted or removed from the current EntityManager or transaction Changes that have already been written to the database through flush or
332. ta is important such as using the cache for read only queries but refreshing when entering a transaction to update an object For write mostly objects the best solution may be to disable the cache for those objects Caching provides no benefit to inserts and the cost of avoiding stale data on updates may mean there is no benefit to caching objects that are always updated Caching will add some overhead to writes as the cache must be updated having a large cache also affects garbage collection so if the cache is not providing any benefit it should be turned off to avoid this overhead This can depend on the complexity of the object though if the object has a lot of complex relationships and only part of the object is updated then caching may still be worth it Cache Coordination One solution to caching in a clustered environment is to use a messaging framework to coordinate the caches between the machines in the cluster JMS or JGroups can be used in combination with JPA or application events to broadcast messages to invalidate the caches on other machines when an update occurs Some JPA and cache providers support cache coordination in a clustered environment TopLink EclipseLink Support cache coordination in a clustered environ ment using JMS or RMI Cache coordination is configured through the Cache annotation or lt cache gt orm xml element and using the persistence unit property eclipselink cache coordination protocol D
333. tabase some databases even have this as the default It can also be set on the JDBC Connection or through native SQL but this is database specific and different databases have different levels of support The main issues with serializable transaction isolation are the same as using SELECT FOR UPDATE see above for the gory details in addition everything read is locked so you cannot decide to only lock certain objects at certain times but lock everything all the time This can be a major concurrency issue for transactions with common read only data and can lead to deadlocks How database implement serializable transaction isolation differs between databases Some databases such as Oracle can perform serializable transaction isolation in more of an optimistic sense than the typically pessimistic implementation Instead of each transaction requiring locks on all the data as it is read the row versions are not checked until the 27 https java sun com javaee 6 docs api javax persistence PessimisticLockScope html 109 Locking transaction is committed if any of the data changed an exception is thrown and the transaction is not allowed to commit Locking 78 28 http en wikibooks org wiki Category 3AJava 20Persistence 2FMapping 110 28 Basics A basic attribute is one where the attribute class is a simple type such as String Number Date or a primitive A basic attribute s value can map directly to the column value
334. tables As with all bi directional relationships it is your object model s and application s responsibility to maintain the relationship in both direction There is no magic in JPA if you add or remove to one side of the collection you must also add or remove from the other side see object corruption Technically the database will be updated correctly if you only add remove from the owning side of the relationship but then your object model will be out of synch which can cause issues 38 1 1 Example of an inverse ManyToMany relationship annotation Entity public class Project Id Column name PROJ_ID private long id ManyToMany mappedBy projects private List lt Employee gt employees 38 2 See Also e Relationships e Cascading e Lazy Fetching e Target Entity e Collections e Maps e Join Fetching e Batch Reading e Common Problems e OneToMany 3 4 Chapter 31 6 on page 148 5 Chapter 29 9 on page 123 6 Chapter 30 2 on page 129 7 Chapter 30 1 on page 126 8 Chapter 30 4 on page 131 9 Chapter 30 5 on page 132 10 Chapter 31 2 on page 140 11 Chapter 31 3 on page 145 12 Chapter 31 6 on page 148 13 Chapter 30 6 on page 135 14 Chapter 35 1 on page 169 181 Many ToMany 38 3 Common Problems Object not in collection after refresh If you have a bi directional ManyToMany relationship ensure that you add to both sides of the relationship See Object corruption Additio
335. te 1 http en wikipedia org wiki Hibernate20 28Java 29 2 http en wikibooks org wiki Category 3AJava 20Persistence 2FPersistence 20Products 3 http en wikibooks org wiki Category 3AJava 20Persistence 27 13 TopLink Essentials TopLink Essentials is an open source project from the Sun java net Glassfish community It is the EJB3 JPA 1 0 reference implementation and is the JPA provider for the Sun Glassfish vl application server TopLink Essentials was based on the TopLink product which Oracle contributed some of the source code from to create the TopLink Essentials project The original contribution was from TopLink s 10 1 3 code base only some of the TopLink product source code was contributed which did not include some key enterprise features The package names were changed and some of the code was moved around TopLink Essentials has been replaced by the EclipseLink project EclipseLink will be the JPA 2 0 reference implementation and be part of Sun Glassfish v3 TopLink Essentials Home e TopLink Essentials Forum e TopLink Essentials Wiki TopLink Essentials TopLink Essentials http en wikipedia org wiki TopLink Chapter 11 on page 25 http en wikipedia org wiki Dracle 20Corporation Chapter 10 on page 23 https glassfish dev java net javaee5 persistence index html http www nabble com java net glassfish persistence f13455 html http wiki glassfish java net Wiki jsp page TopLinkEssentials ht
336. te gt lt entity listener gt lt entity listeners gt lt persistence unit defaults gt http download oracle com javaee 6 api javax persistence ExcludeDefaultListeners html 195 Advanced Topics lt persistence unit metadata gt lt entity mappings gt 41 1 6 Events and Inheritance Entity listeners are inherited If a subclass does not wish to inherit a superclass En tity listener then it must define the ExcludeSuperclassListeners lt exclude superclass listeners gt XML element annotation or 41 1 7 Events and Embeddables JPA does not define any events for Embeddables Some JPA providers may allow defining events for Embeddable objects 41 1 8 Extended Events The JPA events are only defined for the Entity life cycle There are no EntityMangager events or system level events Some JPA providers may provide additional events TopLink EclipseLink Provide an extended event mechanism Additional Entity level events are defined through the DescriptorEventListener API A session level event mechanism is also provided through the SessionEventListener API The event objects also provide additional information including the database row and set of object changes 41 2 Views A database VIEW is a virtual view of a table or query Views are useful for hiding the complexity of a table set of tables or data set In JPA you can map to a VIEW the same as a table using the Table annotation You can t
337. te long id OneToOne fetch FetchType LAZY JoinColumn name ADDRESS_ID private Address address 32 0 2 Example of a OneToOne relationship XML lt entity name Employee class org acme Employee access FIELD gt lt attributes gt lt id name id gt lt column name EMP_ID gt lt id gt lt one to one name address fetch LAZY gt lt join column name ADDRESS_ID gt lt one to one gt lt attributes gt lt entity gt 32 1 Inverse Relationships Target Foreign Keys and Mapped By A typical object centric perspective of a OneToOne relationship has the data model mirror the object model in that the source object has a pointer to the target object so the database source table has a foreign key to the target table This is not how things always work out in the database though in fact many database developers would think having the foreign key in the target table to be logical as this enforces the uniqueness of the OneToOne relationship Personally I prefer the object perspective however you will most likely encounter both To start with consider a bi directional OneToOne relationship you do not require two foreign keys one in each table so a single foreign key in the owning side of the relationship is sufficient In JPA the inverse OneToOne must use the mappedBy attribute with some exceptions this makes the JPA provider use the foreign key and mapping information in the source mapping to define the target
338. the Id mapping in the child as insertable false updateable false and define the OneToOne or ManyToOne using a normal JoinColumn this will ensure the foreign key field is populated by the OneToOne or ManyToOne not the Basic Another option is to first persist the parent then call flush before persisting the child 62 Sequence Strategies Poor insert performance Identity sequencing does not support sequence preallocation so requires a select after each insert in some cases doubling the insert cost Consider using a sequence table or sequence object to allow sequence preallocation Lost latest free id MySQL bug 199 causes its autoincrement counter to be lost on restart So if the last entity is removed and the MySQL server restarted the same id will be re used and thus not be unique 8 http bugs mysql com bug php id 199 63 23 Advanced 23 1 Composite Primary Keys A composite primary key is one that is made up of several columns in the table A composite primary key can be used if no single column in the table is unique It is generally more efficient and simpler to have a one column primary key such as a generated sequence number but sometimes a composite primary key is desirable and unavoidable pa i e al y COMPANY_ID NUMBER le NAME VARCHAR 1 FK_COMPANY_ID FK_COMPANY_ID N f 7 51 ee COMPANY_ID NUMBER COMPANY_ID NUMBER DEP_ID NUMBER DEP_ID
339. the original object read are still the same when updating it This verifies that the object has not changed by another user in between the read and the write JPA supports using an optimistic locking version field that gets updated on each update The field can either be numeric or a timestamp value A numeric value is recommended as a numeric value is more precise portable performant and easier to deal with than a timestamp Chapter 27 1 on page 99 Chapter 27 2 7 on page 107 Chapter 27 2 1 on page 104 Chapter 27 1 1 on page 100 AUNE 99 Locking The CVersion annotation or lt version gt element is used to define the optimistic lock version field The annotation is defined on the version field or property for the object similar to an Id mapping The object must contain an attribute to store the version field The object s version attribute is automatically updated by the JPA provider and should not normally be modified by the application The one exception is if the application reads the object in one transaction sends the object to a client and updates merges the object in another transaction In this case the application must ensure that the original object version is used otherwise any changes in between the read and write will not be detected The EntityManager merge API will always merge the version so the application is only responsible for this if manually merging When a locking contention is detected an Optimis
340. the relationship hierarchy Obviously this is a bad thing and yet having relationships in objects is very desirable The solution to this issue is lazy fetching lazy loading Lazy fetching allows the fetching of a relationship to be deferred until it is accessed This is important not only to avoid the database access but also to avoid the cost of building the objects if they are not needed In JPA lazy fetching can be set on any relationship using the fetch attribute The fetch can be set to either LAZY or EAGER as defined in the FetchType enum The default fetch type is LAZY for all relationships except for OneToOne and ManyToOne but in general it is a good idea to make every relationship LAZY The EAGER default for OneToOne and ManyToOne is for implementation reasons more difficult to implement not because it is a good idea Technically in JPA LAZY is just a hint and a JPA provider is not required to support it however in reality all main JPA providers support it and they would be pretty useless if they did not 30 1 1 Example of a lazy one to one relationship annotations Entity public class Employee Id private long id OneToOne fetch FetchType LAZY JoinColumn name ADDR_ID private Address address 30 1 2 Example of a lazy one to one relationship XML lt entity name Employee class org acme Employee access FIELD gt lt attributes gt lt id name id gt lt one to one name address fetch LAZY gt
341. ticLockException will be thrown This could be wrapped insider a RollbackException or other exceptions if using JTA but it should be set as the cause of the exception The application can handle the exception but should normally report the error to the user and let them determine what to do Example of Version annotation Entity public abstract class Employee Id private long id Version private long version Example of Version XML lt entity name Employee class org acme Employee access FIELD gt lt attributes gt lt id name id gt lt version name version gt lt attributes gt lt entity gt 27 1 1 Common Locking Mistakes Questions and Problems Not sending version to client only locking on the server Probably the most common mistake in locking in general is locking the wrong section of code This is true no matter what form of locking is used whether it be optimistic or pessimistic The basic scenario is 5 https java sun com javaee 5 docs api javax persistence Version html 6 https java sun com javaee 5 docs api javax persistence OptimisticLockException html 100 Optimistic Locking 1 User requests some data the server reads the data from the database and sends it to the user in their client doesn t matter if the client is html rmi web service 2 The user edits the data in the client The user submits the data back to the server 4 The server begins a transaction re
342. tice for those products If such prob lems arise substantially in other domains we stand ready to extend this provision to those domains in future versions of the GPL as needed to protect the freedom of users Finally every program is threatened constantly by software patents States should not allow patents to restrict development and use of software on general purpose computers but in those that do we wish to avoid the special danger that patents applied to a free program could make it effectively proprietary To prevent this the GPL assures that patents cannot be used to render the program non free The precise terms and conditions for copying dis tribution and modification follow TERMS AND CONDITIONS 0 Definitions This License refers to version 3 of the GNU Gen eral Public License Copyright also means copyright like laws that ap ply to other kinds of works such as semiconductor masks The Program refers to any copyrightable work licensed under this License Each licensee is ad dressed as you Licensees and recipients may be individuals or organizations To modify a work means to copy from or adapt all or part of the work in a fashion requiring copy right permission other than the making of an exact copy The resulting work is called a modified ver sion of the earlier work or a work based on the earlier work A covered work means either the unmodif
343. tion of the contributor version For pur poses of this definition control includes the right to grant patent sublicenses in a manner consistent with the requirements of this License Each contributor grants you a non exclusive world wide royalty free patent license under the contrib utor s essential patent claims to make use sell of fer for sale import and otherwise run modify and propagate the contents of its contributor version In the following three paragraphs a patent li cense is any express agreement or commitment however denominated not to enforce a patent such as an express permission to practice a patent or covenant not to sue for patent infringement To grant such a patent license to a party means to make such an agreement or commitment not to en force a patent against the party If you convey a covered work knowingly relying on a patent license and the Corresponding Source of the work is not available for anyone to copy free of charge and under the terms of this License through a publicly available network server or other readily accessible means then you must either 1 cause the Corresponding Source to be so available or 2 arrange to deprive yourself of the benefit of the patent license for this particular work or 3 arrange in a manner consistent with the re quirements of this License to extend the patent license to downstream recipients Knowingly re lying means you hav
344. tion_variable collection_valued_association_field join_single_valued_association_path_expression identification_variable single_valued_association_field collection_member_declaration IN collection_valued_path_expression AS identification_variable single_valued_path_expression state_field_path_expression single_valued_association_path_expression state_field_path_expression identification_variable single_valued_association_path_expression state_field single_valued_association_path_expression identification_variable single_valued_association_field single_valued_association_field collection_valued_path_expression identification_variable t single_valued_association_field collection_valued_association_field state_field embedded_class_state_field simple_state_field 46 1 2 Select Clause SELECT employee id employee phones SELECT DISTINCT employee address city NEW com acme EmployeeInfo AVG employee salary MAX employee salary select_clause SELECT DISTINCT select_ expression select expression select_expression single_valued_path_expression aggregate_expression identification_variable OBJECT identification_variable constructor_expression constructor_expression NEW constructor_name constructor item constructor_ item constructor_item single_valued_path_expression aggregate_ expression 234 Select ageregate_ expression
345. tions_returning numerics aggregate_ expression string expression string primary subquery string_primary state_field_path_expression string literal input_parameter functions_ returning strings aggregate_expression datetime_expression datetime_primary subquery datetime_primary state_field_path_expression input_parameter functions_ returning datetime aggregate_expression boolean_expression boolean_primary subquery boolean_primary state_field_path_expression boolean_literal input_parameter enum_ expression enum_ primary subquery enum_ primary state_field_path_expression enum_literal input_ parameter entity_ expression single valued_association_path_expression simple_entity_ expression simple_entity_expression identification_variable input_ parameter 46 1 4 Functions LENGTH SUBSTRING UPPER CONCAT FOO bar 1 5 functions_returning_numerics LENGTH string_ primary LOCATE string_ primary string _primary simple_arithmetic_expression ABS simple_arithmetic_expression SQRT simple_arithmetic_expression MOD simple_arithmetic_expression simple_ arithmetic_expression SIZE collection_valued_path_ expression functions_returning_ datetime CURRENT_DATE CURRENT_TIME CURRENT _ TIMESTAMP functions_returning_strings CONCAT string primary string primary SUBSTRING string_primary simple arithmetic_expression si
346. tity An object id OID is something that uniquely identifies an object Within a VM this is typically the object s pointer In a relational database table a row is uniquely identified in its table by its primary key When persisting objects to a database you need a unique identifier for the objects this allows you to query the object define relationships to the object and update and delete the object In JPA the object id is defined through the Id annotation or lt id gt element and should correspond to the primary key of the object s table 21 0 4 Example id annotation Entity public class Employee Old private long id 21 0 5 Example id XML lt entity name Employee class org acme Employee access FIELD gt lt attributes gt lt id name id gt lt attributes gt lt entity gt Common Problems Strange behavior unique constraint violation You must never change the id of an object Doing so will cause errors or strange behavior depending on your JPA provider Also do not create two objects with the same id or try persisting an object with the same id as an existing object If you have an object that may be existing use the EntityManager merge API do not use persist for an existing object and avoid relating an un managed existing object to other managed objects 1 http en wikipedia org wiki Primary 20key 2 https java sun com javaee 5 docs api javax persistence Id html 55 Identity No pri
347. to define a sequence table The TableGenerator defines a pkColumnName for the column used to store the name of the sequence valueColumnName for the column used to store the last id allocated and pkColumnValue for the value to store in the name column normally the sequence name Example sequence table SEQUENCE_TABLE SEQ NAME SEQ COUNT EMP_ SEQ 123 PROJ_ SEQ 550 Example table generator annotation Entity public class Employee Id TableGenerator name TABLE_GEN table SEQUENCE_TABLE pkColumnName SEQ_NAME valueColumnName SEQ_COUNT pkColumnValue EMP_SEQ CGeneratedValue strategy GenerationType TABLE https java sun com javaee 5 docs api javax persistence GenerationType html Chapter 23 3 2 on page 74 Chapter 23 3 on page 73 https java sun com javaee 5 docs api javax persistence TableGenerator html oR W N 58 Sequence Strategies generator TABLE_GEN private long id Example table generator XML lt entity name Employee class org acme Employee access FIELD gt lt attributes gt lt id name id gt lt generated value strategy TABLE generator EMP_SEQ gt lt table generator name EMP_SEQ table SEQUENCE_TABLE pk column name SEQ_NAME value column name SEQ_COUNT pk column value EMP_SEQ gt lt id gt lt attributes gt lt entity gt Common Problems Error when allocating a sequence number Errors such as table not found invalid column can occur if you do
348. tp en wikibooks org wiki Category 3AJava 20Persistence 2FPersistence 20Products http en wikibooks org wiki Category 3AJava 20Persistence oo osusoutkrumHm 29 14 Kodo Kodo was originally developed as an Java Data Objects JDO implementation by SolarMetric BEA Systems acquired SolarMetric in 2005 where Kodo was expanded to be an implementation of both the JDO and JPA specifications In 2006 BEA donated a large part of the Kodo source code to the Apache Software Foundation under the name OpenJPA BEA and Kodo were acquired by Oracle Kodo development is now stopped and users are referred to EclipseLink Kodo Kodo 1 http www bea com kodo 2 http en wikibooks org wiki Category 3AJava 20Persistence 2FPersistence 20Products 3 http en wikibooks org wiki Category 3AJava 20Persistence 31 15 Open JPA OpenJPA is an Apache project for supporting the JPA specification Its source code was originally donated from part of BEA s Kodo product Open JPA Open JPA 1 http en wikipedia org wiki OpenJPA 2 http en wikibooks org wiki Category 3AJava 20Persistence 2FPersistence 20Products 3 http en wikibooks org wiki Category 3AJava 20Persistence 33 16 Ebean Ebean is a Java ORM based on the JPA specification The goal of Ebean is to provide mapping compatible with JPA while providing a simpler APT to use and learn 16 1 Index oP WN m Oo COND Why Ebean Example Model Quick Start
349. u to use a SortedSet or TreeSet for your collection type and maintain the correct ordering By default these require your target object to implement the Comparable interface or set a Comparator You can also use the Collections sort method to sort a List when required One option to sort in memory is to use property access and in your set and add methods call Collections sort Example of a collection order by annotation Entity public class Employee Id private long id OneToMany 0rderBy areaCode private List lt Phone gt phones Example of a collection order by XML lt entity name Employee class org acme Employee access FIELD gt lt attributes gt lt id name id gt lt one to many name phones gt lt order by gt areaCode lt order by gt lt one to many gt lt attributes gt lt entity gt 30 5 4 Order Column JPA 2 0 JPA 2 0 adds support for an OrderColumn n OrderColumn can be used to define an order List on any collection mapping It is defined through the OrderColumn annotation or lt order column gt XML element The OrderColumn is maintained by the mapping and should not be an attribute of the target object The table for the OrderColumn depends on the mapping For a OneToMany mapping it will be in the target object s table For a ManyToMany mapping or a OneToMany using a JoinTable it will be in the join table For an ElementCollection mapping it will be in the target table Exam
350. uage e Query By Example QBE e TopLink Expressions e Hibernate Criteria e Object Query Language OQL e Query DSL http en wikibooks org wiki Java 20Persistence 2FJPQL Chapter 45 8 on page 232 http en wikibooks org wiki Java 20Persistence 2FCriteria Chapter 45 6 on page 229 Chapter 45 8 on page 232 http en wikipedia org wiki SQL http wiki eclipse org EclipseLink UserGuide JPA Basic_JPA_Development Querying JPQL EclipseLink_Extensions_ 28EQL 29 http en wikipedia org wiki Object 20Query 20Language http www querydsl com oo Noaow bwnr 215 Querying 44 1 Named Queries There are two main types of queries in JPA named queries and dynamic queries A named query is used for a static query that will be used many times in the application The advantage of a named query is that it can be defined once in one place and reused in the application Most JPA providers also pre parse compile named queries so they are more optimized than dynamic queries which typically must be parsed compiled every time they are executed Since named queries are part of the persistence meta data they can also be optimized or overridden in the orm xml without changing the application code Named queries are defined through the NamedQuery and NamedQueries anno tations or lt named query gt XML element Named queries are accessed through the EntityManager createNamedQuery API and executed through the Query interface
351. uch section unique by adding at the end of it in paren theses the name of the original author or publisher of that section if known or else a unique number Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work In the combination you must combine any sections Entitled History in the various original docu ments forming one section Entitled History like wise combine any sections Entitled Acknowledge ments and any sections Entitled Dedications You must delete all sections Entitled Endorse ments 6 COLLECTIONS OF DOCUMENTS You may make a collection consisting of the Docu ment and other documents released under this Li cense and replace the individual copies of this Li cense in the various documents with a single copy that is included in the collection provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects You may extract a single document from such a col lection and distribute it individually under this Li cense provided you insert a copy of this License into the extracted document and follow this Li cense in all other respects regarding verbatim copy ing of that document 7 AGGREGATION WITH INDEPENDENT WORKS A compilation of the Document or its derivatives with other separate and independent documents or works in or on a volume of a storage or distribution medium is
352. ultiple table join expression could be used to configure an outer join to be used to read the table 13 Chapter 11 on page 25 14 Chapter 10 on page 23 15 Chapter 12 on page 27 16 Chapter 11 on page 25 17 Chapter 10 on page 23 ol Advanced 20 5 Tables with special characters and mixed case Some JPA providers may have issues with table and column names with special characters such as spaces In general it is best to use standard characters no spaces and all uppercase names International languages should be ok as long as the database and JDBC driver supports the character set It may be required to quote table and column names with special characters or in some cases with mixed case For example if the table name had a space it could be defined as the following Table Employee Data Some databases support mixed case table and column names and others are case insensitive If your database is case insensitive or you wish your data model to be portable it is best to use all uppercase names This is normally not a big deal with JPA where you rarely use the table and column names directly from your application but can be an issue in certain cases if using native SQL queries 20 6 Table qualifiers schemas or creators A database table may require to be prefixed with a table qualifier such as the table s creator or its namespace schema or catalog Some databases also support linking table on other database so t
353. updates or cause one user to overwrite another user s changes if not using locking Again note that these can both occur without caching even with a single application and server accessing the database This is why it is normally always important to use optimistic locking Stale data could also be returned to the user 51 6 3 Refreshing Refreshing is the most common solution to stale data Most application users are familiar with the concept of a cache and know when they need fresh data and are willing to click a refresh button This is very common in an Internet browser most browsers have a cache of web pages that have been accessed and will avoid loading the same page twice unless the user clicks the refresh button This same concept can be used in building JPA applications JPA provides several refreshing options see refreshing Some JPA providers also support refreshing options in their 2nd level cache One option is to always refresh on any query to the database This means that find operations will still access the cache but if the query accesses the database and brings back data the 2nd level cache will be refreshed with the data This avoids queries returning stale data but means there will be less benefit from caching The cost is not just in refreshing the objects but in refreshing their relationships Some JPA providers support this option in combination with optimistic locking If the version value in the row from the database
354. va sun com javaee 5 docs api javax persistence QueryHint html 216 Dynamic Queries 44 1 2 Example named query XML lt entity mappings gt lt entity name Employee class org acme Employee access FIELD gt lt named query name findAllEmployeesInCity gt lt query gt Select emp from Employee emp where emp address city city lt query gt lt hint name acme jpa batch value emp address gt lt named query gt lt attributes gt lt id name id gt lt attributes gt lt entity gt lt entity mappings gt 44 1 3 Example named query execution EntityManager em getEntityManager Query query em createNamedQuery findAllEmployeesInCity query setParameter city Ottawa List lt Employee gt employees query getResultList 44 2 Dynamic Queries Dynamic queries are normally used when the query depends on the context For example depending on which items in the query form were filled in the query may have different parameters Dynamic queries are also useful for uncommon queries or prototyping JPA provides two main options for dynamic queries JPQL and the Criteria API Dynamic queries can use parameters and query hints the same as named queries Dynamic queries are accessed through the EntityManager createQuery API and exe cuted through the Query interface Example dynamic query execution EntityManager em getEntityManager Query query em createQuery Select emp from Employee
355. ver the majority of data is persisted in databases specifically relational databases Most things that you do on a computer or web site that involve storing data involve accessing a relational database Relational databases are the standard mode of persistent storage for most industries from banking to manufacturing There are many things that can be stored in databases with Java Java data includes strings numbers date and byte arrays images XML and Java objects Many Java applications use Java objects to model their application data Because Java is an Object Oriented language storing Java objects is a natural and common approach to persisting data from Java There are many ways to access a relational database from Java JPA is just the latest of many different specifications but it seems to be the direction that most programmers are heading What is Java persistence What is Java persistence http en wikipedia org wiki Persistence_ 28computer_science 29 http en wikipedia org wiki 0Object 20 28computer_science 29 20 http en wikipedia org wiki Relational_databases 20 http en wikipedia org wiki Java_Persistence_API 20 http en wikipedia org wiki JDBC 420 http en wikipedia org wiki Serialization 20 http en wikipedia org wiki J2EE_Connector_Architecture 20 http en wikipedia org wiki Object_databases 20 http en wikipedia org wiki XML_database 20 http en wikipedia org wiki Object 200riented 20 http en wikib
356. vide replication support If your database does not support replication you can implement it yourself through having multiple persistence units and persisting and merging your objects to both databases TopLink EclipseLink Support replication load balancing and fail over Replication and load balancing is supported through EclipseLink s partitioning support using the CReplicationPartitioning and CRoundRobinPartitioning annotations and XML 28 Chapter 11 on page 25 29 Chapter 10 on page 23 30 http en wikibooks org wiki Java_Persistence 2FAuditing_and_Security 31 Chapter 11 on page 25 32 Chapter 10 on page 23 203 Advanced Topics 41 12 Partitioning Data partitioning can be used to scale an application across multiple database machines or with a clustered database such as Oracle RAC Partitioning splits your data across each of the database nodes There is horizontal parti tioning and vertical partitioning Vertical partitioning is normally the easiest to implement You can just put half of your classes on one database and the other half on another Ideally the two sets would be isolated from each other and not have any cross database relationships This can be done directly in JPA by having two different persistence units one for each database For horizontal partitioning you need to split your data across multiple database nodes Each database node will have the same tables but each node s table will only store
357. y used if the table already has a last updated timestamp column and is also a convenient way to auto update a last updated column The timestamp version value can be more useful than a numeric version as it includes the relevant information on when the object was last updated The timestamp value in timestamp version locking can either come from the database or from Java mid tier JPA does not allow this to be configured however some JPA providers may provide this option Using the database s current timestamp can be very expensive as it requires a database call to the server 27 2 2 Multiple Versions An object can only have one version in JPA Even if the object maps to multiple tables only the primary table will have the version If any fields in any of the tables changes the version will be updated If you desire multiple versions you may need to map multiple version attributes in your object and manually maintain the duplicate versions perhaps through events Technically there is nothing preventing your from annotating multiple attributes with Version and potentially some JPA providers may support this don t forget to sacrifice a chicken 10 Chapter 27 2 1 on page 104 11 Chapter 27 2 2 on page 104 104 Advanced 27 2 3 Cascaded Locking Locking objects is different than locking rows in the database An object can be more complex than a simple row an object can span multiple tables have inheritance have relationsh
358. yee owner 34 0 4 Example of a ManyToOne relationship XML lt entity name Phone class org acme Phone access FIELD gt lt attributes gt lt id name id gt lt many to one name owner fetch LAZY gt lt join column name OWNER_ID gt lt many to one gt lt attributes gt lt entity gt 2 https java sun com javaee 5 docs api javax persistence ManyToOne html 3 Chapter 35 1 on page 169 166 See Also 34 1 See Also e Relationships e Cascading e Lazy Fetching e Target Entity e Join Fetching e Batch Reading e Common Problems e OneToOne e Mapping a OneToOne Using a Join Table e OneToMany 6 0 34 2 Common Problems Foreign key is also part of the primary key See Primary Keys through OneToOne Relationships Foreign key is also mapped as a basic If you use the same field in two different mappings you typically require to make one of them read only using insertable updateable false See Target Foreign Keys Primary Key Join Columns Cascade Primary Keys Constraint error on insert This typically occurs because you have incorrectly mapped the foreign key in a OneToOne relationship See Target Foreign Keys Primary Key Join Columns Cascade Primary Keys 4 Chapter 29 9 on page 123 5 Chapter 30 2 on page 129 6 Chapter 30 1 on page 126 7 Chapter 30 4 on page 131 8 Chapter 31 3 on page 145 9 Chapter 31 6 on page 148 10 Chapter 30 6 on page 135 11 Chapter 31 7 on
359. you may choose any version ever published not as a draft by the Free Software Foundation If the Document speci fies that a proxy can decide which future versions of 4 Combined Works You may convey a Combined Work under terms of your choice that taken together effectively do not restrict modification of the portions of the Library contained in the Combined Work and reverse en gineering for debugging such modifications if you also do each of the following a Give prominent notice with each copy of the Combined Work that the Library is used in it and that the Library and its use are covered by this Li cense b Accompany the Combined Work with a copy of the GNU GPL and this license document c For a Combined Work that displays copyright no tices during execution include the copyright notice for the Library among these notices as well as a ref erence directing the user to the copies of the GNU GPL and this license document d Do one of the following o 0 Convey the Minimal Corresponding Source under the terms of this License and the Cor responding Application Code in a form suitable for and under terms that permit the user to recombine or relink the Application with a modified version of the Linked Version to produce a modified Com bined Work in the manner specified by section 6 of the GNU GPL for conveying Corresponding Source o 1 Use a suitable shared library mechanism for linking with the Library A suitabl

- upload.wikimedia.

Contents

Download Pdf Manuals

Related Search

Related Contents