EclipseLink JPA Black Belt Course

1. EclipseLink JPABlack Belt Course Section 9: Customizations <PRESENTER>

2. JPA Extensions • EclipseLink provides a rich set of extensions for advanced JPA usage. You can access EclipseLink extended JPA functionality using: • Custom annotations • Persistence unit properties • Query hints • Native API

3. Mappings Converters Mapping Customization Extended metadata Caching Locking Queries and Hints Stored Procedure Query Lazy Loading Byte Code Weaving Change Tracking Returning Policy Persistence Unit Properties JDBC Logging DDL Generation Platforms Customization Performance Enhancements Oracle Spatial Topics

4. Mappings • EclipseLink provide annotations to configure advanced mapping including: • @BasicCollection - stores a collection of simple types, such as String, Number, Date, etc., in a single table • @BasicMap - stores a collection of key-value pairs of simple types, such as String, Number, Date, etc., in a single table • @PrivateOwned - supports orphan management • @JoinFetch - enables the joining and reading of a referenced object(s) in the same query as the source object • @Mutable - indicates that the value of a complex field itself can be changed or not changed (instead of being replaced) • @Transformation - enables the mapping of a single field to to one or more database columns. • @VariableOneToOne - supports OneToOne mappings to an interface rather than an Entity • @ReadOnly - makes an Entity read only

5. Converters • New converter mappings for type conversion and user defined types include: • @Converter • @TypeConverter • @ObjectTypeConverter • @StructConverter • @Convert @Entity@Converter( name="Currency",converterClass=CurrencyConverter.class)publicclassEmployeeimplementsSerializable{@Convert("Currency")privateCurrencysalaryCurrency;

6. Customizers • Use the @Customizer EclipseLink annotation to register a class that can customize the mappings for an Entity using the EclipseLink native API. @Entity@Customizer(EmployeeCustomizer.class)publicclassEmployeeimplementsSerializable{... publicclassEmployeeCustomizer implementsDescriptorCustomizer{publicvoidcustomize(ClassDescriptorDescriptor) throwsException{ descriptor.disableCacheHits(); …

7. Extended Metadata • Annotations • XML • EclipseLink ORM.XML • Native Metadata • Sessions XML • Map XML • API

8. map.xml orm.xml eclispelink-orm.xml orm.xml Metadata Approaches JPA EclipseLink JPA EclipseLink Native persistence.xml persistence.xml persistence.xml + + + sessions.xml @Entity (JPA + EclipseLink) @Entity + + + + + defaults + defaults

9. Concurrency Protection - Locking • Optimistic concurrency is built into JPA, but no support for pessimistic locking is specified • Will likely be addressed in a future JPA release • All credible JPA implementations support pessimistic locks in some way or another • EntityManager lock() method can be used with optimistic locking, and error handling • EclipseLink query hint for pessimistic locking query.setHint(PESSIMISTIC_LOCK, LockNoWait);

10. Optimistic Locking Policy • @OptimisticLocking annotation supports the configuration of advanced optimistic locking policies @Entity@OptimisticLocking( type=OptimisticLockingType.CHANGED_COLUMNS)publicclassEmployeeimplementsSerializable{ • Optimistic locking policies include: • ALL_COLUMNS • CHANGED_COLUMNS • SELECTED_COLUMNS

11. Query Hints • eclipselink.cache-usage • eclipselink.query-type • eclipselink.jdbc.bind-parameters • eclipselink.pessimistic-lock • eclipselink.refresh • eclipselink.refresh.cascade • eclipselink.batch • eclipselink.join-fetch • eclipselink.read-only • eclipselink.jdbc.timeout • eclipselink.jdbc.fetch-size • eclipselink.jdbc.max-rows • eclipselink.result-collection-type

12. Stored Procedure Query • Stored procedure usage has been simplified through the @NamedStoredProcedureQuery and @NamedStoredProcedureQueries annotations. • These annotations encapsulate stored procedure calls as named queries. • Client code is unaware that the query they are executing is a stored procedure and not a JP QL or native SQL query

13. Lazy Loading & Fetch Groups • EclipseLink supports lazy loading of @Basic mappings • Two default Fetch Groups defined automatically: eagerly loaded fields and lazily loaded fields. • Initial Entity select fetches only eager fields. • Referencing *any* lazy field will fetch all lazy fields • Especially useful with CLOB/BLOB fields to avoid loading until necessary • Enabled by byte code weaving • Fetch Groups can be manually defined and added to a query as a hint—overrides default fetch groups.

14. Weaving Support • EclipseLink makes use of Weaving (ASM) to introduce additional functionality into the JPA entity classes • Needed for M:1 and 1:1 lazy fetching • Integrated with compliant Java EE 5 containers (e.g., WLS 10.3) and with OC4J 10.1.3.1+, and Spring 2.0 • Available for Java SE using JDK/JRE’s –javaagent: • Optional • Static weaving also supported • Weaving of .class files before deployment

15. Change Tracking • Use the @ChangeTracking annotation to configure the way changes to Entities are computed. Four options are provided: • ATTRIBUTE – uses weaving to detect which fields or properties of the object change. • OBJECT – uses weaving to detect if the object has been changed, but uses a backup copy of the object to determine what fields or properties changed. • DEFERRED – defers all change detection to the underlying UnitOfWork's change detection process. • AUTO – If weaving is available then ATTRIBUTE, if weaving not available then DEFERRED

16. Returning Policy • Return policy options can be configured using: • @ReturnInsert • @ReturnUpdate • On the Oracle Database, specifying an @ReturnInsert or @ReturnUpdate will add a RETURNING clause to insert and update statements to efficiently reread modified data. • On databases other than Oracle, the underlying ReturningPolicy can be configured using a descriptor customizer. @EntitypublicclassEmployeeimplementsSerializable{...@ReturnInsert@ReturnUpdateprivateStringfirstName;

17. JPA Configuration • EclipseLink offers significant configuration and customization through persistence unit properties in the following areas: • JDBC - configuration of parameter binding, statement caching, batch writing and more. • Logging - configuration of logging level, details (e.g., thread, session, etc.), output target and other options. • DDL Generation – to generate DDL from mapped Entities. • Database, Application Server and Session - specify the target database and application server to enable platform specific integration and features (e.g., Oracle Database native sequencing). • Mapping Customization using • Configuration options are also available to enable usage of Native ORM projects through the JPA API instead of through a Session.

18. JDBC Connection Settings • Resource-level JDBC technology settings are vendors responsibility • Need to specify the four basic JDBC technology properties to obtain driver connections • Driver class, URL, username, password • The property keys will be different, but the values for a given JDBC technology data source will be the same for all vendors • Used when not in a container, or when managed data sources are not available or not desired

19. JDBC Connection Settings <properties> ... <property name=“eclipselink.jdbc.driver” value=“oracle.jdbc.Driver”/> <property name=“eclipselink.jdbc.url” value=“jdbc:oracle:thin:@localhost:1521:XE”/> <property name=“eclipselink.jdbc.user” value=“scott”/> <property name=“eclipselink.jdbc.password” value=“tiger”/>

20. Logging • Users want to control over logging, but vendors use different logging APIs • Can usually configure to use one of the well-known logging APIs • java.util.logging, log4J, etc. • Common requirement is to configure the logging level to show the generated SQL

21. Logging <properties> ... <property name=“eclipselink.logging.level" value="FINE"/> ... </properties>

22. DDL Generation • Standard enables it but does not currently dictate that providers support it • Mapping metadata specifies how DDL should be generated • Vendors may offer differing levels of support, including: • Generating DDL to a file only • Generating and executing DDL in DB • Dropping existing tables before creating new ones

23. DDL Generation <properties> ... <property name=“eclipselink.ddl-generation" value="create-tables"/> ... </properties>

24. Database Platform XML: <properties> <property name=“eclipselink.target-database" value="Derby"/> </properties> API: properties.put( PersistenceUnitProperties.TARGET_DATABASE, TargetDatabase.ORACLE);

25. Target Database Options • EclipseLink 1.0.1 has support for the following database platforms: publicclass TargetDatabase {publicstaticfinal String Auto = "Auto";publicstaticfinal String Oracle = "Oracle";publicstaticfinal String Oracle11 = "Oracle11";publicstaticfinal String Oracle10 = "Oracle10g";publicstaticfinal String Oracle9 = "Oracle9i";publicstaticfinal String Oracle8 = "Oracle8i";publicstaticfinal String Attunity = "Attunity";publicstaticfinal String Cloudscape = "Cloudscape";publicstaticfinal String Database = "Database";publicstaticfinal String DB2 = "DB2";publicstaticfinal String DB2Mainframe = "DB2Mainframe";publicstaticfinal String DBase = "DBase“;publicstaticfinal String Derby = "Derby";publicstaticfinal String HSQL = "HSQL";publicstaticfinal String Informix = "Informix";publicstaticfinal String JavaDB = "JavaDB";publicstaticfinal String MySQL4 = "MySQL4";publicstaticfinal String MySQL = "MySQL";publicstaticfinal String PointBase = "PointBase";publicstaticfinal String PostgreSQL = "PostgreSQL";publicstaticfinal String SQLAnywhere = "SQLAnywhere";publicstaticfinal String SQLServer = "SQLServer";publicstaticfinal String Sybase = "Sybase";publicstaticfinal String TimesTen = "TimesTen"; publicstaticfinal String DEFAULT = Auto; }

26. Server Platform • Enables simplified configuration of the target application server • Used to enable integration with: • JTA transaction manager • Logging • JDBC connection un-wrapping <property name=“eclipselink.target-server“ value=“WebLogic"/> • In EclipseLink 1.0.1 supported server platforms are: publicclass TargetServer {publicstaticfinal String None = "None";publicstaticfinal String OC4J = "OC4J";publicstaticfinal String SunAS9 = "SunAS9";publicstaticfinal String WebSphere = "WebSphere";publicstaticfinal String WebSphere_6_1 = "WebSphere_6_1";publicstaticfinal String WebLogic = "WebLogic";publicstaticfinal String WebLogic_9 = "WebLogic_9";publicstaticfinal String WebLogic_10 = "WebLogic_10";publicstaticfinal String JBoss = "JBoss";publicstaticfinal String DEFAULT = None;

27. Customization Using Properties <properties> ... <property name=“eclipselink.session.customizer" value="acme.MySessionCustomizer"/> <property name=“eclipselink.descriptor.customizer.Employee" value="acme.MyDescriptorCustomizer"/> ... </properties>

28. Performance Enhancements Summary • In EclipseLink, JPA performance has been enhanced with features including: • Change tracking for JPA entities • Read-only queries • Parameter binding: now enabled by default. • Joining: additional support for many-to-many, direct-collection, direct-map, and aggregate-collection mappings, and mapping level inner and outer join support • Inheritance: support for outer joining inheritance subclasses on queries, and support for joining classes with inheritance • Improved performance and concurrency • Dynamic Expression and JPQL parse cache

29. Oracle Spatial • EclipseLink includes the new org.eclipse.persistence.platform.database.oracle.converters.JGeometry converter to provide support for working with Oracle Spatial data and querying.