| <html><head> |
| <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> |
| <title>Apache OpenJPA User's Guide</title><link rel="stylesheet" href="css/docbook.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.72.0"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="book" lang="en" id="manual"><div class="titlepage"><div><div><h1 class="title"><a name="manual"></a>Apache OpenJPA User's Guide</h1></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="part"><a href="#introduction">1. Introduction</a></span></dt><dd><dl><dt><span class="chapter"><a href="#openjpa_intro">1. |
| OpenJPA |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#openjpa_intro_about">1. |
| About This Document |
| </a></span></dt></dl></dd></dl></dd><dt><span class="part"><a href="#jpa_overview">2. Java Persistence API</a></span></dt><dd><dl><dt><span class="chapter"><a href="#jpa_overview_intro">1. |
| Introduction |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_intro_audience">1. |
| Intended Audience |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_intro_transpers">2. |
| Lightweight Persistence |
| </a></span></dt></dl></dd><dt><span class="chapter"><a href="#jpa_overview_why">2. |
| Why JPA? |
| </a></span></dt><dt><span class="chapter"><a href="#jpa_overview_arch">3. |
| Java Persistence API Architecture |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_arch_exceptions">1. |
| JPA Exceptions |
| </a></span></dt></dl></dd><dt><span class="chapter"><a href="#jpa_overview_pc">4. |
| Entity |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_pc_restrict">1. |
| Restrictions on Persistent Classes |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_pc_no_arg">1.1. |
| Default or No-Arg Constructor |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_pc_final">1.2. |
| Final |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_pc_id">1.3. |
| Identity Fields |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_pc_version">1.4. |
| Version Field |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_pc_restrict_inheritance">1.5. |
| Inheritance |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_pc_restrict_fields">1.6. |
| Persistent Fields |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_pc_restrict_conclusion">1.7. |
| Conclusions |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_overview_pc_identity">2. |
| Entity Identity |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_pc_identitycls">2.1. |
| Identity Class |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_pc_identity_hierarchy">2.1.1. |
| Identity Hierarchies |
| </a></span></dt></dl></dd></dl></dd><dt><span class="section"><a href="#jpa_overview_pc_callbacks">3. |
| Lifecycle Callbacks |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_pc_callbacks_methods">3.1. |
| Callback Methods |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_callbacks_using">3.2. |
| Using Callback Methods |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_entity_listeners_using">3.3. |
| Using Entity Listeners |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_entity_listeners_exclude">3.4. |
| Entity Listeners Hierarchy |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_overview_pc_conclusion">4. |
| Conclusions |
| </a></span></dt></dl></dd><dt><span class="chapter"><a href="#jpa_overview_meta">5. |
| Metadata |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_meta_class">1. |
| Class Metadata |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_meta_entity">1.1. |
| Entity |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_meta_idclass">1.2. |
| Id Class |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_meta_embeddablesuper">1.3. |
| Mapped Superclass |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_meta_embeddable">1.4. |
| Embeddable |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_meta_entity_listeners">1.5. |
| EntityListeners |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_meta_classex">1.6. |
| Example |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_overview_meta_field">2. |
| Field and Property Metadata |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_meta_transient">2.1. |
| Transient |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_meta_id">2.2. |
| Id |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_meta_gen">2.3. |
| Generated Value |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_meta_embedid">2.4. |
| Embedded Id |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_meta_version">2.5. |
| Version |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_meta_basic">2.6. |
| Basic |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_meta_fetch">2.6.1. |
| Fetch Type |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_overview_meta_embedded">2.7. |
| Embedded |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_meta_manytoone">2.8. |
| Many To One |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_meta_cascade">2.8.1. |
| Cascade Type |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_overview_meta_onetomany">2.9. |
| One To Many |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_meta_mappedby">2.9.1. |
| Bidirectional Relations |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_overview_meta_onetoone">2.10. |
| One To One |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_meta_manytomany">2.11. |
| Many To Many |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_meta_orderby">2.12. |
| Order By |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_meta_mapkey">2.13. |
| Map Key |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_meta_fielddefaults">2.14. |
| Persistent Field Defaults |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_overview_meta_xml">3. |
| XML Schema |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_meta_complete">4. |
| Conclusion |
| </a></span></dt></dl></dd><dt><span class="chapter"><a href="#jpa_overview_persistence">6. |
| Persistence |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_persistence_xml">1. |
| persistence.xml |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_persistence_use">2. |
| Non-EE Use |
| </a></span></dt></dl></dd><dt><span class="chapter"><a href="#jpa_overview_emfactory">7. |
| EntityManagerFactory |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_emfactory_obtain">1. |
| Obtaining an EntityManagerFactory |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_emfactory_em">2. |
| Obtaining EntityManagers |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_emfactory_perscontext">3. |
| Persistence Context |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_emfactory_perscontext_trans">3.1. |
| Transaction Persistence Context |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_emfactory_perscontext_extend">3.2. |
| Extended Persistence Context |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_overview_emfactory_close">4. |
| Closing the EntityManagerFactory |
| </a></span></dt></dl></dd><dt><span class="chapter"><a href="#jpa_overview_em">8. |
| EntityManager |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_em_trans">1. |
| Transaction Association |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_em_lifecycle">2. |
| Entity Lifecycle Management |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_em_lifeexamples">3. |
| Lifecycle Examples |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_em_identity">4. |
| Entity Identity Management |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_em_cache">5. |
| Cache Management |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_em_query">6. |
| Query Factory |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_em_closing">7. |
| Closing |
| </a></span></dt></dl></dd><dt><span class="chapter"><a href="#jpa_overview_trans">9. |
| Transaction |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_trans_types">1. |
| Transaction Types |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_trans_local">2. |
| The EntityTransaction Interface |
| </a></span></dt></dl></dd><dt><span class="chapter"><a href="#jpa_overview_query">10. |
| JPA Query |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_query_api">1. |
| JPQL API |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_query_basic">1.1. |
| Query Basics |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_query_relations">1.2. |
| Relation Traversal |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_join_fetch">1.3. |
| Fetch Joins |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_query_functions">1.4. |
| JPQL Functions |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_query_inheritance">1.5. |
| Polymorphic Queries |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_query_params">1.6. |
| Query Parameters |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_query_hints">1.7. |
| Query Hints |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_hints_locking">1.7.1. |
| Locking Hints |
| </a></span></dt><dt><span class="section"><a href="#jpa_hints_resultset">1.7.2. |
| Result Set Size Hint |
| </a></span></dt><dt><span class="section"><a href="#jpa_hints_isolation">1.7.3. |
| Isolation Level Hint |
| </a></span></dt><dt><span class="section"><a href="#jpa_hints_fetchplan">1.7.4. |
| Other Fetchplan Hints |
| </a></span></dt><dt><span class="section"><a href="#d0e6512">1.7.5. |
| Oracle Query Hints |
| </a></span></dt><dt><span class="section"><a href="#jpa_hints_named">1.7.6. |
| Named Query Hints |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_overview_query_ordering">1.8. |
| Ordering |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_query_aggregates">1.9. |
| Aggregates |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_query_named">1.10. |
| Named Queries |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_query_delete">1.11. |
| Delete By Query |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_query_update">1.12. |
| Update By Query |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_langref">2. |
| JPQL Language Reference |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_langref_stmnttypes">2.1. |
| JPQL Statement Types |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_langref_select">2.1.1. |
| JPQL Select Statement |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_bulk">2.1.2. |
| JPQL Update and Delete Statements |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_langref_schematypes">2.2. |
| JPQL Abstract Schema Types and Query Domains |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_langref_schemanaming">2.2.1. |
| JPQL Entity Naming |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_schemaexample">2.2.2. |
| JPQL Schema Example |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_langref_fromclause">2.3. |
| JPQL FROM Clause and Navigational Declarations |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_langref_from_identifiers">2.3.1. |
| JPQL FROM Identifiers |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_from_vars">2.3.2. |
| JPQL Identification Variables |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_range">2.3.3. |
| JPQL Range Declarations |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_path">2.3.4. |
| JPQL Path Expressions |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_Joins">2.3.5. |
| JPQL Joins |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_langref_inner_joins">2.3.5.1. |
| JPQL Inner Joins (Relationship Joins) |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_outer_joins">2.3.5.2. |
| JPQL Outer Joins |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_fetch_joins">2.3.5.3. |
| JPQL Fetch Joins |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_langref_collection_dec">2.3.6. |
| JPQL Collection Member Declarations |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_polymorph">2.3.7. |
| JPQL Polymorphism |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_langref_where">2.4. |
| JPQL WHERE Clause |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_cond">2.5. |
| JPQL Conditional Expressions |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_langref_lit">2.5.1. |
| JPQL Literals |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_idvar">2.5.2. |
| JPQL Identification Variables |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_path_exp">2.5.3. |
| JPQL Path Expressions |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_input_params">2.5.4. |
| JPQL Input Parameters |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_langref_pos_params">2.5.4.1. |
| JPQL Positional Parameters |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_named_params">2.5.4.2. |
| JPQL Named Parameters |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_langref_cond_comp">2.5.5. |
| JPQL Conditional Expression Composition |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_operators">2.5.6. |
| JPQL Operators and Operator Precedence |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_between">2.5.7. |
| JPQL Between Expressions |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_in">2.5.8. |
| JPQL In Expressions |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_like">2.5.9. |
| JPQL Like Expressions |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_null">2.5.10. |
| JPQL Null Comparison Expressions |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_empty_comp">2.5.11. |
| JPQL Empty Collection Comparison Expressions |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_collection_member">2.5.12. |
| JPQL Collection Member Expressions |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_exists">2.5.13. |
| JPQL Exists Expressions |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_all_any">2.5.14. |
| JPQL All or Any Expressions |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_subqueries">2.5.15. |
| JPQL Subqueries |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_functional">2.5.16. |
| JPQL Functional Expressions |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_langref_string_fun">2.5.16.1. |
| JPQL String Functions |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_arithmetic">2.5.16.2. |
| JPQL Arithmetic Functions |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_datetime">2.5.16.3. |
| JPQL Datetime Functions |
| </a></span></dt></dl></dd></dl></dd><dt><span class="section"><a href="#jpa_langref_group">2.6. |
| JPQL GROUP BY, HAVING |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_select_clause">2.7. |
| JPQL SELECT Clause |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_langref_resulttype">2.7.1. |
| JPQL Result Type of the SELECT Clause |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_constructor">2.7.2. |
| JPQL Constructor Expressions |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_null_select">2.7.3. |
| JPQL Null Values in the Query Result |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_aggregates">2.7.4. |
| JPQL Aggregate Functions |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_langref_agg_examples">2.7.4.1. |
| JPQL Aggregate Examples |
| </a></span></dt></dl></dd></dl></dd><dt><span class="section"><a href="#jpa_langref_orderby">2.8. |
| JPQL ORDER BY Clause |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_bulk_ops">2.9. |
| JPQL Bulk Update and Delete |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_null_values">2.10. |
| JPQL Null Values |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_equality">2.11. |
| JPQL Equality and Comparison Semantics |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_bnf">2.12. |
| JPQL BNF |
| </a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#jpa_overview_sqlquery">11. |
| SQL Queries |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_sqlquery_create">1. |
| Creating SQL Queries |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_sqlquery_obj">2. |
| Retrieving Persistent Objects with SQL |
| </a></span></dt></dl></dd><dt><span class="chapter"><a href="#jpa_overview_mapping">12. |
| Mapping Metadata |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_mapping_table">1. |
| Table |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_mapping_unq">2. |
| Unique Constraints |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_mapping_column">3. |
| Column |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_mapping_id">4. |
| Identity Mapping |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_mapping_sequence">5. |
| Generators |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_mapping_sequence_seqgen">5.1. |
| Sequence Generator |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_mapping_sequence_tablegen">5.2. |
| TableGenerator |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_mapping_sequence_genex">5.3. |
| Example |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_overview_mapping_inher">6. |
| Inheritance |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_mapping_inher_single">6.1. |
| Single Table |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_mapping_inher_single_adv">6.1.1. |
| Advantages |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_mapping_inher_single_disadv">6.1.2. |
| Disadvantages |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_overview_mapping_inher_joined">6.2. |
| Joined |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_mapping_inher_joined_adv">6.2.1. |
| Advantages |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_mapping_inher_joined_disadv">6.2.2. |
| Disadvantages |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_overview_mapping_inher_tpc">6.3. |
| Table Per Class |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_mapping_inher_tpc_adv">6.3.1. |
| Advantages |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_mapping_inher_tpc_disadv">6.3.2. |
| Disadvantages |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_overview_mapping_inher_together">6.4. |
| Putting it All Together |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_overview_mapping_discrim">7. |
| Discriminator |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_mapping_field">8. |
| Field Mapping |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_mapping_basic">8.1. |
| Basic Mapping |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_mapping_lob">8.1.1. |
| LOBs |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_mapping_enum">8.1.2. |
| Enumerated |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_mapping_temporal">8.1.3. |
| Temporal Types |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_mapping_basic_example">8.1.4. |
| The Updated Mappings |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_overview_mapping_secondary">8.2. |
| Secondary Tables |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_mapping_embed">8.3. |
| Embedded Mapping |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_mapping_rel">8.4. |
| Direct Relations |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_mapping_assoccoll">8.5. |
| Join Table |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_mapping_bidi">8.6. |
| Bidirectional Mapping |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_mapping_map">8.7. |
| Map Mapping |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_overview_mapping_full">9. |
| The Complete Mappings |
| </a></span></dt></dl></dd><dt><span class="chapter"><a href="#jpa_overview_conclusion">13. |
| Conclusion |
| </a></span></dt></dl></dd><dt><span class="part"><a href="#ref_guide">3. Reference Guide</a></span></dt><dd><dl><dt><span class="chapter"><a href="#ref_guide_intro">1. |
| Introduction |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_intro_audience">1. |
| Intended Audience |
| </a></span></dt></dl></dd><dt><span class="chapter"><a href="#ref_guide_conf">2. |
| Configuration |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_conf_intro">1. |
| Introduction |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_conf_specify">2. |
| Runtime Configuration |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_conf_devtools">3. |
| Command Line Configuration |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_conf_devtools_format">3.1. |
| Code Formatting |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_conf_plugins">4. |
| Plugin Configuration |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_conf_openjpa">5. |
| OpenJPA Properties |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#openjpa.AutoClear">5.1. |
| openjpa.AutoClear |
| </a></span></dt><dt><span class="section"><a href="#openjpa.AutoDetach">5.2. |
| openjpa.AutoDetach |
| </a></span></dt><dt><span class="section"><a href="#openjpa.BrokerFactory">5.3. |
| openjpa.BrokerFactory |
| </a></span></dt><dt><span class="section"><a href="#openjpa.BrokerImpl">5.4. |
| openjpa.BrokerImpl |
| </a></span></dt><dt><span class="section"><a href="#openjpa.ClassResolver">5.5. |
| openjpa.ClassResolver |
| </a></span></dt><dt><span class="section"><a href="#openjpa.Compatibility">5.6. |
| openjpa.Compatibility |
| </a></span></dt><dt><span class="section"><a href="#openjpa.ConnectionDriverName">5.7. |
| openjpa.ConnectionDriverName |
| </a></span></dt><dt><span class="section"><a href="#openjpa.Connection2DriverName">5.8. |
| openjpa.Connection2DriverName |
| </a></span></dt><dt><span class="section"><a href="#openjpa.ConnectionFactory">5.9. |
| openjpa.ConnectionFactory |
| </a></span></dt><dt><span class="section"><a href="#openjpa.ConnectionFactory2">5.10. |
| openjpa.ConnectionFactory2 |
| </a></span></dt><dt><span class="section"><a href="#openjpa.ConnectionFactoryName">5.11. |
| openjpa.ConnectionFactoryName |
| </a></span></dt><dt><span class="section"><a href="#openjpa.ConnectionFactory2Name">5.12. |
| openjpa.ConnectionFactory2Name |
| </a></span></dt><dt><span class="section"><a href="#openjpa.ConnectionFactoryMode">5.13. |
| openjpa.ConnectionFactoryMode |
| </a></span></dt><dt><span class="section"><a href="#openjpa.ConnectionFactoryProperties">5.14. |
| openjpa.ConnectionFactoryProperties |
| </a></span></dt><dt><span class="section"><a href="#openjpa.ConnectionFactory2Properties">5.15. |
| openjpa.ConnectionFactory2Properties |
| </a></span></dt><dt><span class="section"><a href="#openjpa.ConnectionPassword">5.16. |
| openjpa.ConnectionPassword |
| </a></span></dt><dt><span class="section"><a href="#openjpa.Connection2Password">5.17. |
| openjpa.Connection2Password |
| </a></span></dt><dt><span class="section"><a href="#openjpa.ConnectionProperties">5.18. |
| openjpa.ConnectionProperties |
| </a></span></dt><dt><span class="section"><a href="#openjpa.Connection2Properties">5.19. |
| openjpa.Connection2Properties |
| </a></span></dt><dt><span class="section"><a href="#openjpa.ConnectionURL">5.20. |
| openjpa.ConnectionURL |
| </a></span></dt><dt><span class="section"><a href="#openjpa.Connection2URL">5.21. |
| openjpa.Connection2URL |
| </a></span></dt><dt><span class="section"><a href="#openjpa.ConnectionUserName">5.22. |
| openjpa.ConnectionUserName |
| </a></span></dt><dt><span class="section"><a href="#openjpa.Connection2UserName">5.23. |
| openjpa.Connection2UserName |
| </a></span></dt><dt><span class="section"><a href="#openjpa.ConnectionRetainMode">5.24. |
| openjpa.ConnectionRetainMode |
| </a></span></dt><dt><span class="section"><a href="#openjpa.DataCache">5.25. |
| openjpa.DataCache |
| </a></span></dt><dt><span class="section"><a href="#openjpa.DataCacheManager">5.26. |
| openjpa.DataCacheManager |
| </a></span></dt><dt><span class="section"><a href="#openjpa.DataCacheTimeout">5.27. |
| openjpa.DataCacheTimeout |
| </a></span></dt><dt><span class="section"><a href="#openjpa.DetachState">5.28. |
| openjpa.DetachState |
| </a></span></dt><dt><span class="section"><a href="#openjpa.DynamicDataStructs">5.29. |
| openjpa.DynamicDataStructs |
| </a></span></dt><dt><span class="section"><a href="#openjpa.FetchBatchSize">5.30. |
| openjpa.FetchBatchSize |
| </a></span></dt><dt><span class="section"><a href="#openjpa.FetchGroups">5.31. |
| openjpa.FetchGroups |
| </a></span></dt><dt><span class="section"><a href="#openjpa.FlushBeforeQueries">5.32. |
| openjpa.FlushBeforeQueries |
| </a></span></dt><dt><span class="section"><a href="#openjpa.IgnoreChanges">5.33. |
| openjpa.IgnoreChanges |
| </a></span></dt><dt><span class="section"><a href="#openjpa.Id">5.34. openjpa.Id</a></span></dt><dt><span class="section"><a href="#openjpa.InverseManager">5.35. |
| openjpa.InverseManager |
| </a></span></dt><dt><span class="section"><a href="#openjpa.LockManager">5.36. |
| openjpa.LockManager |
| </a></span></dt><dt><span class="section"><a href="#openjpa.LockTimeout">5.37. |
| openjpa.LockTimeout |
| </a></span></dt><dt><span class="section"><a href="#openjpa.Log">5.38. |
| openjpa.Log |
| </a></span></dt><dt><span class="section"><a href="#openjpa.ManagedRuntime">5.39. |
| openjpa.ManagedRuntime |
| </a></span></dt><dt><span class="section"><a href="#openjpa.Mapping">5.40. |
| openjpa.Mapping |
| </a></span></dt><dt><span class="section"><a href="#openjpa.MaxFetchDepth">5.41. |
| openjpa.MaxFetchDepth |
| </a></span></dt><dt><span class="section"><a href="#openjpa.MetaDataFactory">5.42. |
| openjpa.MetaDataFactory |
| </a></span></dt><dt><span class="section"><a href="#openjpa.MetaDataRepository">5.43. |
| openjpa.MetaDataRepository |
| </a></span></dt><dt><span class="section"><a href="#openjpa.Multithreaded">5.44. |
| openjpa.Multithreaded |
| </a></span></dt><dt><span class="section"><a href="#openjpa.Optimistic">5.45. |
| openjpa.Optimistic |
| </a></span></dt><dt><span class="section"><a href="#openjpa.OrphanedKeyAction">5.46. |
| openjpa.OrphanedKeyAction |
| </a></span></dt><dt><span class="section"><a href="#openjpa.NontransactionalRead">5.47. |
| openjpa.NontransactionalRead |
| </a></span></dt><dt><span class="section"><a href="#openjpa.NontransactionalWrite">5.48. |
| openjpa.NontransactionalWrite |
| </a></span></dt><dt><span class="section"><a href="#openjpa.ProxyManager">5.49. |
| openjpa.ProxyManager |
| </a></span></dt><dt><span class="section"><a href="#openjpa.QueryCache">5.50. |
| openjpa.QueryCache |
| </a></span></dt><dt><span class="section"><a href="#openjpa.QueryCompilationCache">5.51. |
| openjpa.QueryCompilationCache |
| </a></span></dt><dt><span class="section"><a href="#openjpa.ReadLockLevel">5.52. |
| openjpa.ReadLockLevel |
| </a></span></dt><dt><span class="section"><a href="#openjpa.RemoteCommitProvider">5.53. |
| openjpa.RemoteCommitProvider |
| </a></span></dt><dt><span class="section"><a href="#openjpa.RestoreState">5.54. |
| openjpa.RestoreState |
| </a></span></dt><dt><span class="section"><a href="#openjpa.RetainState">5.55. |
| openjpa.RetainState |
| </a></span></dt><dt><span class="section"><a href="#openjpa.RetryClassRegistration">5.56. |
| openjpa.RetryClassRegistration |
| </a></span></dt><dt><span class="section"><a href="#openjpa.RuntimeUnenhancedClasses">5.57. openjpa.RuntimeUnenhancedClasses</a></span></dt><dt><span class="section"><a href="#openjpa.SavepointManager">5.58. |
| openjpa.SavepointManager |
| </a></span></dt><dt><span class="section"><a href="#openjpa.Sequence">5.59. |
| openjpa.Sequence |
| </a></span></dt><dt><span class="section"><a href="#openjpa.TransactionMode">5.60. |
| openjpa.TransactionMode |
| </a></span></dt><dt><span class="section"><a href="#openjpa.WriteLockLevel">5.61. |
| openjpa.WriteLockLevel |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_conf_jdbc">6. |
| OpenJPA JDBC Properties |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#openjpa.jdbc.ConnectionDecorators">6.1. |
| openjpa.jdbc.ConnectionDecorators |
| </a></span></dt><dt><span class="section"><a href="#openjpa.jdbc.DBDictionary">6.2. |
| openjpa.jdbc.DBDictionary |
| </a></span></dt><dt><span class="section"><a href="#openjpa.jdbc.DriverDataSource">6.3. |
| openjpa.jdbc.DriverDataSource |
| </a></span></dt><dt><span class="section"><a href="#openjpa.jdbc.EagerFetchMode">6.4. |
| openjpa.jdbc.EagerFetchMode |
| </a></span></dt><dt><span class="section"><a href="#openjpa.jdbc.FetchDirection">6.5. |
| openjpa.jdbc.FetchDirection |
| </a></span></dt><dt><span class="section"><a href="#openjpa.jdbc.JDBCListeners">6.6. |
| openjpa.jdbc.JDBCListeners |
| </a></span></dt><dt><span class="section"><a href="#openjpa.jdbc.LRSSize">6.7. |
| openjpa.jdbc.LRSSize |
| </a></span></dt><dt><span class="section"><a href="#openjpa.jdbc.MappingDefaults">6.8. |
| openjpa.jdbc.MappingDefaults |
| </a></span></dt><dt><span class="section"><a href="#openjpa.jdbc.MappingFactory">6.9. |
| openjpa.jdbc.MappingFactory |
| </a></span></dt><dt><span class="section"><a href="#openjpa.jdbc.QuerySQLCache">6.10. |
| openjpa.jdbc.QuerySQLCache |
| </a></span></dt><dt><span class="section"><a href="#openjpa.jdbc.ResultSetType">6.11. |
| openjpa.jdbc.ResultSetType |
| </a></span></dt><dt><span class="section"><a href="#openjpa.jdbc.Schema">6.12. |
| openjpa.jdbc.Schema |
| </a></span></dt><dt><span class="section"><a href="#openjpa.jdbc.SchemaFactory">6.13. |
| openjpa.jdbc.SchemaFactory |
| </a></span></dt><dt><span class="section"><a href="#openjpa.jdbc.Schemas">6.14. |
| openjpa.jdbc.Schemas |
| </a></span></dt><dt><span class="section"><a href="#openjpa.jdbc.SQLFactory">6.15. |
| openjpa.jdbc.SQLFactory |
| </a></span></dt><dt><span class="section"><a href="#openjpa.jdbc.SubclassFetchMode">6.16. |
| openjpa.jdbc.SubclassFetchMode |
| </a></span></dt><dt><span class="section"><a href="#openjpa.jdbc.SynchronizeMappings">6.17. |
| openjpa.jdbc.SynchronizeMappings |
| </a></span></dt><dt><span class="section"><a href="#openjpa.jdbc.TransactionIsolation">6.18. |
| openjpa.jdbc.TransactionIsolation |
| </a></span></dt><dt><span class="section"><a href="#openjpa.jdbc.UpdateManager">6.19. |
| openjpa.jdbc.UpdateManager |
| </a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#ref_guide_logging">3. |
| Logging |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_logging_channels">1. |
| Logging Channels |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_logging_openjpa">2. |
| OpenJPA Logging |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_logging_noop">3. |
| Disabling Logging |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_logging_log4j">4. |
| Log4J |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_logging_commons">5. |
| Apache Commons Logging |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_logging_jdk14">5.1. |
| JDK 1.4 java.util.logging |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_logging_custom">6. |
| Custom Log |
| </a></span></dt></dl></dd><dt><span class="chapter"><a href="#ref_guide_dbsetup">4. |
| JDBC |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_dbsetup_builtin">1. |
| Using the OpenJPA DataSource |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_dbsetup_thirdparty">2. |
| Using a Third-Party DataSource |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_dbsetup_thirdparty_enlist">2.1. |
| Managed and XA DataSources |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_dbsetup_sqlconn">3. |
| Runtime Access to DataSource |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_dbsetup_dbsupport">4. |
| Database Support |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_dbsetup_dbdictprops">4.1. |
| DBDictionary Properties |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_dbsetup_dbsupport_mysql">4.2. |
| MySQLDictionary Properties |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_dbsetup_dbsupport_oracle">4.3. |
| OracleDictionary Properties |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_dbsetup_isolation">5. |
| Setting the Transaction Isolation |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_dbsetup_sql92">6. |
| Setting the SQL Join Syntax |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_dbsetup_multidb">7. |
| Accessing Multiple Databases |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_dbsetup_retain">8. |
| Configuring the Use of JDBC Connections |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_dbsetup_stmtbatch">9. |
| Statement Batching |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_dbsetup_lrs">10. |
| Large Result Sets |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_schema_def">11. |
| Default Schema |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_schema_info">12. |
| Schema Reflection |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_schema_info_list">12.1. |
| Schemas List |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_schema_info_factory">12.2. |
| Schema Factory |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_schema_schematool">13. |
| Schema Tool |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_schema_xml">14. |
| XML Schema Format |
| </a></span></dt></dl></dd><dt><span class="chapter"><a href="#ref_guide_pc">5. |
| Persistent Classes |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_pc_pcclasses">1. |
| Persistent Class List |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_pc_enhance">2. |
| Enhancement |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_pc_enhance_build">2.1. |
| Enhancing at Build Time |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_pc_enhance_runtime_container">2.2. |
| Enhancing JPA Entities on Deployment |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_pc_enhance_runtime">2.3. |
| Enhancing at Runtime |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_pc_enhance_unenhanced_types">2.4. |
| Omitting the OpenJPA enhancer |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_pc_interfaces">3. Managed Interfaces</a></span></dt><dt><span class="section"><a href="#ref_guide_pc_oid">4. |
| Object Identity |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_pc_oid_datastore">4.1. |
| Datastore Identity |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_pc_oid_entitypk">4.2. |
| Entities as Identity Fields |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_pc_oid_application">4.3. |
| Application Identity Tool |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_pc_oid_pkgen_autoinc">4.4. |
| Autoassign / Identity Strategy Caveats |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_inverses">5. |
| Managed Inverses |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_pc_scos">6. |
| Persistent Fields |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_pc_scos_restore">6.1. |
| Restoring State |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_pc_scos_order">6.2. |
| Typing and Ordering |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_pc_calendar_timezone">6.3. |
| Calendar Fields and TimeZones |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_pc_scos_proxy">6.4. |
| Proxies |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_pc_scos_proxy_smart">6.4.1. |
| Smart Proxies |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_pc_scos_proxy_lrs">6.4.2. |
| Large Result Set Proxies |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_pc_scos_proxy_custom">6.4.3. |
| Custom Proxies |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_pc_extern">6.5. |
| Externalization |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_pc_extern_values">6.5.1. |
| External Values |
| </a></span></dt></dl></dd></dl></dd><dt><span class="section"><a href="#ref_guide_fetch">7. |
| Fetch Groups |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_fetch_custom">7.1. |
| Custom Fetch Groups |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_fetch_conf">7.2. |
| Custom Fetch Group Configuration |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_fetch_single_field">7.3. |
| Per-field Fetch Configuration |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_fetch_impl">7.4. |
| Implementation Notes |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_perfpack_eager">8. |
| Eager Fetching |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_perfpack_eager_conf">8.1. |
| Configuring Eager Fetching |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_perfpack_eager_consider">8.2. |
| Eager Fetching Considerations and Limitations |
| </a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#ref_guide_meta">6. |
| Metadata |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_meta_factory">1. |
| Metadata Factory |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_meta_repository">2. Metadata Repository</a></span></dt><dt><span class="section"><a href="#ref_guide_meta_jpa">3. |
| Additional JPA Metadata |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_meta_jpa_datastoreid">3.1. |
| Datastore Identity |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_meta_jpa_version">3.2. |
| Surrogate Version |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_meta_jpa_persistent">3.3. |
| Persistent Field Values |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_meta_jpa_persistent_coll">3.4. Persistent Collection Fields</a></span></dt><dt><span class="section"><a href="#ref_guide_meta_jpa_persistent_map">3.5. Persistent Map Fields</a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_meta_ext">4. |
| Metadata Extensions |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_meta_class">4.1. |
| Class Extensions |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#fetch-groups">4.1.1. |
| Fetch Groups |
| </a></span></dt><dt><span class="section"><a href="#data-cache">4.1.2. |
| Data Cache |
| </a></span></dt><dt><span class="section"><a href="#detached-state-field">4.1.3. |
| Detached State |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_meta_field">4.2. |
| Field Extensions |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#dependent">4.2.1. |
| Dependent |
| </a></span></dt><dt><span class="section"><a href="#load-fetch-group">4.2.2. |
| Load Fetch Group |
| </a></span></dt><dt><span class="section"><a href="#lrs">4.2.3. |
| LRS |
| </a></span></dt><dt><span class="section"><a href="#inverse-logical">4.2.4. |
| Inverse-Logical |
| </a></span></dt><dt><span class="section"><a href="#read-only">4.2.5. |
| Read-Only |
| </a></span></dt><dt><span class="section"><a href="#type">4.2.6. |
| Type |
| </a></span></dt><dt><span class="section"><a href="#externalizer">4.2.7. |
| Externalizer |
| </a></span></dt><dt><span class="section"><a href="#factory">4.2.8. |
| Factory |
| </a></span></dt><dt><span class="section"><a href="#external-values">4.2.9. |
| External Values |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_meta_example">4.3. |
| Example |
| </a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#ref_guide_mapping">7. |
| Mapping |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_mapping_mappingtool">1. |
| Forward Mapping |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_mapping_mappingtool_examples">1.1. |
| Using the Mapping Tool |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_ddl_examples">1.2. |
| Generating DDL SQL |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_synch">1.3. |
| Runtime Forward Mapping |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_pc_reverse">2. |
| Reverse Mapping |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_pc_reverse_custom">2.1. |
| Customizing Reverse Mapping |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_mapping_middle">3. |
| Meet-in-the-Middle Mapping |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_defaults">4. |
| Mapping Defaults |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_factory">5. |
| Mapping Factory |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_notes_nonstdjoins">6. |
| Non-Standard Joins |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_jpa">7. |
| Additional JPA Mappings |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_mapping_jpa_datastoreid">7.1. |
| Datastore Identity Mapping |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_jpa_version">7.2. |
| Surrogate Version Mapping |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_jpa_columns">7.3. |
| Multi-Column Mappings |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_jpa_fieldjoin">7.4. |
| Join Column Attribute Targets |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_jpa_embed">7.5. |
| Embedded Mapping |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_jpa_coll">7.6. |
| Collections |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_mapping_jpa_coll_table">7.6.1. |
| Container Table |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_jpa_coll_joincols">7.6.2. |
| Element Join Columns |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_jpa_coll_order">7.6.3. |
| Order Column |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_mapping_jpa_onemany">7.7. |
| One-Sided One-Many Mapping |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_jpa_map">7.8. |
| Maps |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_jpa_constraints">7.9. |
| Indexes and Constraints |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_mapping_jpa_index">7.9.1. |
| Indexes |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_jpa_fk">7.9.2. |
| Foreign Keys |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_jpa_unique">7.9.3. |
| Unique Constraints |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_xmlmapping">7.10. |
| XML Column Mapping |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_streamsupport">7.11. |
| Stream LOB Support |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_mapping_jpa_map_keycols">8. Key Columns</a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_jpa_map_keyjoincols">9. Key Join Columns</a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_jpa_map_embedkey">10. Key Embedded Mapping</a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_jpa_map_ex">11. Examples</a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_limits">12. |
| Mapping Limitations |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_mapping_limits_tpc">12.1. |
| Table Per Class |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_mapping_ext">13. |
| Mapping Extensions |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_mapping_ext_cls">13.1. |
| Class Extensions |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#subclass-fetch-mode">13.1.1. |
| Subclass Fetch Mode |
| </a></span></dt><dt><span class="section"><a href="#class-strategy">13.1.2. |
| Strategy |
| </a></span></dt><dt><span class="section"><a href="#discriminator-strategy">13.1.3. |
| Discriminator Strategy |
| </a></span></dt><dt><span class="section"><a href="#version-strategy">13.1.4. |
| Version Strategy |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_mapping_ext_field">13.2. |
| Field Extensions |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#eager-fetch-mode">13.2.1. |
| Eager Fetch Mode |
| </a></span></dt><dt><span class="section"><a href="#nonpolymorphic">13.2.2. |
| Nonpolymorphic |
| </a></span></dt><dt><span class="section"><a href="#class-criteria">13.2.3. |
| Class Criteria |
| </a></span></dt><dt><span class="section"><a href="#strategy">13.2.4. |
| Strategy |
| </a></span></dt></dl></dd></dl></dd><dt><span class="section"><a href="#ref_guide_mapping_custom">14. |
| Custom Mappings |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_mapping_custom_class">14.1. |
| Custom Class Mapping |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_custom_versdiscrim">14.2. |
| Custom Discriminator and Version Strategies |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_custom_field">14.3. |
| Custom Field Mapping |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_mapping_custom_vhandler">14.3.1. |
| Value Handlers |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_custom_fieldstrat">14.3.2. |
| Field Strategies |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_custom_field_conf">14.3.3. |
| Configuration |
| </a></span></dt></dl></dd></dl></dd><dt><span class="section"><a href="#ref_guide_orphan">15. |
| Orphaned Keys |
| </a></span></dt></dl></dd><dt><span class="chapter"><a href="#ref_guide_deploy">8. |
| Deployment |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_deploy_factory">1. |
| Factory Deployment |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_deploy_factory_standalone">1.1. |
| Standalone Deployment |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_deploy_inject">1.2. |
| EntityManager Injection |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_enterprise_trans">2. |
| Integrating with the Transaction Manager |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_enterprise_xa">3. |
| XA Transactions |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_enterprise_xa_req">3.1. |
| Using OpenJPA with XA Transactions |
| </a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#ref_guide_runtime">9. |
| Runtime Extensions |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_runtime_arch">1. |
| Architecture |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_runtime_broker_finalization">1.1. |
| Broker Finalization |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_runtime_broker_extension">1.2. |
| Broker Customization and Eviction |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_runtime_jpa">2. |
| JPA Extensions |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_runtime_emfactory">2.1. |
| OpenJPAEntityManagerFactory |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_runtime_em">2.2. |
| OpenJPAEntityManager |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_runtime_jpaquery">2.3. |
| OpenJPAQuery |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_runtime_jpaextent">2.4. |
| Extent |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_runtime_jpacache">2.5. |
| StoreCache |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_runtime_jpaquerycache">2.6. |
| QueryResultCache |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_runtime_jpafetch">2.7. |
| FetchPlan |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_runtime_openjpaentitytransaction">2.8. |
| OpenJPAEntityTransaction |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_runtime_openjpapersistence">2.9. |
| OpenJPAPersistence |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_locking">3. |
| Object Locking |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_locking_default">3.1. |
| Configuring Default Locking |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_locking_runtime">3.2. |
| Configuring Lock Levels at Runtime |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_locking_apis">3.3. |
| Object Locking APIs |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_locking_lockmgr">3.4. |
| Lock Manager |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_locking_rules">3.5. |
| Rules for Locking Behavior |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_locking_issues">3.6. |
| Known Issues and Limitations |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_savepoints">4. |
| Savepoints |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#reg_guide_savepoints_using">4.1. |
| Using Savepoints |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_savepoints_conf">4.2. |
| Configuring Savepoints |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_enterprise_methodql">5. |
| MethodQL |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_sequence">6. |
| Generators |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_sequence_runtime">6.1. |
| Runtime Access |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_runtime_pm_event">7. |
| Transaction Events |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_enterprise_abstractstore">8. |
| Non-Relational Stores |
| </a></span></dt></dl></dd><dt><span class="chapter"><a href="#ref_guide_caching">10. |
| Caching |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_cache">1. |
| Data Cache |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_cache_conf">1.1. |
| Data Cache Configuration |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_cache_use">1.2. |
| Data Cache Usage |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_cache_query">1.3. |
| Query Cache |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_cache_extension">1.4. |
| Cache Extension |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_cache_notes">1.5. |
| Important Notes |
| </a></span></dt><dt><span class="section"><a href="#datastore_cache_issues">1.6. |
| Known Issues and Limitations |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_cache_querycomp">2. |
| Query Compilation Cache |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_cache_querysql">3. |
| Query SQL Cache |
| </a></span></dt></dl></dd><dt><span class="chapter"><a href="#ref_guide_remote">11. |
| Remote and Offline Operation |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_detach">1. |
| Detach and Attach |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_detach_behavior">1.1. |
| Detach Behavior |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_attach_behavior">1.2. |
| Attach Behavior |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_detach_graph">1.3. |
| Defining the Detached Object Graph |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_detach_field">1.3.1. |
| Detached State Field |
| </a></span></dt></dl></dd></dl></dd><dt><span class="section"><a href="#ref_guide_event">2. |
| Remote Event Notification Framework |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_event_conf">2.1. |
| Remote Commit Provider Configuration |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_event_conf_jms">2.1.1. |
| JMS |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_event_conf_tcp">2.1.2. |
| TCP |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_event_conf_common">2.1.3. |
| Common Properties |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_event_customization">2.2. |
| Customization |
| </a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#ref_guide_slice">12. |
| Distributed Persistence |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#slice_overview">1. Overview</a></span></dt><dt><span class="section"><a href="#Features and Limitations">2. Salient Features</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e31151">2.1. Transparency</a></span></dt><dt><span class="section"><a href="#d0e31159">2.2. Custom Distribution Policy</a></span></dt><dt><span class="section"><a href="#d0e31188">2.3. Heterogeneous Database</a></span></dt><dt><span class="section"><a href="#d0e31193">2.4. Parallel Execution</a></span></dt><dt><span class="section"><a href="#d0e31198">2.5. Distributed Query</a></span></dt><dt><span class="section"><a href="#d0e31232">2.6. Targeted Query</a></span></dt><dt><span class="section"><a href="#d0e31249">2.7. Distributed Transaction</a></span></dt><dt><span class="section"><a href="#collocation_constraint">2.8. Collocation Constraint</a></span></dt></dl></dd><dt><span class="section"><a href="#slice_configuration">3. Usage</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e31286">3.1. How to activate Slice Runtime?</a></span></dt><dt><span class="section"><a href="#d0e31297">3.2. How to configure each database slice?</a></span></dt><dt><span class="section"><a href="#distribution_policy">3.3. Implement DistributionPolicy interface</a></span></dt><dt><span class="section"><a href="#d0e31411">3.4. </a></span></dt></dl></dd><dt><span class="section"><a href="#d0e31422">4. Global Properties</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e31425">4.1. openjpa.slice.DistributionPolicy</a></span></dt><dt><span class="section"><a href="#d0e31439">4.2. openjpa.slice.Lenient</a></span></dt><dt><span class="section"><a href="#d0e31455">4.3. openjpa.slice.Master</a></span></dt><dt><span class="section"><a href="#d0e31467">4.4. openjpa.slice.Names</a></span></dt><dt><span class="section"><a href="#d0e31482">4.5. openjpa.slice.ThreadingPolicy</a></span></dt><dt><span class="section"><a href="#d0e31553">4.6. openjpa.slice.TransactionPolicy</a></span></dt></dl></dd><dt><span class="section"><a href="#d0e31599">5. Per-Slice Properties</a></span></dt></dl></dd><dt><span class="chapter"><a href="#ref_guide_integration">13. |
| Third Party Integration |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_integration_ant">1. |
| Apache Ant |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_integration_conf">1.1. |
| Common Ant Configuration Options |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_integration_enhance">1.2. |
| Enhancer Ant Task |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_integration_appidtool">1.3. |
| Application Identity Tool Ant Task |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_integration_mappingtool">1.4. |
| Mapping Tool Ant Task |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_integration_revmappingtool">1.5. |
| Reverse Mapping Tool Ant Task |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_integration_schematool">1.6. |
| Schema Tool Ant Task |
| </a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#ref_guide_optimization">14. |
| Optimization Guidelines |
| </a></span></dt></dl></dd><dt><span class="appendix"><a href="#jpa_resources">1. |
| JPA Resources |
| </a></span></dt><dt><span class="appendix"><a href="#supported_databases">2. |
| Supported Databases |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#dbsupport_derby">1. |
| Apache Derby |
| </a></span></dt><dt><span class="section"><a href="#dbsupport_interbase">2. |
| Borland Interbase |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#dbsupport_interbase_issues">2.1. |
| Known issues with Interbase |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#dbsupport_jdatastore">3. |
| JDataStore |
| </a></span></dt><dt><span class="section"><a href="#dbsupport_db2">4. |
| IBM DB2 |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#dbsupport_db2_issues">4.1. |
| Known issues with DB2 |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#dbsupport_empress">5. |
| Empress |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#dbsupport_empress_issues">5.1. |
| Known issues with Empress |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#dbsupport_h2">6. |
| H2 Database Engine |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#dbsupport_h2_issues">6.1. |
| Known issues with H2 Database Engine |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#dbsupport_hypersonic">7. |
| Hypersonic |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#dbsupport_hypersonic_issues">7.1. |
| Known issues with Hypersonic |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#dbsupport_firebird">8. |
| Firebird |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#dbsupport_firebird_issues">8.1. |
| Known issues with Firebird |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#dbsupport_informix">9. |
| Informix |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#dbsupport_informix_issues">9.1. |
| Known issues with Informix |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#dbsupport_intersystems_cache">10. |
| InterSystems Cache |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#dbsupport_intersystems_cache_issues">10.1. |
| Known issues with InterSystems Cache |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#dbsupport_access">11. |
| Microsoft Access |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#dbsupport_access_issues">11.1. |
| Known issues with Microsoft Access |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#dbsupport_sqlserver">12. |
| Microsoft SQL Server |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#dbsupport_sqlserver_issues">12.1. |
| Known issues with SQL Server |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#dbsupport_foxpro">13. |
| Microsoft FoxPro |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#dbsupport_foxpro_issues">13.1. |
| Known issues with Microsoft FoxPro |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#dbsupport_mysql">14. |
| MySQL |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#dbsupport_mysql_issues">14.1. |
| Known issues with MySQL |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#dbsupport_oracle">15. |
| Oracle |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#dbsupport_oracle_query_hints">15.1. |
| Using Query Hints with Oracle |
| </a></span></dt><dt><span class="section"><a href="#dbsupport_oracle_issues">15.2. |
| Known issues with Oracle |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#dbsupport_pointbase">16. |
| Pointbase |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#dbsupport_pointbase_issues">16.1. |
| Known issues with Pointbase |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#dbsupport_postgresql">17. |
| PostgreSQL |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#dbsupport_postgresql_issues">17.1. |
| Known issues with PostgreSQL |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#dbsupport_sybase">18. |
| Sybase Adaptive Server |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#dbsupport_sybase_issues">18.1. |
| Known issues with Sybase |
| </a></span></dt></dl></dd></dl></dd></dl></div><div class="list-of-tables"><p><b>List of Tables</b></p><dl><dt>2.1. <a href="#d0e103"> |
| Persistence Mechanisms |
| </a></dt><dt>10.1. <a href="#d0e6436"> |
| Interaction of ReadLockMode hint and LockManager |
| </a></dt><dt>4.1. <a href="#d0e20992"> |
| OpenJPA Automatic Flush Behavior |
| </a></dt><dt>5.1. <a href="#d0e23070"> |
| Externalizer Options |
| </a></dt><dt>5.2. <a href="#d0e23142"> |
| Factory Options |
| </a></dt><dt>10.1. <a href="#d0e29786"> |
| Data access methods |
| </a></dt><dt>10.2. <a href="#d0e30388"> |
| Pre-defined aliases |
| </a></dt><dt>10.3. <a href="#d0e30467"> |
| Pre-defined aliases |
| </a></dt><dt>14.1. <a href="#d0e31996"> |
| Optimization Guidelines |
| </a></dt><dt>2.1. <a href="#d0e32625"> |
| Supported Databases and JDBC Drivers |
| </a></dt></dl></div><div class="list-of-examples"><p><b>List of Examples</b></p><dl><dt>3.1. <a href="#jpa_overview_arch_interact_outside"> |
| Interaction of Interfaces Outside Container |
| </a></dt><dt>3.2. <a href="#jpa_overview_arch_interact_inside"> |
| Interaction of Interfaces Inside Container |
| </a></dt><dt>4.1. <a href="#jpa_overview_pc_pcclass"> |
| Persistent Class |
| </a></dt><dt>4.2. <a href="#jpa_overview_pc_identity_appidcode"> |
| Identity Class |
| </a></dt><dt>5.1. <a href="#jpa_overview_meta_classlisting"> |
| Class Metadata |
| </a></dt><dt>5.2. <a href="#jpa_overview_meta_complete_ex"> |
| Complete Metadata |
| </a></dt><dt>6.1. <a href="#jpa_overview_persistence_xmlex"> |
| persistence.xml |
| </a></dt><dt>6.2. <a href="#jpa_overview_persistence_getemfactory"> |
| Obtaining an EntityManagerFactory |
| </a></dt><dt>7.1. <a href="#jpa_overview_emfactory_perscontext_transex"> |
| Behavior of Transaction Persistence Context |
| </a></dt><dt>7.2. <a href="#jpa_overview_emfactory_perscontext_extendex"> |
| Behavior of Extended Persistence Context |
| </a></dt><dt>8.1. <a href="#jpa_overview_em_lifecycle_persist"> |
| Persisting Objects |
| </a></dt><dt>8.2. <a href="#jpa_overview_em_lifecycle_update"> |
| Updating Objects |
| </a></dt><dt>8.3. <a href="#jpa_overview_em_lifecycle_delete"> |
| Removing Objects |
| </a></dt><dt>8.4. <a href="#jpa_overview_em_detachex"> |
| Detaching and Merging |
| </a></dt><dt>9.1. <a href="#jpa_overview_trans_group"> |
| Grouping Operations with Transactions |
| </a></dt><dt>10.1. <a href="#jpa_query_hint1"> |
| Query Hints |
| </a></dt><dt>10.2. <a href="#jpa_query_hint2"> |
| Named Query using Hints |
| </a></dt><dt>10.3. <a href="#jpa_overview_query_deleteex"> |
| Delete by Query |
| </a></dt><dt>10.4. <a href="#jpa_overview_query_updateex"> |
| Update by Query |
| </a></dt><dt>11.1. <a href="#jpa_overview_sqlquery_createex"> |
| Creating a SQL Query |
| </a></dt><dt>11.2. <a href="#jpa_overview_sqlquery_objex"> |
| Retrieving Persistent Objects |
| </a></dt><dt>11.3. <a href="#jpa_overview_sqlquery_obj_paramex"> |
| SQL Query Parameters |
| </a></dt><dt>12.1. <a href="#jpa_overview_mapping_classex"> |
| Mapping Classes |
| </a></dt><dt>12.2. <a href="#jpa_overview_mapping_unq_attrex"> |
| Defining a Unique Constraint |
| </a></dt><dt>12.3. <a href="#jpa_overview_mapping_identityex"> |
| Identity Mapping |
| </a></dt><dt>12.4. <a href="#jpa_overview_mapping_sequenceex"> |
| Generator Mapping |
| </a></dt><dt>12.5. <a href="#jpa_overview_mapping_inher_singleex"> |
| Single Table Mapping |
| </a></dt><dt>12.6. <a href="#jpa_overview_mapping_inher_joinedex"> |
| Joined Subclass Tables |
| </a></dt><dt>12.7. <a href="#jpa_overview_mapping_inher_tpcex"> |
| Table Per Class Mapping |
| </a></dt><dt>12.8. <a href="#jpa_overview_mapping_inher_togetherex"> |
| Inheritance Mapping |
| </a></dt><dt>12.9. <a href="#jpa_overview_mapping_discrimex"> |
| Discriminator Mapping |
| </a></dt><dt>12.10. <a href="#jpa_overview_mapping_basicex"> |
| Basic Field Mapping |
| </a></dt><dt>12.11. <a href="#jpa_overview_mapping_secondaryex"> |
| Secondary Table Field Mapping |
| </a></dt><dt>12.12. <a href="#jpa_overview_mapping_embedex"> |
| Embedded Field Mapping |
| </a></dt><dt>12.13. <a href="#jpa_overview_mapping_joined_overex"> |
| Mapping Mapped Superclass Field |
| </a></dt><dt>12.14. <a href="#jpa_overview_mapping_relex"> |
| Direct Relation Field Mapping |
| </a></dt><dt>12.15. <a href="#jpa_overview_mapping_assoccollex"> |
| Join Table Mapping |
| </a></dt><dt>12.16. <a href="#jpa_overview_mapping_mapex"> |
| Join Table Map Mapping |
| </a></dt><dt>12.17. <a href="#jpa_overview_mapping_fullex"> |
| Full Entity Mappings |
| </a></dt><dt>2.1. <a href="#ref_guide_conf_devtools_format_ex"> |
| Code Formatting with the Application Id Tool |
| </a></dt><dt>3.1. <a href="#ref_guide_logging_openjpa_std_ex"> |
| Standard OpenJPA Log Configuration |
| </a></dt><dt>3.2. <a href="#ref_guide_logging_openjpa_sql_ex"> |
| Standard OpenJPA Log Configuration + All SQL Statements |
| </a></dt><dt>3.3. <a href="#ref_guide_logging_openjpa_file"> |
| Logging to a File |
| </a></dt><dt>3.4. <a href="#ref_guide_logging_log4j_ex"> |
| Standard Log4J Logging |
| </a></dt><dt>3.5. <a href="#ref_guide_logging_jdk14_propfile"> |
| JDK 1.4 Log Properties |
| </a></dt><dt>3.6. <a href="#ref_guide_logging_custom_ex"> |
| Custom Logging Class |
| </a></dt><dt>4.1. <a href="#ref_guide_dbsetup_builtin_ex"> |
| Properties for the OpenJPA DataSource |
| </a></dt><dt>4.2. <a href="#ref_guide_dbsetup_thirdparty_ex"> |
| Properties File for a Third-Party DataSource |
| </a></dt><dt>4.3. <a href="#ref_guide_enterprise_xa_conf_ex"> |
| Managed DataSource Configuration |
| </a></dt><dt>4.4. <a href="#ref_guide_dbsetup_conn_jpa"> |
| Using the EntityManager's Connection |
| </a></dt><dt>4.5. <a href="#ref_guide_dbsetup_conn_from_factory_jpa"> |
| Using the EntityManagerFactory's DataSource |
| </a></dt><dt>4.6. <a href="#ref_guide_dbsetup_dbdict"> |
| Specifying a DBDictionary |
| </a></dt><dt>4.7. <a href="#ref_guide_dbsetup_isoex"> |
| Specifying a Transaction Isolation |
| </a></dt><dt>4.8. <a href="#ref_guide_dbsetup_sql92_conf"> |
| Specifying the Join Syntax Default |
| </a></dt><dt>4.9. <a href="#ref_guide_dbsetup_sql92_fetch"> |
| Specifying the Join Syntax at Runtime |
| </a></dt><dt>4.10. <a href="#ref_guide_dbsetup_sql92_retain_conf"> |
| Specifying Connection Usage Defaults |
| </a></dt><dt>4.11. <a href="#ref_guide_dbsetup_sql92_retain_runtime"> |
| Specifying Connection Usage at Runtime |
| </a></dt><dt>4.12. <a href="#ref_guide_dbsetup_stmtbatch_exmple1"> |
| Enable SQL statement batching |
| </a></dt><dt>4.13. <a href="#ref_guide_dbsetup_stmtbatch_exmple2"> |
| Disable SQL statement batching |
| </a></dt><dt>4.14. <a href="#ref_guide_dbsetup_stmtbatch_exmple3"> |
| Plug-in custom statement batching implementation |
| </a></dt><dt>4.15. <a href="#ref_guide_dbsetup_lrs_def"> |
| Specifying Result Set Defaults |
| </a></dt><dt>4.16. <a href="#ref_guide_dbsetup_lrs_runtime"> |
| Specifying Result Set Behavior at Runtime |
| </a></dt><dt>4.17. <a href="#ref_guide_schema_schematool_create"> |
| Schema Creation |
| </a></dt><dt>4.18. <a href="#ref_guide_schema_schematool_script"> |
| SQL Scripting |
| </a></dt><dt>4.19. <a href="#ref_guide_schema_schematool_table_cleanup"> |
| Table Cleanup |
| </a></dt><dt>4.20. <a href="#ref_guide_schema_schematool_drop"> |
| Schema Drop |
| </a></dt><dt>4.21. <a href="#ref_guide_schema_schematool_reflect"> |
| Schema Reflection |
| </a></dt><dt>4.22. <a href="#ref_guide_schema_xml_basic"> |
| Basic Schema |
| </a></dt><dt>4.23. <a href="#ref_guide_schema_xml_full"> |
| Full Schema |
| </a></dt><dt>5.1. <a href="#ref_guide_pc_enhance_enhancer"> |
| Using the OpenJPA Enhancer |
| </a></dt><dt>5.2. <a href="#ref_guide_pc_enhance_runtime_ex"> |
| Using the OpenJPA Agent for Runtime Enhancement |
| </a></dt><dt>5.3. <a href="#ref_guide_pc_enhance_runtime_opt_ex"> |
| Passing Options to the OpenJPA Agent |
| </a></dt><dt>5.4. <a href="#ref_guide_pc_oid_datastoreentityex"> |
| JPA Datastore Identity Metadata |
| </a></dt><dt>5.5. <a href="#ref_guide_pc_oid_entitypk_simplefind"> |
| Finding an Entity with an Entity Identity Field |
| </a></dt><dt>5.6. <a href="#ref_guide_pc_oid_entitypk_idcls"> |
| Id Class for Entity Identity Fields |
| </a></dt><dt>5.7. <a href="#ref_guide_pc_appid_appidtool"> |
| Using the Application Identity Tool |
| </a></dt><dt>5.8. <a href="#ref_guide_inverses_logicalex"> |
| Specifying Logical Inverses |
| </a></dt><dt>5.9. <a href="#ref_guide_inversesex"> |
| Enabling Managed Inverses |
| </a></dt><dt>5.10. <a href="#ref_guide_inverses_logex"> |
| Log Inconsistencies |
| </a></dt><dt>5.11. <a href="#ref_guide_pc_scos_order_initialvals"> |
| Using Initial Field Values |
| </a></dt><dt>5.12. <a href="#ref_guide_pc_scos_proxy_lrs_itr"> |
| Using a Large Result Set Iterator |
| </a></dt><dt>5.13. <a href="#ref_guide_pc_scos_proxy_lrs_extension"> |
| Marking a Large Result Set Field |
| </a></dt><dt>5.14. <a href="#ref_guide_pc_scos_proxy_custom_ex"> |
| Configuring the Proxy Manager |
| </a></dt><dt>5.15. <a href="#ref_guide_pc_externex"> |
| Using Externalization |
| </a></dt><dt>5.16. <a href="#ref_guide_pc_extern_queryex"> |
| Querying Externalization Fields |
| </a></dt><dt>5.17. <a href="#externvalues_ex"> |
| Using External Values |
| </a></dt><dt>5.18. <a href="#ref_guide_fetch_customgroups"> |
| Custom Fetch Group Metadata |
| </a></dt><dt>5.19. <a href="#ref_guide_fetch_loadgroup"> |
| Load Fetch Group Metadata |
| </a></dt><dt>5.20. <a href="#ref_guide_fetch_conf_query"> |
| Using the FetchPlan |
| </a></dt><dt>5.21. <a href="#ref_guide_fetch-conf_per_field"> |
| Adding an Eager Field |
| </a></dt><dt>5.22. <a href="#ref_guide_perfpack_eager_def"> |
| Setting the Default Eager Fetch Mode |
| </a></dt><dt>5.23. <a href="#ref_guide_perfpack_eager_runtime"> |
| Setting the Eager Fetch Mode at Runtime |
| </a></dt><dt>6.1. <a href="#ref_guide_meta_stdfactoryex"> |
| Setting a Standard Metadata Factory |
| </a></dt><dt>6.2. <a href="#ref_guide_meta_customfactoryex"> |
| Setting a Custom Metadata Factory |
| </a></dt><dt>6.3. <a href="#ref_guide_meta_repo"></a></dt><dt>6.4. <a href="#ref_guide_metaex"> |
| OpenJPA Metadata Extensions |
| </a></dt><dt>7.1. <a href="#ref_guide_mapping_mappingtool_typical"> |
| Using the Mapping Tool |
| </a></dt><dt>7.2. <a href="#ref_guide_mapping_mappingtool_buildschema"> |
| Creating the Relational Schema from Mappings |
| </a></dt><dt>7.3. <a href="#ref_guide_mapping_mappingtool_cleanup_tables"> |
| Refreshing entire schema and cleaning out tables |
| </a></dt><dt>7.4. <a href="#ref_guide_mapping_mappingtool_dropschema"> |
| Dropping Mappings and Association Schema |
| </a></dt><dt>7.5. <a href="#ref_guid_mapping_ddl_full_ddl"> |
| Create DDL for Current Mappings |
| </a></dt><dt>7.6. <a href="#ref_guid_mapping_ddl_part_ddl"> |
| Create DDL to Update Database for Current Mappings |
| </a></dt><dt>7.7. <a href="#ref_guide_mapping_synchex"> |
| Configuring Runtime Forward Mapping |
| </a></dt><dt>7.8. <a href="#ref_guide_pc_reverse_schemagen"> |
| Reflection with the Schema Tool |
| </a></dt><dt>7.9. <a href="#ref_guide_pc_reverse_reversemappingtool"> |
| Using the Reverse Mapping Tool |
| </a></dt><dt>7.10. <a href="#ref_guide_pc_reverse_custom_ex"> |
| Customizing Reverse Mapping with Properties |
| </a></dt><dt>7.11. <a href="#ref_guide_mapping_mappingtool_validate"> |
| Validating Mappings |
| </a></dt><dt>7.12. <a href="#ref_guide_mapping_defaults_conf"> |
| Configuring Mapping Defaults |
| </a></dt><dt>7.13. <a href="#ref_guide_mapping_factory_jpa"> |
| Standard JPA Configuration |
| </a></dt><dt>7.14. <a href="#ref_guide_mapping_jpa_datastoreidex"> |
| Datastore Identity Mapping |
| </a></dt><dt>7.15. <a href="#ref_guide_mapping_jpa_embedex"> |
| Overriding Complex Mappings |
| </a></dt><dt>7.16. <a href="#ref_guide_mapping_jpa_onemanyex"> |
| One-Sided One-Many Mapping |
| </a></dt><dt>7.17. <a href="#ref_guide_xmlmapping_myaddress"> |
| myaddress.xsd |
| </a></dt><dt>7.18. <a href="#ref_guide_xmlmapping_address"> |
| Address.Java |
| </a></dt><dt>7.19. <a href="#ref_guide_xmlmapping_usaaddress"> |
| USAAddress.java |
| </a></dt><dt>7.20. <a href="#ref_guide_xmlmapping_canaddress"> |
| CANAddress.java |
| </a></dt><dt>7.21. <a href="#ref_guide_xmlmapping_annorder"> |
| Showing annotated Order entity with XML mapping strategy |
| </a></dt><dt>7.22. <a href="#ref_guide_xmlmapping_createorder"> |
| Showing creation of Order Entity having shipAddress mapped to XML column |
| </a></dt><dt>7.23. <a href="#ref_guide_xmlmapping_ejbquery"> |
| Sample EJB Queries for XML Column mapping |
| </a></dt><dt>7.24. <a href="#ref_guide_streamsupport_example"> |
| Showing annotated InputStream |
| </a></dt><dt>7.25. <a href="#ref_guide_mapping_jpa_map_stringrelmap">String Key, Entity Value Map Mapping</a></dt><dt>7.26. <a href="#ref_guide_orphan_logex"> |
| Custom Logging Orphaned Keys |
| </a></dt><dt>8.1. <a href="#ref_guide_enterprise_transex">Configuring Transaction Manager Integration</a></dt><dt>9.1. <a href="#ref_guide_runtime_pm_evictex"> |
| Evict from Data Cache |
| </a></dt><dt>9.2. <a href="#ref_guide_runtime_jpaextentex"> |
| Using a JPA Extent |
| </a></dt><dt>9.3. <a href="#ref_guide_locking_default_conf"> |
| Setting Default Lock Levels |
| </a></dt><dt>9.4. <a href="#ref_guide_locking_fetch"> |
| Setting Runtime Lock Levels |
| </a></dt><dt>9.5. <a href="#ref_guide_locking_explicit"> |
| Locking APIs |
| </a></dt><dt>9.6. <a href="#ref_guide_locking_disable"> |
| Disabling Locking |
| </a></dt><dt>9.7. <a href="#ref_guide_savepoints_example"> |
| Using Savepoints |
| </a></dt><dt>9.8. <a href="#ref_guide_sequence_named"> |
| Named Seq Sequence |
| </a></dt><dt>9.9. <a href="#ref_guide_sequence_systemex"> |
| System Sequence Configuration |
| </a></dt><dt>10.1. <a href="#ref_guide_cache_conf_sjvm"> |
| Single-JVM Data Cache |
| </a></dt><dt>10.2. <a href="#ref_guide_cache_conf_size"> |
| Data Cache Size |
| </a></dt><dt>10.3. <a href="#ex_timeout_cache"> |
| Data Cache Timeout |
| </a></dt><dt>10.4. <a href="#ex_exclude_types_from_cache"> |
| Excluding entities |
| </a></dt><dt>10.5. <a href="#ex_include_types_in_cache"> |
| Including entities |
| </a></dt><dt>10.6. <a href="#ref_guide_cache_access_jpa"> |
| Accessing the StoreCache |
| </a></dt><dt>10.7. <a href="#ref_guide_cache_use_jpa"> |
| StoreCache Usage |
| </a></dt><dt>10.8. <a href="#ref_guide_cache_pmevict"> |
| Automatic Data Cache Eviction |
| </a></dt><dt>10.9. <a href="#ref_guide_cache_queryaccess"> |
| Accessing the QueryResultCache |
| </a></dt><dt>10.10. <a href="#ref_guide_cache_cachesize"> |
| Query Cache Size |
| </a></dt><dt>10.11. <a href="#ref_guide_cache_disablequery"> |
| Disabling the Query Cache |
| </a></dt><dt>10.12. <a href="#ref_guide_cache_query_classchange"> |
| Evicting Queries |
| </a></dt><dt>10.13. <a href="#ref_guide_cache_query_pin"> |
| Pinning, and Unpinning Query Results |
| </a></dt><dt>10.14. <a href="#ref_guide_cache_query_disable"> |
| Disabling and Enabling Query Caching |
| </a></dt><dt>10.15. <a href="#ref_guide_cache_limits_extent"> |
| Query Replaces Extent |
| </a></dt><dt>11.1. <a href="#ref_guide_detach_graph_confex"> |
| Configuring Detached State |
| </a></dt><dt>11.2. <a href="#ref_guide_event_conf_jmsex"> |
| JMS Remote Commit Provider Configuration |
| </a></dt><dt>11.3. <a href="#ref_guide_event_conf_tcpex"> |
| TCP Remote Commit Provider Configuration |
| </a></dt><dt>11.4. <a href="#ref_guide_event_conf_jms2ex"> |
| JMS Remote Commit Provider transmitting Persisted Object Ids |
| </a></dt><dt>13.1. <a href="#ref_guide_integration_conf_config"> |
| Using the <config> Ant Tag |
| </a></dt><dt>13.2. <a href="#ref_guide_integration_props"> |
| Using the Properties Attribute of the <config> Tag |
| </a></dt><dt>13.3. <a href="#ref_guide_integration_propsfile"> |
| Using the PropertiesFile Attribute of the <config> Tag |
| </a></dt><dt>13.4. <a href="#ref_guide_integration_conf_classpath"> |
| Using the <classpath> Ant Tag |
| </a></dt><dt>13.5. <a href="#ref_guide_integration_conf_codeformat"> |
| Using the <codeformat> Ant Tag |
| </a></dt><dt>13.6. <a href="#ref_guide_integration_enhance_task"> |
| Invoking the Enhancer from Ant |
| </a></dt><dt>13.7. <a href="#ref_guide_integration_appidtool_task"> |
| Invoking the Application Identity Tool from Ant |
| </a></dt><dt>13.8. <a href="#ref_guide_integration_mappingtool_task"> |
| Invoking the Mapping Tool from Ant |
| </a></dt><dt>13.9. <a href="#ref_guide_integration_revmappingtool_task"> |
| Invoking the Reverse Mapping Tool from Ant |
| </a></dt><dt>13.10. <a href="#ref_guide_integration_schematool_task"> |
| Invoking the Schema Tool from Ant |
| </a></dt><dt>2.1. <a href="#example_props_derby"> |
| Example properties for Derby |
| </a></dt><dt>2.2. <a href="#example_props_interbase"> |
| Example properties for Interbase |
| </a></dt><dt>2.3. <a href="#example_props_jdatastore"> |
| Example properties for JDataStore |
| </a></dt><dt>2.4. <a href="#example_props_db2"> |
| Example properties for IBM DB2 |
| </a></dt><dt>2.5. <a href="#example_props_empress"> |
| Example properties for Empress |
| </a></dt><dt>2.6. <a href="#example_props_h2"> |
| Example properties for H2 Database Engine |
| </a></dt><dt>2.7. <a href="#example_props_hypersonic"> |
| Example properties for Hypersonic |
| </a></dt><dt>2.8. <a href="#example_props_firebird"> |
| Example properties for Firebird |
| </a></dt><dt>2.9. <a href="#example_props_informix"> |
| Example properties for Informix Dynamic Server |
| </a></dt><dt>2.10. <a href="#example_props_intersystems_cache"> |
| Example properties for InterSystems Cache |
| </a></dt><dt>2.11. <a href="#example_props_access"> |
| Example properties for Microsoft Access |
| </a></dt><dt>2.12. <a href="#example_props_sqlserver"> |
| Example properties for Microsoft SQLServer |
| </a></dt><dt>2.13. <a href="#example_props_foxpro"> |
| Example properties for Microsoft FoxPro |
| </a></dt><dt>2.14. <a href="#example_props_mysql"> |
| Example properties for MySQL |
| </a></dt><dt>2.15. <a href="#example_props_oracle"> |
| Example properties for Oracle |
| </a></dt><dt>2.16. <a href="#dbsupport_oracle_query_hints_ex"> |
| Using Oracle Hints |
| </a></dt><dt>2.17. <a href="#example_props_pointbase"> |
| Example properties for Pointbase |
| </a></dt><dt>2.18. <a href="#example_props_postgresql"> |
| Example properties for PostgreSQL |
| </a></dt><dt>2.19. <a href="#example_props_sybase"> |
| Example properties for Sybase |
| </a></dt></dl></div><div class="part" lang="en" id="introduction"><div class="titlepage"><div><div><h1 class="title"><a name="introduction"></a>Part 1. Introduction</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="chapter"><a href="#openjpa_intro">1. |
| OpenJPA |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#openjpa_intro_about">1. |
| About This Document |
| </a></span></dt></dl></dd></dl></div><div class="chapter" lang="en" id="openjpa_intro"><div class="titlepage"><div><div><h2 class="title"><a name="openjpa_intro"></a>Chapter 1. |
| OpenJPA |
| </h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#openjpa_intro_about">1. |
| About This Document |
| </a></span></dt></dl></div><a class="indexterm" name="d0e13"></a><p> |
| OpenJPA is Apache's implementation of Sun's Java Persistence API (JPA) |
| specification for the transparent persistence of Java objects. This |
| document provides an overview of the JPA standard and technical |
| details on the use of OpenJPA. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="openjpa_intro_about"></a>1. |
| About This Document |
| </h2></div></div></div><p> |
| This document is intended for OpenJPA users. It is divided into several parts: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| The <a href="#jpa_overview_intro" title="Chapter 1. Introduction">JPA Overview</a> describes the |
| fundamentals of the JPA specification. |
| </p></li><li><p> |
| The <a href="#ref_guide_intro" title="Chapter 1. Introduction">OpenJPA Reference Guide</a> contains |
| detailed documentation on all aspects of OpenJPA. Browse through this guide |
| to familiarize yourself with the many advanced features and customization |
| opportunities OpenJPA provides. Later, you can use the guide when you need |
| details on a specific aspect of OpenJPA. |
| </p></li></ul></div></div></div></div><div class="part" lang="en" id="jpa_overview"><div class="titlepage"><div><div><h1 class="title"><a name="jpa_overview"></a>Part 2. Java Persistence API</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="chapter"><a href="#jpa_overview_intro">1. |
| Introduction |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_intro_audience">1. |
| Intended Audience |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_intro_transpers">2. |
| Lightweight Persistence |
| </a></span></dt></dl></dd><dt><span class="chapter"><a href="#jpa_overview_why">2. |
| Why JPA? |
| </a></span></dt><dt><span class="chapter"><a href="#jpa_overview_arch">3. |
| Java Persistence API Architecture |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_arch_exceptions">1. |
| JPA Exceptions |
| </a></span></dt></dl></dd><dt><span class="chapter"><a href="#jpa_overview_pc">4. |
| Entity |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_pc_restrict">1. |
| Restrictions on Persistent Classes |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_pc_no_arg">1.1. |
| Default or No-Arg Constructor |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_pc_final">1.2. |
| Final |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_pc_id">1.3. |
| Identity Fields |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_pc_version">1.4. |
| Version Field |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_pc_restrict_inheritance">1.5. |
| Inheritance |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_pc_restrict_fields">1.6. |
| Persistent Fields |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_pc_restrict_conclusion">1.7. |
| Conclusions |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_overview_pc_identity">2. |
| Entity Identity |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_pc_identitycls">2.1. |
| Identity Class |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_pc_identity_hierarchy">2.1.1. |
| Identity Hierarchies |
| </a></span></dt></dl></dd></dl></dd><dt><span class="section"><a href="#jpa_overview_pc_callbacks">3. |
| Lifecycle Callbacks |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_pc_callbacks_methods">3.1. |
| Callback Methods |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_callbacks_using">3.2. |
| Using Callback Methods |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_entity_listeners_using">3.3. |
| Using Entity Listeners |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_entity_listeners_exclude">3.4. |
| Entity Listeners Hierarchy |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_overview_pc_conclusion">4. |
| Conclusions |
| </a></span></dt></dl></dd><dt><span class="chapter"><a href="#jpa_overview_meta">5. |
| Metadata |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_meta_class">1. |
| Class Metadata |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_meta_entity">1.1. |
| Entity |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_meta_idclass">1.2. |
| Id Class |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_meta_embeddablesuper">1.3. |
| Mapped Superclass |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_meta_embeddable">1.4. |
| Embeddable |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_meta_entity_listeners">1.5. |
| EntityListeners |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_meta_classex">1.6. |
| Example |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_overview_meta_field">2. |
| Field and Property Metadata |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_meta_transient">2.1. |
| Transient |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_meta_id">2.2. |
| Id |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_meta_gen">2.3. |
| Generated Value |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_meta_embedid">2.4. |
| Embedded Id |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_meta_version">2.5. |
| Version |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_meta_basic">2.6. |
| Basic |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_meta_fetch">2.6.1. |
| Fetch Type |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_overview_meta_embedded">2.7. |
| Embedded |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_meta_manytoone">2.8. |
| Many To One |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_meta_cascade">2.8.1. |
| Cascade Type |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_overview_meta_onetomany">2.9. |
| One To Many |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_meta_mappedby">2.9.1. |
| Bidirectional Relations |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_overview_meta_onetoone">2.10. |
| One To One |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_meta_manytomany">2.11. |
| Many To Many |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_meta_orderby">2.12. |
| Order By |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_meta_mapkey">2.13. |
| Map Key |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_meta_fielddefaults">2.14. |
| Persistent Field Defaults |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_overview_meta_xml">3. |
| XML Schema |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_meta_complete">4. |
| Conclusion |
| </a></span></dt></dl></dd><dt><span class="chapter"><a href="#jpa_overview_persistence">6. |
| Persistence |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_persistence_xml">1. |
| persistence.xml |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_persistence_use">2. |
| Non-EE Use |
| </a></span></dt></dl></dd><dt><span class="chapter"><a href="#jpa_overview_emfactory">7. |
| EntityManagerFactory |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_emfactory_obtain">1. |
| Obtaining an EntityManagerFactory |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_emfactory_em">2. |
| Obtaining EntityManagers |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_emfactory_perscontext">3. |
| Persistence Context |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_emfactory_perscontext_trans">3.1. |
| Transaction Persistence Context |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_emfactory_perscontext_extend">3.2. |
| Extended Persistence Context |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_overview_emfactory_close">4. |
| Closing the EntityManagerFactory |
| </a></span></dt></dl></dd><dt><span class="chapter"><a href="#jpa_overview_em">8. |
| EntityManager |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_em_trans">1. |
| Transaction Association |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_em_lifecycle">2. |
| Entity Lifecycle Management |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_em_lifeexamples">3. |
| Lifecycle Examples |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_em_identity">4. |
| Entity Identity Management |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_em_cache">5. |
| Cache Management |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_em_query">6. |
| Query Factory |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_em_closing">7. |
| Closing |
| </a></span></dt></dl></dd><dt><span class="chapter"><a href="#jpa_overview_trans">9. |
| Transaction |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_trans_types">1. |
| Transaction Types |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_trans_local">2. |
| The EntityTransaction Interface |
| </a></span></dt></dl></dd><dt><span class="chapter"><a href="#jpa_overview_query">10. |
| JPA Query |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_query_api">1. |
| JPQL API |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_query_basic">1.1. |
| Query Basics |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_query_relations">1.2. |
| Relation Traversal |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_join_fetch">1.3. |
| Fetch Joins |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_query_functions">1.4. |
| JPQL Functions |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_query_inheritance">1.5. |
| Polymorphic Queries |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_query_params">1.6. |
| Query Parameters |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_query_hints">1.7. |
| Query Hints |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_hints_locking">1.7.1. |
| Locking Hints |
| </a></span></dt><dt><span class="section"><a href="#jpa_hints_resultset">1.7.2. |
| Result Set Size Hint |
| </a></span></dt><dt><span class="section"><a href="#jpa_hints_isolation">1.7.3. |
| Isolation Level Hint |
| </a></span></dt><dt><span class="section"><a href="#jpa_hints_fetchplan">1.7.4. |
| Other Fetchplan Hints |
| </a></span></dt><dt><span class="section"><a href="#d0e6512">1.7.5. |
| Oracle Query Hints |
| </a></span></dt><dt><span class="section"><a href="#jpa_hints_named">1.7.6. |
| Named Query Hints |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_overview_query_ordering">1.8. |
| Ordering |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_query_aggregates">1.9. |
| Aggregates |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_query_named">1.10. |
| Named Queries |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_query_delete">1.11. |
| Delete By Query |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_query_update">1.12. |
| Update By Query |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_langref">2. |
| JPQL Language Reference |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_langref_stmnttypes">2.1. |
| JPQL Statement Types |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_langref_select">2.1.1. |
| JPQL Select Statement |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_bulk">2.1.2. |
| JPQL Update and Delete Statements |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_langref_schematypes">2.2. |
| JPQL Abstract Schema Types and Query Domains |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_langref_schemanaming">2.2.1. |
| JPQL Entity Naming |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_schemaexample">2.2.2. |
| JPQL Schema Example |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_langref_fromclause">2.3. |
| JPQL FROM Clause and Navigational Declarations |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_langref_from_identifiers">2.3.1. |
| JPQL FROM Identifiers |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_from_vars">2.3.2. |
| JPQL Identification Variables |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_range">2.3.3. |
| JPQL Range Declarations |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_path">2.3.4. |
| JPQL Path Expressions |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_Joins">2.3.5. |
| JPQL Joins |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_langref_inner_joins">2.3.5.1. |
| JPQL Inner Joins (Relationship Joins) |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_outer_joins">2.3.5.2. |
| JPQL Outer Joins |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_fetch_joins">2.3.5.3. |
| JPQL Fetch Joins |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_langref_collection_dec">2.3.6. |
| JPQL Collection Member Declarations |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_polymorph">2.3.7. |
| JPQL Polymorphism |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_langref_where">2.4. |
| JPQL WHERE Clause |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_cond">2.5. |
| JPQL Conditional Expressions |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_langref_lit">2.5.1. |
| JPQL Literals |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_idvar">2.5.2. |
| JPQL Identification Variables |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_path_exp">2.5.3. |
| JPQL Path Expressions |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_input_params">2.5.4. |
| JPQL Input Parameters |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_langref_pos_params">2.5.4.1. |
| JPQL Positional Parameters |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_named_params">2.5.4.2. |
| JPQL Named Parameters |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_langref_cond_comp">2.5.5. |
| JPQL Conditional Expression Composition |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_operators">2.5.6. |
| JPQL Operators and Operator Precedence |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_between">2.5.7. |
| JPQL Between Expressions |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_in">2.5.8. |
| JPQL In Expressions |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_like">2.5.9. |
| JPQL Like Expressions |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_null">2.5.10. |
| JPQL Null Comparison Expressions |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_empty_comp">2.5.11. |
| JPQL Empty Collection Comparison Expressions |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_collection_member">2.5.12. |
| JPQL Collection Member Expressions |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_exists">2.5.13. |
| JPQL Exists Expressions |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_all_any">2.5.14. |
| JPQL All or Any Expressions |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_subqueries">2.5.15. |
| JPQL Subqueries |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_functional">2.5.16. |
| JPQL Functional Expressions |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_langref_string_fun">2.5.16.1. |
| JPQL String Functions |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_arithmetic">2.5.16.2. |
| JPQL Arithmetic Functions |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_datetime">2.5.16.3. |
| JPQL Datetime Functions |
| </a></span></dt></dl></dd></dl></dd><dt><span class="section"><a href="#jpa_langref_group">2.6. |
| JPQL GROUP BY, HAVING |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_select_clause">2.7. |
| JPQL SELECT Clause |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_langref_resulttype">2.7.1. |
| JPQL Result Type of the SELECT Clause |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_constructor">2.7.2. |
| JPQL Constructor Expressions |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_null_select">2.7.3. |
| JPQL Null Values in the Query Result |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_aggregates">2.7.4. |
| JPQL Aggregate Functions |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_langref_agg_examples">2.7.4.1. |
| JPQL Aggregate Examples |
| </a></span></dt></dl></dd></dl></dd><dt><span class="section"><a href="#jpa_langref_orderby">2.8. |
| JPQL ORDER BY Clause |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_bulk_ops">2.9. |
| JPQL Bulk Update and Delete |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_null_values">2.10. |
| JPQL Null Values |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_equality">2.11. |
| JPQL Equality and Comparison Semantics |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_bnf">2.12. |
| JPQL BNF |
| </a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#jpa_overview_sqlquery">11. |
| SQL Queries |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_sqlquery_create">1. |
| Creating SQL Queries |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_sqlquery_obj">2. |
| Retrieving Persistent Objects with SQL |
| </a></span></dt></dl></dd><dt><span class="chapter"><a href="#jpa_overview_mapping">12. |
| Mapping Metadata |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_mapping_table">1. |
| Table |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_mapping_unq">2. |
| Unique Constraints |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_mapping_column">3. |
| Column |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_mapping_id">4. |
| Identity Mapping |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_mapping_sequence">5. |
| Generators |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_mapping_sequence_seqgen">5.1. |
| Sequence Generator |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_mapping_sequence_tablegen">5.2. |
| TableGenerator |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_mapping_sequence_genex">5.3. |
| Example |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_overview_mapping_inher">6. |
| Inheritance |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_mapping_inher_single">6.1. |
| Single Table |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_mapping_inher_single_adv">6.1.1. |
| Advantages |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_mapping_inher_single_disadv">6.1.2. |
| Disadvantages |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_overview_mapping_inher_joined">6.2. |
| Joined |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_mapping_inher_joined_adv">6.2.1. |
| Advantages |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_mapping_inher_joined_disadv">6.2.2. |
| Disadvantages |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_overview_mapping_inher_tpc">6.3. |
| Table Per Class |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_mapping_inher_tpc_adv">6.3.1. |
| Advantages |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_mapping_inher_tpc_disadv">6.3.2. |
| Disadvantages |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_overview_mapping_inher_together">6.4. |
| Putting it All Together |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_overview_mapping_discrim">7. |
| Discriminator |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_mapping_field">8. |
| Field Mapping |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_mapping_basic">8.1. |
| Basic Mapping |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_mapping_lob">8.1.1. |
| LOBs |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_mapping_enum">8.1.2. |
| Enumerated |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_mapping_temporal">8.1.3. |
| Temporal Types |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_mapping_basic_example">8.1.4. |
| The Updated Mappings |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_overview_mapping_secondary">8.2. |
| Secondary Tables |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_mapping_embed">8.3. |
| Embedded Mapping |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_mapping_rel">8.4. |
| Direct Relations |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_mapping_assoccoll">8.5. |
| Join Table |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_mapping_bidi">8.6. |
| Bidirectional Mapping |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_mapping_map">8.7. |
| Map Mapping |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_overview_mapping_full">9. |
| The Complete Mappings |
| </a></span></dt></dl></dd><dt><span class="chapter"><a href="#jpa_overview_conclusion">13. |
| Conclusion |
| </a></span></dt></dl></div><div class="chapter" lang="en" id="jpa_overview_intro"><div class="titlepage"><div><div><h2 class="title"><a name="jpa_overview_intro"></a>Chapter 1. |
| Introduction |
| </h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#jpa_overview_intro_audience">1. |
| Intended Audience |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_intro_transpers">2. |
| Lightweight Persistence |
| </a></span></dt></dl></div><p> |
| <a class="indexterm" name="d0e47"></a> |
| <a class="indexterm" name="d0e53"></a> |
| The Java Persistence API (JPA) is a specification from |
| Sun Microsystems for the persistence of Java objects to any relational |
| datastore. JPA requires J2SE 1.5 (also referred to as "Java 5") or |
| higher, as it makes heavy use of new Java language features such as annotations |
| and generics. This document provides an overview of JPA. Unless |
| otherwise noted, the information presented applies to all JPA implementations. |
| </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| For coverage of OpenJPA's many extensions to the JPA specification, |
| see the <a href="#ref_guide_intro" title="Chapter 1. Introduction">Reference Guide</a>. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="jpa_overview_intro_audience"></a>1. |
| Intended Audience |
| </h2></div></div></div><p> |
| This document is intended for developers who want to learn about JPA |
| in order to use it in their applications. It assumes that you have a strong |
| knowledge of object-oriented concepts and Java, including Java 5 annotations and |
| generics. It also assumes some experience with relational databases and the |
| Structured Query Language (SQL). |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="jpa_overview_intro_transpers"></a>2. |
| Lightweight Persistence |
| </h2></div></div></div><a class="indexterm" name="d0e71"></a><p> |
| <a class="indexterm" name="d0e76"></a> |
| <span class="emphasis"><em>Persistent data</em></span> is information that can outlive the program |
| that creates it. The majority of complex programs use persistent data: GUI |
| applications need to store user preferences across program invocations, web |
| applications track user movements and orders over long periods of time, etc. |
| </p><p> |
| <span class="emphasis"><em>Lightweight persistence</em></span> is the storage and retrieval of |
| persistent data with little or no work from you, the developer. For example, |
| Java serialization |
| <a class="indexterm" name="d0e88"></a> |
| is a form of lightweight persistence because it can be used to persist Java |
| objects directly to a file with very little effort. Serialization's capabilities |
| as a lightweight persistence mechanism pale in comparison to those provided by |
| JPA, however. The next chapter compares JPA to serialization and other available |
| persistence mechanisms. |
| </p></div></div><div class="chapter" lang="en" id="jpa_overview_why"><div class="titlepage"><div><div><h2 class="title"><a name="jpa_overview_why"></a>Chapter 2. |
| Why JPA? |
| </h2></div></div></div><a class="indexterm" name="d0e96"></a><p> |
| Java developers who need to store and retrieve persistent data already have |
| several options available to them: serialization, JDBC, JDO, proprietary |
| object-relational mapping tools, object databases, and EJB 2 entity beans. Why |
| introduce yet another persistence framework? The answer to this question is that |
| with the exception of JDO, each of the aforementioned persistence solutions has |
| severe limitations. JPA attempts to overcome these limitations, as illustrated |
| by the table below. |
| </p><div class="table"><a name="d0e103"></a><p class="title"><b>Table 2.1. |
| Persistence Mechanisms |
| </b></p><div class="table-contents"><table summary="
 Persistence Mechanisms
 " border="1"><colgroup><col align="left"><col align="left"><col align="left"><col align="left"><col align="left"><col align="left"><col align="left"><col align="left"></colgroup><thead><tr><th align="left"> |
| Supports: |
| </th><th align="left"> |
| Serialization |
| </th><th align="left"> |
| JDBC |
| </th><th align="left"> |
| ORM |
| </th><th align="left"> |
| ODB |
| </th><th align="left"> |
| EJB 2 |
| </th><th align="left"> |
| JDO |
| </th><th align="left"> |
| JPA |
| </th></tr></thead><tbody><tr><td align="left"> |
| Java Objects |
| </td><td align="left"> |
| <span class="bold"><strong> |
| Yes |
| </strong></span> |
| </td><td align="left"> |
| No |
| </td><td align="left"> |
| <span class="bold"><strong> |
| Yes |
| </strong></span> |
| </td><td align="left"> |
| <span class="bold"><strong> |
| Yes |
| </strong></span> |
| </td><td align="left"> |
| <span class="bold"><strong> |
| Yes |
| </strong></span> |
| </td><td align="left"> |
| <span class="bold"><strong> |
| Yes |
| </strong></span> |
| </td><td align="left"> |
| <span class="bold"><strong> |
| Yes |
| </strong></span> |
| </td></tr><tr><td align="left"> |
| Advanced OO Concepts |
| </td><td align="left"> |
| <span class="bold"><strong> |
| Yes |
| </strong></span> |
| </td><td align="left"> |
| No |
| </td><td align="left"> |
| <span class="bold"><strong> |
| Yes |
| </strong></span> |
| </td><td align="left"> |
| <span class="bold"><strong> |
| Yes |
| </strong></span> |
| </td><td align="left"> |
| No |
| </td><td align="left"> |
| <span class="bold"><strong> |
| Yes |
| </strong></span> |
| </td><td align="left"> |
| <span class="bold"><strong> |
| Yes |
| </strong></span> |
| </td></tr><tr><td align="left"> |
| Transactional Integrity |
| </td><td align="left"> |
| No |
| </td><td align="left"> |
| <span class="bold"><strong> |
| Yes |
| </strong></span> |
| </td><td align="left"> |
| <span class="bold"><strong> |
| Yes |
| </strong></span> |
| </td><td align="left"> |
| <span class="bold"><strong> |
| Yes |
| </strong></span> |
| </td><td align="left"> |
| <span class="bold"><strong> |
| Yes |
| </strong></span> |
| </td><td align="left"> |
| <span class="bold"><strong> |
| Yes |
| </strong></span> |
| </td><td align="left"> |
| <span class="bold"><strong> |
| Yes |
| </strong></span> |
| </td></tr><tr><td align="left"> |
| Concurrency |
| </td><td align="left"> |
| No |
| </td><td align="left"> |
| <span class="bold"><strong> |
| Yes |
| </strong></span> |
| </td><td align="left"> |
| <span class="bold"><strong> |
| Yes |
| </strong></span> |
| </td><td align="left"> |
| <span class="bold"><strong> |
| Yes |
| </strong></span> |
| </td><td align="left"> |
| <span class="bold"><strong> |
| Yes |
| </strong></span> |
| </td><td align="left"> |
| <span class="bold"><strong> |
| Yes |
| </strong></span> |
| </td><td align="left"> |
| <span class="bold"><strong> |
| Yes |
| </strong></span> |
| </td></tr><tr><td align="left"> |
| Large Data Sets |
| </td><td align="left"> |
| No |
| </td><td align="left"> |
| <span class="bold"><strong> |
| Yes |
| </strong></span> |
| </td><td align="left"> |
| <span class="bold"><strong> |
| Yes |
| </strong></span> |
| </td><td align="left"> |
| <span class="bold"><strong> |
| Yes |
| </strong></span> |
| </td><td align="left"> |
| <span class="bold"><strong> |
| Yes |
| </strong></span> |
| </td><td align="left"> |
| <span class="bold"><strong> |
| Yes |
| </strong></span> |
| </td><td align="left"> |
| <span class="bold"><strong> |
| Yes |
| </strong></span> |
| </td></tr><tr><td align="left"> |
| Existing Schema |
| </td><td align="left"> |
| No |
| </td><td align="left"> |
| <span class="bold"><strong> |
| Yes |
| </strong></span> |
| </td><td align="left"> |
| <span class="bold"><strong> |
| Yes |
| </strong></span> |
| </td><td align="left"> |
| No |
| </td><td align="left"> |
| <span class="bold"><strong> |
| Yes |
| </strong></span> |
| </td><td align="left"> |
| <span class="bold"><strong> |
| Yes |
| </strong></span> |
| </td><td align="left"> |
| <span class="bold"><strong> |
| Yes |
| </strong></span> |
| </td></tr><tr><td align="left"> |
| Relational and Non-Relational Stores |
| </td><td align="left"> |
| No |
| </td><td align="left"> |
| No |
| </td><td align="left"> |
| No |
| </td><td align="left"> |
| No |
| </td><td align="left"> |
| <span class="bold"><strong> |
| Yes |
| </strong></span> |
| </td><td align="left"> |
| <span class="bold"><strong> |
| Yes |
| </strong></span> |
| </td><td align="left"> |
| No |
| </td></tr><tr><td align="left"> |
| Queries |
| </td><td align="left"> |
| No |
| </td><td align="left"> |
| <span class="bold"><strong> |
| Yes |
| </strong></span> |
| </td><td align="left"> |
| <span class="bold"><strong> |
| Yes |
| </strong></span> |
| </td><td align="left"> |
| <span class="bold"><strong> |
| Yes |
| </strong></span> |
| </td><td align="left"> |
| <span class="bold"><strong> |
| Yes |
| </strong></span> |
| </td><td align="left"> |
| <span class="bold"><strong> |
| Yes |
| </strong></span> |
| </td><td align="left"> |
| <span class="bold"><strong> |
| Yes |
| </strong></span> |
| </td></tr><tr><td align="left"> |
| Strict Standards / Portability |
| </td><td align="left"> |
| <span class="bold"><strong> |
| Yes |
| </strong></span> |
| </td><td align="left"> |
| No |
| </td><td align="left"> |
| No |
| </td><td align="left"> |
| No |
| </td><td align="left"> |
| <span class="bold"><strong> |
| Yes |
| </strong></span> |
| </td><td align="left"> |
| <span class="bold"><strong> |
| Yes |
| </strong></span> |
| </td><td align="left"> |
| <span class="bold"><strong> |
| Yes |
| </strong></span> |
| </td></tr><tr><td align="left"> |
| Simplicity |
| </td><td align="left"> |
| <span class="bold"><strong> |
| Yes |
| </strong></span> |
| </td><td align="left"> |
| <span class="bold"><strong> |
| Yes |
| </strong></span> |
| </td><td align="left"> |
| <span class="bold"><strong> |
| Yes |
| </strong></span> |
| </td><td align="left"> |
| <span class="bold"><strong> |
| Yes |
| </strong></span> |
| </td><td align="left"> |
| No |
| </td><td align="left"> |
| <span class="bold"><strong> |
| Yes |
| </strong></span> |
| </td><td align="left"> |
| <span class="bold"><strong> |
| Yes |
| </strong></span> |
| </td></tr></tbody></table></div></div><br class="table-break"><div class="itemizedlist"><ul type="disc"><li><p> |
| <a class="indexterm" name="d0e464"></a> |
| <a class="indexterm" name="d0e468"></a> |
| <span class="emphasis"><em>Serialization</em></span> is Java's built-in mechanism for transforming |
| an object graph into a series of bytes, which can then be sent over the network |
| or stored in a file. Serialization is very easy to use, but it is also very |
| limited. It must store and retrieve the entire object graph at once, making it |
| unsuitable for dealing with large amounts of data. It cannot undo changes that |
| are made to objects if an error occurs while updating information, making it |
| unsuitable for applications that require strict data integrity. Multiple threads |
| or programs cannot read and write the same serialized data concurrently without |
| conflicting with each other. It provides no query capabilities. All these |
| factors make serialization useless for all but the most trivial persistence |
| needs. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e480"></a> |
| <a class="indexterm" name="d0e486"></a> |
| <a class="indexterm" name="d0e490"></a> |
| Many developers use the <span class="emphasis"><em>Java Database Connectivity</em></span> (JDBC) |
| APIs to manipulate persistent data in relational databases. JDBC overcomes most |
| of the shortcomings of serialization: it can handle large amounts of data, has |
| mechanisms to ensure data integrity, supports concurrent access to information, |
| and has a sophisticated query language in SQL. Unfortunately, JDBC does not |
| duplicate serialization's ease of use. The relational paradigm used by JDBC was |
| not designed for storing objects, and therefore forces you to either abandon |
| object-oriented programming for the portions of your code that deal with |
| persistent data, or to find a way of mapping object-oriented concepts like |
| inheritance to relational databases yourself. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e502"></a> |
| <a class="indexterm" name="d0e508"></a> |
| <a class="indexterm" name="d0e512"></a> |
| There are many proprietary software products that can perform the mapping |
| between objects and relational database tables for you. These <span class="emphasis"><em> |
| object-relational mapping</em></span> (ORM) frameworks allow you to focus on the |
| object model and not concern yourself with the mismatch between the |
| object-oriented and relational paradigms. Unfortunately, each of these product |
| has its own set of APIs. Your code becomes tied to the proprietary interfaces of |
| a single vendor. If the vendor raises prices, fails to fix show-stopping bugs, |
| or falls behind in features, you cannot switch to another product without |
| rewriting all of your persistence code. This is referred to as vendor lock-in. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e524"></a> |
| <a class="indexterm" name="d0e530"></a> |
| <a class="indexterm" name="d0e534"></a> |
| <a class="indexterm" name="d0e540"></a> |
| Rather than map objects to relational databases, some software companies have |
| developed a form of database designed specifically to store objects. These |
| <span class="emphasis"><em>object databases</em></span> (ODBs) are often much easier to use than |
| object-relational mapping software. The Object Database Management Group (ODMG) |
| was formed to create a standard API for accessing object databases; few object |
| database vendors, however, comply with the ODMG's recommendations. Thus, vendor |
| lock-in plagues object databases as well. Many companies are also hesitant to |
| switch from tried-and-true relational systems to the relatively unknown object |
| database technology. Fewer data-analysis tools are available for object database |
| systems, and there are vast quantities of data already stored in older |
| relational databases. For all of these reasons and more, object databases have |
| not caught on as well as their creators hoped. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e550"></a> |
| <a class="indexterm" name="d0e556"></a> |
| <a class="indexterm" name="d0e560"></a> |
| The Enterprise Edition of the Java platform introduced entity Enterprise Java |
| Beans (EJBs). EJB 2.x entities are components that represent persistent |
| information in a datastore. Like object-relational mapping solutions, EJB 2.x |
| entities provide an object-oriented view of persistent data. Unlike |
| object-relational software, however, EJB 2.x entities are not limited to |
| relational databases; the persistent information they represent may come from an |
| Enterprise Information System (EIS) or other storage device. Also, EJB 2.x |
| entities use a strict standard, making them portable across vendors. |
| Unfortunately, the EJB 2.x standard is somewhat limited in the object-oriented |
| concepts it can represent. Advanced features like inheritance, polymorphism, and |
| complex relations are absent. Additionally, EBJ 2.x entities are difficult to |
| code, and they require heavyweight and often expensive application servers to |
| run. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e569"></a> |
| <a class="indexterm" name="d0e573"></a> |
| The JDO specification uses an API that is strikingly similar to JPA. JDO, |
| however, supports non-relational databases, a feature that some argue dilutes |
| the specification. |
| </p></li></ul></div><p> |
| <a class="indexterm" name="d0e581"></a> |
| JPA combines the best features from each of the persistence mechanisms listed |
| above. Creating entities under JPA is as simple as creating serializable |
| classes. JPA supports the large data sets, data consistency, concurrent use, and |
| query capabilities of JDBC. Like object-relational software and object |
| databases, JPA allows the use of advanced object-oriented concepts such as |
| inheritance. JPA avoids vendor lock-in by relying on a strict specification like |
| JDO and EJB 2.x entities. JPA focuses on relational databases. And like JDO, JPA |
| is extremely easy to use. |
| </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| OpenJPA typically stores data in relational databases, but can be customized for |
| use with non-relational datastores as well. |
| </p></div><p> |
| JPA is not ideal for every application. For many applications, though, it |
| provides an exciting alternative to other persistence mechanisms. |
| </p></div><div class="chapter" lang="en" id="jpa_overview_arch"><div class="titlepage"><div><div><h2 class="title"><a name="jpa_overview_arch"></a>Chapter 3. |
| Java Persistence API Architecture |
| </h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#jpa_overview_arch_exceptions">1. |
| JPA Exceptions |
| </a></span></dt></dl></div><a class="indexterm" name="d0e594"></a><p> |
| The diagram below illustrates the relationships between the primary components |
| of the JPA architecture. |
| </p><div class="mediaobject"><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="267"><tr><td><img src="img/jpa-arch.png"></td></tr></table></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| A number of the depicted interfaces are only required outside of an |
| EJB3-compliant application server. In an application server, <code class="classname"> |
| EntityManager</code> instances are typically injected, rendering the |
| <code class="classname">EntityManagerFactory</code> unnecessary. Also, transactions |
| within an application server are handled using standard application server |
| transaction controls. Thus, the <code class="classname">EntityTransaction</code> also |
| goes unused. |
| </p></div><div class="itemizedlist"><ul type="disc"><li><p> |
| <a class="indexterm" name="d0e624"></a> |
| <span class="bold"><strong><a href="#jpa_overview_persistence" title="Chapter 6. Persistence"><code class="classname"> |
| Persistence</code></a></strong></span>: The <code class="classname"> |
| javax.persistence.Persistence</code> class contains static helper methods |
| to obtain <code class="classname">EntityManagerFactory</code> instances in a |
| vendor-neutral fashion. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e642"></a> |
| <span class="bold"><strong><a href="#jpa_overview_emfactory" title="Chapter 7. EntityManagerFactory"><code class="classname"> |
| EntityManagerFactory</code></a></strong></span>: The <code class="classname"> |
| javax.persistence.EntityManagerFactory</code> class is a factory for |
| <code class="classname"> EntityManager</code> s. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e660"></a> |
| <span class="bold"><strong><a href="#jpa_overview_em" title="Chapter 8. EntityManager"><code class="classname">EntityManager |
| </code></a></strong></span>: The <code class="classname">javax.persistence.EntityManager |
| </code> is the primary JPA interface used by applications. Each |
| <code class="classname">EntityManager</code> manages a set of persistent objects, and |
| has APIs to insert new objects and delete existing ones. When used outside the |
| container, there is a one-to-one relationship between an <code class="classname"> |
| EntityManager</code> and an <code class="classname"> EntityTransaction</code>. |
| <code class="classname"> EntityManager</code>s also act as factories for <code class="classname"> |
| Query</code> instances. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e690"></a> |
| <span class="bold"><strong><a href="#jpa_overview_pc" title="Chapter 4. Entity"><code class="classname">Entity |
| </code></a></strong></span>: Entites are persistent objects that represent |
| datastore records. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e702"></a> |
| <span class="bold"><strong><a href="#jpa_overview_trans" title="Chapter 9. Transaction"><code class="classname"> |
| EntityTransaction</code></a></strong></span>: Each <code class="classname">EntityManager |
| </code> has a one-to-one relation with a single <code class="classname"> |
| javax.persistence.EntityTransaction</code>. <code class="classname"> |
| EntityTransaction</code>s allow operations on persistent data to be |
| grouped into units of work that either completely succeed or completely fail, |
| leaving the datastore in its original state. These all-or-nothing operations |
| are important for maintaining data integrity. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e723"></a> |
| <a class="indexterm" name="d0e727"></a> |
| <a class="indexterm" name="d0e733"></a> |
| <a class="indexterm" name="d0e737"></a> |
| <a class="indexterm" name="d0e745"></a> |
| <a class="indexterm" name="d0e751"></a> |
| <span class="bold"><strong><a href="#jpa_overview_query" title="Chapter 10. JPA Query"><code class="classname">Query |
| </code></a></strong></span>: The <code class="classname">javax.persistence.Query |
| </code> interface is implemented by each JPA vendor to find persistent |
| objects that meet certain criteria. JPA standardizes support for queries using |
| both the Java Persistence Query Language (JPQL) and the Structured Query |
| Language (SQL). You obtain <code class="classname">Query</code> instances from an |
| <code class="classname">EntityManager</code>. |
| </p></li></ul></div><p> |
| The example below illustrates how the JPA interfaces interact to execute a JPQL |
| query and update persistent objects. The example assumes execution outside a |
| container. |
| </p><div class="example"><a name="jpa_overview_arch_interact_outside"></a><p class="title"><b>Example 3.1. |
| Interaction of Interfaces Outside Container |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| // get an EntityManagerFactory using the Persistence class; typically |
| // the factory is cached for easy repeated use |
| EntityManagerFactory factory = Persistence.createEntityManagerFactory(null); |
| |
| // get an EntityManager from the factory |
| EntityManager em = factory.createEntityManager(PersistenceContextType.EXTENDED); |
| |
| // updates take place within transactions |
| EntityTransaction tx = em.getTransaction(); |
| tx.begin(); |
| |
| // query for all employees who work in our research division |
| // and put in over 40 hours a week average |
| Query query = em.createQuery("select e from Employee e where " |
| + "e.division.name = 'Research' AND e.avgHours > 40"); |
| List results = query.getResultList (); |
| |
| // give all those hard-working employees a raise |
| for (Object res : results) { |
| Employee emp = (Employee) res; |
| emp.setSalary(emp.getSalary() * 1.1); |
| } |
| |
| // commit the updates and free resources |
| tx.commit(); |
| em.close(); |
| factory.close(); |
| </pre></div></div><br class="example-break"><p> |
| Within a container, the <code class="classname">EntityManager</code> will be injected |
| and transactions will be handled declaratively. Thus, the in-container version |
| of the example consists entirely of business logic: |
| </p><div class="example"><a name="jpa_overview_arch_interact_inside"></a><p class="title"><b>Example 3.2. |
| Interaction of Interfaces Inside Container |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| // query for all employees who work in our research division |
| // and put in over 40 hours a week average - note that the EntityManager em |
| // is injected using a @Resource annotation |
| Query query = em.createQuery("select e from Employee e where " |
| + "e.division.name = 'Research' and e.avgHours > 40"); |
| List results = query.getResultList(); |
| |
| // give all those hard-working employees a raise |
| for (Object res : results) { |
| emp = (Employee) res; |
| emp.setSalary(emp.getSalary() * 1.1); |
| } |
| </pre></div></div><br class="example-break"><p> |
| The remainder of this document explores the JPA interfaces in detail. We present |
| them in roughly the order that you will use them as you develop your |
| application. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="jpa_overview_arch_exceptions"></a>1. |
| JPA Exceptions |
| </h2></div></div></div><a class="indexterm" name="d0e791"></a><a class="indexterm" name="d0e798"></a><div class="mediaobject"><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="285"><tr><td><img src="img/jpa-exceptions.png"></td></tr></table></div><p> |
| The diagram above depicts the JPA exception architecture. All |
| exceptions are unchecked. JPA uses standard exceptions where |
| appropriate, most notably <code class="classname">IllegalArgumentException</code>s and |
| <code class="classname">IllegalStateException</code>s. The specification also provides |
| a few JPA-specific exceptions in the <code class="literal">javax.persistence</code> |
| package. These exceptions should be self-explanatory. See the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="http://java.sun.com/javaee/5/docs/api" target="_top">Javadoc</a> for |
| additional details on JPA exceptions. |
| </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| All exceptions thrown by OpenJPA implement |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/util/ExceptionInfo.html" target="_top"><code class="classname"> |
| org.apache.openjpa.util.ExceptionInfo</code></a> to provide you with |
| additional error information. |
| </p></div></div></div><div class="chapter" lang="en" id="jpa_overview_pc"><div class="titlepage"><div><div><h2 class="title"><a name="jpa_overview_pc"></a>Chapter 4. |
| Entity |
| </h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#jpa_overview_pc_restrict">1. |
| Restrictions on Persistent Classes |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_pc_no_arg">1.1. |
| Default or No-Arg Constructor |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_pc_final">1.2. |
| Final |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_pc_id">1.3. |
| Identity Fields |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_pc_version">1.4. |
| Version Field |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_pc_restrict_inheritance">1.5. |
| Inheritance |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_pc_restrict_fields">1.6. |
| Persistent Fields |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_pc_restrict_conclusion">1.7. |
| Conclusions |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_overview_pc_identity">2. |
| Entity Identity |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_pc_identitycls">2.1. |
| Identity Class |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_pc_identity_hierarchy">2.1.1. |
| Identity Hierarchies |
| </a></span></dt></dl></dd></dl></dd><dt><span class="section"><a href="#jpa_overview_pc_callbacks">3. |
| Lifecycle Callbacks |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_pc_callbacks_methods">3.1. |
| Callback Methods |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_callbacks_using">3.2. |
| Using Callback Methods |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_entity_listeners_using">3.3. |
| Using Entity Listeners |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_entity_listeners_exclude">3.4. |
| Entity Listeners Hierarchy |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_overview_pc_conclusion">4. |
| Conclusions |
| </a></span></dt></dl></div><a class="indexterm" name="d0e835"></a><a class="indexterm" name="d0e838"></a><a class="indexterm" name="d0e843"></a><a class="indexterm" name="d0e850"></a><p> |
| JPA recognizes two types of persistent classes: <span class="emphasis"><em>entity</em></span> |
| classes and <span class="emphasis"><em>embeddable</em></span> classes. Each persistent instance of |
| an entity class - each <span class="emphasis"><em>entity</em></span> - represents a unique |
| datastore record. You can use the <code class="classname">EntityManager</code> to find |
| an entity by its persistent identity (covered later in this chapter), or use a |
| <code class="classname">Query</code> to find entities matching certain criteria. |
| </p><p> |
| An instance of an embeddable class, on the other hand, is only stored as part of |
| a separate entity. Embeddable instances have no persistent identity, and are |
| never returned directly from the <code class="classname">EntityManager</code> or from a |
| <code class="classname">Query</code> unless the query uses a projection on owning class |
| to the embedded instance. For example, if <code class="classname">Address</code> is |
| embedded in <code class="classname">Company</code>, then |
| a query <code class="classname">"SELECT a FROM Address a"</code> will never return the |
| embedded <code class="classname">Address</code> of <code class="classname">Company</code>; |
| but a projection query such as |
| <code class="classname">"SELECT c.address FROM Company c"</code> will. |
| </p><p> |
| Despite these differences, there are few distinctions between entity classes and |
| embeddable classes. In fact, writing either type of persistent class is a lot |
| like writing any other class. There are no special parent classes to |
| extend from, field types to use, or methods to write. This is one important way |
| in which JPA makes persistence transparent to you, the developer. |
| </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| JPA supports both fields and JavaBean properties as persistent state. For |
| simplicity, however, we will refer to all persistent state as persistent fields, |
| unless we want to note a unique aspect of persistent properties. |
| </p></div><div class="example"><a name="jpa_overview_pc_pcclass"></a><p class="title"><b>Example 4.1. |
| Persistent Class |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| package org.mag; |
| |
| /** |
| * Example persistent class. Notice that it looks exactly like any other |
| * class. JPA makes writing persistent classes completely transparent. |
| */ |
| public class Magazine { |
| |
| private String isbn; |
| private String title; |
| private Set articles = new HashSet(); |
| private Article coverArticle; |
| private int copiesSold; |
| private double price; |
| private Company publisher; |
| private int version; |
| |
| protected Magazine() { |
| } |
| |
| public Magazine(String title, String isbn) { |
| this.title = title; |
| this.isbn = isbn; |
| } |
| |
| public void publish(Company publisher, double price) { |
| this.publisher = publisher; |
| publisher.addMagazine(this); |
| this.price = price; |
| } |
| |
| public void sell() { |
| copiesSold++; |
| publisher.addRevenue(price); |
| } |
| |
| public void addArticle(Article article) { |
| articles.add(article); |
| } |
| |
| // rest of methods omitted |
| } |
| </pre></div></div><br class="example-break"><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="jpa_overview_pc_restrict"></a>1. |
| Restrictions on Persistent Classes |
| </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#jpa_overview_pc_no_arg">1.1. |
| Default or No-Arg Constructor |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_pc_final">1.2. |
| Final |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_pc_id">1.3. |
| Identity Fields |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_pc_version">1.4. |
| Version Field |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_pc_restrict_inheritance">1.5. |
| Inheritance |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_pc_restrict_fields">1.6. |
| Persistent Fields |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_pc_restrict_conclusion">1.7. |
| Conclusions |
| </a></span></dt></dl></div><a class="indexterm" name="d0e911"></a><p> |
| There are very few restrictions placed on persistent classes. Still, it never |
| hurts to familiarize yourself with exactly what JPA does and does not support. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_overview_pc_no_arg"></a>1.1. |
| Default or No-Arg Constructor |
| </h3></div></div></div><a class="indexterm" name="d0e921"></a><a class="indexterm" name="d0e926"></a><p> |
| The JPA specification requires that all persistent classes have a no-arg |
| constructor. This constructor may be public or protected. Because the compiler |
| automatically creates a default no-arg constructor when no other constructor is |
| defined, only classes that define constructors must also include a no-arg |
| constructor. |
| </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| OpenJPA's <span class="emphasis"><em>enhancer</em></span> will automatically add a protected |
| no-arg constructor to your class when required. Therefore, this restriction does |
| not apply when using the enhancer. See <a href="#ref_guide_pc_enhance" title="2. Enhancement">Section 2, “ |
| Enhancement |
| ”</a> |
| of the Reference Guide for details. |
| </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_overview_pc_final"></a>1.2. |
| Final |
| </h3></div></div></div><p> |
| Entity classes may not be final. No method of an entity class can be final. |
| </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| OpenJPA supports final classes and final methods. |
| </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_overview_pc_id"></a>1.3. |
| Identity Fields |
| </h3></div></div></div><a class="indexterm" name="d0e952"></a><a class="indexterm" name="d0e957"></a><p> |
| All entity classes must declare one or more fields which together form the |
| persistent identity of an instance. These are called <span class="emphasis"><em>identity |
| </em></span> or <span class="emphasis"><em>primary key</em></span> fields. In our <code class="classname"> |
| Magazine</code> class, <code class="literal">isbn</code> and <code class="literal">title</code> |
| are identity fields, because no two magazine records in the datastore can have |
| the same <code class="literal">isbn</code> and <code class="literal">title</code> values. |
| <a href="#jpa_overview_meta_id" title="2.2. Id">Section 2.2, “ |
| Id |
| ”</a> will show you how to denote your |
| identity fields in JPA metadata. <a href="#jpa_overview_pc_identity" title="2. Entity Identity">Section 2, “ |
| Entity Identity |
| ”</a> |
| below examines persistent identity. |
| </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| OpenJPA fully supports identity fields, but does not require them. See |
| <a href="#ref_guide_pc_oid" title="4. Object Identity">Section 4, “ |
| Object Identity |
| ”</a> of the Reference Guide for details. |
| </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_overview_pc_version"></a>1.4. |
| Version Field |
| </h3></div></div></div><a class="indexterm" name="d0e997"></a><a class="indexterm" name="d0e1002"></a><p> |
| The <code class="literal">version</code> field in our <code class="classname">Magazine</code> |
| class may seem out of place. JPA uses a version field in your entities to detect |
| concurrent modifications to the same datastore record. When the JPA runtime |
| detects an attempt to concurrently modify the same record, it throws an |
| exception to the transaction attempting to commit last. This prevents |
| overwriting the previous commit with stale data. |
| </p><p> |
| A version field is not required, but without one concurrent threads or |
| processes might succeed in making conflicting changes to the same record at the |
| same time. This is unacceptable to most applications. |
| <a href="#jpa_overview_meta_version" title="2.5. Version">Section 2.5, “ |
| Version |
| ”</a> shows you how to designate a |
| version field in JPA metadata. |
| </p><p> |
| The version field must be an integral type (<code class="classname"> int</code>, |
| <code class="classname">Long</code>, etc) or a <code class="classname"> |
| java.sql.Timestamp</code>. You should consider version fields immutable. |
| Changing the field value has undefined results. |
| </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| OpenJPA fully supports version fields, but does not require them for concurrency |
| detection. OpenJPA can maintain surrogate version values or use state |
| comparisons to detect concurrent modifications. See |
| <a href="#ref_guide_mapping_jpa" title="7. Additional JPA Mappings">Section 7, “ |
| Additional JPA Mappings |
| ”</a> in the Reference Guide. |
| </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_overview_pc_restrict_inheritance"></a>1.5. |
| Inheritance |
| </h3></div></div></div><a class="indexterm" name="d0e1038"></a><a class="indexterm" name="d0e1045"></a><p> |
| JPA fully supports inheritance in persistent classes. It allows persistent |
| classes to inherit from non-persistent classes, persistent classes to inherit |
| from other persistent classes, and non-persistent classes to inherit from |
| persistent classes. It is even possible to form inheritance hierarchies in which |
| persistence skips generations. There are, however, a few important limitations: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| Persistent classes cannot inherit from certain natively-implemented system |
| classes such as <code class="classname">java.net.Socket</code> and <code class="classname"> |
| java.lang.Thread</code>. |
| </p></li><li><p> |
| If a persistent class inherits from a non-persistent class, the fields of the |
| non-persistent superclass cannot be persisted. |
| </p></li><li><p> |
| All classes in an inheritance tree must use the same identity type. We cover |
| entity identity in <a href="#jpa_overview_pc_identity" title="2. Entity Identity">Section 2, “ |
| Entity Identity |
| ”</a>. |
| </p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_overview_pc_restrict_fields"></a>1.6. |
| Persistent Fields |
| </h3></div></div></div><a class="indexterm" name="d0e1073"></a><a class="indexterm" name="d0e1080"></a><a class="indexterm" name="d0e1087"></a><p> |
| JPA manages the state of all persistent fields. Before you access persistent |
| state, the JPA runtime makes sure that it has been loaded from the datastore. |
| When you set a field, the runtime records that it has changed so that the new |
| value will be persisted. This allows you to treat the field in exactly the same |
| way you treat any other field - another aspect of JPA's transparency. |
| </p><p> |
| JPA does not support static or final fields. It does, however, include built-in |
| support for most common field types. These types can be roughly divided into |
| three categories: immutable types, mutable types, and relations. |
| </p><p> |
| <a class="indexterm" name="d0e1098"></a> |
| <a class="indexterm" name="d0e1104"></a> |
| <span class="emphasis"><em>Immutable</em></span> types, once created, cannot be changed. The only |
| way to alter a persistent field of an immutable type is to assign a new value to |
| the field. JPA supports the following immutable types: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| All primitives (<code class="classname">int, float, byte</code>, etc) |
| </p></li><li><p> |
| All primitive wrappers (<code class="classname">java.lang.Integer, java.lang.Float, |
| java.lang.Byte</code>, etc) |
| </p></li><li><p> |
| <code class="classname">java.lang.String</code> |
| </p></li><li><p> |
| <code class="classname">java.math.BigInteger</code> |
| </p></li><li><p> |
| <code class="classname">java.math.BigDecimal</code> |
| </p></li></ul></div><p> |
| JPA also supports <code class="classname">byte[]</code>, <code class="classname">Byte[]</code>, |
| <code class="classname">char[]</code>, and <code class="classname">Character[]</code> as |
| immutable types. That is, you can persist fields of these types, |
| but you should not manipulate individual array indexes without resetting the |
| array into the persistent field. |
| </p><p> |
| <a class="indexterm" name="d0e1160"></a> |
| <a class="indexterm" name="d0e1168"></a> |
| <a class="indexterm" name="d0e1178"></a> |
| <a class="indexterm" name="d0e1184"></a> |
| Persistent fields of <span class="emphasis"><em>mutable</em></span> types can be altered without |
| assigning the field a new value. Mutable types can be modified directly through |
| their own methods. The JPA specification requires that implementations support |
| the following mutable field types: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="classname">java.util.Date</code> |
| </p></li><li><p> |
| <code class="classname">java.util.Calendar</code> |
| </p></li><li><p> |
| <code class="classname">java.sql.Date</code> |
| </p></li><li><p> |
| <code class="classname">java.sql.Timestamp</code> |
| </p></li><li><p> |
| <code class="classname">java.sql.Time</code> |
| </p></li><li><p> |
| Enums |
| </p></li><li><p> |
| Entity types (relations between entities) |
| </p></li><li><p> |
| Embeddable types |
| </p></li><li><p> |
| <code class="classname">java.util.Collection</code>s of entities |
| </p></li><li><p> |
| <code class="classname">java.util.Set</code>s of entities |
| </p></li><li><p> |
| <code class="classname">java.util.List</code>s of entities |
| </p></li><li><p> |
| <code class="classname">java.util.Map</code>s in which each entry maps the value of one |
| of a related entity's fields to that entity. |
| </p></li></ul></div><p> |
| Collection and map types may be parameterized. |
| </p><p> |
| <a class="indexterm" name="d0e1263"></a> |
| <a class="indexterm" name="d0e1269"></a> |
| Most JPA implementations also have support for persisting serializable values as |
| binary data in the datastore. <a href="#jpa_overview_meta" title="Chapter 5. Metadata">Chapter 5, <i xmlns:xlink="http://www.w3.org/1999/xlink"> |
| Metadata |
| </i></a> has more |
| information on persisting serializable types. |
| </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| OpenJPA also supports arrays, <code class="classname">java.lang.Number</code>, |
| <code class="classname">java.util.Locale</code>, all JDK 1.2 <code class="classname">Set</code>, |
| <code class="classname">List</code>, and <code class="classname">Map</code> types, |
| and many other mutable and immutable field types. OpenJPA also allows you to |
| plug in support for custom types. |
| </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_overview_pc_restrict_conclusion"></a>1.7. |
| Conclusions |
| </h3></div></div></div><p> |
| This section detailed all of the restrictions JPA places on persistent classes. |
| While it may seem like we presented a lot of information, you will seldom find |
| yourself hindered by these restrictions in practice. Additionally, there are |
| often ways of using JPA's other features to circumvent any limitations you run |
| into. |
| </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="jpa_overview_pc_identity"></a>2. |
| Entity Identity |
| </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#jpa_overview_pc_identitycls">2.1. |
| Identity Class |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_pc_identity_hierarchy">2.1.1. |
| Identity Hierarchies |
| </a></span></dt></dl></dd></dl></div><a class="indexterm" name="d0e1305"></a><a class="indexterm" name="d0e1312"></a><a class="indexterm" name="d0e1317"></a><p> |
| <a class="indexterm" name="d0e1324"></a> |
| <a class="indexterm" name="d0e1330"></a> |
| <a class="indexterm" name="d0e1336"></a> |
| <a class="indexterm" name="d0e1342"></a> |
| Java recognizes two forms of object identity: numeric identity and qualitative |
| identity. If two references are <span class="emphasis"><em>numerically</em></span> identical, then |
| they refer to the same JVM instance in memory. You can test for this using the |
| <code class="literal">==</code> operator. <span class="emphasis"><em>Qualitative</em></span> identity, on |
| the other hand, relies on some user-defined criteria to determine whether two |
| objects are "equal". You test for qualitative identity using the <code class="methodname"> |
| equals</code> method. By default, this method simply relies on numeric |
| identity. |
| </p><p> |
| JPA introduces another form of object identity, called <span class="emphasis"><em>entity |
| identity</em></span> or <span class="emphasis"><em>persistent identity</em></span>. Entity |
| identity tests whether two persistent objects represent the same state in the |
| datastore. |
| </p><p> |
| <a class="indexterm" name="d0e1370"></a> |
| <a class="indexterm" name="d0e1376"></a> |
| The entity identity of each persistent instance is encapsulated in its |
| <span class="emphasis"><em>identity field(s)</em></span>. If two entities of the same type have |
| the same identity field values, then the two entities represent the same state |
| in the datastore. Each entity's identity field values must be unique among all |
| other entites of the same type. |
| </p><p> |
| Identity fields must be primitives, primitive wrappers, <code class="classname"> |
| String</code>s, <code class="classname">Date</code>s, <code class="classname"> |
| Timestamp</code>s, or embeddable types. |
| </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| OpenJPA supports entities as identity fields, as the Reference Guide discusses |
| in <a href="#ref_guide_pc_oid_entitypk" title="4.2. Entities as Identity Fields">Section 4.2, “ |
| Entities as Identity Fields |
| ”</a>. For legacy schemas with binary |
| primary key columns, OpenJPA also supports using identity fields of type |
| <code class="classname">byte[]</code>. When you use a <code class="classname">byte[]</code> |
| identity field, you must create an identity class. Identity classes are |
| covered below. |
| </p></div><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3><p> |
| Changing the fields of an embeddable instance while it is assigned to an |
| identity field has undefined results. Always treat embeddable identity instances |
| as immutable objects in your applications. |
| </p></div><p> |
| <a class="indexterm" name="d0e1414"></a> |
| <a class="indexterm" name="d0e1420"></a> |
| If you are dealing with a single persistence context (see |
| <a href="#jpa_overview_emfactory_perscontext" title="3. Persistence Context">Section 3, “ |
| Persistence Context |
| ”</a>), then you do not |
| have to compare identity fields to test whether two entity references represent |
| the same state in the datastore. There is a much easier way: the <code class="literal">== |
| </code> operator. JPA requires that each persistence context maintain only |
| one JVM object to represent each unique datastore record. Thus, entity identity |
| is equivalent to numeric identity within a persistence context. This is referred |
| to as the <span class="emphasis"><em>uniqueness requirement</em></span>. |
| </p><p> |
| The uniqueness requirement is extremely important - without it, it would be |
| impossible to maintain data integrity. Think of what could happen if two |
| different objects in the same transaction were allowed to represent the same |
| persistent data. If you made different modifications to each of these objects, |
| which set of changes should be written to the datastore? How would your |
| application logic handle seeing two different "versions" of the same data? |
| Thanks to the uniqueness requirement, these questions do not have to be |
| answered. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_overview_pc_identitycls"></a>2.1. |
| Identity Class |
| </h3></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#jpa_overview_pc_identity_hierarchy">2.1.1. |
| Identity Hierarchies |
| </a></span></dt></dl></div><p> |
| <a class="indexterm" name="d0e1441"></a> |
| <a class="indexterm" name="d0e1447"></a> |
| If your entity has only one identity field, you can use the value of that field |
| as the entity's identity object in all <a href="#jpa_overview_em" title="Chapter 8. EntityManager"> |
| <code class="classname">EntityManager</code></a> APIs. Otherwise, you must supply an |
| identity class to use for identity objects. Your identity class must meet the |
| following criteria: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| The class must be public. |
| </p></li><li><p> |
| The class must be serializable. |
| </p></li><li><p> |
| The class must have a public no-args constructor. |
| </p></li><li><p> |
| The names of the non-static fields or properties of the class must be the same |
| as the names of the identity fields or properties of the corresponding entity |
| class, and the types must be identical. |
| </p></li><li><p> |
| The <code class="methodname">equals</code> and <code class="methodname">hashCode</code> |
| methods of the class must use the values of all fields or properties |
| corresponding to identity fields or properties in the entity class. |
| </p></li><li><p> |
| If the class is an inner class, it must be <code class="literal">static</code>. |
| </p></li><li><p> |
| All entity classes related by inheritance must use the same identity class, or |
| else each entity class must have its own identity class whose inheritance |
| hierarchy mirrors the inheritance hierarchy of the owning entity classes (see |
| <a href="#jpa_overview_pc_identity_hierarchy" title="2.1.1. Identity Hierarchies">Section 2.1.1, “ |
| Identity Hierarchies |
| ”</a>). |
| </p></li></ul></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| Though you may still create identity classes by hand, OpenJPA provides the |
| <code class="classname">appidtool</code> to automatically generate proper identity |
| classes based on your identity fields. See |
| <a href="#ref_guide_pc_oid_application" title="4.3. Application Identity Tool">Section 4.3, “ |
| Application Identity Tool |
| ”</a> of the Reference Guide. |
| </p></div><div class="example"><a name="jpa_overview_pc_identity_appidcode"></a><p class="title"><b>Example 4.2. |
| Identity Class |
| </b></p><div class="example-contents"><p> |
| This example illustrates a proper identity class for an entity with multiple |
| identity fields. |
| </p><pre class="programlisting"> |
| /** |
| * Persistent class using application identity. |
| */ |
| public class Magazine { |
| |
| private String isbn; // identity field |
| private String title; // identity field |
| |
| // rest of fields and methods omitted |
| |
| |
| /** |
| * Application identity class for Magazine. |
| */ |
| public static class MagazineId { |
| |
| // each identity field in the Magazine class must have a |
| // corresponding field in the identity class |
| public String isbn; |
| public String title; |
| |
| /** |
| * Equality must be implemented in terms of identity field |
| * equality, and must use instanceof rather than comparing |
| * classes directly (some JPA implementations may subclass the |
| * identity class). |
| */ |
| public boolean equals(Object other) { |
| if (other == this) |
| return true; |
| if (!(other instanceof MagazineId)) |
| return false; |
| |
| MagazineId mi = (MagazineId) other; |
| return (isbn == mi.isbn |
| || (isbn != null && isbn.equals(mi.isbn))) |
| && (title == mi.title |
| || (title != null && title.equals(mi.title))); |
| } |
| |
| /** |
| * Hashcode must also depend on identity values. |
| */ |
| public int hashCode() { |
| return ((isbn == null) ? 0 : isbn.hashCode()) |
| ^ ((title == null) ? 0 : title.hashCode()); |
| } |
| |
| public String toString() { |
| return isbn + ":" + title; |
| } |
| } |
| } |
| </pre></div></div><br class="example-break"><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="jpa_overview_pc_identity_hierarchy"></a>2.1.1. |
| Identity Hierarchies |
| </h4></div></div></div><a class="indexterm" name="d0e1509"></a><div class="mediaobject"><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="213"><tr><td><img src="img/appid-hierarchy.png"></td></tr></table></div><p> |
| An alternative to having a single identity class for an entire inheritance |
| hierarchy is to have one identity class per level in the inheritance hierarchy. |
| The requirements for using a hierarchy of identity classes are as follows: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| The inheritance hierarchy of identity classes must exactly mirror the hierarchy |
| of the persistent classes that they identify. In the example pictured above, |
| abstract class <code class="classname">Person</code> is extended by abstract class |
| <code class="classname">Employee</code>, which is extended by non-abstract class |
| <code class="classname"> FullTimeEmployee</code>, which is extended by non-abstract |
| class <code class="classname">Manager</code>. The corresponding identity classes, then, |
| are an abstract <code class="classname">PersonId</code> class, extended by an abstract |
| <code class="classname">EmployeeId</code> class, extended by a non-abstract <code class="classname"> |
| FullTimeEmployeeId</code> class, extended by a non-abstract <code class="classname"> |
| ManagerId</code> class. |
| </p></li><li><p> |
| Subclasses in the identity hierarchy may define additional identity fields until |
| the hierarchy becomes non-abstract. In the aforementioned example, <code class="classname"> |
| Person</code> defines an identity field <code class="literal">ssn</code>, <code class="classname"> |
| Employee</code> defines additional identity field <code class="literal">userName |
| </code>, and <code class="classname">FullTimeEmployee</code> adds a final identity |
| field, <code class="literal">empId</code>. However, <code class="classname">Manager</code> may not |
| define any additional identity fields, since it is a subclass of a non-abstract |
| class. The hierarchy of identity classes, of course, must match the identity |
| field definitions of the persistent class hierarchy. |
| </p></li><li><p> |
| It is not necessary for each abstract class to declare identity fields. In the |
| previous example, the abstract <code class="classname">Person</code> and <code class="classname"> |
| Employee</code> classes could declare no identity fields, and the first |
| concrete subclass <code class="classname">FullTimeEmployee</code> could define one or |
| more identity fields. |
| </p></li><li><p> |
| All subclasses of a concrete identity class must be <code class="methodname">equals |
| </code> and <code class="methodname">hashCode</code>-compatible with the |
| concrete superclass. This means that in our example, a <code class="classname">ManagerId |
| </code> instance and a <code class="classname">FullTimeEmployeeId</code> instance |
| with the same identity field values should have the same hash code, and should |
| compare equal to each other using the <code class="methodname">equals</code> method of |
| either one. In practice, this requirement reduces to the following coding |
| practices: |
| </p><div class="orderedlist"><ol type="1"><li><p> |
| Use <code class="literal">instanceof</code> instead of comparing <code class="classname">Class |
| </code> objects in the <code class="methodname">equals</code> methods of your |
| identity classes. |
| </p></li><li><p> |
| An identity class that extends another non-abstract identity class should not |
| override <code class="methodname">equals</code> or <code class="methodname">hashCode</code>. |
| </p></li></ol></div></li></ul></div></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="jpa_overview_pc_callbacks"></a>3. |
| Lifecycle Callbacks |
| </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#jpa_overview_pc_callbacks_methods">3.1. |
| Callback Methods |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_callbacks_using">3.2. |
| Using Callback Methods |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_entity_listeners_using">3.3. |
| Using Entity Listeners |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_entity_listeners_exclude">3.4. |
| Entity Listeners Hierarchy |
| </a></span></dt></dl></div><a class="indexterm" name="d0e1627"></a><a class="indexterm" name="d0e1630"></a><p> |
| It is often necessary to perform various actions at different stages of a |
| persistent object's lifecycle. JPA includes a variety of callbacks methods for |
| monitoring changes in the lifecycle of your persistent objects. These callbacks |
| can be defined on the persistent classes themselves and on non-persistent |
| listener classes. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_overview_pc_callbacks_methods"></a>3.1. |
| Callback Methods |
| </h3></div></div></div><a class="indexterm" name="d0e1642"></a><a class="indexterm" name="d0e1647"></a><p> |
| Every persistence event has a corresponding callback method marker. These |
| markers are shared between persistent classes and their listeners. You can use |
| these markers to designate a method for callback either by annotating that |
| method or by listing the method in the XML mapping file for a given class. The |
| lifecycle events and their corresponding method markers are: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <a class="indexterm" name="d0e1658"></a> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="http://java.sun.com/javaee/5/docs/api/javax/persistence/PrePersist.html" target="_top"> |
| <code class="classname">PrePersist</code></a>: Methods marked with this annotation |
| will be invoked before an object is persisted. This could be used for assigning |
| primary key values to persistent objects. This is equivalent to the XML element |
| tag <code class="literal">pre-persist</code>. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e1675"></a> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="http://java.sun.com/javaee/5/docs/api/javax/persistence/PostPersist.html" target="_top"> |
| <code class="classname">PostPersist</code></a>: Methods marked with this annotation |
| will be invoked after an object has transitioned to the persistent state. You |
| might want to use such methods to update a screen after a new row is added. This |
| is equivalent to the XML element tag <code class="literal">post-persist</code>. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e1692"></a> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="http://java.sun.com/javaee/5/docs/api/javax/persistence/PostLoad.html" target="_top"> |
| <code class="classname">PostLoad</code></a>: Methods marked with this annotation |
| will be invoked after all eagerly fetched fields of your class have been loaded |
| from the datastore. No other persistent fields can be accessed in this method. |
| This is equivalent to the XML element tag <code class="literal">post-load</code>. |
| </p><p> |
| <code class="classname">PostLoad</code> is often used to initialize non-persistent |
| fields whose values depend on the values of persistent fields, such as a complex |
| datastructure. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e1714"></a> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="http://java.sun.com/javaee/5/docs/api/javax/persistence/PreUpdate.html" target="_top"> |
| <code class="classname">PreUpdate</code></a>: Methods marked with this annotation |
| will be invoked just the persistent values in your objects are flushed to the |
| datastore. This is equivalent to the XML element tag <code class="literal"> |
| pre-update</code>. |
| </p><p> |
| <code class="classname">PreUpdate</code> is the complement to <code class="classname">PostLoad |
| </code>. While methods marked with <code class="classname">PostLoad</code> are most |
| often used to initialize non-persistent values from persistent data, methods |
| annotated with <code class="classname">PreUpdate</code> is normally used to set |
| persistent fields with information cached in non-persistent data. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e1745"></a> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="http://java.sun.com/javaee/5/docs/api/javax/persistence/PostUpdate.html" target="_top"> |
| <code class="classname">PostUpdate</code></a>: Methods marked with this annotation |
| will be invoked after changes to a given instance have been stored to the |
| datastore. This is useful for clearing stale data cached at the application |
| layer. This is equivalent to the XML element tag <code class="literal">post-update</code>. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e1762"></a> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="http://java.sun.com/javaee/5/docs/api/javax/persistence/PreRemove.html" target="_top"> |
| <code class="classname">PreRemove</code></a>: Methods marked with this annotation |
| will be invoked before an object transactions to the deleted state. Access to |
| persistent fields is valid within this method. You might use this method to |
| cascade the deletion to related objects based on complex criteria, or to perform |
| other cleanup. This is equivalent to the XML element tag <code class="literal"> |
| pre-remove</code>. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e1779"></a> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="http://java.sun.com/javaee/5/docs/api/javax/persistence/PostRemove.html" target="_top"> |
| <code class="classname">PostRemove</code></a>: Methods marked with this annotation |
| will be invoked after an object has been marked as to be deleted. This is |
| equivalent to the XML element tag <code class="literal">post-remove</code>. |
| </p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_overview_callbacks_using"></a>3.2. |
| Using Callback Methods |
| </h3></div></div></div><p> |
| When declaring callback methods on a persistent class, any method may be used |
| which takes no arguments and is not shared with any property access fields. |
| Multiple events can be assigned to a single method as well. |
| </p><p> |
| Below is an example of how to declare callback methods on persistent classes: |
| </p><pre class="programlisting"> |
| /** |
| * Example persistent class declaring our entity listener. |
| */ |
| @Entity |
| public class Magazine { |
| |
| @Transient |
| private byte[][] data; |
| |
| @ManyToMany |
| private List<Photo> photos; |
| |
| @PostLoad |
| public void convertPhotos() { |
| data = new byte[photos.size()][]; |
| for (int i = 0; i < photos.size(); i++) |
| data[i] = photos.get(i).toByteArray(); |
| } |
| |
| @PreDelete |
| public void logMagazineDeletion() { |
| getLog().debug("deleting magazine containing" + photos.size() |
| + " photos."); |
| } |
| } |
| |
| </pre><p> |
| In an XML mapping file, we can define the same methods without annotations: |
| </p><pre class="programlisting"> |
| <entity class="Magazine"> |
| <pre-remove>logMagazineDeletion</pre-remove> |
| <post-load>convertPhotos</post-load> |
| </entity> |
| </pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| We fully explore persistence metadata annotations and XML in |
| <a href="#jpa_overview_meta" title="Chapter 5. Metadata">Chapter 5, <i xmlns:xlink="http://www.w3.org/1999/xlink"> |
| Metadata |
| </i></a>. |
| </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_overview_entity_listeners_using"></a>3.3. |
| Using Entity Listeners |
| </h3></div></div></div><p> |
| Mixing lifecycle event code into your persistent classes is not always ideal. It |
| is often more elegant to handle cross-cutting lifecycle events in a |
| non-persistent listener class. JPA allows for this, requiring only that listener |
| classes have a public no-arg constructor. Like persistent classes, your listener |
| classes can consume any number of callbacks. The callback methods must take in a |
| single <code class="classname">java.lang.Object</code> argument which represents the |
| persistent object that triggered the event. |
| </p><p> |
| Entities can enumerate listeners using the <code class="classname">EntityListeners |
| </code> annotation. This annotation takes an array of listener classes as |
| its value. |
| </p><p> |
| Below is an example of how to declare an entity and its corresponding listener |
| classes. |
| </p><pre class="programlisting"> |
| /** |
| * Example persistent class declaring our entity listener. |
| */ |
| @Entity |
| @EntityListeners({ MagazineLogger.class, ... }) |
| public class Magazine { |
| |
| // ... // |
| } |
| |
| |
| /** |
| * Example entity listener. |
| */ |
| public class MagazineLogger { |
| |
| @PostPersist |
| public void logAddition(Object pc) { |
| getLog ().debug ("Added new magazine:" + ((Magazine) pc).getTitle ()); |
| } |
| |
| |
| @PreRemove |
| public void logDeletion(Object pc) { |
| getLog().debug("Removing from circulation:" + |
| ((Magazine) pc).getTitle()); |
| } |
| } |
| </pre><p> |
| In XML, we define both the listeners and their callback methods as so: |
| </p><pre class="programlisting"> |
| <entity class="Magazine"> |
| <entity-listeners> |
| <entity-listener class="MagazineLogger"> |
| <post-persist>logAddition</post-persist> |
| <pre-remove>logDeletion</pre-remove> |
| </entity-listener> |
| </entity-listeners> |
| </entity> |
| </pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_overview_entity_listeners_exclude"></a>3.4. |
| Entity Listeners Hierarchy |
| </h3></div></div></div><a class="indexterm" name="d0e1835"></a><p> |
| Entity listener methods are invoked in a specific order when a given event is |
| fired. So-called <span class="emphasis"><em>default</em></span> listeners are invoked first: these |
| are listeners which have been defined in a package annotation or in the root |
| element of XML mapping files. Next, entity listeners are invoked in the order of |
| the inheritance hierarchy, with superclass listeners being invoked before |
| subclass listeners. Finally, if an entity has multiple listeners for the same |
| event, the listeners are invoked in declaration order. |
| </p><p> |
| You can exclude default listeners and listeners defined in superclasses from the |
| invocation chain through the use of two class-level annotations: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="classname">ExcludeDefaultListeners</code>: This annotation indicates that |
| no default listeners will be invoked for this class, or any of its subclasses. |
| The XML equivalent is the empty <code class="literal">exclude-default-listeners</code> |
| element. |
| </p></li><li><p> |
| <code class="classname">ExcludeSuperclassListeners</code>: This annotation will cause |
| OpenJPA to skip invoking any listeners declared in superclasses. The XML |
| equivalent is the empty <code class="literal">exclude-superclass-listeners</code> element. |
| </p></li></ul></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="jpa_overview_pc_conclusion"></a>4. |
| Conclusions |
| </h2></div></div></div><p> |
| This chapter covered everything you need to know to write persistent class |
| definitions in JPA. JPA cannot use your persistent classes, however, until you |
| complete one additional step: you must define the persistence metadata. The next |
| chapter explores metadata in detail. |
| </p></div></div><div class="chapter" lang="en" id="jpa_overview_meta"><div class="titlepage"><div><div><h2 class="title"><a name="jpa_overview_meta"></a>Chapter 5. |
| Metadata |
| </h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#jpa_overview_meta_class">1. |
| Class Metadata |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_meta_entity">1.1. |
| Entity |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_meta_idclass">1.2. |
| Id Class |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_meta_embeddablesuper">1.3. |
| Mapped Superclass |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_meta_embeddable">1.4. |
| Embeddable |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_meta_entity_listeners">1.5. |
| EntityListeners |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_meta_classex">1.6. |
| Example |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_overview_meta_field">2. |
| Field and Property Metadata |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_meta_transient">2.1. |
| Transient |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_meta_id">2.2. |
| Id |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_meta_gen">2.3. |
| Generated Value |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_meta_embedid">2.4. |
| Embedded Id |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_meta_version">2.5. |
| Version |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_meta_basic">2.6. |
| Basic |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_meta_fetch">2.6.1. |
| Fetch Type |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_overview_meta_embedded">2.7. |
| Embedded |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_meta_manytoone">2.8. |
| Many To One |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_meta_cascade">2.8.1. |
| Cascade Type |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_overview_meta_onetomany">2.9. |
| One To Many |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_meta_mappedby">2.9.1. |
| Bidirectional Relations |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_overview_meta_onetoone">2.10. |
| One To One |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_meta_manytomany">2.11. |
| Many To Many |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_meta_orderby">2.12. |
| Order By |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_meta_mapkey">2.13. |
| Map Key |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_meta_fielddefaults">2.14. |
| Persistent Field Defaults |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_overview_meta_xml">3. |
| XML Schema |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_meta_complete">4. |
| Conclusion |
| </a></span></dt></dl></div><a class="indexterm" name="d0e1875"></a><a class="indexterm" name="d0e1878"></a><p> |
| JPA requires that you accompany each persistent class with persistence metadata. |
| This metadata serves three primary purposes: |
| </p><div class="orderedlist"><ol type="1"><li><p> |
| To identify persistent classes. |
| </p></li><li><p> |
| To override default JPA behavior. |
| </p></li><li><p> |
| To provide the JPA implementation with information that it cannot glean from |
| simply reflecting on the persistent class. |
| </p></li></ol></div><p> |
| <a class="indexterm" name="d0e1899"></a> |
| Persistence metadata is specified using either the Java 5 annotations defined in |
| the <code class="literal">javax.persistence</code> package, XML mapping files, or a |
| mixture of both. In the latter case, XML declarations override conflicting |
| annotations. If you choose to use XML metadata, the XML files must be available |
| at development and runtime, and must be discoverable via either of two |
| strategies: |
| </p><div class="orderedlist"><ol type="1"><li><p> |
| In a resource named <code class="filename">orm.xml</code> placed in a <code class="filename"> |
| META-INF</code> directory within a directory in your classpath or within a |
| jar archive containing your persistent classes. |
| </p></li><li><p> |
| Declared in your <a href="#jpa_overview_persistence_xml" title="1. persistence.xml"><code class="filename"> |
| persistence.xml</code></a> configuration file. In this case, each XML |
| metadata file must be listed in a <code class="literal">mapping-file</code> element whose |
| content is either a path to the given file or a resource location available to |
| the class' class loader. |
| </p></li></ol></div><p> |
| We describe the standard metadata annotations and XML equivalents throughout |
| this chapter. The full schema for XML mapping files is available in |
| <a href="#jpa_overview_meta_xml" title="3. XML Schema">Section 3, “ |
| XML Schema |
| ”</a>. JPA also standardizes relational |
| mapping metadata and named query metadata, which we discuss in |
| <a href="#jpa_overview_mapping" title="Chapter 12. Mapping Metadata">Chapter 12, <i xmlns:xlink="http://www.w3.org/1999/xlink"> |
| Mapping Metadata |
| </i></a> and |
| <a href="#jpa_overview_query_named" title="1.10. Named Queries">Section 1.10, “ |
| Named Queries |
| ”</a> respectively. |
| </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| OpenJPA defines many useful annotations beyond the standard set. See |
| <a href="#ref_guide_meta_jpa" title="3. Additional JPA Metadata">Section 3, “ |
| Additional JPA Metadata |
| ”</a> and |
| <a href="#ref_guide_meta_ext" title="4. Metadata Extensions">Section 4, “ |
| Metadata Extensions |
| ”</a> |
| in the Reference Guide for details. There are currently no XML equivalents for |
| these extension annotations. |
| </p></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| Persistence metadata may be used to validate the contents of your entities prior to communicating |
| with the database. This differs from mapping meta data which is primarily used for schema generation. |
| For example if you indicate that a relationship is not optional (e.g. @Basic(optional=false)) OpenJPA |
| will validate that the variable in your entity is not null <span class="emphasis"><em>before</em></span> inserting a row |
| in the database. |
| </p></div><div class="mediaobject"><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="369"><tr><td><img src="img/jpa-meta-model.png"></td></tr></table></div><p> |
| Through the course of this chapter, we will create the persistent object model |
| above. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="jpa_overview_meta_class"></a>1. |
| Class Metadata |
| </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#jpa_overview_meta_entity">1.1. |
| Entity |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_meta_idclass">1.2. |
| Id Class |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_meta_embeddablesuper">1.3. |
| Mapped Superclass |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_meta_embeddable">1.4. |
| Embeddable |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_meta_entity_listeners">1.5. |
| EntityListeners |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_meta_classex">1.6. |
| Example |
| </a></span></dt></dl></div><p> |
| The following metadata annotations and XML elements apply to persistent class |
| declarations. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_overview_meta_entity"></a>1.1. |
| Entity |
| </h3></div></div></div><a class="indexterm" name="d0e1961"></a><a class="indexterm" name="d0e1966"></a><a class="indexterm" name="d0e1971"></a><p> |
| The <code class="classname">Entity</code> annotation denotes an entity class. All entity |
| classes must have this annotation. The <code class="classname">Entity</code> annotation |
| takes one optional property: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">String name</code>: Name used to refer to the entity in queries. |
| Must not be a reserved literal in JPQL. Defaults to the unqualified name of the |
| entity class. |
| </p></li></ul></div><p> |
| The equivalent XML element is <code class="literal">entity</code>. It has the following |
| attributes: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">class</code>: The entity class. This attribute is required. |
| </p></li><li><p> |
| <code class="literal">name</code>: Named used to refer to the class in queries. See the |
| name property above. |
| </p></li><li><p> |
| <code class="literal">access</code>: The access type to use for the class. Must either be |
| <code class="literal">FIELD</code> or <code class="literal">PROPERTY</code>. For details on access |
| types, see <a href="#jpa_overview_meta_field" title="2. Field and Property Metadata">Section 2, “ |
| Field and Property Metadata |
| ”</a>. |
| </p></li></ul></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| OpenJPA uses a process called <span class="emphasis"><em>enhancement</em></span> to modify the |
| bytecode of entities for transparent lazy loading and immediate dirty tracking. |
| See <a href="#ref_guide_pc_enhance" title="2. Enhancement">Section 2, “ |
| Enhancement |
| ”</a> in the Reference Guide for |
| details on enhancement. |
| </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_overview_meta_idclass"></a>1.2. |
| Id Class |
| </h3></div></div></div><a class="indexterm" name="d0e2034"></a><a class="indexterm" name="d0e2037"></a><a class="indexterm" name="d0e2042"></a><p> |
| As we discussed in <a href="#jpa_overview_pc_identitycls" title="2.1. Identity Class">Section 2.1, “ |
| Identity Class |
| ”</a>, |
| entities with multiple identity fields must use an <span class="emphasis"><em> identity class |
| </em></span> to encapsulate their persistent identity. The <code class="classname">IdClass |
| </code> annotation specifies this class. It accepts a single <code class="classname"> |
| java.lang.Class</code> value. |
| </p><p> |
| The equivalent XML element is <code class="literal">id-class</code>, which has a single |
| attribute: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">class</code>: Set this required attribute to the name of the |
| identity class. |
| </p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_overview_meta_embeddablesuper"></a>1.3. |
| Mapped Superclass |
| </h3></div></div></div><a class="indexterm" name="d0e2075"></a><a class="indexterm" name="d0e2078"></a><a class="indexterm" name="d0e2083"></a><p> |
| A <span class="emphasis"><em>mapped superclass</em></span> is a non-entity class that can define |
| persistent state and mapping information for entity subclasses. Mapped |
| superclasses are usually abstract. Unlike true entities, you cannot query a |
| mapped superclass, pass a mapped superclass instance to any <code class="classname"> |
| EntityManager</code> or <code class="classname">Query</code> methods, or declare a |
| persistent relation with a mapped superclass target. You denote a mapped |
| superclass with the <code class="classname">MappedSuperclass</code> marker annotation. |
| </p><p> |
| The equivalent XML element is <code class="literal">mapped-superclass</code>. It expects |
| the following attributes: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">class</code>: The entity class. This attribute is required. |
| </p></li><li><p> |
| <code class="literal">access</code>: The access type to use for the class. Must either be |
| <code class="literal">FIELD</code> or <code class="literal">PROPERTY</code>. For details on access |
| types, see <a href="#jpa_overview_meta_field" title="2. Field and Property Metadata">Section 2, “ |
| Field and Property Metadata |
| ”</a>. |
| </p></li></ul></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| OpenJPA allows you to query on mapped superclasses. A query on a mapped |
| superclass will return all matching subclass instances. OpenJPA also allows you |
| to declare relations to mapped superclass types; however, you cannot query |
| across these relations. |
| </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_overview_meta_embeddable"></a>1.4. |
| Embeddable |
| </h3></div></div></div><a class="indexterm" name="d0e2134"></a><a class="indexterm" name="d0e2137"></a><a class="indexterm" name="d0e2142"></a><p> |
| The <code class="classname">Embeddable</code> annotation designates an embeddable |
| persistent class. Embeddable instances are stored as part of the record of their |
| owning instance. All embeddable classes must have this annotation. |
| </p><p> |
| A persistent class can either be an entity or an embeddable class, but not both. |
| </p><p> |
| The equivalent XML element is <code class="literal">embeddable</code>. It understands the |
| following attributes: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">class</code>: The entity class. This attribute is required. |
| </p></li><li><p> |
| <code class="literal">access</code>: The access type to use for the class. Must either be |
| <code class="literal">FIELD</code> or <code class="literal">PROPERTY</code>. For details on access |
| types, see <a href="#jpa_overview_meta_field" title="2. Field and Property Metadata">Section 2, “ |
| Field and Property Metadata |
| ”</a>. |
| </p></li></ul></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| OpenJPA allows a persistent class to be both an entity and an embeddable class. |
| Instances of the class will act as entites when persisted explicitly or assigned |
| to non-embedded fields of entities. Instances will act as embedded values when |
| assigned to embedded fields of entities. |
| </p><p> |
| To signal that a class is both an entity and an embeddable class in OpenJPA, |
| simply add both the <code class="literal">@Entity</code> and the <code class="literal">@Embeddable |
| </code> annotations to the class. |
| </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_overview_meta_entity_listeners"></a>1.5. |
| EntityListeners |
| </h3></div></div></div><a class="indexterm" name="d0e2194"></a><a class="indexterm" name="d0e2197"></a><a class="indexterm" name="d0e2200"></a><a class="indexterm" name="d0e2205"></a><p> |
| An entity may list its lifecycle event listeners in the <code class="classname"> |
| EntityListeners</code> annotation. This value of this annotation is an |
| array of the listener <code class="classname">Class</code> es for the entity. The |
| equivalent XML element is <code class="literal">entity-listeners</code>. For more details |
| on entity listeners, see <a href="#jpa_overview_pc_callbacks" title="3. Lifecycle Callbacks">Section 3, “ |
| Lifecycle Callbacks |
| ”</a>. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_overview_meta_classex"></a>1.6. |
| Example |
| </h3></div></div></div><p> |
| Here are the class declarations for our persistent object model, annotated with |
| the appropriate persistence metadata. Note that <code class="classname">Magazine</code> |
| declares an identity class, and that <code class="classname">Document</code> and |
| <code class="classname">Address</code> are a mapped superclass and an embeddable class, |
| respectively. <code class="classname">LifetimeSubscription</code> and <code class="classname"> |
| TrialSubscription</code> override the default entity name to supply a |
| shorter alias for use in queries. |
| </p><div class="example"><a name="jpa_overview_meta_classlisting"></a><p class="title"><b>Example 5.1. |
| Class Metadata |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| package org.mag; |
| |
| @Entity |
| @IdClass(Magazine.MagazineId.class) |
| public class Magazine { |
| ... |
| |
| public static class MagazineId { |
| ... |
| } |
| } |
| |
| @Entity |
| public class Article { |
| ... |
| } |
| |
| |
| package org.mag.pub; |
| |
| @Entity |
| public class Company { |
| ... |
| } |
| |
| @Entity |
| public class Author { |
| ... |
| } |
| |
| @Embeddable |
| public class Address { |
| ... |
| } |
| |
| |
| package org.mag.subscribe; |
| |
| @MappedSuperclass |
| public abstract class Document { |
| ... |
| } |
| |
| @Entity |
| public class Contract |
| extends Document { |
| ... |
| } |
| |
| @Entity |
| public class Subscription { |
| ... |
| |
| @Entity |
| public static class LineItem |
| extends Contract { |
| ... |
| } |
| } |
| |
| @Entity(name="Lifetime") |
| public class LifetimeSubscription |
| extends Subscription { |
| ... |
| } |
| |
| @Entity(name="Trial") |
| public class TrialSubscription |
| extends Subscription { |
| ... |
| } |
| </pre><p> |
| The equivalent declarations in XML: |
| </p><pre class="programlisting"> |
| <entity-mappings 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_1_0.xsd" |
| version="1.0"> |
| <mapped-superclass class="org.mag.subscribe.Document"> |
| ... |
| </mapped-superclass> |
| <entity class="org.mag.Magazine"> |
| <id-class class="org.mag.Magazine$MagazineId"/> |
| ... |
| </entity> |
| <entity class="org.mag.Article"> |
| ... |
| </entity> |
| <entity class="org.mag.pub.Company"> |
| ... |
| </entity> |
| <entity class="org.mag.pub.Author"> |
| ... |
| </entity> |
| <entity class="org.mag.subscribe.Contract"> |
| ... |
| </entity> |
| <entity class="org.mag.subscribe.LineItem"> |
| ... |
| </entity> |
| <entity class="org.mag.subscribe.LifetimeSubscription" name="Lifetime"> |
| ... |
| </entity> |
| <entity class="org.mag.subscribe.TrialSubscription" name="Trial"> |
| ... |
| </entity> |
| <embeddable class="org.mag.pub.Address"> |
| ... |
| </embeddable> |
| </entity-mappings> |
| </pre></div></div><br class="example-break"></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="jpa_overview_meta_field"></a>2. |
| Field and Property Metadata |
| </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#jpa_overview_meta_transient">2.1. |
| Transient |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_meta_id">2.2. |
| Id |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_meta_gen">2.3. |
| Generated Value |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_meta_embedid">2.4. |
| Embedded Id |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_meta_version">2.5. |
| Version |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_meta_basic">2.6. |
| Basic |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_meta_fetch">2.6.1. |
| Fetch Type |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_overview_meta_embedded">2.7. |
| Embedded |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_meta_manytoone">2.8. |
| Many To One |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_meta_cascade">2.8.1. |
| Cascade Type |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_overview_meta_onetomany">2.9. |
| One To Many |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_meta_mappedby">2.9.1. |
| Bidirectional Relations |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_overview_meta_onetoone">2.10. |
| One To One |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_meta_manytomany">2.11. |
| Many To Many |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_meta_orderby">2.12. |
| Order By |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_meta_mapkey">2.13. |
| Map Key |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_meta_fielddefaults">2.14. |
| Persistent Field Defaults |
| </a></span></dt></dl></div><p> |
| The persistence implementation must be able to retrieve and set the persistent |
| state of your entities, mapped superclasses, and embeddable types. JPA offers |
| two modes of persistent state access: <span class="emphasis"><em>field access</em></span>, and |
| <span class="emphasis"><em>property access</em></span>. Under field access, the implementation |
| injects state directly into your persistent fields, and retrieves changed state |
| from your fields as well. To declare field access on an entity with XML |
| metadata, set the <code class="literal">access</code> attribute of your <code class="literal">entity |
| </code> XML element to <code class="literal">FIELD</code>. To use field access for an |
| entity using annotation metadata, simply place your metadata and mapping |
| annotations on your field declarations: |
| </p><pre class="programlisting"> |
| @ManyToOne |
| private Company publisher; |
| </pre><p> |
| <a class="indexterm" name="d0e2276"></a> |
| <a class="indexterm" name="d0e2282"></a> |
| <a class="indexterm" name="d0e2288"></a> |
| Property access, on the other hand, retrieves and loads state through JavaBean |
| "getter" and "setter" methods. For a property <code class="literal">p</code> of type |
| <code class="literal">T</code>, you must define the following getter method: |
| </p><pre class="programlisting"> |
| T getP(); |
| </pre><p> |
| For boolean properties, this is also acceptable: |
| </p><pre class="programlisting"> |
| boolean isP(); |
| </pre><p> |
| You must also define the following setter method: |
| </p><pre class="programlisting"> |
| void setP(T value); |
| </pre><p> |
| To use property access, set your <code class="literal">entity</code> element's <code class="literal"> |
| access</code> attribute to <code class="literal">PROPERTY</code>, or place your |
| metadata and mapping annotations on the getter method: |
| </p><pre class="programlisting"> |
| @ManyToOne |
| private Company getPublisher() { ... } |
| |
| private void setPublisher(Company publisher) { ... } |
| </pre><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3><p> |
| When using property access, only the getter and setter method for a property |
| should ever access the underlying persistent field directly. Other methods, |
| including internal business methods in the persistent class, should go through |
| the getter and setter methods when manipulating persistent state. |
| </p><p> |
| Also, take care when adding business logic to your getter and setter methods. |
| Consider that they are invoked by the persistence implementation to load and |
| retrieve all persistent state; other side effects might not be desirable. |
| </p></div><p> |
| Each class must use either field access or property access for all state; you |
| cannot use both access types within the same class. Additionally, a subclass |
| must use the same access type as its superclass. |
| </p><p> |
| The remainder of this document uses the term "persistent field" to refer to |
| either a persistent field or a persistent property. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_overview_meta_transient"></a>2.1. |
| Transient |
| </h3></div></div></div><a class="indexterm" name="d0e2335"></a><a class="indexterm" name="d0e2338"></a><a class="indexterm" name="d0e2343"></a><p> |
| The <code class="classname">Transient</code> annotation specifies that a field is |
| non-persistent. Use it to exclude fields from management that would otherwise be |
| persistent. <code class="classname">Transient</code> is a marker annotation only; it |
| has no properties. |
| </p><p> |
| The equivalent XML element is <code class="literal">transient</code>. It has a single |
| attribute: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">name</code>: The transient field or property name. This attribute |
| is required. |
| </p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_overview_meta_id"></a>2.2. |
| Id |
| </h3></div></div></div><a class="indexterm" name="d0e2371"></a><a class="indexterm" name="d0e2374"></a><a class="indexterm" name="d0e2379"></a><p> |
| Annotate your simple identity fields with <code class="classname">Id</code>. This |
| annotation has no properties. We explore entity identity and identity fields in |
| <a href="#jpa_overview_pc_id" title="1.3. Identity Fields">Section 1.3, “ |
| Identity Fields |
| ”</a>. |
| </p><p> |
| The equivalent XML element is <code class="literal">id</code>. It has one required |
| attribute: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">name</code>: The name of the identity field or property. |
| </p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_overview_meta_gen"></a>2.3. |
| Generated Value |
| </h3></div></div></div><a class="indexterm" name="d0e2406"></a><a class="indexterm" name="d0e2409"></a><a class="indexterm" name="d0e2414"></a><p> |
| The previous section showed you how to declare your identity fields with the |
| <code class="classname">Id</code> annotation. It is often convenient to allow the |
| persistence implementation to assign a unique value to your identity fields |
| automatically. JPA includes the <code class="classname">GeneratedValue</code> |
| annotation for this purpose. It has the following properties: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">GenerationType strategy</code>: Enum value specifying how to |
| auto-generate the field value. The <code class="classname">GenerationType</code> enum |
| has the following values: |
| </p><div class="itemizedlist"><ul type="circle"><li><p> |
| <code class="literal">GeneratorType.AUTO</code>: The default. Assign the field a |
| generated value, leaving the details to the JPA vendor. |
| </p></li><li><p> |
| <code class="literal">GenerationType.IDENTITY</code>: The database will assign an |
| identity value on insert. |
| </p></li><li><p> |
| <code class="literal">GenerationType.SEQUENCE</code>: Use a datastore sequence to |
| generate a field value. |
| </p></li><li><p> |
| <code class="literal">GenerationType.TABLE</code>: Use a sequence table to generate a |
| field value. |
| </p></li></ul></div></li><li><p> |
| <code class="literal">String generator</code>: The name of a generator defined in mapping |
| metadata. We show you how to define named generators in |
| <a href="#jpa_overview_mapping_sequence" title="5. Generators">Section 5, “ |
| Generators |
| ”</a>. If the <code class="classname"> |
| GenerationType</code> is set but this property is unset, the JPA |
| implementation uses appropriate defaults for the selected generation type. |
| </p></li></ul></div><p> |
| The equivalent XML element is <code class="literal">generated-value</code>, which |
| includes the following attributes: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">strategy</code>: One of <code class="literal"> TABLE</code>, <code class="literal"> |
| SEQUENCE</code>, <code class="literal"> IDENTITY</code>, or <code class="literal">AUTO</code>, |
| defaulting to <code class="literal">AUTO</code>. |
| </p></li><li><p> |
| <code class="literal">generator</code>: Equivalent to the generator property listed |
| above. |
| </p></li></ul></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| OpenJPA allows you to use the <code class="classname">GeneratedValue</code> annotation |
| on any field, not just identity fields. Before using the <code class="literal">IDENTITY |
| </code> generation strategy, however, read |
| <a href="#ref_guide_pc_oid_pkgen_autoinc" title="4.4. Autoassign / Identity Strategy Caveats">Section 4.4, “ |
| Autoassign / Identity Strategy Caveats |
| ”</a> in the Reference Guide. |
| </p><p> |
| OpenJPA also offers additional generator strategies for non-numeric fields, |
| which you can access by setting <code class="literal">strategy</code> to <code class="literal">AUTO |
| </code> (the default), and setting the <code class="literal">generator</code> string |
| to: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <a class="indexterm" name="d0e2532"></a> |
| <a class="indexterm" name="d0e2538"></a> |
| <code class="literal">uuid-string</code>: OpenJPA will generate a 128-bit type 1 UUID |
| unique within the network, represented as a 16-character string. For more |
| information on UUIDs, see the IETF UUID draft specification at: |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="http://www1.ics.uci.edu/~ejw/authoring/uuid-guid/" target="_top"> |
| http://www1.ics.uci.edu/~ejw/authoring/uuid-guid/</a> |
| </p></li><li><p> |
| <a class="indexterm" name="d0e2551"></a> |
| <a class="indexterm" name="d0e2557"></a> |
| <code class="literal">uuid-hex</code>: Same as <code class="literal"> uuid-string</code>, but |
| represents the type 1 UUID as a 32-character hexadecimal string. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e2570"></a> |
| <a class="indexterm" name="d0e2576"></a> |
| <code class="literal">uuid-type4-string</code>: OpenJPA will generate a 128-bit type 4 |
| pseudo-random UUID, represented as a 16-character string. For more |
| information on UUIDs, see the IETF UUID draft specification at: |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="http://www1.ics.uci.edu/~ejw/authoring/uuid-guid/" target="_top"> |
| http://www1.ics.uci.edu/~ejw/authoring/uuid-guid/</a> |
| </p></li><li><p> |
| <a class="indexterm" name="d0e2589"></a> |
| <a class="indexterm" name="d0e2595"></a> |
| <code class="literal">uuid-type4-hex</code>: Same as <code class="literal"> uuid-type4-string</code> |
| , but represents the type 4 UUID as a 32-character hexadecimal string. |
| </p></li></ul></div><p> |
| These string constants are defined in |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/Generator.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.Generator</code></a>. |
| </p><p> |
| If the entities are mapped to the same table name but with different schema |
| name within one <code class="literal">PersistenceUnit</code> intentionally, and the |
| strategy of <code class="literal">GeneratedType.AUTO</code> is used to generate the ID |
| for each entity, a schema name for each entity must be explicitly declared |
| either through the annotation or the mapping.xml file. Otherwise, the mapping |
| tool only creates the tables for those entities with the schema names under |
| each schema. In addition, there will be only one |
| <code class="literal">OPENJPA_SEQUENCE_TABLE</code> created for all the entities within |
| the <code class="literal">PersistenceUnit</code> if the entities are not identified |
| with the schema name. Read <a href="#ref_guide_sequence" title="6. Generators">Section 6, “ |
| Generators |
| ”</a> and |
| <a href="#ref_guide_schema_def" title="11. Default Schema">Section 11, “ |
| Default Schema |
| ”</a> in the Reference Guide. |
| </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_overview_meta_embedid"></a>2.4. |
| Embedded Id |
| </h3></div></div></div><a class="indexterm" name="d0e2633"></a><a class="indexterm" name="d0e2636"></a><a class="indexterm" name="d0e2641"></a><p> |
| If your entity has multiple identity values, you may declare multiple <code class="literal"> |
| @Id</code> fields, or you may declare a single <code class="literal">@EmbeddedId</code> |
| field. The type of a field annotated with <code class="classname">EmbeddedId</code> must |
| be an embeddable entity class. The fields of this embeddable class are |
| considered the identity values of the owning entity. We explore entity identity |
| and identity fields in <a href="#jpa_overview_pc_id" title="1.3. Identity Fields">Section 1.3, “ |
| Identity Fields |
| ”</a>. |
| </p><p> |
| The <code class="classname">EmbeddedId</code> annotation has no properties. |
| </p><p> |
| The equivalent XML element is <code class="literal">embedded-id</code>. It has one |
| required attribute: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">name</code>: The name of the identity field or property. |
| </p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_overview_meta_version"></a>2.5. |
| Version |
| </h3></div></div></div><a class="indexterm" name="d0e2679"></a><a class="indexterm" name="d0e2682"></a><a class="indexterm" name="d0e2687"></a><p> |
| Use the <code class="classname">Version</code> annotation to designate a version field. |
| <a href="#jpa_overview_pc_version" title="1.4. Version Field">Section 1.4, “ |
| Version Field |
| ”</a> explained the importance of |
| version fields to JPA. This is a marker annotation; it has no properties. |
| </p><p> |
| The equivalent XML element is <code class="literal">version</code>, which has a single |
| attribute: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">name</code>: The name of the version field or property. This |
| attribute is required. |
| </p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_overview_meta_basic"></a>2.6. |
| Basic |
| </h3></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#jpa_overview_meta_fetch">2.6.1. |
| Fetch Type |
| </a></span></dt></dl></div><a class="indexterm" name="d0e2714"></a><a class="indexterm" name="d0e2717"></a><a class="indexterm" name="d0e2722"></a><p> |
| <code class="classname">Basic</code> signifies a standard value persisted as-is to the |
| datastore. You can use the <code class="classname">Basic</code> annotation on persistent |
| fields of the following types: primitives, primitive wrappers, <code class="classname"> |
| java.lang.String</code>, <code class="classname">byte[]</code>, <code class="classname"> |
| Byte[]</code>, <code class="classname">char[]</code>, <code class="classname"> |
| Character[]</code>, <code class="classname">java.math.BigDecimal</code>, |
| <code class="classname">java.math.BigInteger</code>, <code class="classname"> |
| java.util.Date</code>, <code class="classname">java.util.Calendar</code>, |
| <code class="classname">java.sql.Date</code>, <code class="classname">java.sql.Timestamp</code>, |
| <code class="classname">Enum</code>s, and <code class="classname">Serializable</code> types. |
| </p><p> |
| <code class="classname">Basic</code> declares these properties: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">FetchType fetch</code>: Whether to load the field eagerly |
| (<code class="literal">FetchType.EAGER</code>) or lazily (<code class="literal"> |
| FetchType.LAZY</code>). Defaults to <code class="literal">FetchType.EAGER</code>. |
| </p></li><li><p> |
| <code class="literal">boolean optional</code>: Whether the datastore allows null values. |
| Defaults to true. |
| </p></li></ul></div><p> |
| The equivalent XML element is <code class="literal">basic</code>. It has the following |
| attributes: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">name</code>: The name of the field or property. This attribute is |
| required. |
| </p></li><li><p> |
| <code class="literal">fetch</code>: One of <code class="literal">EAGER</code> or <code class="literal">LAZY |
| </code>. |
| </p></li><li><p> |
| <code class="literal">optional</code>: Boolean indicating whether the field value may be |
| null. |
| </p></li></ul></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="jpa_overview_meta_fetch"></a>2.6.1. |
| Fetch Type |
| </h4></div></div></div><a class="indexterm" name="d0e2834"></a><a class="indexterm" name="d0e2839"></a><a class="indexterm" name="d0e2844"></a><p> |
| Many metadata annotations in JPA have a <code class="literal">fetch</code> property. This |
| property can take on one of two values: <code class="literal">FetchType.EAGER</code> or |
| <code class="literal">FetchType.LAZY</code>. <code class="literal">FetchType.EAGER</code> means that |
| the field is loaded by the JPA implementation before it returns the persistent |
| object to you. Whenever you retrieve an entity from a query or from the |
| <code class="classname">EntityManager</code>, you are guaranteed that all of its eager |
| fields are populated with datastore data. |
| </p><p> |
| <code class="literal">FetchType.LAZY</code> is a hint to the JPA runtime that you want to |
| defer loading of the field until you access it. This is called <span class="emphasis"><em>lazy |
| loading</em></span>. Lazy loading is completely transparent; when you attempt to |
| read the field for the first time, the JPA runtime will load the value from the |
| datastore and populate the field automatically. Lazy loading is only a hint and |
| not a directive because some JPA implementations cannot lazy-load certain field |
| types. |
| </p><p> |
| With a mix of eager and lazily-loaded fields, you can ensure that commonly-used |
| fields load efficiently, and that other state loads transparently when accessed. |
| As you will see in <a href="#jpa_overview_emfactory_perscontext" title="3. Persistence Context">Section 3, “ |
| Persistence Context |
| ”</a>, |
| you can also use eager fetching to ensure that entites have all needed data |
| loaded before they become <span class="emphasis"><em>detached</em></span> at the end of a |
| persistence context. |
| </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| OpenJPA can lazy-load any field type. OpenJPA also allows you to dynamically |
| change which fields are eagerly or lazily loaded at runtime. See |
| <a href="#ref_guide_fetch" title="7. Fetch Groups">Section 7, “ |
| Fetch Groups |
| ”</a> in the Reference Guide for details. |
| </p><p> |
| The Reference Guide details OpenJPA's eager fetching behavior in |
| <a href="#ref_guide_perfpack_eager" title="8. Eager Fetching">Section 8, “ |
| Eager Fetching |
| ”</a>. |
| </p></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_overview_meta_embedded"></a>2.7. |
| Embedded |
| </h3></div></div></div><a class="indexterm" name="d0e2893"></a><a class="indexterm" name="d0e2896"></a><a class="indexterm" name="d0e2901"></a><p> |
| Use the <code class="classname">Embedded</code> marker annotation on embeddable field |
| types. Embedded fields are mapped as part of the datastore record of the |
| declaring entity. In our sample model, <code class="classname">Author</code> and |
| <code class="classname">Company</code> each embed their <code class="classname">Address</code>, |
| rather than forming a relation to an <code class="classname">Address</code> as a |
| separate entity. |
| </p><p> |
| The equivalent XML element is <code class="literal">embedded</code>, which expects a |
| single attribute: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">name</code>: The name of the field or property. This attribute is |
| required. |
| </p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_overview_meta_manytoone"></a>2.8. |
| Many To One |
| </h3></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#jpa_overview_meta_cascade">2.8.1. |
| Cascade Type |
| </a></span></dt></dl></div><a class="indexterm" name="d0e2938"></a><a class="indexterm" name="d0e2941"></a><a class="indexterm" name="d0e2946"></a><p> |
| When an entity <code class="literal">A</code> references a single entity <code class="literal"> |
| B</code>, and other <code class="literal">A</code>s might also reference the same |
| <code class="literal">B</code>, we say there is a <span class="emphasis"><em>many to one</em></span> |
| relation from <code class="literal">A</code> to <code class="literal">B</code>. In our sample |
| model, for example, each magazine has a reference to its publisher. Multiple |
| magazines might have the same publisher. We say, then, that the <code class="literal"> |
| Magazine.publisher</code> field is a many to one relation from magazines to |
| publishers. |
| </p><p> |
| JPA indicates many to one relations between entities with the <code class="classname"> |
| ManyToOne</code> annotation. This annotation has the following properties: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">Class targetEntity</code>: The class of the related entity type. |
| </p></li><li><p> |
| <code class="literal">CascadeType[] cascade</code>: Array of enum values defining cascade |
| behavior for this field. We explore cascades below. Defaults to an empty array. |
| </p></li><li><p> |
| <code class="literal">FetchType fetch</code>: Whether to load the field eagerly |
| (<code class="literal">FetchType.EAGER</code>) or lazily |
| (<code class="literal">FetchType.LAZY</code>). Defaults to <code class="literal"> |
| FetchType.EAGER</code>. See <a href="#jpa_overview_meta_fetch" title="2.6.1. Fetch Type">Section 2.6.1, “ |
| Fetch Type |
| ”</a> above |
| for details on fetch types. |
| </p></li><li><p> |
| <code class="literal">boolean optional</code>: Whether the related object must exist. If |
| <code class="literal">false</code>, this field cannot be null. Defaults to <code class="literal"> |
| true</code>. |
| </p></li></ul></div><p> |
| The equivalent XML element is <code class="literal">many-to-one</code>. It accepts the |
| following attributes: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">name</code>: The name of the field or property. This attribute is |
| required. |
| </p></li><li><p> |
| <code class="literal">target-entity</code>: The class of the related type. |
| </p></li><li><p> |
| <code class="literal">fetch</code>: One of <code class="literal">EAGER</code> or <code class="literal"> |
| LAZY</code>. |
| </p></li><li><p> |
| <code class="literal">optional</code>: Boolean indicating whether the field value may be |
| null. |
| </p></li></ul></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="jpa_overview_meta_cascade"></a>2.8.1. |
| Cascade Type |
| </h4></div></div></div><a class="indexterm" name="d0e3063"></a><a class="indexterm" name="d0e3066"></a><p> |
| We introduce the JPA <code class="classname">EntityManager</code> in |
| <a href="#jpa_overview_em" title="Chapter 8. EntityManager">Chapter 8, <i xmlns:xlink="http://www.w3.org/1999/xlink"> |
| EntityManager |
| </i></a>. The <code class="classname">EntityManager |
| </code> has APIs to persist new entities, remove (delete) existing |
| entities, refresh entity state from the datastore, and merge <span class="emphasis"><em>detached |
| </em></span> entity state back into the persistence context. We explore all of |
| these APIs in detail later in the overview. |
| </p><p> |
| When the <code class="classname">EntityManager</code> is performing the above |
| operations, you can instruct it to automatically cascade the operation to the |
| entities held in a persistent field with the <code class="literal">cascade</code> property |
| of your metadata annotation. This process is recursive. The <code class="literal">cascade |
| </code> property accepts an array of <code class="classname">CascadeType</code> enum |
| values. |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">CascadeType.PERSIST</code>: When persisting an entity, also persist |
| the entities held in this field. We suggest liberal application of this cascade |
| rule, because if the <code class="classname">EntityManager</code> finds a field that |
| references a new entity during flush, and the field does not use <code class="literal"> |
| CascadeType.PERSIST</code>, it is an error. |
| </p></li><li><p> |
| <code class="literal">CascadeType.REMOVE</code>: When deleting an entity, also delete the |
| entities held in this field. |
| </p></li><li><p> |
| <code class="literal">CascadeType.REFRESH</code>: When refreshing an entity, also refresh |
| the entities held in this field. |
| </p></li><li><p> |
| <code class="literal">CascadeType.MERGE</code>: When merging entity state, also merge the |
| entities held in this field. |
| </p></li></ul></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| OpenJPA offers enhancements to JPA's CascadeType.REMOVE functionality, |
| including additional annotations to control how and when dependent fields will |
| be removed. See <a href="#dependent" title="4.2.1. Dependent">Section 4.2.1, “ |
| Dependent |
| ”</a> for more details. |
| </p></div><p> |
| <code class="classname">CascadeType</code> defines one additional value, <code class="literal"> |
| CascadeType.ALL</code>, that acts as a shortcut for all of the values above. |
| The following annotations are equivalent: |
| </p><pre class="programlisting"> |
| @ManyToOne(cascade={CascadeType.PERSIST,CascadeType.REMOVE, |
| CascadeType.REFRESH,CascadeType.MERGE}) |
| private Company publisher; |
| </pre><pre class="programlisting"> |
| @ManyToOne(cascade=CascadeType.ALL) |
| private Company publisher; |
| </pre><p> |
| In XML, these enumeration constants are available as child elements of the |
| <code class="literal">cascade</code> element. The <code class="literal">cascade</code> element is |
| itself a child of <code class="literal">many-to-one</code>. The following examples are |
| equivalent: |
| </p><pre class="programlisting"> |
| <many-to-one name="publisher"> |
| <cascade> |
| <cascade-persist/> |
| <cascade-merge/> |
| <cascade-remove/> |
| <cascade-refresh/> |
| </cascade> |
| </many-to-one> |
| </pre><pre class="programlisting"> |
| <many-to-one name="publisher"> |
| <cascade> |
| <cascade-all/> |
| </cascade> |
| </many-to-one> |
| </pre></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_overview_meta_onetomany"></a>2.9. |
| One To Many |
| </h3></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#jpa_overview_meta_mappedby">2.9.1. |
| Bidirectional Relations |
| </a></span></dt></dl></div><a class="indexterm" name="d0e3164"></a><a class="indexterm" name="d0e3167"></a><a class="indexterm" name="d0e3172"></a><p> |
| When an entity <code class="literal">A</code> references multiple <code class="literal">B</code> |
| entities, and no two <code class="literal">A</code>s reference the same <code class="literal"> |
| B</code>, we say there is a <span class="emphasis"><em>one to many</em></span> relation from |
| <code class="literal">A</code> to <code class="literal">B</code>. |
| </p><p> |
| One to many relations are the exact inverse of the many to one relations we |
| detailed in the preceding section. In that section, we said that the <code class="literal"> |
| Magazine.publisher</code> field is a many to one relation from magazines to |
| publishers. Now, we see that the <code class="literal">Company.mags</code> field is the |
| inverse - a one to many relation from publishers to magazines. Each company may |
| publish multiple magazines, but each magazine can have only one publisher. |
| </p><p> |
| JPA indicates one to many relations between entities with the <code class="classname"> |
| OneToMany</code> annotation. This annotation has the following properties: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">Class targetEntity</code>: The class of the related entity type. |
| This information is usually taken from the parameterized collection or map |
| element type. You must supply it explicitly, however, if your field isn't a |
| parameterized type. |
| </p></li><li><p> |
| <code class="literal">String mappedBy</code>: Names the many to one field in the related |
| entity that maps this bidirectional relation. We explain bidirectional relations |
| below. Leaving this property unset signals that this is a standard |
| unidirectional relation. |
| </p></li><li><p> |
| <code class="literal">CascadeType[] cascade</code>: Array of enum values defining cascade |
| behavior for the collection elements. We explore cascades above in |
| <a href="#jpa_overview_meta_cascade" title="2.8.1. Cascade Type">Section 2.8.1, “ |
| Cascade Type |
| ”</a>. Defaults to an empty array. |
| </p></li><li><p> |
| <code class="literal">FetchType fetch</code>: Whether to load the field eagerly |
| (<code class="literal">FetchType.EAGER</code>) or lazily |
| (<code class="literal">FetchType.LAZY</code>). Defaults to <code class="literal"> |
| FetchType.LAZY</code>. See <a href="#jpa_overview_meta_fetch" title="2.6.1. Fetch Type">Section 2.6.1, “ |
| Fetch Type |
| ”</a> above |
| for details on fetch types. |
| </p></li></ul></div><p> |
| The equivalent XML element is <code class="literal">one-to-many</code>, which includes |
| the following attributes: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">name</code>: The name of the field or property. This attribute is |
| required. |
| </p></li><li><p> |
| <code class="literal">target-entity</code>: The class of the related type. |
| </p></li><li><p> |
| <code class="literal">fetch</code>: One of <code class="literal">EAGER</code> or <code class="literal"> |
| LAZY</code>. |
| </p></li><li><p> |
| <code class="literal">mapped-by</code>: The name of the field or property that owns the |
| relation. See <a href="#jpa_overview_meta_field" title="2. Field and Property Metadata">Section 2, “ |
| Field and Property Metadata |
| ”</a>. |
| </p></li></ul></div><p> |
| You may also nest the <code class="literal">cascade</code> element within a <code class="literal"> |
| one-to-many</code> element. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="jpa_overview_meta_mappedby"></a>2.9.1. |
| Bidirectional Relations |
| </h4></div></div></div><a class="indexterm" name="d0e3300"></a><a class="indexterm" name="d0e3303"></a><a class="indexterm" name="d0e3308"></a><p> |
| When two fields are logical inverses of each other, they form a <span class="emphasis"><em> |
| bidirectional relation</em></span>. Our model contains two bidirectional |
| relations: <code class="literal">Magazine.publisher</code> and <code class="literal">Company.mags |
| </code> form one bidirectional relation, and <code class="literal">Article.authors |
| </code> and <code class="literal">Author.articles</code> form the other. In both cases, |
| there is a clear link between the two fields that form the relationship. A |
| magazine refers to its publisher while the publisher refers to all its published |
| magazines. An article refers to its authors while each author refers to her |
| written articles. |
| </p><p> |
| When the two fields of a bidirectional relation share the same datastore |
| mapping, JPA formalizes the connection with the <code class="literal">mappedBy</code> |
| property. Marking <code class="literal">Company.mags</code> as <code class="literal">mappedBy</code> |
| <code class="literal">Magazine.publisher</code> means two things: |
| </p><div class="orderedlist"><ol type="1"><li><p> |
| <code class="literal">Company.mags</code> uses the datastore mapping for <code class="literal"> |
| Magazine.publisher</code>, but inverses it. In fact, it is illegal to |
| specify any additional mapping information when you use the <code class="literal">mappedBy |
| </code> property. All mapping information is read from the referenced field. |
| We explore mapping in depth in <a href="#jpa_overview_mapping" title="Chapter 12. Mapping Metadata">Chapter 12, <i xmlns:xlink="http://www.w3.org/1999/xlink"> |
| Mapping Metadata |
| </i></a>. |
| </p></li><li><p> |
| <code class="literal">Magazine.publisher</code> is the "owner" of the relation. The field |
| that specifies the mapping data is always the owner. This means that changes to |
| the <code class="literal">Magazine.publisher</code> field are reflected in the datastore, |
| while changes to the <code class="literal">Company.mags</code> field alone are not. |
| Changes to <code class="literal">Company.mags</code> may still affect the JPA |
| implementation's cache, however. Thus, it is very important that you keep your |
| object model consistent by properly maintaining both sides of your bidirectional |
| relations at all times. |
| </p></li></ol></div><p> |
| You should always take advantage of the <code class="literal">mappedBy</code> property |
| rather than mapping each field of a bidirectional relation independently. |
| Failing to do so may result in the JPA implementation trying to update the |
| database with conflicting data. Be careful to only mark one side of the relation |
| as <code class="literal">mappedBy</code>, however. One side has to actually do the |
| mapping! |
| </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| You can configure OpenJPA to automatically synchronize both sides of a |
| bidirectional relation, or to perform various actions when it detects |
| inconsistent relations. See <a href="#ref_guide_inverses" title="5. Managed Inverses">Section 5, “ |
| Managed Inverses |
| ”</a> in the |
| Reference Guide for details. |
| </p></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_overview_meta_onetoone"></a>2.10. |
| One To One |
| </h3></div></div></div><a class="indexterm" name="d0e3390"></a><a class="indexterm" name="d0e3393"></a><a class="indexterm" name="d0e3398"></a><p> |
| When an entity <code class="literal">A</code> references a single entity <code class="literal"> |
| B</code>, and no other <code class="literal">A</code>s can reference the same <code class="literal"> |
| B</code>, we say there is a <span class="emphasis"><em>one to one</em></span> relation between |
| <code class="literal">A</code> and <code class="literal">B</code>. In our sample model, <code class="classname"> |
| Magazine</code> has a one to one relation to <code class="classname">Article</code> |
| through the <code class="literal">Magazine.coverArticle</code> field. No two magazines can |
| have the same cover article. |
| </p><p> |
| JPA indicates one to one relations between entities with the <code class="classname"> |
| OneToOne</code> annotation. This annotation has the following properties: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">Class targetEntity</code>: The class of the related entity type. |
| This information is usually taken from the field type. |
| </p></li><li><p> |
| <code class="literal">String mappedBy</code>: Names the field in the related entity that |
| maps this bidirectional relation. We explain bidirectional relations in |
| <a href="#jpa_overview_meta_mappedby" title="2.9.1. Bidirectional Relations">Section 2.9.1, “ |
| Bidirectional Relations |
| ”</a> above. Leaving this property |
| unset signals that this is a standard unidirectional relation. |
| </p></li><li><p> |
| <code class="literal">CascadeType[] cascade</code>: Array of enum values defining cascade |
| behavior for this field. We explore cascades in |
| <a href="#jpa_overview_meta_cascade" title="2.8.1. Cascade Type">Section 2.8.1, “ |
| Cascade Type |
| ”</a> above. Defaults to an empty |
| array. |
| </p></li><li><p> |
| <code class="literal">FetchType fetch</code>: Whether to load the field eagerly |
| (<code class="literal">FetchType.EAGER</code>) or lazily |
| (<code class="literal">FetchType.LAZY</code>). Defaults to <code class="literal"> |
| FetchType.EAGER</code>. See <a href="#jpa_overview_meta_fetch" title="2.6.1. Fetch Type">Section 2.6.1, “ |
| Fetch Type |
| ”</a> above |
| for details on fetch types. |
| </p></li><li><p> |
| <code class="literal">boolean optional</code>: Whether the related object must exist. If |
| <code class="literal">false</code>, this field cannot be null. Defaults to <code class="literal"> |
| true</code>. |
| </p></li></ul></div><p> |
| The equivalent XML element is <code class="literal">one-to-one</code> which understands |
| the following attributes: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">name</code>: The name of the field or property. This attribute is |
| required. |
| </p></li><li><p> |
| <code class="literal">target-entity</code>: The class of the related type. |
| </p></li><li><p> |
| <code class="literal">fetch</code>: One of <code class="literal">EAGER</code> or <code class="literal"> |
| LAZY</code>. |
| </p></li><li><p> |
| <code class="literal">mapped-by</code>: The field that owns the relation. See |
| <a href="#jpa_overview_meta_field" title="2. Field and Property Metadata">Section 2, “ |
| Field and Property Metadata |
| ”</a>. |
| </p></li></ul></div><p> |
| You may also nest the <code class="literal">cascade</code> element within a <code class="literal"> |
| one-to-one</code> element. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_overview_meta_manytomany"></a>2.11. |
| Many To Many |
| </h3></div></div></div><a class="indexterm" name="d0e3541"></a><a class="indexterm" name="d0e3544"></a><a class="indexterm" name="d0e3549"></a><p> |
| When an entity <code class="literal">A</code> references multiple <code class="literal">B</code> |
| entities, and other <code class="literal">A</code>s might reference some of the same |
| <code class="literal">B</code>s, we say there is a <span class="emphasis"><em>many to many</em></span> |
| relation between <code class="literal">A</code> and <code class="literal">B</code>. In our sample |
| model, for example, each article has a reference to all the authors that |
| contributed to the article. Other articles might have some of the same authors. |
| We say, then, that <code class="classname">Article</code> and <code class="classname">Author |
| </code> have a many to many relation through the <code class="literal">Article.authors |
| </code> field. |
| </p><p> |
| JPA indicates many to many relations between entities with the <code class="classname"> |
| ManyToMany</code> annotation. This annotation has the following properties: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">Class targetEntity</code>: The class of the related entity type. |
| This information is usually taken from the parameterized collection or map |
| element type. You must supply it explicitly, however, if your field isn't a |
| parameterized type. |
| </p></li><li><p> |
| <code class="literal">String mappedBy</code>: Names the many to many field in the related |
| entity that maps this bidirectional relation. We explain bidirectional relations |
| in <a href="#jpa_overview_meta_mappedby" title="2.9.1. Bidirectional Relations">Section 2.9.1, “ |
| Bidirectional Relations |
| ”</a> above. Leaving this |
| property unset signals that this is a standard unidirectional relation. |
| </p></li><li><p> |
| <code class="literal">CascadeType[] cascade</code>: Array of enum values defining cascade |
| behavior for the collection elements. We explore cascades above in |
| <a href="#jpa_overview_meta_cascade" title="2.8.1. Cascade Type">Section 2.8.1, “ |
| Cascade Type |
| ”</a>. Defaults to an empty array. |
| </p></li><li><p> |
| <code class="literal">FetchType fetch</code>: Whether to load the field eagerly |
| (<code class="literal">FetchType.EAGER</code>) or lazily |
| (<code class="literal">FetchType.LAZY</code>). Defaults to <code class="literal"> |
| FetchType.LAZY</code>. See <a href="#jpa_overview_meta_fetch" title="2.6.1. Fetch Type">Section 2.6.1, “ |
| Fetch Type |
| ”</a> above |
| for details on fetch types. |
| </p></li></ul></div><p> |
| The equivalent XML element is <code class="literal">many-to-many</code>. It accepts the |
| following attributes: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">name</code>: The name of the field or property. This attribute is |
| required. |
| </p></li><li><p> |
| <code class="literal">target-entity</code>: The class of the related type. |
| </p></li><li><p> |
| <code class="literal">fetch</code>: One of <code class="literal">EAGER</code> or <code class="literal"> |
| LAZY</code>. |
| </p></li><li><p> |
| <code class="literal">mapped-by</code>: The field that owns the relation. See |
| <a href="#jpa_overview_meta_field" title="2. Field and Property Metadata">Section 2, “ |
| Field and Property Metadata |
| ”</a>. |
| </p></li></ul></div><p> |
| You may also nest the <code class="literal">cascade</code> element within a <code class="literal"> |
| many-to-many</code> element. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_overview_meta_orderby"></a>2.12. |
| Order By |
| </h3></div></div></div><a class="indexterm" name="d0e3680"></a><a class="indexterm" name="d0e3683"></a><a class="indexterm" name="d0e3688"></a><p> |
| Datastores such as relational databases do not preserve the order of records. |
| Your persistent <code class="classname">List</code> fields might be ordered one way the |
| first time you retrieve an object from the datastore, and a completely different |
| way the next. To ensure consistent ordering of collection fields, you must use |
| the <code class="classname">OrderBy</code> annotation. The <code class="classname">OrderBy |
| </code> annotation's value is a string defining the order of the collection |
| elements. An empty value means to sort on the identity value(s) of the elements |
| in ascending order. Any other value must be of the form: |
| </p><pre class="programlisting"> |
| <field name>[ ASC|DESC][, ...] |
| </pre><p> |
| Each <code class="literal"><field name></code> is the name of a persistent field in |
| the collection's element type. You can optionally follow each field by the |
| keyword <code class="literal">ASC</code> for ascending order, or <code class="literal">DESC</code> |
| for descending order. If the direction is omitted, it defaults to ascending. |
| </p><p> |
| The equivalent XML element is <code class="literal">order-by</code> which can be listed as |
| a sub-element of the <code class="literal">one-to-many</code> or <code class="literal">many-to-many |
| </code> elements. The text within this element is parsed as the order by |
| string. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_overview_meta_mapkey"></a>2.13. |
| Map Key |
| </h3></div></div></div><a class="indexterm" name="d0e3731"></a><a class="indexterm" name="d0e3734"></a><a class="indexterm" name="d0e3739"></a><p> |
| JPA supports persistent <code class="classname">Map</code> fields through either a |
| <a href="#jpa_overview_meta_onetomany" title="2.9. One To Many"><code class="classname"> OneToMany</code> |
| </a> or <a href="#jpa_overview_meta_manytomany" title="2.11. Many To Many"><code class="classname">ManyToMany |
| </code></a> association. The related entities form the map values. JPA |
| derives the map keys by extracting a field from each entity value. The |
| <code class="classname">MapKey</code> annotation designates the field that is used as |
| the key. It has the following properties: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">String name</code>: The name of a field in the related entity class |
| to use as the map key. If no name is given, defaults to the identity field of |
| the related entity class. |
| </p></li></ul></div><p> |
| The equivalent XML element is <code class="literal">map-key</code> which can be listed as |
| a sub-element of the <code class="literal">one-to-many</code> or <code class="literal">many-to-many |
| </code> elements. The <code class="literal">map-key</code> element has the following |
| attributes: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">name</code>: The name of the field in the related entity class to |
| use as the map key. |
| </p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_overview_meta_fielddefaults"></a>2.14. |
| Persistent Field Defaults |
| </h3></div></div></div><p> |
| In the absence of any of the annotations above, JPA defines the following |
| default behavior for declared fields: |
| </p><div class="orderedlist"><ol type="1"><li><p> |
| Fields declared <code class="literal">static, transient</code>, or <code class="literal">final |
| </code> default to non-persistent. |
| </p></li><li><p> |
| Fields of any primitive type, primitive wrapper type, <code class="classname"> |
| java.lang.String</code>, <code class="classname">byte[]</code>, <code class="classname"> |
| Byte[]</code>, <code class="classname">char[]</code>, <code class="classname"> |
| Character[]</code>, <code class="classname">java.math.BigDecimal</code>, |
| <code class="classname">java.math.BigInteger</code>, <code class="classname"> |
| java.util.Date</code>, <code class="classname"> java.util.Calendar</code>, |
| <code class="classname">java.sql.Date</code>, <code class="classname">java.sql.Timestamp</code>, |
| or any <code class="classname">Serializable</code> type default to persistent, as if |
| annotated with <a href="#jpa_overview_meta_basic" title="2.6. Basic"><code class="literal"> |
| @Basic</code></a>. |
| </p></li><li><p> |
| Fields of an embeddable type default to persistent, as if annotated with |
| <a href="#jpa_overview_meta_embedded" title="2.7. Embedded"><code class="literal">@Embedded</code></a>. |
| </p></li><li><p> |
| All other fields default to non-persistent. |
| </p></li></ol></div><p> |
| Note that according to these defaults, all relations between entities must be |
| annotated explicitly. Without an annotation, a relation field will default to |
| serialized storage if the related entity type is serializable, or will default |
| to being non-persistent if not. |
| </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="jpa_overview_meta_xml"></a>3. |
| XML Schema |
| </h2></div></div></div><a class="indexterm" name="d0e3862"></a><a class="indexterm" name="d0e3867"></a><p> |
| We present the complete XML schema below. Many of the elements relate to |
| object/relational mapping rather than metadata; these elements are discussed in |
| <a href="#jpa_overview_mapping" title="Chapter 12. Mapping Metadata">Chapter 12, <i xmlns:xlink="http://www.w3.org/1999/xlink"> |
| Mapping Metadata |
| </i></a>. |
| </p><pre class="programlisting"> |
| <?xml version="1.0" encoding="UTF-8"?> |
| <xsd:schema targetNamespace="http://java.sun.com/xml/ns/persistence/orm" |
| xmlns:orm="http://java.sun.com/xml/ns/persistence/orm" |
| xmlns:xsd="http://www.w3.org/2001/XMLSchema" |
| elementFormDefault="qualified" |
| attributeFormDefault="unqualified" |
| version="1.0"> |
| |
| <xsd:annotation> |
| <xsd:documentation> |
| @(#)orm_1_0.xsd 1.0 Feb 14 2006 |
| </xsd:documentation> |
| </xsd:annotation> |
| <xsd:annotation> |
| <xsd:documentation> |
| |
| This is the XML Schema for the persistence object-relational |
| mapping file. |
| The file may be named "META-INF/orm.xml" in the persistence |
| archive or it may be named some other name which would be |
| used to locate the file as resource on the classpath. |
| |
| </xsd:documentation> |
| </xsd:annotation> |
| |
| <xsd:complexType name="emptyType"/> |
| |
| <xsd:simpleType name="versionType"> |
| <xsd:restriction base="xsd:token"> |
| <xsd:pattern value="[0-9]+(\.[0-9]+)*"/> |
| </xsd:restriction> |
| </xsd:simpleType> |
| |
| <!-- **************************************************** --> |
| |
| <xsd:element name="entity-mappings"> |
| <xsd:complexType> |
| <xsd:annotation> |
| <xsd:documentation> |
| |
| The entity-mappings element is the root element of an mapping |
| file. It contains the following four types of elements: |
| |
| 1. The persistence-unit-metadata element contains metadata |
| for the entire persistence unit. It is undefined if this element |
| occurs in multiple mapping files within the same persistence unit. |
| |
| 2. The package, schema, catalog and access elements apply to all of |
| the entity, mapped-superclass and embeddable elements defined in |
| the same file in which they occur. |
| |
| 3. The sequence-generator, table-generator, named-query, |
| named-native-query and sql-result-set-mapping elements are global |
| to the persistence unit. It is undefined to have more than one |
| sequence-generator or table-generator of the same name in the same |
| or different mapping files in a persistence unit. It is also |
| undefined to have more than one named-query or named-native-query |
| of the same name in the same or different mapping files in a |
| persistence unit. |
| |
| 4. The entity, mapped-superclass and embeddable elements each define |
| the mapping information for a managed persistent class. The mapping |
| information contained in these elements may be complete or it may |
| be partial. |
| |
| </xsd:documentation> |
| </xsd:annotation> |
| <xsd:sequence> |
| <xsd:element name="description" type="xsd:string" |
| minOccurs="0"/> |
| <xsd:element name="persistence-unit-metadata" |
| type="orm:persistence-unit-metadata" |
| minOccurs="0"/> |
| <xsd:element name="package" type="xsd:string" |
| minOccurs="0"/> |
| <xsd:element name="schema" type="xsd:string" |
| minOccurs="0"/> |
| <xsd:element name="catalog" type="xsd:string" |
| minOccurs="0"/> |
| <xsd:element name="access" type="orm:access-type" |
| minOccurs="0"/> |
| <xsd:element name="sequence-generator" type="orm:sequence-generator" |
| minOccurs="0" maxOccurs="unbounded"/> |
| <xsd:element name="table-generator" type="orm:table-generator" |
| minOccurs="0" maxOccurs="unbounded"/> |
| <xsd:element name="named-query" type="orm:named-query" |
| minOccurs="0" maxOccurs="unbounded"/> |
| <xsd:element name="named-native-query" type="orm:named-native-query" |
| minOccurs="0" maxOccurs="unbounded"/> |
| <xsd:element name="sql-result-set-mapping" |
| type="orm:sql-result-set-mapping" |
| minOccurs="0" maxOccurs="unbounded"/> |
| <xsd:element name="mapped-superclass" type="orm:mapped-superclass" |
| minOccurs="0" maxOccurs="unbounded"/> |
| <xsd:element name="entity" type="orm:entity" |
| minOccurs="0" maxOccurs="unbounded"/> |
| <xsd:element name="embeddable" type="orm:embeddable" |
| minOccurs="0" maxOccurs="unbounded"/> |
| </xsd:sequence> |
| <xsd:attribute name="version" type="orm:versionType" |
| fixed="1.0" use="required"/> |
| </xsd:complexType> |
| </xsd:element> |
| |
| <!-- **************************************************** --> |
| |
| <xsd:complexType name="persistence-unit-metadata"> |
| <xsd:annotation> |
| <xsd:documentation> |
| |
| Metadata that applies to the persistence unit and not just to |
| the mapping file in which it is contained. |
| |
| If the xml-mapping-metadata-complete element is specified then |
| the complete set of mapping metadata for the persistence unit |
| is contained in the XML mapping files for the persistence unit. |
| |
| </xsd:documentation> |
| </xsd:annotation> |
| <xsd:sequence> |
| <xsd:element name="xml-mapping-metadata-complete" type="orm:emptyType" |
| minOccurs="0"/> |
| <xsd:element name="persistence-unit-defaults" |
| type="orm:persistence-unit-defaults" |
| minOccurs="0"/> |
| </xsd:sequence> |
| </xsd:complexType> |
| |
| <!-- **************************************************** --> |
| |
| <xsd:complexType name="persistence-unit-defaults"> |
| <xsd:annotation> |
| <xsd:documentation> |
| |
| These defaults are applied to the persistence unit as a whole |
| unless they are overridden by local annotation or XML |
| element settings. |
| |
| schema - Used as the schema for all tables or secondary tables |
| that apply to the persistence unit |
| catalog - Used as the catalog for all tables or secondary tables |
| that apply to the persistence unit |
| access - Used as the access type for all managed classes in |
| the persistence unit |
| cascade-persist - Adds cascade-persist to the set of cascade options |
| in entity relationships of the persistence unit |
| entity-listeners - List of default entity listeners to be invoked |
| on each entity in the persistence unit. |
| |
| </xsd:documentation> |
| </xsd:annotation> |
| <xsd:sequence> |
| <xsd:element name="schema" type="xsd:string" |
| minOccurs="0"/> |
| <xsd:element name="catalog" type="xsd:string" |
| minOccurs="0"/> |
| <xsd:element name="access" type="orm:access-type" |
| minOccurs="0"/> |
| <xsd:element name="cascade-persist" type="orm:emptyType" |
| minOccurs="0"/> |
| <xsd:element name="entity-listeners" type="orm:entity-listeners" |
| minOccurs="0"/> |
| </xsd:sequence> |
| </xsd:complexType> |
| |
| <!-- **************************************************** --> |
| |
| <xsd:complexType name="entity"> |
| <xsd:annotation> |
| <xsd:documentation> |
| |
| Defines the settings and mappings for an entity. Is allowed to be |
| sparsely populated and used in conjunction with the annotations. |
| Alternatively, the metadata-complete attribute can be used to |
| indicate that no annotations on the entity class (and its fields |
| or properties) are to be processed. If this is the case then |
| the defaulting rules for the entity and its subelements will |
| be recursively applied. |
| |
| @Target(TYPE) @Retention(RUNTIME) |
| public @interface Entity { |
| String name() default ""; |
| } |
| |
| </xsd:documentation> |
| </xsd:annotation> |
| <xsd:sequence> |
| <xsd:element name="description" type="xsd:string" minOccurs="0"/> |
| <xsd:element name="table" type="orm:table" |
| minOccurs="0"/> |
| <xsd:element name="secondary-table" type="orm:secondary-table" |
| minOccurs="0" maxOccurs="unbounded"/> |
| <xsd:element name="primary-key-join-column" |
| type="orm:primary-key-join-column" |
| minOccurs="0" maxOccurs="unbounded"/> |
| <xsd:element name="id-class" type="orm:id-class" minOccurs="0"/> |
| <xsd:element name="inheritance" type="orm:inheritance" minOccurs="0"/> |
| <xsd:element name="discriminator-value" type="orm:discriminator-value" |
| minOccurs="0"/> |
| <xsd:element name="discriminator-column" |
| type="orm:discriminator-column" |
| minOccurs="0"/> |
| <xsd:element name="sequence-generator" type="orm:sequence-generator" |
| minOccurs="0"/> |
| <xsd:element name="table-generator" type="orm:table-generator" |
| minOccurs="0"/> |
| <xsd:element name="named-query" type="orm:named-query" |
| minOccurs="0" maxOccurs="unbounded"/> |
| <xsd:element name="named-native-query" type="orm:named-native-query" |
| minOccurs="0" maxOccurs="unbounded"/> |
| <xsd:element name="sql-result-set-mapping" |
| type="orm:sql-result-set-mapping" |
| minOccurs="0" maxOccurs="unbounded"/> |
| <xsd:element name="exclude-default-listeners" type="orm:emptyType" |
| minOccurs="0"/> |
| <xsd:element name="exclude-superclass-listeners" type="orm:emptyType" |
| minOccurs="0"/> |
| <xsd:element name="entity-listeners" type="orm:entity-listeners" |
| minOccurs="0"/> |
| <xsd:element name="pre-persist" type="orm:pre-persist" minOccurs="0"/> |
| <xsd:element name="post-persist" type="orm:post-persist" |
| minOccurs="0"/> |
| <xsd:element name="pre-remove" type="orm:pre-remove" minOccurs="0"/> |
| <xsd:element name="post-remove" type="orm:post-remove" minOccurs="0"/> |
| <xsd:element name="pre-update" type="orm:pre-update" minOccurs="0"/> |
| <xsd:element name="post-update" type="orm:post-update" minOccurs="0"/> |
| <xsd:element name="post-load" type="orm:post-load" minOccurs="0"/> |
| <xsd:element name="attribute-override" type="orm:attribute-override" |
| minOccurs="0" maxOccurs="unbounded"/> |
| <xsd:element name="association-override" |
| type="orm:association-override" |
| minOccurs="0" maxOccurs="unbounded"/> |
| <xsd:element name="attributes" type="orm:attributes" minOccurs="0"/> |
| </xsd:sequence> |
| <xsd:attribute name="name" type="xsd:string"/> |
| <xsd:attribute name="class" type="xsd:string" use="required"/> |
| <xsd:attribute name="access" type="orm:access-type"/> |
| <xsd:attribute name="metadata-complete" type="xsd:boolean"/> |
| </xsd:complexType> |
| |
| <!-- **************************************************** --> |
| |
| <xsd:complexType name="attributes"> |
| <xsd:annotation> |
| <xsd:documentation> |
| |
| This element contains the entity field or property mappings. |
| It may be sparsely populated to include only a subset of the |
| fields or properties. If metadata-complete for the entity is true |
| then the remainder of the attributes will be defaulted according |
| to the default rules. |
| |
| </xsd:documentation> |
| </xsd:annotation> |
| <xsd:sequence> |
| <xsd:choice> |
| <xsd:element name="id" type="orm:id" |
| minOccurs="0" maxOccurs="unbounded"/> |
| <xsd:element name="embedded-id" type="orm:embedded-id" |
| minOccurs="0"/> |
| </xsd:choice> |
| <xsd:element name="basic" type="orm:basic" |
| minOccurs="0" maxOccurs="unbounded"/> |
| <xsd:element name="version" type="orm:version" |
| minOccurs="0" maxOccurs="unbounded"/> |
| <xsd:element name="many-to-one" type="orm:many-to-one" |
| minOccurs="0" maxOccurs="unbounded"/> |
| <xsd:element name="one-to-many" type="orm:one-to-many" |
| minOccurs="0" maxOccurs="unbounded"/> |
| <xsd:element name="one-to-one" type="orm:one-to-one" |
| minOccurs="0" maxOccurs="unbounded"/> |
| <xsd:element name="many-to-many" type="orm:many-to-many" |
| minOccurs="0" maxOccurs="unbounded"/> |
| <xsd:element name="embedded" type="orm:embedded" |
| minOccurs="0" maxOccurs="unbounded"/> |
| <xsd:element name="transient" type="orm:transient" |
| minOccurs="0" maxOccurs="unbounded"/> |
| </xsd:sequence> |
| </xsd:complexType> |
| |
| <!-- **************************************************** --> |
| |
| <xsd:simpleType name="access-type"> |
| <xsd:annotation> |
| <xsd:documentation> |
| |
| This element determines how the persistence provider accesses the |
| state of an entity or embedded object. |
| |
| </xsd:documentation> |
| </xsd:annotation> |
| <xsd:restriction base="xsd:token"> |
| <xsd:enumeration value="PROPERTY"/> |
| <xsd:enumeration value="FIELD"/> |
| </xsd:restriction> |
| </xsd:simpleType> |
| |
| <!-- **************************************************** --> |
| |
| <xsd:complexType name="entity-listeners"> |
| <xsd:annotation> |
| <xsd:documentation> |
| |
| @Target({TYPE}) @Retention(RUNTIME) |
| public @interface EntityListeners { |
| Class[] value(); |
| } |
| |
| </xsd:documentation> |
| </xsd:annotation> |
| <xsd:sequence> |
| <xsd:element name="entity-listener" type="orm:entity-listener" |
| minOccurs="0" maxOccurs="unbounded"/> |
| </xsd:sequence> |
| </xsd:complexType> |
| |
| <!-- **************************************************** --> |
| |
| <xsd:complexType name="entity-listener"> |
| <xsd:annotation> |
| <xsd:documentation> |
| |
| Defines an entity listener to be invoked at lifecycle events |
| for the entities that list this listener. |
| |
| </xsd:documentation> |
| </xsd:annotation> |
| <xsd:sequence> |
| <xsd:element name="pre-persist" type="orm:pre-persist" minOccurs="0"/> |
| <xsd:element name="post-persist" type="orm:post-persist" |
| minOccurs="0"/> |
| <xsd:element name="pre-remove" type="orm:pre-remove" minOccurs="0"/> |
| <xsd:element name="post-remove" type="orm:post-remove" minOccurs="0"/> |
| <xsd:element name="pre-update" type="orm:pre-update" minOccurs="0"/> |
| <xsd:element name="post-update" type="orm:post-update" minOccurs="0"/> |
| <xsd:element name="post-load" type="orm:post-load" minOccurs="0"/> |
| </xsd:sequence> |
| <xsd:attribute name="class" type="xsd:string" use="required"/> |
| </xsd:complexType> |
| |
| <!-- **************************************************** --> |
| |
| <xsd:complexType name="pre-persist"> |
| <xsd:annotation> |
| <xsd:documentation> |
| |
| @Target({METHOD}) @Retention(RUNTIME) |
| public @interface PrePersist {} |
| |
| </xsd:documentation> |
| </xsd:annotation> |
| <xsd:attribute name="method-name" type="xsd:string" use="required"/> |
| </xsd:complexType> |
| |
| <!-- **************************************************** --> |
| |
| <xsd:complexType name="post-persist"> |
| <xsd:annotation> |
| <xsd:documentation> |
| |
| @Target({METHOD}) @Retention(RUNTIME) |
| public @interface PostPersist {} |
| |
| </xsd:documentation> |
| </xsd:annotation> |
| <xsd:attribute name="method-name" type="xsd:string" use="required"/> |
| </xsd:complexType> |
| |
| <!-- **************************************************** --> |
| |
| <xsd:complexType name="pre-remove"> |
| <xsd:annotation> |
| <xsd:documentation> |
| |
| @Target({METHOD}) @Retention(RUNTIME) |
| public @interface PreRemove {} |
| |
| </xsd:documentation> |
| </xsd:annotation> |
| <xsd:attribute name="method-name" type="xsd:string" use="required"/> |
| </xsd:complexType> |
| |
| <!-- **************************************************** --> |
| |
| <xsd:complexType name="post-remove"> |
| <xsd:annotation> |
| <xsd:documentation> |
| |
| @Target({METHOD}) @Retention(RUNTIME) |
| public @interface PostRemove {} |
| |
| </xsd:documentation> |
| </xsd:annotation> |
| <xsd:attribute name="method-name" type="xsd:string" use="required"/> |
| </xsd:complexType> |
| |
| <!-- **************************************************** --> |
| |
| <xsd:complexType name="pre-update"> |
| <xsd:annotation> |
| <xsd:documentation> |
| |
| @Target({METHOD}) @Retention(RUNTIME) |
| public @interface PreUpdate {} |
| |
| </xsd:documentation> |
| </xsd:annotation> |
| <xsd:attribute name="method-name" type="xsd:string" use="required"/> |
| </xsd:complexType> |
| |
| <!-- **************************************************** --> |
| |
| <xsd:complexType name="post-update"> |
| <xsd:annotation> |
| <xsd:documentation> |
| |
| @Target({METHOD}) @Retention(RUNTIME) |
| public @interface PostUpdate {} |
| |
| </xsd:documentation> |
| </xsd:annotation> |
| <xsd:attribute name="method-name" type="xsd:string" use="required"/> |
| </xsd:complexType> |
| |
| <!-- **************************************************** --> |
| |
| <xsd:complexType name="post-load"> |
| <xsd:annotation> |
| <xsd:documentation> |
| |
| @Target({METHOD}) @Retention(RUNTIME) |
| public @interface PostLoad {} |
| |
| </xsd:documentation> |
| </xsd:annotation> |
| <xsd:attribute name="method-name" type="xsd:string" use="required"/> |
| </xsd:complexType> |
| |
| <!-- **************************************************** --> |
| |
| <xsd:complexType name="query-hint"> |
| <xsd:annotation> |
| <xsd:documentation> |
| |
| @Target({}) @Retention(RUNTIME) |
| public @interface QueryHint { |
| String name(); |
| String value(); |
| } |
| |
| </xsd:documentation> |
| </xsd:annotation> |
| <xsd:attribute name="name" type="xsd:string" use="required"/> |
| <xsd:attribute name="value" type="xsd:string" use="required"/> |
| </xsd:complexType> |
| |
| <!-- **************************************************** --> |
| |
| <xsd:complexType name="named-query"> |
| <xsd:annotation> |
| <xsd:documentation> |
| |
| @Target({TYPE}) @Retention(RUNTIME) |
| public @interface NamedQuery { |
| String name(); |
| String query(); |
| QueryHint[] hints() default {}; |
| } |
| |
| </xsd:documentation> |
| </xsd:annotation> |
| <xsd:sequence> |
| <xsd:element name="query" type="xsd:string"/> |
| <xsd:element name="hint" type="orm:query-hint" |
| minOccurs="0" maxOccurs="unbounded"/> |
| </xsd:sequence> |
| <xsd:attribute name="name" type="xsd:string" use="required"/> |
| </xsd:complexType> |
| |
| <!-- **************************************************** --> |
| |
| <xsd:complexType name="named-native-query"> |
| <xsd:annotation> |
| <xsd:documentation> |
| |
| @Target({TYPE}) @Retention(RUNTIME) |
| public @interface NamedNativeQuery { |
| String name(); |
| String query(); |
| QueryHint[] hints() default {}; |
| Class resultClass() default void.class; |
| String resultSetMapping() default ""; //named SqlResultSetMapping |
| } |
| |
| </xsd:documentation> |
| </xsd:annotation> |
| <xsd:sequence> |
| <xsd:element name="query" type="xsd:string"/> |
| <xsd:element name="hint" type="orm:query-hint" |
| minOccurs="0" maxOccurs="unbounded"/> |
| </xsd:sequence> |
| <xsd:attribute name="name" type="xsd:string" use="required"/> |
| <xsd:attribute name="result-class" type="xsd:string"/> |
| <xsd:attribute name="result-set-mapping" type="xsd:string"/> |
| </xsd:complexType> |
| |
| <!-- **************************************************** --> |
| |
| <xsd:complexType name="sql-result-set-mapping"> |
| <xsd:annotation> |
| <xsd:documentation> |
| |
| @Target({TYPE}) @Retention(RUNTIME) |
| public @interface SqlResultSetMapping { |
| String name(); |
| EntityResult[] entities() default {}; |
| ColumnResult[] columns() default {}; |
| } |
| |
| </xsd:documentation> |
| </xsd:annotation> |
| <xsd:sequence> |
| <xsd:element name="entity-result" type="orm:entity-result" |
| minOccurs="0" maxOccurs="unbounded"/> |
| <xsd:element name="column-result" type="orm:column-result" |
| minOccurs="0" maxOccurs="unbounded"/> |
| </xsd:sequence> |
| <xsd:attribute name="name" type="xsd:string" use="required"/> |
| </xsd:complexType> |
| |
| <!-- **************************************************** --> |
| |
| <xsd:complexType name="entity-result"> |
| <xsd:annotation> |
| <xsd:documentation> |
| |
| @Target({}) @Retention(RUNTIME) |
| public @interface EntityResult { |
| Class entityClass(); |
| FieldResult[] fields() default {}; |
| String discriminatorColumn() default ""; |
| } |
| |
| </xsd:documentation> |
| </xsd:annotation> |
| <xsd:sequence> |
| <xsd:element name="field-result" type="orm:field-result" |
| minOccurs="0" maxOccurs="unbounded"/> |
| </xsd:sequence> |
| <xsd:attribute name="entity-class" type="xsd:string" use="required"/> |
| <xsd:attribute name="discriminator-column" type="xsd:string"/> |
| </xsd:complexType> |
| |
| <!-- **************************************************** --> |
| |
| <xsd:complexType name="field-result"> |
| <xsd:annotation> |
| <xsd:documentation> |
| |
| @Target({}) @Retention(RUNTIME) |
| public @interface FieldResult { |
| String name(); |
| String column(); |
| } |
| |
| </xsd:documentation> |
| </xsd:annotation> |
| <xsd:attribute name="name" type="xsd:string" use="required"/> |
| <xsd:attribute name="column" type="xsd:string" use="required"/> |
| </xsd:complexType> |
| |
| <!-- **************************************************** --> |
| |
| <xsd:complexType name="column-result"> |
| <xsd:annotation> |
| <xsd:documentation> |
| |
| @Target({}) @Retention(RUNTIME) |
| public @interface ColumnResult { |
| String name(); |
| } |
| |
| </xsd:documentation> |
| </xsd:annotation> |
| <xsd:attribute name="name" type="xsd:string" use="required"/> |
| </xsd:complexType> |
| |
| <!-- **************************************************** --> |
| |
| <xsd:complexType name="table"> |
| <xsd:annotation> |
| <xsd:documentation> |
| |
| @Target({TYPE}) @Retention(RUNTIME) |
| public @interface Table { |
| String name() default ""; |
| String catalog() default ""; |
| String schema() default ""; |
| UniqueConstraint[] uniqueConstraints() default {}; |
| } |
| |
| </xsd:documentation> |
| </xsd:annotation> |
| <xsd:sequence> |
| <xsd:element name="unique-constraint" type="orm:unique-constraint" |
| minOccurs="0" maxOccurs="unbounded"/> |
| </xsd:sequence> |
| <xsd:attribute name="name" type="xsd:string"/> |
| <xsd:attribute name="catalog" type="xsd:string"/> |
| <xsd:attribute name="schema" type="xsd:string"/> |
| </xsd:complexType> |
| |
| <!-- **************************************************** --> |
| |
| <xsd:complexType name="secondary-table"> |
| <xsd:annotation> |
| <xsd:documentation> |
| |
| @Target({TYPE}) @Retention(RUNTIME) |
| public @interface SecondaryTable { |
| String name(); |
| String catalog() default ""; |
| String schema() default ""; |
| PrimaryKeyJoinColumn[] pkJoinColumns() default {}; |
| UniqueConstraint[] uniqueConstraints() default {}; |
| } |
| |
| </xsd:documentation> |
| </xsd:annotation> |
| <xsd:sequence> |
| <xsd:element name="primary-key-join-column" |
| type="orm:primary-key-join-column" |
| minOccurs="0" maxOccurs="unbounded"/> |
| <xsd:element name="unique-constraint" type="orm:unique-constraint" |
| minOccurs="0" maxOccurs="unbounded"/> |
| </xsd:sequence> |
| <xsd:attribute name="name" type="xsd:string" use="required"/> |
| <xsd:attribute name="catalog" type="xsd:string"/> |
| <xsd:attribute name="schema" type="xsd:string"/> |
| </xsd:complexType> |
| |
| <!-- **************************************************** --> |
| |
| <xsd:complexType name="unique-constraint"> |
| <xsd:annotation> |
| <xsd:documentation> |
| |
| @Target({}) @Retention(RUNTIME) |
| public @interface UniqueConstraint { |
| String[] columnNames(); |
| } |
| |
| </xsd:documentation> |
| </xsd:annotation> |
| <xsd:sequence> |
| <xsd:element name="column-name" type="xsd:string" |
| maxOccurs="unbounded"/> |
| </xsd:sequence> |
| </xsd:complexType> |
| |
| <!-- **************************************************** --> |
| |
| <xsd:complexType name="column"> |
| <xsd:annotation> |
| <xsd:documentation> |
| |
| @Target({METHOD, FIELD}) @Retention(RUNTIME) |
| public @interface Column { |
| String name() default ""; |
| boolean unique() default false; |
| boolean nullable() default true; |
| boolean insertable() default true; |
| boolean updatable() default true; |
| String columnDefinition() default ""; |
| String table() default ""; |
| int length() default 255; |
| int precision() default 0; // decimal precision |
| int scale() default 0; // decimal scale |
| } |
| |
| </xsd:documentation> |
| </xsd:annotation> |
| <xsd:attribute name="name" type="xsd:string"/> |
| <xsd:attribute name="unique" type="xsd:boolean"/> |
| <xsd:attribute name="nullable" type="xsd:boolean"/> |
| <xsd:attribute name="insertable" type="xsd:boolean"/> |
| <xsd:attribute name="updatable" type="xsd:boolean"/> |
| <xsd:attribute name="column-definition" type="xsd:string"/> |
| <xsd:attribute name="table" type="xsd:string"/> |
| <xsd:attribute name="length" type="xsd:int"/> |
| <xsd:attribute name="precision" type="xsd:int"/> |
| <xsd:attribute name="scale" type="xsd:int"/> |
| </xsd:complexType> |
| |
| <!-- **************************************************** --> |
| |
| <xsd:complexType name="join-column"> |
| <xsd:annotation> |
| <xsd:documentation> |
| |
| @Target({METHOD, FIELD}) @Retention(RUNTIME) |
| public @interface JoinColumn { |
| String name() default ""; |
| String referencedColumnName() default ""; |
| boolean unique() default false; |
| boolean nullable() default true; |
| boolean insertable() default true; |
| boolean updatable() default true; |
| String columnDefinition() default ""; |
| String table() default ""; |
| } |
| |
| </xsd:documentation> |
| </xsd:annotation> |
| <xsd:attribute name="name" type="xsd:string"/> |
| <xsd:attribute name="referenced-column-name" type="xsd:string"/> |
| <xsd:attribute name="unique" type="xsd:boolean"/> |
| <xsd:attribute name="nullable" type="xsd:boolean"/> |
| <xsd:attribute name="insertable" type="xsd:boolean"/> |
| <xsd:attribute name="updatable" type="xsd:boolean"/> |
| <xsd:attribute name="column-definition" type="xsd:string"/> |
| <xsd:attribute name="table" type="xsd:string"/> |
| </xsd:complexType> |
| |
| <!-- **************************************************** --> |
| |
| <xsd:simpleType name="generation-type"> |
| <xsd:annotation> |
| <xsd:documentation> |
| |
| public enum GenerationType { TABLE, SEQUENCE, IDENTITY, AUTO }; |
| |
| </xsd:documentation> |
| </xsd:annotation> |
| <xsd:restriction base="xsd:token"> |
| <xsd:enumeration value="TABLE"/> |
| <xsd:enumeration value="SEQUENCE"/> |
| <xsd:enumeration value="IDENTITY"/> |
| <xsd:enumeration value="AUTO"/> |
| </xsd:restriction> |
| </xsd:simpleType> |
| |
| <!-- **************************************************** --> |
| |
| <xsd:complexType name="attribute-override"> |
| <xsd:annotation> |
| <xsd:documentation> |
| |
| @Target({TYPE, METHOD, FIELD}) @Retention(RUNTIME) |
| public @interface AttributeOverride { |
| String name(); |
| Column column(); |
| } |
| |
| </xsd:documentation> |
| </xsd:annotation> |
| <xsd:sequence> |
| <xsd:element name="column" type="orm:column"/> |
| </xsd:sequence> |
| <xsd:attribute name="name" type="xsd:string" use="required"/> |
| </xsd:complexType> |
| |
| <!-- **************************************************** --> |
| |
| <xsd:complexType name="association-override"> |
| <xsd:annotation> |
| <xsd:documentation> |
| |
| @Target({TYPE, METHOD, FIELD}) @Retention(RUNTIME) |
| public @interface AssociationOverride { |
| String name(); |
| JoinColumn[] joinColumns(); |
| } |
| |
| </xsd:documentation> |
| </xsd:annotation> |
| <xsd:sequence> |
| <xsd:element name="join-column" type="orm:join-column" |
| maxOccurs="unbounded"/> |
| </xsd:sequence> |
| <xsd:attribute name="name" type="xsd:string" use="required"/> |
| </xsd:complexType> |
| |
| <!-- **************************************************** --> |
| |
| <xsd:complexType name="id-class"> |
| <xsd:annotation> |
| <xsd:documentation> |
| |
| @Target({TYPE}) @Retention(RUNTIME) |
| public @interface IdClass { |
| Class value(); |
| } |
| |
| </xsd:documentation> |
| </xsd:annotation> |
| <xsd:attribute name="class" type="xsd:string" use="required"/> |
| </xsd:complexType> |
| |
| <!-- **************************************************** --> |
| |
| <xsd:complexType name="id"> |
| <xsd:annotation> |
| <xsd:documentation> |
| |
| @Target({METHOD, FIELD}) @Retention(RUNTIME) |
| public @interface Id {} |
| |
| </xsd:documentation> |
| </xsd:annotation> |
| <xsd:sequence> |
| <xsd:element name="column" type="orm:column" |
| minOccurs="0"/> |
| <xsd:element name="generated-value" type="orm:generated-value" |
| minOccurs="0"/> |
| <xsd:element name="temporal" type="orm:temporal" |
| minOccurs="0"/> |
| <xsd:element name="table-generator" type="orm:table-generator" |
| minOccurs="0"/> |
| <xsd:element name="sequence-generator" type="orm:sequence-generator" |
| minOccurs="0"/> |
| </xsd:sequence> |
| <xsd:attribute name="name" type="xsd:string" use="required"/> |
| </xsd:complexType> |
| |
| <!-- **************************************************** --> |
| |
| <xsd:complexType name="embedded-id"> |
| <xsd:annotation> |
| <xsd:documentation> |
| |
| @Target({METHOD, FIELD}) @Retention(RUNTIME) |
| public @interface EmbeddedId {} |
| |
| </xsd:documentation> |
| </xsd:annotation> |
| <xsd:sequence> |
| <xsd:element name="attribute-override" type="orm:attribute-override" |
| minOccurs="0" maxOccurs="unbounded"/> |
| </xsd:sequence> |
| <xsd:attribute name="name" type="xsd:string" use="required"/> |
| </xsd:complexType> |
| |
| <!-- **************************************************** --> |
| |
| <xsd:complexType name="transient"> |
| <xsd:annotation> |
| <xsd:documentation> |
| |
| @Target({METHOD, FIELD}) @Retention(RUNTIME) |
| public @interface Transient {} |
| |
| </xsd:documentation> |
| </xsd:annotation> |
| <xsd:attribute name="name" type="xsd:string" use="required"/> |
| </xsd:complexType> |
| |
| <!-- **************************************************** --> |
| |
| <xsd:complexType name="version"> |
| <xsd:annotation> |
| <xsd:documentation> |
| |
| @Target({METHOD, FIELD}) @Retention(RUNTIME) |
| public @interface Version {} |
| |
| </xsd:documentation> |
| </xsd:annotation> |
| <xsd:sequence> |
| <xsd:element name="column" type="orm:column" minOccurs="0"/> |
| <xsd:element name="temporal" type="orm:temporal" minOccurs="0"/> |
| </xsd:sequence> |
| <xsd:attribute name="name" type="xsd:string" use="required"/> |
| </xsd:complexType> |
| |
| <!-- **************************************************** --> |
| |
| <xsd:complexType name="basic"> |
| <xsd:annotation> |
| <xsd:documentation> |
| |
| @Target({METHOD, FIELD}) @Retention(RUNTIME) |
| public @interface Basic { |
| FetchType fetch() default EAGER; |
| boolean optional() default true; |
| } |
| |
| </xsd:documentation> |
| </xsd:annotation> |
| <xsd:sequence> |
| <xsd:element name="column" type="orm:column" minOccurs="0"/> |
| <xsd:choice> |
| <xsd:element name="lob" type="orm:lob" minOccurs="0"/> |
| <xsd:element name="temporal" type="orm:temporal" minOccurs="0"/> |
| <xsd:element name="enumerated" type="orm:enumerated" minOccurs="0"/> |
| </xsd:choice> |
| </xsd:sequence> |
| <xsd:attribute name="name" type="xsd:string" use="required"/> |
| <xsd:attribute name="fetch" type="orm:fetch-type"/> |
| <xsd:attribute name="optional" type="xsd:boolean"/> |
| </xsd:complexType> |
| |
| <!-- **************************************************** --> |
| |
| <xsd:simpleType name="fetch-type"> |
| <xsd:annotation> |
| <xsd:documentation> |
| |
| public enum FetchType { LAZY, EAGER }; |
| |
| </xsd:documentation> |
| </xsd:annotation> |
| <xsd:restriction base="xsd:token"> |
| <xsd:enumeration value="LAZY"/> |
| <xsd:enumeration value="EAGER"/> |
| </xsd:restriction> |
| </xsd:simpleType> |
| |
| <!-- **************************************************** --> |
| |
| <xsd:complexType name="lob"> |
| <xsd:annotation> |
| <xsd:documentation> |
| |
| @Target({METHOD, FIELD}) @Retention(RUNTIME) |
| public @interface Lob {} |
| |
| </xsd:documentation> |
| </xsd:annotation> |
| </xsd:complexType> |
| |
| <!-- **************************************************** --> |
| |
| <xsd:simpleType name="temporal"> |
| <xsd:annotation> |
| <xsd:documentation> |
| |
| @Target({METHOD, FIELD}) @Retention(RUNTIME) |
| public @interface Temporal { |
| TemporalType value(); |
| } |
| |
| </xsd:documentation> |
| </xsd:annotation> |
| <xsd:restriction base="orm:temporal-type"/> |
| </xsd:simpleType> |
| |
| <!-- **************************************************** --> |
| |
| <xsd:simpleType name="temporal-type"> |
| <xsd:annotation> |
| <xsd:documentation> |
| |
| public enum TemporalType { |
| DATE, // java.sql.Date |
| TIME, // java.sql.Time |
| TIMESTAMP // java.sql.Timestamp |
| } |
| |
| </xsd:documentation> |
| </xsd:annotation> |
| <xsd:restriction base="xsd:token"> |
| <xsd:enumeration value="DATE"/> |
| <xsd:enumeration value="TIME"/> |
| <xsd:enumeration value="TIMESTAMP"/> |
| </xsd:restriction> |
| </xsd:simpleType> |
| |
| <!-- **************************************************** --> |
| |
| <xsd:simpleType name="enumerated"> |
| <xsd:annotation> |
| <xsd:documentation> |
| |
| @Target({METHOD, FIELD}) @Retention(RUNTIME) |
| public @interface Enumerated { |
| EnumType value() default ORDINAL; |
| } |
| |
| </xsd:documentation> |
| </xsd:annotation> |
| <xsd:restriction base="orm:enum-type"/> |
| </xsd:simpleType> |
| |
| <!-- **************************************************** --> |
| |
| <xsd:simpleType name="enum-type"> |
| <xsd:annotation> |
| <xsd:documentation> |
| |
| public enum EnumType { |
| ORDINAL, |
| STRING |
| } |
| |
| </xsd:documentation> |
| </xsd:annotation> |
| <xsd:restriction base="xsd:token"> |
| <xsd:enumeration value="ORDINAL"/> |
| <xsd:enumeration value="STRING"/> |
| </xsd:restriction> |
| </xsd:simpleType> |
| |
| <!-- **************************************************** --> |
| |
| <xsd:complexType name="many-to-one"> |
| <xsd:annotation> |
| <xsd:documentation> |
| |
| @Target({METHOD, FIELD}) @Retention(RUNTIME) |
| public @interface ManyToOne { |
| Class targetEntity() default void.class; |
| CascadeType[] cascade() default {}; |
| FetchType fetch() default EAGER; |
| boolean optional() default true; |
| } |
| |
| </xsd:documentation> |
| </xsd:annotation> |
| <xsd:sequence> |
| <xsd:choice> |
| <xsd:element name="join-column" type="orm:join-column" |
| minOccurs="0" maxOccurs="unbounded"/> |
| <xsd:element name="join-table" type="orm:join-table" |
| minOccurs="0"/> |
| </xsd:choice> |
| <xsd:element name="cascade" type="orm:cascade-type" |
| minOccurs="0"/> |
| </xsd:sequence> |
| <xsd:attribute name="name" type="xsd:string" use="required"/> |
| <xsd:attribute name="target-entity" type="xsd:string"/> |
| <xsd:attribute name="fetch" type="orm:fetch-type"/> |
| <xsd:attribute name="optional" type="xsd:boolean"/> |
| </xsd:complexType> |
| |
| <!-- **************************************************** --> |
| |
| <xsd:complexType name="cascade-type"> |
| <xsd:annotation> |
| <xsd:documentation> |
| |
| public enum CascadeType { ALL, PERSIST, MERGE, REMOVE, REFRESH}; |
| |
| </xsd:documentation> |
| </xsd:annotation> |
| <xsd:sequence> |
| <xsd:element name="cascade-all" type="orm:emptyType" |
| minOccurs="0"/> |
| <xsd:element name="cascade-persist" type="orm:emptyType" |
| minOccurs="0"/> |
| <xsd:element name="cascade-merge" type="orm:emptyType" |
| minOccurs="0"/> |
| <xsd:element name="cascade-remove" type="orm:emptyType" |
| minOccurs="0"/> |
| <xsd:element name="cascade-refresh" type="orm:emptyType" |
| minOccurs="0"/> |
| </xsd:sequence> |
| </xsd:complexType> |
| |
| <!-- **************************************************** --> |
| |
| <xsd:complexType name="one-to-one"> |
| <xsd:annotation> |
| <xsd:documentation> |
| |
| @Target({METHOD, FIELD}) @Retention(RUNTIME) |
| public @interface OneToOne { |
| Class targetEntity() default void.class; |
| CascadeType[] cascade() default {}; |
| FetchType fetch() default EAGER; |
| boolean optional() default true; |
| String mappedBy() default ""; |
| } |
| |
| </xsd:documentation> |
| </xsd:annotation> |
| <xsd:sequence> |
| <xsd:choice> |
| <xsd:element name="primary-key-join-column" |
| type="orm:primary-key-join-column" |
| minOccurs="0" maxOccurs="unbounded"/> |
| <xsd:element name="join-column" type="orm:join-column" |
| minOccurs="0" maxOccurs="unbounded"/> |
| <xsd:element name="join-table" type="orm:join-table" |
| minOccurs="0"/> |
| </xsd:choice> |
| <xsd:element name="cascade" type="orm:cascade-type" |
| minOccurs="0"/> |
| </xsd:sequence> |
| <xsd:attribute name="name" type="xsd:string" use="required"/> |
| <xsd:attribute name="target-entity" type="xsd:string"/> |
| <xsd:attribute name="fetch" type="orm:fetch-type"/> |
| <xsd:attribute name="optional" type="xsd:boolean"/> |
| <xsd:attribute name="mapped-by" type="xsd:string"/> |
| </xsd:complexType> |
| |
| <!-- **************************************************** --> |
| |
| <xsd:complexType name="one-to-many"> |
| <xsd:annotation> |
| <xsd:documentation> |
| |
| @Target({METHOD, FIELD}) @Retention(RUNTIME) |
| public @interface OneToMany { |
| Class targetEntity() default void.class; |
| CascadeType[] cascade() default {}; |
| FetchType fetch() default LAZY; |
| String mappedBy() default ""; |
| } |
| |
| </xsd:documentation> |
| </xsd:annotation> |
| <xsd:sequence> |
| <xsd:element name="order-by" type="orm:order-by" |
| minOccurs="0"/> |
| <xsd:element name="map-key" type="orm:map-key" |
| minOccurs="0"/> |
| <xsd:choice> |
| <xsd:element name="join-table" type="orm:join-table" |
| minOccurs="0"/> |
| <xsd:element name="join-column" type="orm:join-column" |
| minOccurs="0" maxOccurs="unbounded"/> |
| </xsd:choice> |
| <xsd:element name="cascade" type="orm:cascade-type" |
| minOccurs="0"/> |
| </xsd:sequence> |
| <xsd:attribute name="name" type="xsd:string" use="required"/> |
| <xsd:attribute name="target-entity" type="xsd:string"/> |
| <xsd:attribute name="fetch" type="orm:fetch-type"/> |
| <xsd:attribute name="mapped-by" type="xsd:string"/> |
| </xsd:complexType> |
| |
| <!-- **************************************************** --> |
| |
| <xsd:complexType name="join-table"> |
| <xsd:annotation> |
| <xsd:documentation> |
| |
| @Target({METHOD, FIELD}) @Retention(RUNTIME) |
| public @interface JoinTable { |
| String name() default ""; |
| String catalog() default ""; |
| String schema() default ""; |
| JoinColumn[] joinColumns() default {}; |
| JoinColumn[] inverseJoinColumns() default {}; |
| UniqueConstraint[] uniqueConstraints() default {}; |
| } |
| |
| </xsd:documentation> |
| </xsd:annotation> |
| <xsd:sequence> |
| <xsd:element name="join-column" type="orm:join-column" |
| minOccurs="0" maxOccurs="unbounded"/> |
| <xsd:element name="inverse-join-column" type="orm:join-column" |
| minOccurs="0" maxOccurs="unbounded"/> |
| <xsd:element name="unique-constraint" type="orm:unique-constraint" |
| minOccurs="0" maxOccurs="unbounded"/> |
| </xsd:sequence> |
| <xsd:attribute name="name" type="xsd:string"/> |
| <xsd:attribute name="catalog" type="xsd:string"/> |
| <xsd:attribute name="schema" type="xsd:string"/> |
| </xsd:complexType> |
| |
| <!-- **************************************************** --> |
| |
| <xsd:complexType name="many-to-many"> |
| <xsd:annotation> |
| <xsd:documentation> |
| |
| @Target({METHOD, FIELD}) @Retention(RUNTIME) |
| public @interface ManyToMany { |
| Class targetEntity() default void.class; |
| CascadeType[] cascade() default {}; |
| FetchType fetch() default LAZY; |
| String mappedBy() default ""; |
| } |
| |
| </xsd:documentation> |
| </xsd:annotation> |
| <xsd:sequence> |
| <xsd:element name="order-by" type="orm:order-by" |
| minOccurs="0"/> |
| <xsd:element name="map-key" type="orm:map-key" |
| minOccurs="0"/> |
| <xsd:element name="join-table" type="orm:join-table" |
| minOccurs="0"/> |
| <xsd:element name="cascade" type="orm:cascade-type" |
| minOccurs="0"/> |
| </xsd:sequence> |
| <xsd:attribute name="name" type="xsd:string" use="required"/> |
| <xsd:attribute name="target-entity" type="xsd:string"/> |
| <xsd:attribute name="fetch" type="orm:fetch-type"/> |
| <xsd:attribute name="mapped-by" type="xsd:string"/> |
| </xsd:complexType> |
| |
| <!-- **************************************************** --> |
| |
| <xsd:complexType name="generated-value"> |
| <xsd:annotation> |
| <xsd:documentation> |
| |
| @Target({METHOD, FIELD}) @Retention(RUNTIME) |
| public @interface GeneratedValue { |
| GenerationType strategy() default AUTO; |
| String generator() default ""; |
| } |
| |
| </xsd:documentation> |
| </xsd:annotation> |
| <xsd:attribute name="strategy" type="orm:generation-type"/> |
| <xsd:attribute name="generator" type="xsd:string"/> |
| </xsd:complexType> |
| |
| <!-- **************************************************** --> |
| |
| <xsd:complexType name="map-key"> |
| <xsd:annotation> |
| <xsd:documentation> |
| |
| @Target({METHOD, FIELD}) @Retention(RUNTIME) |
| public @interface MapKey { |
| String name() default ""; |
| } |
| |
| </xsd:documentation> |
| </xsd:annotation> |
| <xsd:attribute name="name" type="xsd:string"/> |
| </xsd:complexType> |
| |
| <!-- **************************************************** --> |
| |
| <xsd:simpleType name="order-by"> |
| <xsd:annotation> |
| <xsd:documentation> |
| |
| @Target({METHOD, FIELD}) @Retention(RUNTIME) |
| public @interface OrderBy { |
| String value() default ""; |
| } |
| |
| </xsd:documentation> |
| </xsd:annotation> |
| <xsd:restriction base="xsd:string"/> |
| </xsd:simpleType> |
| |
| <!-- **************************************************** --> |
| |
| <xsd:complexType name="inheritance"> |
| <xsd:annotation> |
| <xsd:documentation> |
| |
| @Target({TYPE}) @Retention(RUNTIME) |
| public @interface Inheritance { |
| InheritanceType strategy() default SINGLE_TABLE; |
| } |
| |
| </xsd:documentation> |
| </xsd:annotation> |
| <xsd:attribute name="strategy" type="orm:inheritance-type"/> |
| </xsd:complexType> |
| |
| <!-- **************************************************** --> |
| |
| <xsd:simpleType name="inheritance-type"> |
| <xsd:annotation> |
| <xsd:documentation> |
| |
| public enum InheritanceType |
| { SINGLE_TABLE, JOINED, TABLE_PER_CLASS}; |
| |
| </xsd:documentation> |
| </xsd:annotation> |
| <xsd:restriction base="xsd:token"> |
| <xsd:enumeration value="SINGLE_TABLE"/> |
| <xsd:enumeration value="JOINED"/> |
| <xsd:enumeration value="TABLE_PER_CLASS"/> |
| </xsd:restriction> |
| </xsd:simpleType> |
| |
| <!-- **************************************************** --> |
| |
| <xsd:simpleType name="discriminator-value"> |
| <xsd:annotation> |
| <xsd:documentation> |
| |
| @Target({TYPE}) @Retention(RUNTIME) |
| public @interface DiscriminatorValue { |
| String value(); |
| } |
| |
| </xsd:documentation> |
| </xsd:annotation> |
| <xsd:restriction base="xsd:string"/> |
| </xsd:simpleType> |
| |
| <!-- **************************************************** --> |
| |
| <xsd:simpleType name="discriminator-type"> |
| <xsd:annotation> |
| <xsd:documentation> |
| |
| public enum DiscriminatorType { STRING, CHAR, INTEGER }; |
| |
| </xsd:documentation> |
| </xsd:annotation> |
| <xsd:restriction base="xsd:token"> |
| <xsd:enumeration value="STRING"/> |
| <xsd:enumeration value="CHAR"/> |
| <xsd:enumeration value="INTEGER"/> |
| </xsd:restriction> |
| </xsd:simpleType> |
| |
| <!-- **************************************************** --> |
| |
| <xsd:complexType name="primary-key-join-column"> |
| <xsd:annotation> |
| <xsd:documentation> |
| |
| @Target({TYPE, METHOD, FIELD}) @Retention(RUNTIME) |
| public @interface PrimaryKeyJoinColumn { |
| String name() default ""; |
| String referencedColumnName() default ""; |
| String columnDefinition() default ""; |
| } |
| |
| </xsd:documentation> |
| </xsd:annotation> |
| <xsd:attribute name="name" type="xsd:string"/> |
| <xsd:attribute name="referenced-column-name" type="xsd:string"/> |
| <xsd:attribute name="column-definition" type="xsd:string"/> |
| </xsd:complexType> |
| |
| <!-- **************************************************** --> |
| |
| <xsd:complexType name="discriminator-column"> |
| <xsd:annotation> |
| <xsd:documentation> |
| |
| @Target({TYPE}) @Retention(RUNTIME) |
| public @interface DiscriminatorColumn { |
| String name() default "DTYPE"; |
| DiscriminatorType discriminatorType() default STRING; |
| String columnDefinition() default ""; |
| int length() default 31; |
| } |
| |
| </xsd:documentation> |
| </xsd:annotation> |
| <xsd:attribute name="name" type="xsd:string"/> |
| <xsd:attribute name="discriminator-type" type="orm:discriminator-type"/> |
| <xsd:attribute name="column-definition" type="xsd:string"/> |
| <xsd:attribute name="length" type="xsd:int"/> |
| </xsd:complexType> |
| |
| <!-- **************************************************** --> |
| |
| <xsd:complexType name="embeddable"> |
| <xsd:annotation> |
| <xsd:documentation> |
| |
| Defines the settings and mappings for embeddable objects. Is |
| allowed to be sparsely populated and used in conjunction with |
| the annotations. Alternatively, the metadata-complete attribute |
| can be used to indicate that no annotations are to be processed |
| in the class. If this is the case then the defaulting rules will |
| be recursively applied. |
| |
| @Target({TYPE}) @Retention(RUNTIME) |
| public @interface Embeddable {} |
| |
| </xsd:documentation> |
| </xsd:annotation> |
| <xsd:sequence> |
| <xsd:element name="description" type="xsd:string" minOccurs="0"/> |
| <xsd:element name="attributes" type="orm:embeddable-attributes" |
| minOccurs="0"/> |
| </xsd:sequence> |
| <xsd:attribute name="class" type="xsd:string" use="required"/> |
| <xsd:attribute name="access" type="orm:access-type"/> |
| <xsd:attribute name="metadata-complete" type="xsd:boolean"/> |
| </xsd:complexType> |
| |
| <!-- **************************************************** --> |
| |
| <xsd:complexType name="embeddable-attributes"> |
| <xsd:sequence> |
| <xsd:element name="basic" type="orm:basic" |
| minOccurs="0" maxOccurs="unbounded"/> |
| <xsd:element name="transient" type="orm:transient" |
| minOccurs="0" maxOccurs="unbounded"/> |
| </xsd:sequence> |
| </xsd:complexType> |
| |
| <!-- **************************************************** --> |
| |
| <xsd:complexType name="embedded"> |
| <xsd:annotation> |
| <xsd:documentation> |
| |
| @Target({METHOD, FIELD}) @Retention(RUNTIME) |
| public @interface Embedded {} |
| |
| </xsd:documentation> |
| </xsd:annotation> |
| <xsd:sequence> |
| <xsd:element name="attribute-override" type="orm:attribute-override" |
| minOccurs="0" maxOccurs="unbounded"/> |
| </xsd:sequence> |
| <xsd:attribute name="name" type="xsd:string" use="required"/> |
| </xsd:complexType> |
| |
| <!-- **************************************************** --> |
| |
| <xsd:complexType name="mapped-superclass"> |
| <xsd:annotation> |
| <xsd:documentation> |
| |
| Defines the settings and mappings for a mapped superclass. Is |
| allowed to be sparsely populated and used in conjunction with |
| the annotations. Alternatively, the metadata-complete attribute |
| can be used to indicate that no annotations are to be processed |
| If this is the case then the defaulting rules will be recursively |
| applied. |
| |
| @Target(TYPE) @Retention(RUNTIME) |
| public @interface MappedSuperclass{} |
| |
| </xsd:documentation> |
| </xsd:annotation> |
| <xsd:sequence> |
| <xsd:element name="description" type="xsd:string" minOccurs="0"/> |
| <xsd:element name="id-class" type="orm:id-class" minOccurs="0"/> |
| <xsd:element name="exclude-default-listeners" type="orm:emptyType" |
| minOccurs="0"/> |
| <xsd:element name="exclude-superclass-listeners" type="orm:emptyType" |
| minOccurs="0"/> |
| <xsd:element name="entity-listeners" type="orm:entity-listeners" |
| minOccurs="0"/> |
| <xsd:element name="pre-persist" type="orm:pre-persist" minOccurs="0"/> |
| <xsd:element name="post-persist" type="orm:post-persist" |
| minOccurs="0"/> |
| <xsd:element name="pre-remove" type="orm:pre-remove" minOccurs="0"/> |
| <xsd:element name="post-remove" type="orm:post-remove" minOccurs="0"/> |
| <xsd:element name="pre-update" type="orm:pre-update" minOccurs="0"/> |
| <xsd:element name="post-update" type="orm:post-update" minOccurs="0"/> |
| <xsd:element name="post-load" type="orm:post-load" minOccurs="0"/> |
| <xsd:element name="attributes" type="orm:attributes" minOccurs="0"/> |
| </xsd:sequence> |
| <xsd:attribute name="class" type="xsd:string" use="required"/> |
| <xsd:attribute name="access" type="orm:access-type"/> |
| <xsd:attribute name="metadata-complete" type="xsd:boolean"/> |
| </xsd:complexType> |
| |
| <!-- **************************************************** --> |
| |
| <xsd:complexType name="sequence-generator"> |
| <xsd:annotation> |
| <xsd:documentation> |
| |
| @Target({TYPE, METHOD, FIELD}) @Retention(RUNTIME) |
| public @interface SequenceGenerator { |
| String name(); |
| String sequenceName() default ""; |
| int initialValue() default 1; |
| int allocationSize() default 50; |
| } |
| |
| </xsd:documentation> |
| </xsd:annotation> |
| <xsd:attribute name="name" type="xsd:string" use="required"/> |
| <xsd:attribute name="sequence-name" type="xsd:string"/> |
| <xsd:attribute name="initial-value" type="xsd:int"/> |
| <xsd:attribute name="allocation-size" type="xsd:int"/> |
| </xsd:complexType> |
| |
| <!-- **************************************************** --> |
| |
| <xsd:complexType name="table-generator"> |
| <xsd:annotation> |
| <xsd:documentation> |
| |
| @Target({TYPE, METHOD, FIELD}) @Retention(RUNTIME) |
| public @interface TableGenerator { |
| String name(); |
| String table() default ""; |
| String catalog() default ""; |
| String schema() default ""; |
| String pkColumnName() default ""; |
| String valueColumnName() default ""; |
| String pkColumnValue() default ""; |
| int initialValue() default 0; |
| int allocationSize() default 50; |
| UniqueConstraint[] uniqueConstraints() default {}; |
| } |
| |
| </xsd:documentation> |
| </xsd:annotation> |
| <xsd:sequence> |
| <xsd:element name="unique-constraint" type="orm:unique-constraint" |
| minOccurs="0" maxOccurs="unbounded"/> |
| </xsd:sequence> |
| <xsd:attribute name="name" type="xsd:string" use="required"/> |
| <xsd:attribute name="table" type="xsd:string"/> |
| <xsd:attribute name="catalog" type="xsd:string"/> |
| <xsd:attribute name="schema" type="xsd:string"/> |
| <xsd:attribute name="pk-column-name" type="xsd:string"/> |
| <xsd:attribute name="value-column-name" type="xsd:string"/> |
| <xsd:attribute name="pk-column-value" type="xsd:string"/> |
| <xsd:attribute name="initial-value" type="xsd:int"/> |
| <xsd:attribute name="allocation-size" type="xsd:int"/> |
| </xsd:complexType> |
| |
| </xsd:schema> |
| </pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="jpa_overview_meta_complete"></a>4. |
| Conclusion |
| </h2></div></div></div><p> |
| That exhausts persistence metadata annotations. We present the class definitions |
| for our sample model below: |
| </p><div class="example"><a name="jpa_overview_meta_complete_ex"></a><p class="title"><b>Example 5.2. |
| Complete Metadata |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| package org.mag; |
| |
| @Entity |
| @IdClass(Magazine.MagazineId.class) |
| public class Magazine { |
| |
| @Id private String isbn; |
| @Id private String title; |
| @Version private int version; |
| |
| private double price; // defaults to @Basic |
| private int copiesSold; // defaults to @Basic |
| |
| @OneToOne(fetch=FetchType.LAZY, |
| cascade={CascadeType.PERSIST,CascadeType.REMOVE}) |
| private Article coverArticle; |
| |
| @OneToMany(cascade={CascadeType.PERSIST,CascadeType.REMOVE}) |
| @OrderBy |
| private Collection<Article> articles; |
| |
| @ManyToOne(fetch=FetchType.LAZY, cascade=CascadeType.PERSIST) |
| private Company publisher; |
| |
| @Transient private byte[] data; |
| |
| ... |
| |
| public static class MagazineId { |
| ... |
| } |
| } |
| |
| @Entity |
| public class Article { |
| |
| @Id private long id; |
| @Version private int version; |
| |
| private String title; // defaults to @Basic |
| private byte[] content; // defaults to @Basic |
| |
| @ManyToMany(cascade=CascadeType.PERSIST) |
| @OrderBy("lastName, firstName") |
| private Collection<Author> authors; |
| |
| ... |
| } |
| |
| |
| package org.mag.pub; |
| |
| @Entity |
| public class Company { |
| |
| @Id private long id; |
| @Version private int version; |
| |
| private String name; // defaults to @Basic |
| private double revenue; // defaults to @Basic |
| private Address address; // defaults to @Embedded |
| |
| @OneToMany(mappedBy="publisher", cascade=CascadeType.PERSIST) |
| private Collection<Magazine> mags; |
| |
| @OneToMany(cascade={CascadeType.PERSIST,CascadeType.REMOVE}) |
| private Collection<Subscription> subscriptions; |
| |
| ... |
| } |
| |
| @Entity |
| public class Author { |
| |
| @Id private long id; |
| @Version private int version; |
| |
| private String firstName; // defaults to @Basic |
| private double lastName; // defaults to @Basic |
| private Address address; // defaults to @Embedded |
| |
| @ManyToMany(mappedBy="authors", cascade=CascadeType.PERSIST) |
| private Collection<Article> arts; |
| |
| ... |
| } |
| |
| @Embeddable |
| public class Address { |
| |
| private String street; // defaults to @Basic |
| private String city; // defaults to @Basic |
| private String state; // defaults to @Basic |
| private String zip; // defaults to @Basic |
| |
| ... |
| } |
| |
| |
| package org.mag.subscribe; |
| |
| @MappedSuperclass |
| public abstract class Document { |
| |
| @Id private long id; |
| @Version private int version; |
| |
| ... |
| } |
| |
| @Entity |
| public class Contract |
| extends Document { |
| |
| private String terms; // defaults to @Basic |
| |
| ... |
| } |
| |
| @Entity |
| public class Subscription { |
| |
| @Id private long id; |
| @Version private int version; |
| |
| private Date startDate; // defaults to @Basic |
| private double payment; // defaults to @Basic |
| |
| @OneToMany(cascade={CascadeType.PERSIST,CascadeType.REMOVE}) |
| @MapKey(name="num") |
| private Map<Long,LineItem> lineItems; |
| |
| ... |
| |
| @Entity |
| public static class LineItem |
| extends Contract { |
| |
| private String comments; // defaults to @Basic |
| private double price; // defaults to @Basic |
| private long num; // defaults to @Basic |
| |
| @ManyToOne |
| private Magazine magazine; |
| |
| ... |
| } |
| } |
| |
| @Entity(name="Lifetime") |
| public class LifetimeSubscription |
| extends Subscription { |
| |
| @Basic(fetch=FetchType.LAZY) |
| private boolean getEliteClub() { ... } |
| public void setEliteClub(boolean elite) { ... } |
| |
| ... |
| } |
| |
| @Entity(name="Trial") |
| public class TrialSubscription |
| extends Subscription { |
| |
| public Date getEndDate() { ... } |
| public void setEndDate(Date end) { ... } |
| |
| ... |
| } |
| </pre><p> |
| The same metadata declarations in XML: |
| </p><pre class="programlisting"> |
| <entity-mappings> |
| <!-- declares a default access type for all entities --> |
| <access-type>FIELD</access-type> |
| <mapped-superclass class="org.mag.subscribe.Document"> |
| <attributes> |
| <id name="id"> |
| <generated-value strategy="IDENTITY"/> |
| </id> |
| <version name="version"/> |
| </attributes> |
| </mapped-superclass> |
| <entity class="org.mag.Magazine"> |
| <id-class="org.mag.Magazine$MagazineId"/> |
| <attributes> |
| <id name="isbn"/> |
| <id name="title"/> |
| <basic name="name"/> |
| <basic name="price"/> |
| <basic name="copiesSold"/> |
| <version name="version"/> |
| <many-to-one name="publisher" fetch="LAZY"> |
| <cascade> |
| <cascade-persist/> |
| </cascade> |
| </many-to-one> |
| <one-to-many name="articles"> |
| <order-by/> |
| <cascade> |
| <cascade-persist/> |
| <cascade-remove/> |
| </cascade> |
| </one-to-many> |
| <one-to-one name="coverArticle" fetch="LAZY"> |
| <cascade> |
| <cascade-persist/> |
| <cascade-remove/> |
| </cascade> |
| </one-to-one> |
| <transient name="data"/> |
| </attributes> |
| </entity> |
| <entity class="org.mag.Article"> |
| <attributes> |
| <id name="id"/> |
| <basic name="title"/> |
| <basic name="content"/> |
| <version name="version"/> |
| <many-to-many name="articles"> |
| <order-by>lastName, firstName</order-by> |
| </many-to-many> |
| </attributes> |
| </entity> |
| <entity class="org.mag.pub.Company"> |
| <attributes> |
| <id name="id"/> |
| <basic name="name"/> |
| <basic name="revenue"/> |
| <version name="version"/> |
| <one-to-many name="mags" mapped-by="publisher"> |
| <cascade> |
| <cascade-persist/> |
| </cascade> |
| </one-to-many> |
| <one-to-many name="subscriptions"> |
| <cascade> |
| <cascade-persist/> |
| <cascade-remove/> |
| </cascade> |
| </one-to-many> |
| </attributes> |
| </entity> |
| <entity class="org.mag.pub.Author"> |
| <attributes> |
| <id name="id"/> |
| <basic name="firstName"/> |
| <basic name="lastName"/> |
| <version name="version"/> |
| <many-to-many name="arts" mapped-by="authors"> |
| <cascade> |
| <cascade-persist/> |
| </cascade> |
| </many-to-many> |
| </attributes> |
| </entity> |
| <entity class="org.mag.subcribe.Contract"> |
| <attributes> |
| <basic name="terms"/> |
| </attributes> |
| </entity> |
| <entity class="org.mag.subcribe.Subscription"> |
| <attributes> |
| <id name="id"/> |
| <basic name="payment"/> |
| <basic name="startDate"/> |
| <version name="version"/> |
| <one-to-many name="items"> |
| <map-key name="num"> |
| <cascade> |
| <cascade-persist/> |
| <cascade-remove/> |
| </cascade> |
| </one-to-many> |
| </attributes> |
| </entity> |
| <entity class="org.mag.subscribe.Subscription.LineItem"> |
| <attributes> |
| <basic name="comments"/> |
| <basic name="price"/> |
| <basic name="num"/> |
| <many-to-one name="magazine"/> |
| </attributes> |
| </entity> |
| <entity class="org.mag.subscribe.LifetimeSubscription" name="Lifetime" |
| access="PROPERTY"> |
| <attributes> |
| <basic name="eliteClub" fetch="LAZY"/> |
| </attributes> |
| </entity> |
| <entity class="org.mag.subscribe.TrialSubscription" name="Trial"> |
| <attributes> |
| <basic name="endDate"/> |
| </attributes> |
| </entity> |
| <embeddable class="org.mag.pub.Address"> |
| <attributes> |
| <basic name="street"/> |
| <basic name="city"/> |
| <basic name="state"/> |
| <basic name="zip"/> |
| </attributes> |
| </embeddable> |
| </entity-mappings> |
| </pre></div></div><br class="example-break"><p> |
| <a href="#jpa_overview_mapping" title="Chapter 12. Mapping Metadata">Chapter 12, <i xmlns:xlink="http://www.w3.org/1999/xlink"> |
| Mapping Metadata |
| </i></a> will show you how to map your |
| persistent classes to the datastore using additional annotations and XML markup. |
| First, however, we turn to the JPA runtime APIs. |
| </p></div></div><div class="chapter" lang="en" id="jpa_overview_persistence"><div class="titlepage"><div><div><h2 class="title"><a name="jpa_overview_persistence"></a>Chapter 6. |
| Persistence |
| </h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#jpa_overview_persistence_xml">1. |
| persistence.xml |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_persistence_use">2. |
| Non-EE Use |
| </a></span></dt></dl></div><a class="indexterm" name="d0e3904"></a><a class="indexterm" name="d0e3907"></a><a class="indexterm" name="d0e3912"></a><a class="indexterm" name="d0e3917"></a><div class="mediaobject"><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="285"><tr><td><img src="img/persistence.png"></td></tr></table></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| OpenJPA also includes the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/OpenJPAPersistence.html" target="_top"> |
| <code class="classname">OpenJPAPersistence</code></a> helper class to provide |
| additional utility methods. |
| </p></div><p> |
| Within a container, you will typically use <span class="emphasis"><em>injection</em></span> to |
| access an <code class="classname">EntityManagerFactory</code>. Applications operating |
| of a container, however, can use the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="http://java.sun.com/javaee/5/docs/api/javax/persistence/Persistence.html" target="_top"> |
| <code class="classname">Persistence</code></a> class to obtain <code class="classname"> |
| EntityManagerFactory</code> objects in a vendor-neutral fashion. |
| </p><pre class="programlisting"> |
| public static EntityManagerFactory createEntityManagerFactory(String name); |
| public static EntityManagerFactory createEntityManagerFactory(String name, Map props); |
| </pre><p> |
| Each <code class="methodname">createEntityManagerFactory</code> method searches the |
| system for an <code class="classname">EntityManagerFactory</code> definition with the |
| given name. Use <code class="literal">null</code> for an unnamed factory. The optional map |
| contains vendor-specific property settings used to further configure the |
| factory. |
| </p><p> |
| <code class="filename">persistence.xml</code> files define <code class="classname"> |
| EntityManagerFactories</code>. The <code class="methodname">createEntityManagerFactory |
| </code> methods search for <code class="filename">persistence.xml</code> files |
| within the <code class="filename">META-INF</code> directory of any <code class="literal">CLASSPATH |
| </code> element. For example, if your <code class="literal">CLASSPATH</code> contains |
| the <code class="filename">conf</code> directory, you could place an <code class="classname"> |
| EntityManagerFactory</code> definition in <code class="filename"> |
| conf/META-INF/persistence.xml</code>. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="jpa_overview_persistence_xml"></a>1. |
| persistence.xml |
| </h2></div></div></div><p> |
| The <code class="filename">persistence.xml</code> file format obeys the following |
| Document Type Descriptor (DTD): |
| </p><pre class="programlisting"> |
| <!ELEMENT persistence (persistence-unit*)> |
| <!ELEMENT persistence-unit (description?,provider?,jta-data-source?, |
| non-jta-data-source?,(class|jar-file|mapping-file)*, |
| exclude-unlisted-classes?,properties?)> |
| <!ATTLIST persistence-unit name CDATA #REQUIRED> |
| <!ATTLIST persistence-unit transaction-type (JTA|RESOURCE_LOCAL) "JTA"> |
| <!ELEMENT description (#PCDATA)> |
| <!ELEMENT provider (#PCDATA)> |
| <!ELEMENT jta-data-source (#PCDATA)> |
| <!ELEMENT non-jta-data-source (#PCDATA)> |
| <!ELEMENT mapping-file (#PCDATA)> |
| <!ELEMENT jar-file (#PCDATA)> |
| <!ELEMENT class (#PCDATA)> |
| <!ELEMENT exclude-unlisted-classes EMPTY> |
| <!ELEMENT properties (property*)> |
| <!ELEMENT property EMPTY> |
| <!ATTLIST property name CDATA #REQUIRED> |
| <!ATTLIST property value CDATA #REQUIRED> |
| </pre><p> |
| The root element of a <code class="filename">persistence.xml</code> file is <code class="literal"> |
| persistence</code>, which then contains one or more <code class="literal"> |
| persistence-unit</code> definitions. Each persistence unit describes the |
| configuration for the entity managers created by the persistence unit's entity |
| manager factory. The persistence unit can specify these elements and attribtues. |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">name</code>: This is the name you pass to the <code class="methodname"> |
| Persistence.createEntityManagerFactory</code> methods described above. The |
| name attribute is required. |
| </p></li><li><p> |
| <code class="literal">transaction-type</code>: Whether to use managed |
| (<code class="literal">JTA</code>) or local (<code class="literal">RESOURCE_LOCAL</code>) |
| transaction management. |
| </p></li><li><p> |
| <code class="literal">provider</code>: If you are using a third-party JPA vendor, this |
| element names its implementation of the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="http://java.sun.com/javaee/5/docs/api/javax/persistence/spi/PersistenceProvider.html" target="_top"> |
| <code class="classname">PersistenceProvider</code></a> bootstrapping interface. |
| </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| Set the <code class="literal">provider</code> to <code class="classname"> |
| org.apache.openjpa.persistence.PersistenceProviderImpl</code> to use |
| OpenJPA. |
| </p></div></li><li><p> |
| <code class="literal">jta-data-source</code>: The JNDI name of a JDBC <code class="classname"> |
| DataSource</code> that is automatically enlisted in JTA transactions. This |
| may be an XA <code class="classname">DataSource</code>. |
| </p></li><li><p> |
| <code class="literal">non-jta-data-source</code>: The JNDI name of a JDBC <code class="classname"> |
| DataSource</code> that is not enlisted in JTA transactions. |
| </p></li><li><p> |
| <code class="literal">mapping-file</code>*: The resource names of XML mapping files for |
| entities and embeddable classes. You can also specify mapping information in an |
| <code class="filename">orm.xml</code> file in your <code class="filename">META-INF</code> |
| directory. If present, the <code class="filename">orm.xml</code> mapping file will be |
| read automatically. |
| </p></li><li><p> |
| <code class="literal">jar-file</code>*: The names of jar files containing entities and |
| embeddable classes. The implementation will scan the jar for annotated classes. |
| </p></li><li><p> |
| <code class="literal">class</code>*: The class names of entities and embeddable classes. |
| </p></li><li><p> |
| <code class="literal">properties</code>: This element contains nested <code class="literal">property |
| </code> elements used to specify vendor-specific settings. Each <code class="literal"> |
| property</code> has a name attribute and a value attribute. |
| </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| The Reference Guide's <a href="#ref_guide_conf" title="Chapter 2. Configuration">Chapter 2, <i xmlns:xlink="http://www.w3.org/1999/xlink"> |
| Configuration |
| </i></a> describes OpenJPA's |
| configuration properties. |
| </p></div></li></ul></div><p> |
| Here is a typical <code class="filename">persistence.xml</code> file for a non-EE |
| environment: |
| </p><div class="example"><a name="jpa_overview_persistence_xmlex"></a><p class="title"><b>Example 6.1. |
| persistence.xml |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| <?xml version="1.0"?> |
| <persistence> |
| <persistence-unit name="openjpa"> |
| <provider>org.apache.openjpa.persistence.PersistenceProviderImpl</provider> |
| <class>tutorial.Animal</class> |
| <class>tutorial.Dog</class> |
| <class>tutorial.Rabbit</class> |
| <class>tutorial.Snake</class> |
| <properties> |
| <property name="openjpa.ConnectionURL" value="jdbc:hsqldb:tutorial_database"/> |
| <property name="openjpa.ConnectionDriverName" value="org.hsqldb.jdbcDriver"/> |
| <property name="openjpa.ConnectionUserName" value="sa"/> |
| <property name="openjpa.ConnectionPassword" value=""/> |
| <property name="openjpa.Log" value="DefaultLevel=WARN, Tool=INFO"/> |
| </properties> |
| </persistence-unit> |
| </persistence> |
| </pre></div></div><br class="example-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="jpa_overview_persistence_use"></a>2. |
| Non-EE Use |
| </h2></div></div></div><p> |
| The example below demonstrates the <code class="classname">Persistence</code> class in |
| action. You will typically execute code like this on application startup, then |
| cache the resulting factory for future use. This bootstrapping code is only |
| necessary in non-EE environments; in an EE environment <code class="classname"> |
| EntityManagerFactories</code> are typically injected. |
| </p><div class="example"><a name="jpa_overview_persistence_getemfactory"></a><p class="title"><b>Example 6.2. |
| Obtaining an EntityManagerFactory |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| // if your persistence.xml file does not contain all settings already, you |
| // can add vendor settings to a map |
| Properties props = new Properties(); |
| ... |
| |
| // create the factory defined by the "openjpa" entity-manager entry |
| EntityManagerFactory emf = Persistence.createEntityManagerFactory("openjpa", props); |
| </pre></div></div><br class="example-break"></div></div><div class="chapter" lang="en" id="jpa_overview_emfactory"><div class="titlepage"><div><div><h2 class="title"><a name="jpa_overview_emfactory"></a>Chapter 7. |
| EntityManagerFactory |
| </h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#jpa_overview_emfactory_obtain">1. |
| Obtaining an EntityManagerFactory |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_emfactory_em">2. |
| Obtaining EntityManagers |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_emfactory_perscontext">3. |
| Persistence Context |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_emfactory_perscontext_trans">3.1. |
| Transaction Persistence Context |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_emfactory_perscontext_extend">3.2. |
| Extended Persistence Context |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_overview_emfactory_close">4. |
| Closing the EntityManagerFactory |
| </a></span></dt></dl></div><a class="indexterm" name="d0e4153"></a><div class="mediaobject"><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="279"><tr><td><img src="img/entitymanagerfactory.png"></td></tr></table></div><p> |
| The <code class="classname">EntityManagerFactory</code> creates <code class="classname"> |
| EntityManager</code> instances for application use. |
| </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| OpenJPA extends the standard <code class="classname">EntityManagerFactory</code> |
| interface with the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/OpenJPAEntityManagerFactory.html" target="_top"> |
| <code class="classname">OpenJPAEntityManagerFactory</code></a> to provide additional |
| functionality. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="jpa_overview_emfactory_obtain"></a>1. |
| Obtaining an EntityManagerFactory |
| </h2></div></div></div><a class="indexterm" name="d0e4182"></a><a class="indexterm" name="d0e4187"></a><a class="indexterm" name="d0e4192"></a><p> |
| Within a container, you will typically use <span class="emphasis"><em>injection</em></span> to |
| access an <code class="classname">EntityManagerFactory</code>. There are, however, |
| alternative mechanisms for <code class="classname">EntityManagerFactory</code> |
| construction. |
| </p><p> |
| Some vendors may supply public constructors for their <code class="classname"> |
| EntityManagerFactory</code> implementations, but we recommend using the |
| Java Connector Architecture (JCA) in a managed environment, or the <code class="classname"> |
| Persistence</code> class' <code class="methodname">createEntityManagerFactory |
| </code> methods in an unmanaged environment, as described in |
| <a href="#jpa_overview_persistence" title="Chapter 6. Persistence">Chapter 6, <i xmlns:xlink="http://www.w3.org/1999/xlink"> |
| Persistence |
| </i></a>. These strategies allow |
| vendors to pool factories, cutting down on resource utilization. |
| </p><p> |
| <a class="indexterm" name="d0e4221"></a> |
| JPA allows you to create and configure an <code class="classname"> |
| EntityManagerFactory</code>, then store it in a Java Naming and Directory |
| Interface (JNDI) tree for later retrieval and use. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="jpa_overview_emfactory_em"></a>2. |
| Obtaining EntityManagers |
| </h2></div></div></div><a class="indexterm" name="d0e4231"></a><a class="indexterm" name="d0e4238"></a><pre class="programlisting"> |
| public EntityManager createEntityManager(); |
| public EntityManager createEntityManager(Map map); |
| </pre><p> |
| The two <code class="methodname">createEntityManager</code> methods above create a new |
| <code class="classname">EntityManager</code> each time they are invoked. The optional |
| <code class="classname">Map</code> is used to to supply vendor-specific settings. If you |
| have configured your implementation for JTA transactions and a JTA transaction |
| is active, the returned <code class="classname">EntityManager</code> will be |
| synchronized with that transaction. |
| </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| OpenJPA recognizes the following string keys in the map supplied to <code class="methodname"> |
| createEntityManager</code>: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">openjpa.ConnectionUserName</code> |
| </p></li><li><p> |
| <code class="literal">openjpa.ConnectionPassword</code> |
| </p></li><li><p> |
| <code class="literal">openjpa.ConnectionRetainMode</code> |
| </p></li><li><p> |
| <code class="literal">openjpa.TransactionMode</code> |
| </p></li><li><p> |
| <code class="literal">openjpa.<property></code>, where <span class="emphasis"><em><property> |
| </em></span> is any JavaBean property of the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/OpenJPAEntityManager.html" target="_top"> |
| <code class="classname"> |
| org.apache.openjpa.persistence.OpenJPAEntityManager</code></a>. |
| </p></li></ul></div><p> |
| The last option uses reflection to configure any property of OpenJPA's |
| <code class="classname">EntityManager</code> implementation with the value supplied in |
| your map. The first options correspond exactly to the same-named OpenJPA |
| configuration keys described in <a href="#ref_guide_conf" title="Chapter 2. Configuration">Chapter 2, <i xmlns:xlink="http://www.w3.org/1999/xlink"> |
| Configuration |
| </i></a> of the |
| Reference Guide. |
| </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="jpa_overview_emfactory_perscontext"></a>3. |
| Persistence Context |
| </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#jpa_overview_emfactory_perscontext_trans">3.1. |
| Transaction Persistence Context |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_emfactory_perscontext_extend">3.2. |
| Extended Persistence Context |
| </a></span></dt></dl></div><a class="indexterm" name="d0e4314"></a><a class="indexterm" name="d0e4317"></a><p> |
| A persistence context is a set of entities such that for any persistent identity |
| there is a unique entity instance. Within a persistence context, entities are |
| <span class="emphasis"><em>managed</em></span>. The <code class="classname"> EntityManager</code> controls |
| their lifecycle, and they can access datastore resources. |
| </p><p> |
| When a persistence context ends, previously-managed entities become <span class="emphasis"><em> |
| detached</em></span>. A detached entity is no longer under the control of the |
| <code class="classname">EntityManager</code>, and no longer has access to datastore |
| resources. We discuss detachment in detail in |
| <a href="#jpa_overview_em_lifecycle" title="2. Entity Lifecycle Management">Section 2, “ |
| Entity Lifecycle Management |
| ”</a>. For now, it is sufficient to |
| know that detachment has two obvious consequences: |
| </p><div class="orderedlist"><ol type="1"><li><p> |
| The detached entity cannot load any additional persistent state. |
| </p></li><li><p> |
| The <code class="classname">EntityManager</code> will not return the detached entity |
| from <code class="methodname">find</code>, nor will queries include the detached |
| entity in their results. Instead, <code class="methodname">find</code> method |
| invocations and query executions that would normally incorporate the detached |
| entity will create a new managed entity with the same identity. |
| </p></li></ol></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| OpenJPA offers several features related to detaching entities. See |
| <a href="#ref_guide_detach" title="1. Detach and Attach">Section 1, “ |
| Detach and Attach |
| ”</a> in the Reference Guide. |
| <a href="#ref_guide_detach_graph" title="1.3. Defining the Detached Object Graph">Section 1.3, “ |
| Defining the Detached Object Graph |
| ”</a> in particular describes how to |
| use the <code class="literal">DetachState</code> setting to boost the performance of |
| merging detached entities. |
| </p></div><p> |
| Injected <code class="classname">EntityManager</code>s have a <span class="emphasis"><em>transaction |
| </em></span> persistence context, |
| while <code class="classname"> EntityManager</code>s obtained through the |
| <code class="classname">EntityManagerFactory</code> have an <span class="emphasis"><em>extended |
| </em></span> persistence context. We describe these persistence context types |
| below. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_overview_emfactory_perscontext_trans"></a>3.1. |
| Transaction Persistence Context |
| </h3></div></div></div><p> |
| Under the transaction persistence context model, an <code class="classname"> EntityManager |
| </code> begins a new persistence context with each transaction, and ends |
| the context when the transaction commits or rolls back. Within the transaction, |
| entities you retrieve through the <code class="classname">EntityManager</code> or via |
| <code class="classname">Queries</code> are managed entities. They can access datastore |
| resources to lazy-load additional persistent state as needed, and only one |
| entity may exist for any persistent identity. |
| </p><p> |
| When the transaction completes, all entities lose their association with the |
| <code class="classname">EntityManager</code> and become detached. Traversing a |
| persistent field that wasn't already loaded now has undefined results. And using |
| the <code class="classname"> EntityManager</code> or a <code class="classname">Query</code> to |
| retrieve additional objects may now create new instances with the same |
| persistent identities as detached instances. |
| </p><p> |
| If you use an <code class="classname">EntityManager</code> with a transaction |
| persistence context model outside of an active transaction, each method |
| invocation creates a new persistence context, performs the method action, and |
| ends the persistence context. For example, consider using the <code class="methodname"> |
| EntityManager.find</code> method outside of a transaction. The <code class="classname"> |
| EntityManager</code> will create a temporary persistence context, perform |
| the find operation, end the persistence context, and return the detached result |
| object to you. A second call with the same id will return a second detached |
| object. |
| </p><p> |
| When the next transaction begins, the <code class="classname">EntityManager</code> will |
| begin a new persistence context, and will again start returning managed |
| entities. As you'll see in <a href="#jpa_overview_em" title="Chapter 8. EntityManager">Chapter 8, <i xmlns:xlink="http://www.w3.org/1999/xlink"> |
| EntityManager |
| </i></a>, you can |
| also merge the previously-detached entites back into the new persistence |
| context. |
| </p><div class="example"><a name="jpa_overview_emfactory_perscontext_transex"></a><p class="title"><b>Example 7.1. |
| Behavior of Transaction Persistence Context |
| </b></p><div class="example-contents"><p> |
| The following code illustrates the behavior of entites under an <code class="classname"> |
| EntityManager</code> using a transaction persistence context. |
| </p><pre class="programlisting"> |
| EntityManager em; // injected |
| ... |
| |
| // outside a transaction: |
| |
| // each operation occurs in a separate persistence context, and returns |
| // a new detached instance |
| Magazine mag1 = em.find(Magazine.class, magId); |
| Magazine mag2 = em.find(Magazine.class, magId); |
| assertTrue(mag2 != mag1); |
| ... |
| |
| // transaction begins: |
| |
| // within a transaction, a subsequent lookup doesn't return any of the |
| // detached objects. however, two lookups within the same transaction |
| // return the same instance, because the persistence context spans the |
| // transaction |
| Magazine mag3 = em.find(Magazine.class, magId); |
| assertTrue(mag3 != mag1 && mag3 != mag2); |
| Magazine mag4 = em.find(Magazine.class (magId); |
| assertTrue(mag4 == mag3); |
| ... |
| |
| // transaction commits: |
| |
| // once again, each operation returns a new instance |
| Magazine mag5 = em.find(Magazine.class, magId); |
| assertTrue(mag5 != mag3); |
| </pre></div></div><br class="example-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_overview_emfactory_perscontext_extend"></a>3.2. |
| Extended Persistence Context |
| </h3></div></div></div><p> |
| An <code class="classname">EntityManager</code> using an extended persistence context |
| maintains the same persistence context for its entire lifecycle. Whether inside |
| a transaction or not, all entities returned from the <code class="classname">EntityManager |
| </code> are managed, and the <code class="classname">EntityManager</code> never |
| creates two entity instances to represent the same persistent identity. Entities |
| only become detached when you finally close the <code class="classname">EntityManager |
| </code> (or when they are serialized). |
| </p><div class="example"><a name="jpa_overview_emfactory_perscontext_extendex"></a><p class="title"><b>Example 7.2. |
| Behavior of Extended Persistence Context |
| </b></p><div class="example-contents"><p> |
| The following code illustrates the behavior of entites under an <code class="classname"> |
| EntityManager</code> using an extended persistence context. |
| </p><pre class="programlisting"> |
| EntityManagerFactory emf = ... |
| EntityManager em = emf.createEntityManager(); |
| |
| // persistence context active for entire life of EM, so only one entity |
| // for a given persistent identity |
| Magazine mag1 = em.find(Magazine.class, magId); |
| Magazine mag2 = em.find(Magazine.class, magId); |
| assertTrue(mag2 == mag1); |
| |
| em.getTransaction().begin(); |
| |
| // same persistence context active within the transaction |
| Magazine mag3 = em.find(Magazine.class, magId); |
| assertTrue(mag3 == mag1); |
| Magazine mag4 = em.find(Magazine.class (magId); |
| assertTrue(mag4 == mag1); |
| |
| em.getTransaction.commit (); |
| |
| // when the transaction commits, instance still managed |
| Magazine mag5 = em.find(Magazine.class, magId); |
| assertTrue(mag5 == mag1); |
| |
| // instance finally becomes detached when EM closes |
| em.close(); |
| </pre></div></div><br class="example-break"></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="jpa_overview_emfactory_close"></a>4. |
| Closing the EntityManagerFactory |
| </h2></div></div></div><a class="indexterm" name="d0e4466"></a><pre class="programlisting"> |
| public boolean isOpen (); |
| public void close (); |
| </pre><p> |
| <code class="classname">EntityManagerFactory</code> instances are heavyweight objects. |
| Each factory might maintain a metadata cache, object state cache, <code class="classname"> |
| EntityManager</code> pool, connection pool, and more. If your application |
| no longer needs an <code class="classname">EntityManagerFactory</code>, you should |
| close it to free these resources. When an <code class="classname">EntityManagerFactory |
| </code> closes, all <code class="classname">EntityManager</code>s from that |
| factory, and by extension all entities managed by those <code class="classname"> |
| EntityManager</code>s, become invalid. Attempting to close an <code class="classname"> |
| EntityManagerFactory</code> while one or more of its <code class="classname"> |
| EntityManager</code>s has an active transaction may result in an |
| <code class="classname">IllegalStateException</code>. |
| </p><p> |
| Closing an <code class="classname">EntityManagerFactory</code> should not be taken |
| lightly. It is much better to keep a factory open for a long period of time than |
| to repeatedly create and close new factories. Thus, most applications will never |
| close the factory, or only close it when the application is exiting. Only |
| applications that require multiple factories with different configurations have |
| an obvious reason to create and close multiple <code class="classname">EntityManagerFactory |
| </code> instances. Once a factory is closed, all methods except |
| <code class="methodname">isOpen</code> throw an <code class="classname"> |
| IllegalStateException</code>. |
| </p></div></div><div class="chapter" lang="en" id="jpa_overview_em"><div class="titlepage"><div><div><h2 class="title"><a name="jpa_overview_em"></a>Chapter 8. |
| EntityManager |
| </h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#jpa_overview_em_trans">1. |
| Transaction Association |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_em_lifecycle">2. |
| Entity Lifecycle Management |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_em_lifeexamples">3. |
| Lifecycle Examples |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_em_identity">4. |
| Entity Identity Management |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_em_cache">5. |
| Cache Management |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_em_query">6. |
| Query Factory |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_em_closing">7. |
| Closing |
| </a></span></dt></dl></div><a class="indexterm" name="d0e4520"></a><div class="mediaobject"><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="189"><tr><td><img src="img/entitymanager.png"></td></tr></table></div><p> |
| The diagram above presents an overview of the <code class="classname">EntityManager |
| </code> interface. For a complete treatment of the <code class="classname"> |
| EntityManager</code> API, see the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="http://java.sun.com/javaee/5/docs/api/javax/persistence/EntityManager.html" target="_top"> |
| Javadoc</a> documentation. Methods whose parameter signatures consist of |
| an ellipsis (...) are overloaded to take multiple parameter types. |
| </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| OpenJPA extends the standard <code class="classname">EntityManager</code> interface with |
| the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/OpenJPAEntityManager.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.OpenJPAEntityManager</code> |
| </a> interface to provide additional functionality. |
| </p></div><p> |
| The <code class="classname">EntityManager</code> is the primary interface used by |
| application developers to interact with the JPA runtime. The methods |
| of the <code class="classname">EntityManager</code> can be divided into the following |
| functional categories: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="classname">Transaction</code> association. |
| </p></li><li><p> |
| Entity lifecycle management. |
| </p></li><li><p> |
| Entity identity management. |
| </p></li><li><p> |
| Cache management. |
| </p></li><li><p> |
| <code class="classname">Query</code> factory. |
| </p></li><li><p> |
| Closing. |
| </p></li></ul></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="jpa_overview_em_trans"></a>1. |
| Transaction Association |
| </h2></div></div></div><a class="indexterm" name="d0e4586"></a><a class="indexterm" name="d0e4593"></a><pre class="programlisting"> |
| public EntityTransaction getTransaction (); |
| </pre><p> |
| Every <code class="classname">EntityManager</code> has a one-to-one relation with an |
| <a href="#jpa_overview_trans" title="Chapter 9. Transaction"><code class="classname">EntityTransaction</code> |
| </a> instance. In fact, many vendors use a single class to implement both the |
| <code class="classname">EntityManager</code> and <code class="classname">EntityTransaction |
| </code> interfaces. If your application requires multiple concurrent |
| transactions, you will use multiple <code class="classname">EntityManager</code>s. |
| </p><p> |
| You can retrieve the <code class="classname">EntityTransaction</code> associated with an |
| <code class="classname">EntityManager</code> through the <code class="methodname">getTransaction |
| </code> method. Note that most JPA implementations can |
| integrate with an application server's managed transactions. If you take |
| advantage of this feature, you will control transactions by declarative |
| demarcation or through the Java Transaction API (JTA) rather than through the |
| <code class="classname">EntityTransaction</code>. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="jpa_overview_em_lifecycle"></a>2. |
| Entity Lifecycle Management |
| </h2></div></div></div><a class="indexterm" name="d0e4636"></a><p> |
| <code class="classname">EntityManager</code>s perform several actions that affect the |
| lifecycle state of entity instances. |
| </p><pre class="programlisting"> |
| public void persist(Object entity); |
| </pre><p> |
| <a class="indexterm" name="d0e4650"></a> |
| <a class="indexterm" name="d0e4656"></a> |
| <a class="indexterm" name="d0e4662"></a> |
| Transitions new instances to managed. On the next flush or commit, the newly |
| persisted instances will be inserted into the datastore. |
| </p><p> |
| For a given entity <code class="literal">A</code>, the <code class="methodname">persist</code> |
| method behaves as follows: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| If <code class="literal">A</code> is a new entity, it becomes managed. |
| </p></li><li><p> |
| If <code class="literal">A</code> is an existing managed entity, it is ignored. However, |
| the persist operation cascades as defined below. |
| </p></li><li><p> |
| If <code class="literal">A</code> is a removed entity, it becomes managed. |
| </p></li><li><p> |
| If <code class="literal">A</code> is a detached entity, an <code class="classname"> |
| IllegalArgumentException</code> is thrown. |
| </p></li><li><p> |
| The persist operation recurses on all relation fields of <code class="literal">A</code> |
| whose <a href="#jpa_overview_meta_cascade" title="2.8.1. Cascade Type">cascades</a> include |
| <code class="literal">CascadeType.PERSIST</code>. |
| </p></li></ul></div><p> |
| This action can only be used in the context of an active transaction. |
| </p><pre class="programlisting"> |
| public void remove(Object entity); |
| </pre><p> |
| <a class="indexterm" name="d0e4722"></a> |
| <a class="indexterm" name="d0e4728"></a> |
| <a class="indexterm" name="d0e4734"></a> |
| Transitions managed instances to removed. The instances will be deleted from the |
| datastore on the next flush or commit. Accessing a removed entity has undefined |
| results. |
| </p><p> |
| For a given entity <code class="literal">A</code>, the <code class="methodname">remove</code> |
| method behaves as follows: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| If <code class="literal">A</code> is a new entity, it is ignored. However, the remove |
| operation cascades as defined below. |
| </p></li><li><p> |
| If <code class="literal">A</code> is an existing managed entity, it becomes removed. |
| </p></li><li><p> |
| If <code class="literal">A</code> is a removed entity, it is ignored. |
| </p></li><li><p> |
| If <code class="literal">A</code> is a detached entity, an <code class="classname"> |
| IllegalArgumentException</code> is thrown. |
| </p></li><li><p> |
| The remove operation recurses on all relation fields of <code class="literal">A</code> |
| whose <a href="#jpa_overview_meta_cascade" title="2.8.1. Cascade Type">cascades</a> include |
| <code class="literal">CascadeType.REMOVE</code>. |
| </p></li></ul></div><p> |
| This action can only be used in the context of an active transaction. |
| </p><pre class="programlisting"> |
| public void refresh(Object entity); |
| </pre><p> |
| <a class="indexterm" name="d0e4794"></a> |
| <a class="indexterm" name="d0e4800"></a> |
| <a class="indexterm" name="d0e4806"></a> |
| <a class="indexterm" name="d0e4812"></a> |
| Use the <code class="methodname">refresh</code> action to make sure the persistent |
| state of an instance is synchronized with the values in the datastore. |
| <code class="methodname">refresh</code> is intended for long-running optimistic |
| transactions in which there is a danger of seeing stale data. |
| </p><p> |
| For a given entity <code class="literal">A</code>, the <code class="methodname">refresh</code> |
| method behaves as follows: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| If <code class="literal">A</code> is a new entity, it is ignored. However, the refresh |
| operation cascades as defined below. |
| </p></li><li><p> |
| If <code class="literal">A</code> is an existing managed entity, its state is refreshed |
| from the datastore. |
| </p></li><li><p> |
| If <code class="literal">A</code> is a removed entity, it is ignored. |
| </p></li><li><p> |
| If <code class="literal">A</code> is a detached entity, an <code class="classname"> |
| IllegalArgumentException</code> is thrown. |
| </p></li><li><p> |
| The refresh operation recurses on all relation fields of <code class="literal">A</code> |
| whose <a href="#jpa_overview_meta_cascade" title="2.8.1. Cascade Type">cascades</a> include |
| <code class="literal">CascadeType.REFRESH</code>. |
| </p></li></ul></div><pre class="programlisting"> |
| public Object merge(Object entity); |
| </pre><p> |
| <a class="indexterm" name="d0e4876"></a> |
| <a class="indexterm" name="d0e4884"></a> |
| <a class="indexterm" name="d0e4890"></a> |
| <a class="indexterm" name="d0e4896"></a> |
| <a class="indexterm" name="d0e4900"></a> |
| A common use case for an application running in a servlet or application server |
| is to "detach" objects from all server resources, modify them, and then "attach" |
| them again. For example, a servlet might store persistent data in a user session |
| between a modification based on a series of web forms. Between each form |
| request, the web container might decide to serialize the session, requiring that |
| the stored persistent state be disassociated from any other resources. |
| Similarly, a client/server application might transfer persistent objects to a |
| client via serialization, allow the client to modify their state, and then have |
| the client return the modified data in order to be saved. This is sometimes |
| referred to as the <span class="emphasis"><em>data transfer object</em></span> or <span class="emphasis"><em>value |
| object</em></span> pattern, and it allows fine-grained manipulation of data |
| objects without incurring the overhead of multiple remote method invocations. |
| </p><p> |
| JPA provides support for this pattern by automatically detaching |
| entities when they are serialized or when a persistence context ends (see |
| <a href="#jpa_overview_emfactory_perscontext" title="3. Persistence Context">Section 3, “ |
| Persistence Context |
| ”</a> for an exploration of |
| persistence contexts). The JPA <span class="emphasis"><em>merge</em></span> API |
| re-attaches detached entities. This allows you to detach a persistent instance, |
| modify the detached instance offline, and merge the instance back into an |
| <code class="classname">EntityManager</code> (either the same one that detached the |
| instance, or a new one). The changes will then be applied to the existing |
| instance from the datastore. |
| </p><p> |
| A detached entity maintains its persistent identity, but cannot load additional |
| state from the datastore. Accessing any persistent field or property that was |
| not loaded at the time of detachment has undefined results. Also, be sure not to |
| alter the version or identity fields of detached instances if you plan on |
| merging them later. |
| </p><p> |
| The <code class="methodname">merge</code> method returns a managed copy of the given |
| detached entity. Changes made to the persistent state of the detached entity are |
| applied to this managed instance. Because merging involves changing persistent |
| state, you can only merge within a transaction. |
| </p><p> |
| If you attempt to merge an instance whose representation has changed in the |
| datastore since detachment, the merge operation will throw an exception, or the |
| transaction in which you perform the merge will fail on commit, just as if a |
| normal optimistic conflict were detected. |
| </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| OpenJPA offers enhancements to JPA detachment functionality, |
| including additional options to control which fields are detached. See |
| <a href="#ref_guide_detach" title="1. Detach and Attach">Section 1, “ |
| Detach and Attach |
| ”</a> in the Reference Guide for details. |
| </p></div><p> |
| For a given entity <code class="literal">A</code>, the <code class="methodname">merge</code> |
| method behaves as follows: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| If <code class="literal">A</code> is a detached entity, its state is copied into existing |
| managed instance <code class="literal">A'</code> of the same entity identity, or a new |
| managed copy of <code class="literal">A</code> is created. |
| </p></li><li><p> |
| If <code class="literal">A</code> is a new entity, a new managed entity <code class="literal">A' |
| </code> is created and the state of <code class="literal">A</code> is copied into |
| <code class="literal">A'</code>. |
| </p></li><li><p> |
| If <code class="literal">A</code> is an existing managed entity, it is ignored. However, |
| the merge operation still cascades as defined below. |
| </p></li><li><p> |
| If <code class="literal">A</code> is a removed entity, an <code class="classname"> |
| IllegalArgumentException</code> is thrown. |
| </p></li><li><p> |
| The merge operation recurses on all relation fields of <code class="literal">A</code> |
| whose <a href="#jpa_overview_meta_cascade" title="2.8.1. Cascade Type">cascades</a> include |
| <code class="literal">CascadeType.MERGE</code>. |
| </p></li></ul></div><pre class="programlisting"> |
| public void lock (Object entity, LockModeType mode); |
| </pre><p> |
| <a class="indexterm" name="d0e5001"></a> |
| <a class="indexterm" name="d0e5007"></a> |
| This method locks the given entity using the named mode. The |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="http://java.sun.com/javaee/5/docs/api/javax/persistence/LockmodeType.html" target="_top"> |
| <code class="classname">javax.persistence.LockModeType</code></a> enum defines two |
| modes: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">READ</code>: Other transactions may concurrently read the object, |
| but cannot concurrently update it. |
| </p></li><li><p> |
| <code class="literal">WRITE</code>: Other transactions cannot concurrently read or write |
| the object. When a transaction is committed that holds WRITE locks on any |
| entites, those entites will have their version incremented even if the entities |
| themselves did not change in the transaction. |
| </p></li></ul></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| OpenJPA has additional APIs for controlling object locking. See |
| <a href="#ref_guide_locking" title="3. Object Locking">Section 3, “ |
| Object Locking |
| ”</a> in the Reference Guide for details. |
| </p></div><p> |
| The following diagram illustrates the lifecycle of an entity with respect to the |
| APIs presented in this section. |
| </p><div class="mediaobject"><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="297"><tr><td><img src="img/jpa-state-transitions.png"></td></tr></table></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="jpa_overview_em_lifeexamples"></a>3. |
| Lifecycle Examples |
| </h2></div></div></div><p> |
| The examples below demonstrate how to use the lifecycle methods presented in the |
| previous section. The examples are appropriate for out-of-container use. Within |
| a container, <code class="classname"> EntityManager</code>s are usually injected, and |
| transactions are usually managed. You would therefore omit the <code class="methodname"> |
| createEntityManager</code> and <code class="methodname">close</code> calls, as |
| well as all transaction demarcation code. |
| </p><div class="example"><a name="jpa_overview_em_lifecycle_persist"></a><p class="title"><b>Example 8.1. |
| Persisting Objects |
| </b></p><div class="example-contents"><a class="indexterm" name="d0e5059"></a><pre class="programlisting"> |
| // create some objects |
| Magazine mag = new Magazine("1B78-YU9L", "JavaWorld"); |
| |
| Company pub = new Company("Weston House"); |
| pub.setRevenue(1750000D); |
| mag.setPublisher(pub); |
| pub.addMagazine(mag); |
| |
| Article art = new Article("JPA Rules!", "Transparent Object Persistence"); |
| art.addAuthor(new Author("Fred", "Hoyle")); |
| mag.addArticle(art); |
| |
| // persist |
| EntityManager em = emf.createEntityManager(); |
| em.getTransaction().begin(); |
| em.persist(mag); |
| em.persist(pub); |
| em.persist(art); |
| em.getTransaction().commit(); |
| |
| // or we could continue using the EntityManager... |
| em.close(); |
| </pre></div></div><br class="example-break"><div class="example"><a name="jpa_overview_em_lifecycle_update"></a><p class="title"><b>Example 8.2. |
| Updating Objects |
| </b></p><div class="example-contents"><a class="indexterm" name="d0e5071"></a><pre class="programlisting"> |
| Magazine.MagazineId mi = new Magazine.MagazineId(); |
| mi.isbn = "1B78-YU9L"; |
| mi.title = "JavaWorld"; |
| |
| // updates should always be made within transactions; note that |
| // there is no code explicitly linking the magazine or company |
| // with the transaction; JPA automatically tracks all changes |
| EntityManager em = emf.createEntityManager(); |
| em.getTransaction().begin(); |
| Magazine mag = em.find(Magazine.class, mi); |
| mag.setPrice(5.99); |
| Company pub = mag.getPublisher(); |
| pub.setRevenue(1750000D); |
| em.getTransaction().commit(); |
| |
| // or we could continue using the EntityManager... |
| em.close(); |
| </pre></div></div><br class="example-break"><div class="example"><a name="jpa_overview_em_lifecycle_delete"></a><p class="title"><b>Example 8.3. |
| Removing Objects |
| </b></p><div class="example-contents"><a class="indexterm" name="d0e5083"></a><pre class="programlisting"> |
| // assume we have an object id for the company whose subscriptions |
| // we want to delete |
| Object oid = ...; |
| |
| // deletes should always be made within transactions |
| EntityManager em = emf.createEntityManager(); |
| em.getTransaction().begin(); |
| Company pub = (Company) em.find(Company.class, oid); |
| for (Subscription sub : pub.getSubscriptions()) |
| em.remove(sub); |
| pub.getSubscriptions().clear(); |
| em.getTransaction().commit(); |
| |
| // or we could continue using the EntityManager... |
| em.close(); |
| </pre></div></div><br class="example-break"><div class="example"><a name="jpa_overview_em_detachex"></a><p class="title"><b>Example 8.4. |
| Detaching and Merging |
| </b></p><div class="example-contents"><p> |
| This example demonstrates a common client/server scenario. The client requests |
| objects and makes changes to them, while the server handles the object lookups |
| and transactions. |
| </p><pre class="programlisting"> |
| // CLIENT: |
| // requests an object with a given oid |
| Record detached = (Record) getFromServer(oid); |
| |
| ... |
| |
| // SERVER: |
| // send object to client; object detaches on EM close |
| Object oid = processClientRequest(); |
| EntityManager em = emf.createEntityManager(); |
| Record record = em.find(Record.class, oid); |
| em.close(); |
| sendToClient(record); |
| |
| ... |
| |
| // CLIENT: |
| // makes some modifications and sends back to server |
| detached.setSomeField("bar"); |
| sendToServer(detached); |
| |
| ... |
| |
| // SERVER: |
| // merges the instance and commit the changes |
| Record modified = (Record) processClientRequest(); |
| EntityManager em = emf.createEntityManager(); |
| em.getTransaction().begin(); |
| Record merged = (Record) em.merge(modified); |
| merged.setLastModified(System.currentTimeMillis()); |
| merged.setModifier(getClientIdentityCode()); |
| em.getTransaction().commit(); |
| em.close(); |
| </pre></div></div><br class="example-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="jpa_overview_em_identity"></a>4. |
| Entity Identity Management |
| </h2></div></div></div><p> |
| Each <code class="classname">EntityManager</code> is responsible for managing the |
| persistent identities of the managed objects in the persistence context. The |
| following methods allow you to interact with the management of persistent |
| identities. The behavior of these methods is deeply affected by the persistence |
| context type of the <code class="classname">EntityManager</code>; see |
| <a href="#jpa_overview_emfactory_perscontext" title="3. Persistence Context">Section 3, “ |
| Persistence Context |
| ”</a> for an explanation of |
| persistence contexts. |
| </p><pre class="programlisting"> |
| public <T> T find(Class<T> cls, Object oid); |
| </pre><p> |
| <a class="indexterm" name="d0e5116"></a> |
| <a class="indexterm" name="d0e5124"></a> |
| <a class="indexterm" name="d0e5130"></a> |
| This method returns the persistent instance of the given type with the given |
| persistent identity. If the instance is already present in the current |
| persistence context, the cached version will be returned. Otherwise, a new |
| instance will be constructed and loaded with state from the datastore. If no |
| entity with the given type and identity exists in the datastore, this method |
| returns null. |
| </p><pre class="programlisting"> |
| public <T> T getReference(Class<T> cls, Object oid); |
| </pre><p> |
| <a class="indexterm" name="d0e5140"></a> |
| <a class="indexterm" name="d0e5148"></a> |
| <a class="indexterm" name="d0e5154"></a> |
| <a class="indexterm" name="d0e5160"></a> |
| This method is similar to <code class="methodname">find</code>, but does not |
| necessarily go to the database when the entity is not found in cache. The |
| implementation may construct a <span class="emphasis"><em>hollow</em></span> entity and return it |
| to you instead. Hollow entities do not have any state loaded. The state only |
| gets loaded when you attempt to access a persistent field. At that time, the |
| implementation may throw an <code class="classname">EntityNotFoundException</code> if it |
| discovers that the entity does not exist in the datastore. The implementation |
| may also throw an <code class="classname">EntityNotFoundException</code> from the |
| <code class="methodname">getReference</code> method itself. Unlike <code class="methodname"> |
| find</code>, <code class="methodname">getReference</code> does not return null. |
| </p><pre class="programlisting"> |
| public boolean contains(Object entity); |
| </pre><p> |
| <a class="indexterm" name="d0e5189"></a> |
| <a class="indexterm" name="d0e5195"></a> |
| Returns true if the given entity is part of the current persistence context, and |
| false otherwise. Removed entities are not considered part of the current |
| persistence context. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="jpa_overview_em_cache"></a>5. |
| Cache Management |
| </h2></div></div></div><a class="indexterm" name="d0e5204"></a><pre class="programlisting"> |
| public void flush(); |
| </pre><p> |
| <a class="indexterm" name="d0e5213"></a> |
| <a class="indexterm" name="d0e5219"></a> |
| <a class="indexterm" name="d0e5225"></a> |
| The <code class="methodname">flush</code> method writes any changes that have been made |
| in the current transaction to the datastore. If the <code class="classname">EntityManager |
| </code> does not already have a connection to the datastore, it obtains one |
| for the flush and retains it for the duration of the transaction. Any exceptions |
| during flush cause the transaction to be marked for rollback. See |
| <a href="#jpa_overview_trans" title="Chapter 9. Transaction">Chapter 9, <i xmlns:xlink="http://www.w3.org/1999/xlink"> |
| Transaction |
| </i></a>. |
| </p><p> |
| Flushing requires an active transaction. If there isn't a transaction in |
| progress, the <code class="methodname">flush</code> method throws a <code class="classname"> |
| TransactionRequiredException</code>. |
| </p><pre class="programlisting"> |
| public FlushModeType getFlushMode(); |
| public void setFlushMode(FlushModeType flushMode); |
| </pre><p> |
| <a class="indexterm" name="d0e5251"></a> |
| <a class="indexterm" name="d0e5257"></a> |
| The <code class="classname">EntityManager</code>'s <code class="literal">FlushMode</code> property |
| controls whether to flush transactional changes before executing queries. This |
| allows the query results to take into account changes you have made during the |
| current transaction. Available |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="http://java.sun.com/javaee/5/docs/api/javax/persistence/FlushModeType.html" target="_top"> |
| <code class="classname">javax.persistence.FlushModeType</code></a> constants are: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">COMMIT</code>: Only flush when committing, or when told to do so |
| through the <code class="methodname">flush</code> method. Query results may not take |
| into account changes made in the current transaction. |
| </p></li><li><p> |
| <code class="literal">AUTO</code>: The implementation is permitted to flush before |
| queries to ensure that the results reflect the most recent object state. |
| </p></li></ul></div><p> |
| You can also set the flush mode on individual |
| <a href="#jpa_overview_query" title="Chapter 10. JPA Query"><code class="classname">Query</code></a> |
| instances. |
| </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| OpenJPA only flushes before a query if the query might be affected by data |
| changed in the current transaction. Additionally, OpenJPA allows fine-grained |
| control over flushing behavior. See the Reference Guide's |
| <a href="#ref_guide_dbsetup_retain" title="8. Configuring the Use of JDBC Connections">Section 8, “ |
| Configuring the Use of JDBC Connections |
| ”</a>. |
| </p></div><pre class="programlisting"> |
| public void clear(); |
| </pre><p> |
| <a class="indexterm" name="d0e5303"></a> |
| <a class="indexterm" name="d0e5309"></a> |
| Clearing the <code class="classname">EntityManager</code> effectively ends the |
| persistence context. All entities managed by the <code class="classname">EntityManager |
| </code> become detached. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="jpa_overview_em_query"></a>6. |
| Query Factory |
| </h2></div></div></div><a class="indexterm" name="d0e5324"></a><a class="indexterm" name="d0e5331"></a><pre class="programlisting"> |
| public Query createQuery(String query); |
| </pre><p> |
| <code class="classname">Query</code> objects are used to find entities matching certain |
| criteria. The <code class="methodname">createQuery</code> method creates a query using |
| the given Java Persistence Query Language (JPQL) string. See |
| <a href="#jpa_overview_query" title="Chapter 10. JPA Query">Chapter 10, <i xmlns:xlink="http://www.w3.org/1999/xlink"> |
| JPA Query |
| </i></a> for details. |
| </p><pre class="programlisting"> |
| public Query createNamedQuery(String name); |
| </pre><p> |
| This method retrieves a query defined in metadata by name. The returned |
| <code class="classname">Query</code> instance is initialized with the information |
| declared in metadata. For more information on named queries, read |
| <a href="#jpa_overview_query_named" title="1.10. Named Queries">Section 1.10, “ |
| Named Queries |
| ”</a>. |
| </p><pre class="programlisting"> |
| public Query createNativeQuery(String sql); |
| public Query createNativeQuery(String sql, Class resultCls); |
| public Query createNativeQuery(String sql, String resultMapping); |
| </pre><p> |
| <span class="emphasis"><em>Native</em></span> queries are queries in the datastore's native |
| language. For relational databases, this the Structured Query Language (SQL). |
| <a href="#jpa_overview_sqlquery" title="Chapter 11. SQL Queries">Chapter 11, <i xmlns:xlink="http://www.w3.org/1999/xlink"> |
| SQL Queries |
| </i></a> elaborates on JPA's |
| native query support. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="jpa_overview_em_closing"></a>7. |
| Closing |
| </h2></div></div></div><a class="indexterm" name="d0e5369"></a><pre class="programlisting"> |
| public boolean isOpen(); |
| public void close(); |
| </pre><p> |
| When an <code class="classname">EntityManager</code> is no longer needed, you should |
| call its <code class="methodname">close</code> method. Closing an <code class="classname"> |
| EntityManager</code> releases any resources it is using. The persistence |
| context ends, and the entities managed by the <code class="classname">EntityManager |
| </code> become detached. Any <code class="classname">Query</code> instances the |
| <code class="classname">EntityManager</code> created become invalid. Calling any method |
| other than <code class="methodname">isOpen</code> on a closed <code class="classname">EntityManager |
| </code> results in an <code class="classname">IllegalStateException</code>. You |
| cannot close a <code class="classname">EntityManager</code> that is in the middle of a |
| transaction. |
| </p><p> |
| If you are in a managed environment using injected entity managers, you should |
| not close them. |
| </p></div></div><div class="chapter" lang="en" id="jpa_overview_trans"><div class="titlepage"><div><div><h2 class="title"><a name="jpa_overview_trans"></a>Chapter 9. |
| Transaction |
| </h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#jpa_overview_trans_types">1. |
| Transaction Types |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_trans_local">2. |
| The EntityTransaction Interface |
| </a></span></dt></dl></div><a class="indexterm" name="d0e5414"></a><p> |
| Transactions are critical to maintaining data integrity. They are used to group |
| operations into units of work that act in an all-or-nothing fashion. |
| Transactions have the following qualities: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <a class="indexterm" name="d0e5425"></a> |
| <a class="indexterm" name="d0e5431"></a> |
| <span class="emphasis"><em>Atomicity</em></span>. Atomicity refers to the all-or-nothing property |
| of transactions. Either every data update in the transaction completes |
| successfully, or they all fail, leaving the datastore in its original state. A |
| transaction cannot be only partially successful. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e5443"></a> |
| <a class="indexterm" name="d0e5449"></a> |
| <span class="emphasis"><em>Consistency</em></span>. Each transaction takes the datastore from one |
| consistent state to another consistent state. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e5461"></a> |
| <a class="indexterm" name="d0e5467"></a> |
| <span class="emphasis"><em>Isolation</em></span>. Transactions are isolated from each other. When |
| you are reading persistent data in one transaction, you cannot "see" the changes |
| that are being made to that data in other transactions. Similarly, the updates |
| you make in one transaction cannot conflict with updates made in concurrent |
| transactions. The form of conflict resolution employed depends on whether you |
| are using pessimistic or optimistic transactions. Both types are described later |
| in this chapter. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e5479"></a> |
| <a class="indexterm" name="d0e5485"></a> |
| <span class="emphasis"><em>Durability</em></span>. The effects of successful transactions are |
| durable; the updates made to persistent data last for the lifetime of the |
| datastore. |
| </p></li></ul></div><p> |
| <a class="indexterm" name="d0e5496"></a> |
| <a class="indexterm" name="d0e5502"></a> |
| Together, these qualities are called the ACID properties of transactions. To |
| understand why these properties are so important to maintaining data integrity, |
| consider the following example: |
| </p><p> |
| Suppose you create an application to manage bank accounts. The application |
| includes a method to transfer funds from one user to another, and it looks |
| something like this: |
| </p><pre class="programlisting"> |
| public void transferFunds(User from, User to, double amnt) { |
| from.decrementAccount(amnt); |
| to.incrementAccount(amnt); |
| } |
| </pre><p> |
| Now suppose that user Alice wants to transfer 100 dollars to user Bob. No |
| problem; you simply invoke your <code class="methodname">transferFunds</code> method, |
| supplying Alice in the <code class="literal">from</code> parameter, Bob in the <code class="literal"> |
| to</code> parameter, and <code class="literal">100.00</code> as the <code class="literal">amnt |
| </code>. The first line of the method is executed, and 100 dollars is |
| subtracted from Alice's account. But then, something goes wrong. An unexpected |
| exception occurs, or the hardware fails, and your method never completes. |
| </p><p> |
| You are left with a situation in which the 100 dollars has simply disappeared. |
| Thanks to the first line of your method, it is no longer in Alice's account, and |
| yet it was never transferred to Bob's account either. The datastore is in an |
| inconsistent state. |
| </p><p> |
| The importance of transactions should now be clear. If the two lines of the |
| <code class="methodname">transferFunds</code> method had been placed together in a |
| transaction, it would be impossible for only the first line to succeed. Either |
| the funds would be transferred properly or they would not be transferred at all, |
| and an exception would be thrown. Money could never vanish into thin air, and |
| the data store could never get into an inconsistent state. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="jpa_overview_trans_types"></a>1. |
| Transaction Types |
| </h2></div></div></div><a class="indexterm" name="d0e5539"></a><p> |
| There are two major types of transactions: pessimistic transactions and |
| optimistic transactions. Each type has both advantages and disadvantages. |
| </p><p> |
| <a class="indexterm" name="d0e5548"></a> |
| <a class="indexterm" name="d0e5554"></a> |
| <a class="indexterm" name="d0e5560"></a> |
| Pessimistic transactions generally lock the datastore records they act on, |
| preventing other concurrent transactions from using the same data. This avoids |
| conflicts between transactions, but consumes database resources. Additionally, |
| locking records can result in <span class="emphasis"><em>deadlock</em></span>, a situation in |
| which two transactions are both waiting for the other to release its locks |
| before completing. The results of a deadlock are datastore-dependent; usually |
| one transaction is forcefully rolled back after some specified timeout interval, |
| and an exception is thrown. |
| </p><p> |
| <a class="indexterm" name="d0e5571"></a> |
| <a class="indexterm" name="d0e5577"></a> |
| This document will often use the term <span class="emphasis"><em>datastore</em></span> transaction |
| in place of <span class="emphasis"><em>pessimistic</em></span> transaction. This is to acknowledge |
| that some datastores do not support pessimistic semantics, and that the exact |
| meaning of a non-optimistic JPA transaction is dependent on the datastore. Most |
| of the time, a datastore transaction is equivalent to a pessimistic transaction. |
| </p><p> |
| <a class="indexterm" name="d0e5591"></a> |
| <a class="indexterm" name="d0e5597"></a> |
| Optimistic transactions consume less resources than pessimistic/datastore |
| transactions, but only at the expense of reliability. Because optimistic |
| transactions do not lock datastore records, two transactions might change the |
| same persistent information at the same time, and the conflict will not be |
| detected until the second transaction attempts to flush or commit. At this time, |
| the second transaction will realize that another transaction has concurrently |
| modified the same records (usually through a timestamp or versioning system), |
| and will throw an appropriate exception. Note that optimistic transactions still |
| maintain data integrity; they are simply more likely to fail in heavily |
| concurrent situations. |
| </p><p> |
| Despite their drawbacks, optimistic transactions are the best choice for most |
| applications. They offer better performance, better scalability, and lower risk |
| of hanging due to deadlock. |
| </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| OpenJPA uses optimistic semantics by default, but supports both optimistic and |
| datastore transactions. OpenJPA also offers advanced locking and versioning APIs |
| for fine-grained control over database resource allocation and object |
| versioning. See <a href="#ref_guide_locking" title="3. Object Locking">Section 3, “ |
| Object Locking |
| ”</a> of the Reference Guide for |
| details on locking. <a href="#jpa_overview_meta_version" title="2.5. Version">Section 2.5, “ |
| Version |
| ”</a> |
| of this document covers standard object versioning, while |
| <a href="#ref_guide_mapping_jpa" title="7. Additional JPA Mappings">Section 7, “ |
| Additional JPA Mappings |
| ”</a> of the Reference Guide discusses |
| additional versioning strategies available in OpenJPA. |
| </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="jpa_overview_trans_local"></a>2. |
| The EntityTransaction Interface |
| </h2></div></div></div><a class="indexterm" name="d0e5617"></a><div class="mediaobject"><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="129"><tr><td><img src="img/jpa-transaction.png"></td></tr></table></div><p> |
| JPA integrates with your container's <span class="emphasis"><em>managed</em></span> transactions, |
| allowing you to use the container's declarative transaction demarcation and its |
| Java Transaction API (JTA) implementation for transaction management. Outside of |
| a container, though, you must demarcate transactions manually through JPA. The |
| <code class="classname">EntityTransaction</code> interface controls unmanaged |
| transactions in JPA. |
| </p><pre class="programlisting"> |
| public void begin(); |
| public void commit(); |
| public void rollback(); |
| </pre><p> |
| <a class="indexterm" name="d0e5638"></a> |
| <a class="indexterm" name="d0e5644"></a> |
| <a class="indexterm" name="d0e5650"></a> |
| <a class="indexterm" name="d0e5656"></a> |
| <a class="indexterm" name="d0e5662"></a> |
| The <code class="methodname">begin</code>, <code class="methodname">commit</code>, and |
| <code class="methodname">rollback</code> methods demarcate transaction boundaries. The |
| methods should be self-explanatory: <code class="methodname">begin</code> starts a |
| transaction, <code class="methodname">commit</code> attempts to commit the |
| transaction's changes to the datastore, and <code class="methodname">rollback</code> |
| aborts the transaction, in which case the datastore is "rolled back" to its |
| previous state. JPA implementations will automatically roll back transactions if |
| any exception is thrown during the commit process. |
| </p><p> |
| Unless you are using an extended persistence context, committing or rolling back |
| also ends the persistence context. All managed entites will be detached from the |
| <code class="classname">EntityManager</code>. |
| </p><pre class="programlisting"> |
| public boolean isActive(); |
| </pre><p> |
| <a class="indexterm" name="d0e5695"></a> |
| Finally, the <code class="methodname">isActive</code> method returns <code class="literal">true |
| </code> if the transaction is in progress (<code class="methodname">begin</code> |
| has been called more recently than <code class="methodname">commit</code> or |
| <code class="methodname">rollback</code>), and <code class="literal">false</code> otherwise. |
| </p><div class="example"><a name="jpa_overview_trans_group"></a><p class="title"><b>Example 9.1. |
| Grouping Operations with Transactions |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| public void transferFunds(EntityManager em, User from, User to, double amnt) { |
| // note: it would be better practice to move the transaction demarcation |
| // code out of this method, but for the purposes of example... |
| Transaction trans = em.getTransaction(); |
| trans.begin(); |
| try |
| { |
| from.decrementAccount(amnt); |
| to.incrementAccount(amnt); |
| trans.commit(); |
| } |
| catch (RuntimeException re) |
| { |
| if (trans.isActive()) |
| trans.rollback(); // or could attempt to fix error and retry |
| throw re; |
| } |
| } |
| </pre></div></div><br class="example-break"></div></div><div class="chapter" lang="en" id="jpa_overview_query"><div class="titlepage"><div><div><h2 class="title"><a name="jpa_overview_query"></a>Chapter 10. |
| JPA Query |
| </h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#jpa_query_api">1. |
| JPQL API |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_query_basic">1.1. |
| Query Basics |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_query_relations">1.2. |
| Relation Traversal |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_join_fetch">1.3. |
| Fetch Joins |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_query_functions">1.4. |
| JPQL Functions |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_query_inheritance">1.5. |
| Polymorphic Queries |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_query_params">1.6. |
| Query Parameters |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_query_hints">1.7. |
| Query Hints |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_hints_locking">1.7.1. |
| Locking Hints |
| </a></span></dt><dt><span class="section"><a href="#jpa_hints_resultset">1.7.2. |
| Result Set Size Hint |
| </a></span></dt><dt><span class="section"><a href="#jpa_hints_isolation">1.7.3. |
| Isolation Level Hint |
| </a></span></dt><dt><span class="section"><a href="#jpa_hints_fetchplan">1.7.4. |
| Other Fetchplan Hints |
| </a></span></dt><dt><span class="section"><a href="#d0e6512">1.7.5. |
| Oracle Query Hints |
| </a></span></dt><dt><span class="section"><a href="#jpa_hints_named">1.7.6. |
| Named Query Hints |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_overview_query_ordering">1.8. |
| Ordering |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_query_aggregates">1.9. |
| Aggregates |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_query_named">1.10. |
| Named Queries |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_query_delete">1.11. |
| Delete By Query |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_query_update">1.12. |
| Update By Query |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_langref">2. |
| JPQL Language Reference |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_langref_stmnttypes">2.1. |
| JPQL Statement Types |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_langref_select">2.1.1. |
| JPQL Select Statement |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_bulk">2.1.2. |
| JPQL Update and Delete Statements |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_langref_schematypes">2.2. |
| JPQL Abstract Schema Types and Query Domains |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_langref_schemanaming">2.2.1. |
| JPQL Entity Naming |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_schemaexample">2.2.2. |
| JPQL Schema Example |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_langref_fromclause">2.3. |
| JPQL FROM Clause and Navigational Declarations |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_langref_from_identifiers">2.3.1. |
| JPQL FROM Identifiers |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_from_vars">2.3.2. |
| JPQL Identification Variables |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_range">2.3.3. |
| JPQL Range Declarations |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_path">2.3.4. |
| JPQL Path Expressions |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_Joins">2.3.5. |
| JPQL Joins |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_langref_inner_joins">2.3.5.1. |
| JPQL Inner Joins (Relationship Joins) |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_outer_joins">2.3.5.2. |
| JPQL Outer Joins |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_fetch_joins">2.3.5.3. |
| JPQL Fetch Joins |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_langref_collection_dec">2.3.6. |
| JPQL Collection Member Declarations |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_polymorph">2.3.7. |
| JPQL Polymorphism |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_langref_where">2.4. |
| JPQL WHERE Clause |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_cond">2.5. |
| JPQL Conditional Expressions |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_langref_lit">2.5.1. |
| JPQL Literals |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_idvar">2.5.2. |
| JPQL Identification Variables |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_path_exp">2.5.3. |
| JPQL Path Expressions |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_input_params">2.5.4. |
| JPQL Input Parameters |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_langref_pos_params">2.5.4.1. |
| JPQL Positional Parameters |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_named_params">2.5.4.2. |
| JPQL Named Parameters |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_langref_cond_comp">2.5.5. |
| JPQL Conditional Expression Composition |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_operators">2.5.6. |
| JPQL Operators and Operator Precedence |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_between">2.5.7. |
| JPQL Between Expressions |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_in">2.5.8. |
| JPQL In Expressions |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_like">2.5.9. |
| JPQL Like Expressions |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_null">2.5.10. |
| JPQL Null Comparison Expressions |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_empty_comp">2.5.11. |
| JPQL Empty Collection Comparison Expressions |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_collection_member">2.5.12. |
| JPQL Collection Member Expressions |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_exists">2.5.13. |
| JPQL Exists Expressions |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_all_any">2.5.14. |
| JPQL All or Any Expressions |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_subqueries">2.5.15. |
| JPQL Subqueries |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_functional">2.5.16. |
| JPQL Functional Expressions |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_langref_string_fun">2.5.16.1. |
| JPQL String Functions |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_arithmetic">2.5.16.2. |
| JPQL Arithmetic Functions |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_datetime">2.5.16.3. |
| JPQL Datetime Functions |
| </a></span></dt></dl></dd></dl></dd><dt><span class="section"><a href="#jpa_langref_group">2.6. |
| JPQL GROUP BY, HAVING |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_select_clause">2.7. |
| JPQL SELECT Clause |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_langref_resulttype">2.7.1. |
| JPQL Result Type of the SELECT Clause |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_constructor">2.7.2. |
| JPQL Constructor Expressions |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_null_select">2.7.3. |
| JPQL Null Values in the Query Result |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_aggregates">2.7.4. |
| JPQL Aggregate Functions |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_langref_agg_examples">2.7.4.1. |
| JPQL Aggregate Examples |
| </a></span></dt></dl></dd></dl></dd><dt><span class="section"><a href="#jpa_langref_orderby">2.8. |
| JPQL ORDER BY Clause |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_bulk_ops">2.9. |
| JPQL Bulk Update and Delete |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_null_values">2.10. |
| JPQL Null Values |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_equality">2.11. |
| JPQL Equality and Comparison Semantics |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_bnf">2.12. |
| JPQL BNF |
| </a></span></dt></dl></dd></dl></div><a class="indexterm" name="d0e5728"></a><a class="indexterm" name="d0e5733"></a><div class="mediaobject"><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="195"><tr><td><img src="img/jpa-query.png"></td></tr></table></div><p> |
| The <code class="classname">javax.persistence.Query</code> interface is the mechanism |
| for issuing queries in JPA. The primary query language used is the Java |
| Persistence Query Language, or <code class="literal">JPQL</code>. JPQL is syntactically |
| very similar to SQL, but is object-oriented rather than table-oriented. |
| </p><p> |
| The API for executing JPQL queries will be discussed in |
| <a href="#jpa_query_api" title="1. JPQL API">Section 1, “ |
| JPQL API |
| ”</a>, and a full language reference will be |
| covered in <a href="#jpa_langref" title="2. JPQL Language Reference">Section 2, “ |
| JPQL Language Reference |
| ”</a>. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="jpa_query_api"></a>1. |
| JPQL API |
| </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#jpa_overview_query_basic">1.1. |
| Query Basics |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_query_relations">1.2. |
| Relation Traversal |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_join_fetch">1.3. |
| Fetch Joins |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_query_functions">1.4. |
| JPQL Functions |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_query_inheritance">1.5. |
| Polymorphic Queries |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_query_params">1.6. |
| Query Parameters |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_query_hints">1.7. |
| Query Hints |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_hints_locking">1.7.1. |
| Locking Hints |
| </a></span></dt><dt><span class="section"><a href="#jpa_hints_resultset">1.7.2. |
| Result Set Size Hint |
| </a></span></dt><dt><span class="section"><a href="#jpa_hints_isolation">1.7.3. |
| Isolation Level Hint |
| </a></span></dt><dt><span class="section"><a href="#jpa_hints_fetchplan">1.7.4. |
| Other Fetchplan Hints |
| </a></span></dt><dt><span class="section"><a href="#d0e6512">1.7.5. |
| Oracle Query Hints |
| </a></span></dt><dt><span class="section"><a href="#jpa_hints_named">1.7.6. |
| Named Query Hints |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_overview_query_ordering">1.8. |
| Ordering |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_query_aggregates">1.9. |
| Aggregates |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_query_named">1.10. |
| Named Queries |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_query_delete">1.11. |
| Delete By Query |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_query_update">1.12. |
| Update By Query |
| </a></span></dt></dl></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_overview_query_basic"></a>1.1. |
| Query Basics |
| </h3></div></div></div><pre class="programlisting">SELECT x FROM Magazine x |
| </pre><p> |
| The preceding is a simple JPQL query for all <code class="classname">Magazine</code> |
| entities. |
| </p><pre class="programlisting"> |
| public Query createQuery(String jpql); |
| </pre><p> |
| The |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="http://java.sun.com/javaee/5/docs/api/javax/persistence/EntityManager.html" target="_top"> |
| <code class="methodname">EntityManager.createQuery</code></a> method creates a |
| <code class="classname">Query</code> instance from a given JPQL string. |
| </p><pre class="programlisting"> |
| public List getResultList(); |
| </pre><p> |
| Invoking |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="http://java.sun.com/javaee/5/docs/api/javax/persistence/Query.html#getResultList()" target="_top"> |
| <code class="methodname">Query.getResultList</code></a> executes the query and |
| returns a <code class="classname">List</code> containing the matching objects. The |
| following example executes our <code class="classname">Magazine</code> query above: |
| </p><pre class="programlisting"> |
| EntityManager em = ... |
| Query q = em.createQuery("SELECT x FROM Magazine x"); |
| List<Magazine> results = (List<Magazine>) q.getResultList(); |
| </pre><p> |
| A JPQL query has an internal namespace declared in the <code class="literal">from</code> |
| clause of the query. Arbitrary identifiers are assigned to entities so that they |
| can be referenced elsewhere in the query. In the query example above, the |
| identifier <code class="literal">x</code> is assigned to the entity <code class="classname"> Magazine |
| </code>. |
| </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| The <code class="literal">as</code> keyword can optionally be used when declaring |
| identifiers in the <code class="literal">from</code> clause. <code class="literal">SELECT x FROM |
| Magazine x</code> and <code class="literal">SELECT x FROM Magazine AS x</code> are |
| synonymous. |
| </p></div><p> |
| Following the <code class="literal">select</code> clause of the query is the object or |
| objects that the query returns. In the case of the query above, the query's |
| result list will contain instances of the <code class="classname">Magazine</code> class. |
| </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| When selecting entities, you can optional use the keyword <code class="literal">object |
| </code>. The clauses <code class="literal">select x</code> and <code class="literal">SELECT |
| OBJECT(x)</code> are synonymous. |
| </p></div><p> |
| The optional <code class="literal">where</code> clause places criteria on matching |
| results. For example: |
| </p><pre class="programlisting">SELECT x FROM Magazine x WHERE x.title = 'JDJ'</pre><p> |
| Keywords in JPQL expressions are case-insensitive, but entity, identifier, and |
| member names are not. For example, the expression above could also be expressed |
| as: |
| </p><pre class="programlisting">select x from Magazine x where x.title = 'JDJ'</pre><p> |
| But it could not be expressed as: |
| </p><pre class="programlisting">SELECT x FROM Magazine x WHERE x.TITLE = 'JDJ'</pre><p> |
| As with the <code class="literal">select</code> clause, alias names in the <code class="literal">where |
| </code> clause are resolved to the entity declared in the <code class="literal">from |
| </code> clause. The query above could be described in English as "for all |
| <code class="classname">Magazine</code> instances <code class="literal">x</code>, return a list |
| of every <code class="literal">x</code> such that <code class="literal">x</code>'s <code class="literal">title |
| </code> field is equal to 'JDJ'". |
| </p><p> |
| JPQL uses SQL-like syntax for query criteria. The <code class="literal">and</code> and |
| <code class="literal">or</code> logical operators chain multiple criteria together: |
| </p><pre class="programlisting"> |
| SELECT x FROM Magazine x WHERE x.title = 'JDJ' OR x.title = 'JavaPro' |
| </pre><p> |
| The <code class="literal">=</code> operator tests for equality. <code class="literal"><> |
| </code> tests for inequality. JPQL also supports the following arithmetic |
| operators for numeric comparisons: <code class="literal">>, >=, <, <=</code>. |
| For example: |
| </p><pre class="programlisting"> |
| SELECT x FROM Magazine x WHERE x.price > 3.00 AND x.price <= 5.00 |
| </pre><p> |
| This query returns all magazines whose price is greater than 3.00 and less than |
| or equal to 5.00. |
| </p><pre class="programlisting"> |
| SELECT x FROM Magazine x WHERE x.price <> 3.00 |
| </pre><p> |
| This query returns all Magazines whose price is not equal to 3.00. |
| </p><p> |
| You can group expressions together using parentheses in order to specify how |
| they are evaluated. This is similar to how parentheses are used in Java. For |
| example: |
| </p><pre class="programlisting"> |
| SELECT x FROM Magazine x WHERE (x.price > 3.00 AND x.price <= 5.00) OR x.price < 7.00 |
| </pre><p> |
| This expression would match magazines whose price is less than 7.00. |
| Alternately: |
| </p><pre class="programlisting"> |
| SELECT x FROM Magazine x WHERE x.price > 3.00 AND (x.price <= 5.00 OR x.price < 7.00) |
| </pre><p> |
| This expression would match magazines whose price is 4.00, 5.00 or 6.00, but not |
| 1.00, 2.00 or 3.00. |
| </p><p> |
| JPQL also includes the following conditionals: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <a class="indexterm" name="d0e5930"></a> |
| <code class="literal">[NOT] BETWEEN</code>: Shorthand for expressing that a value falls |
| between two other values. The following two statements are synonymous: |
| </p><pre class="programlisting"> |
| SELECT x FROM Magazine x WHERE x.price >= 3.00 AND x.price <= 5.00 |
| </pre><pre class="programlisting"> |
| SELECT x FROM Magazine x WHERE x.price BETWEEN 3.00 AND 5.00 |
| </pre></li><li><p> |
| <a class="indexterm" name="d0e5944"></a> |
| <code class="literal">[NOT] LIKE</code>: Performs a string comparison with wildcard |
| support. The special character '_' in the parameter means to match any single |
| character, and the special character '%' means to match any sequence of |
| characters. The following statement matches title fields "JDJ" and "JavaPro", |
| but not "IT Insider": |
| </p><pre class="programlisting"> |
| SELECT x FROM Magazine x WHERE x.title LIKE 'J%' |
| </pre><p> |
| The following statement matches the title field "JDJ" but not "JavaPro": |
| </p><pre class="programlisting"> |
| SELECT x FROM Magazine x WHERE x.title LIKE 'J__' |
| </pre></li><li><p> |
| <a class="indexterm" name="d0e5960"></a> |
| <code class="literal">[NOT] IN</code>: Specifies that the member must be equal to one |
| element of the provided list. The following two statements are synonymous: |
| </p><pre class="programlisting"> |
| SELECT x FROM Magazine x WHERE x.title IN ('JDJ', 'JavaPro', 'IT Insider') |
| </pre><pre class="programlisting">SELECT x FROM Magazine x WHERE x.title = 'JDJ' OR x.title = 'JavaPro' OR x.title = 'IT Insider' |
| </pre></li><li><p> |
| <a class="indexterm" name="d0e5974"></a> |
| <code class="literal">IS [NOT] EMPTY</code>: Specifies that the collection field holds no |
| elements. For example: |
| </p><pre class="programlisting"> |
| SELECT x FROM Magazine x WHERE x.articles is empty |
| </pre><p> |
| This statement will return all magazines whose <code class="literal"> articles</code> |
| member contains no elements. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e5991"></a> |
| <code class="literal">IS [NOT] NULL</code>: Specifies that the field is equal to null. |
| For example: |
| </p><pre class="programlisting"> |
| SELECT x FROM Magazine x WHERE x.publisher is null |
| </pre><p> |
| This statement will return all Magazine instances whose "publisher" field is set |
| to <code class="literal">null</code>. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e6008"></a> |
| <code class="literal">NOT</code>: Negates the contained expression. For example, the |
| following two statements are synonymous: |
| </p><pre class="programlisting"> |
| SELECT x FROM Magazine x WHERE NOT(x.price = 10.0) |
| </pre><pre class="programlisting"> |
| SELECT x FROM Magazine x WHERE x.price <> 10.0 |
| </pre></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_overview_query_relations"></a>1.2. |
| Relation Traversal |
| </h3></div></div></div><p> |
| Relations between objects can be traversed using Java-like syntax. For example, |
| if the Magazine class has a field named "publisher" of type Company, that |
| relation can be queried as follows: |
| </p><pre class="programlisting"> |
| SELECT x FROM Magazine x WHERE x.publisher.name = 'Random House' |
| </pre><p> |
| This query returns all <code class="classname">Magazine</code> instances whose <code class="literal"> |
| publisher</code> field is set to a <code class="classname">Company</code> instance |
| whose name is "Random House". |
| </p><p> |
| Single-valued relation traversal implies that the relation is not null. In SQL |
| terms, this is known as an <span class="emphasis"><em>inner join</em></span>. If you want to also |
| include relations that are null, you can specify: |
| </p><pre class="programlisting"> |
| SELECT x FROM Magazine x WHERE x.publisher.name = 'Random House' or x.publisher is null |
| </pre><p> |
| You can also traverse collection fields in queries, but you must declare each |
| traversal in the <code class="literal">from</code> clause. Consider: |
| </p><pre class="programlisting"> |
| SELECT x FROM Magazine x, IN(x.articles) y WHERE y.authorName = 'John Doe' |
| </pre><p> |
| This query says that for each <code class="classname">Magazine</code><code class="literal"> x |
| </code>, traverse the <code class="literal">articles</code> relation and check each |
| <code class="classname">Article</code> <code class="literal">y</code>, and pass the filter if |
| <code class="literal">y</code>'s <code class="literal">authorName</code> field is equal to "John |
| Doe". In short, this query will return all magazines that have any articles |
| written by John Doe. |
| </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| The <code class="literal">IN()</code> syntax can also be expressed with the keywords |
| <code class="literal">inner join</code>. The statements <code class="literal">SELECT x FROM Magazine |
| x, IN(x.articles) y WHERE y.authorName = 'John Doe'</code> and <code class="literal"> |
| SELECT x FROM Magazine x inner join x.articles y WHERE y.authorName = 'John Doe' |
| </code> are synonymous. |
| </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_overview_join_fetch"></a>1.3. |
| Fetch Joins |
| </h3></div></div></div><p> |
| JPQL queries may specify one or more <code class="literal">join fetch</code> declarations, |
| which allow the query to specify which fields in the returned instances will be |
| pre-fetched. |
| </p><pre class="programlisting"> |
| SELECT x FROM Magazine x join fetch x.articles WHERE x.title = 'JDJ' |
| </pre><p> |
| The query above returns <code class="classname">Magazine</code> instances and guarantees |
| that the <code class="literal">articles</code> field will already be fetched in the |
| returned instances. |
| </p><p> |
| Multiple fields may be specified in separate <code class="literal">join fetch</code> |
| declarations: </p><pre class="programlisting"> |
| SELECT x FROM Magazine x join fetch x.articles join fetch x.authors WHERE x.title = 'JDJ' |
| </pre><p> |
| </p><p> |
| </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> Specifying the <code class="literal">join fetch</code> declaration is |
| functionally equivalent to adding the fields to the Query's <code class="classname"> |
| FetchConfiguration</code>. See <a href="#ref_guide_fetch" title="7. Fetch Groups">Section 7, “ |
| Fetch Groups |
| ”</a>. |
| </p></div><p> |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_overview_query_functions"></a>1.4. |
| JPQL Functions |
| </h3></div></div></div><p> |
| As well as supporting direct field and relation comparisons, JPQL supports a |
| pre-defined set of functions that you can apply. |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <a class="indexterm" name="d0e6137"></a> |
| <code class="literal">CONCAT(string1, string2)</code>: Concatenates two string fields or |
| literals. For example: |
| </p><pre class="programlisting"> |
| SELECT x FROM Magazine x WHERE CONCAT(x.title, 's') = 'JDJs' |
| </pre></li><li><p> |
| <a class="indexterm" name="d0e6149"></a> |
| <code class="literal">SUBSTRING(string, startIndex, length)</code>: Returns the part of |
| the <code class="literal">string</code> argument starting at <code class="literal">startIndex</code> |
| (1-based) and ending at <code class="literal">length</code> characters past <code class="literal"> |
| startIndex</code>. |
| </p><pre class="programlisting"> |
| SELECT x FROM Magazine x WHERE SUBSTRING(x.title, 1, 1) = 'J' |
| </pre></li><li><p> |
| <a class="indexterm" name="d0e6173"></a> |
| <code class="literal">TRIM([LEADING | TRAILING | BOTH] [character FROM] string</code>: |
| Trims the specified character from either the beginning ( <code class="literal">LEADING |
| </code>) end ( <code class="literal">TRAILING</code>) or both ( <code class="literal"> BOTH |
| </code>) of the string argument. If no trim character is specified, the |
| space character will be trimmed. |
| </p><pre class="programlisting"> |
| SELECT x FROM Magazine x WHERE TRIM(BOTH 'J' FROM x.title) = 'D' |
| </pre></li><li><p> |
| <a class="indexterm" name="d0e6194"></a> |
| <code class="literal">LOWER(string)</code>: Returns the lower-case of the specified |
| string argument. |
| </p><pre class="programlisting"> |
| SELECT x FROM Magazine x WHERE LOWER(x.title) = 'jdj' |
| </pre></li><li><p> |
| <a class="indexterm" name="d0e6206"></a> |
| <code class="literal">UPPER(string)</code>: Returns the upper-case of the specified |
| string argument. |
| </p><pre class="programlisting"> |
| SELECT x FROM Magazine x WHERE UPPER(x.title) = 'JAVAPRO' |
| </pre></li><li><p> |
| <a class="indexterm" name="d0e6218"></a> |
| <code class="literal">LENGTH(string)</code>: Returns the number of characters in the |
| specified string argument. |
| </p><pre class="programlisting"> |
| SELECT x FROM Magazine x WHERE LENGTH(x.title) = 3 |
| </pre></li><li><p> |
| <a class="indexterm" name="d0e6230"></a> |
| <code class="literal">LOCATE(searchString, candidateString [, startIndex])</code>: |
| Returns the first index of <code class="literal">searchString</code> in <code class="literal"> |
| candidateString</code>. Positions are 1-based. If the string is not found, |
| returns 0. |
| </p><pre class="programlisting"> |
| SELECT x FROM Magazine x WHERE LOCATE('D', x.title) = 2 |
| </pre></li><li><p> |
| <a class="indexterm" name="d0e6248"></a> |
| <code class="literal">ABS(number)</code>: Returns the absolute value of the argument. |
| </p><pre class="programlisting"> |
| SELECT x FROM Magazine x WHERE ABS(x.price) >= 5.00 |
| </pre></li><li><p> |
| <a class="indexterm" name="d0e6260"></a> |
| <code class="literal">SQRT(number)</code>: Returns the square root of the argument. |
| </p><pre class="programlisting"> |
| SELECT x FROM Magazine x WHERE SQRT(x.price) >= 1.00 |
| </pre></li><li><p> |
| <a class="indexterm" name="d0e6272"></a> |
| <code class="literal">MOD(number, divisor)</code>: Returns the modulo of <code class="literal">number |
| </code> and <code class="literal">divisor</code>. |
| </p><pre class="programlisting"> |
| SELECT x FROM Magazine x WHERE MOD(x.price, 10) = 0 |
| </pre></li><li><p> |
| <a class="indexterm" name="d0e6290"></a> |
| <code class="literal">CURRENT_DATE</code>: Returns the current date. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e6300"></a> |
| <code class="literal">CURRENT_TIME</code>: Returns the current time. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e6310"></a> |
| <code class="literal">CURRENT_TIMESTAMP</code>: Returns the current timestamp. |
| </p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_overview_query_inheritance"></a>1.5. |
| Polymorphic Queries |
| </h3></div></div></div><p> |
| All JPQL queries are polymorphic, which means the <code class="literal">from</code> clause |
| of a query includes not only instances of the specific entity class to which it |
| refers, but all subclasses of that class as well. The instances returned by a |
| query include instances of the subclasses that satisfy the query conditions. For |
| example, the following query may return instances of <code class="classname"> Magazine |
| </code>, as well as <code class="classname">Tabloid</code> and <code class="classname">Digest |
| </code> instances, where <code class="classname">Tabloid</code> and <code class="classname"> |
| Digest</code> are <code class="classname">Magazine</code> subclasses. |
| </p><pre class="programlisting">SELECT x FROM Magazine x WHERE x.price < 5</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_overview_query_params"></a>1.6. |
| Query Parameters |
| </h3></div></div></div><p> |
| JPQL provides support for parameterized queries. Either named parameters or |
| positional parameters may be specified in the query string. Parameters allow you |
| to re-use query templates where only the input parameters vary. A single query |
| can declare either named parameters or positional parameters, but is not allowed |
| to declare both named and positional parameters. |
| </p><pre class="programlisting"> |
| public Query setParameter (int pos, Object value); |
| </pre><p> |
| Specify positional parameters in your JPQL string using an integer prefixed by a |
| question mark. You can then populate the <code class="classname">Query</code> object |
| with positional parameter values via calls to the <code class="methodname">setParameter |
| </code> method above. The method returns the <code class="classname">Query</code> |
| instance for optional method chaining. |
| </p><pre class="programlisting"> |
| EntityManager em = ... |
| Query q = em.createQuery("SELECT x FROM Magazine x WHERE x.title = ?1 and x.price > ?2"); |
| q.setParameter(1, "JDJ").setParameter(2, 5.0); |
| List<Magazine> results = (List<Magazine>) q.getResultList(); |
| </pre><p> |
| This code will substitute <code class="literal">JDJ</code> for the <code class="literal">?1</code> |
| parameter and <code class="literal">5.0</code> for the <code class="literal">?2</code> parameter, |
| then execute the query with those values. |
| </p><pre class="programlisting"> |
| public Query setParameter(String name, Object value); |
| </pre><p> |
| Named parameter are denoted by prefixing an arbitrary name with a colon in your |
| JPQL string. You can then populate the <code class="classname"> Query</code> object with |
| parameter values using the method above. Like the positional parameter method, |
| this method returns the <code class="classname">Query</code> instance for optional |
| method chaining. |
| </p><pre class="programlisting"> |
| EntityManager em = ... |
| Query q = em.createQuery("SELECT x FROM Magazine x WHERE x.title = :titleParam and x.price > :priceParam"); |
| q.setParameter("titleParam", "JDJ").setParameter("priceParam", 5.0); |
| List<Magazine> results = (List<Magazine>) q.getResultList(); |
| </pre><p> |
| This code substitutes <code class="literal">JDJ</code> for the <code class="literal"> :titleParam |
| </code> parameter and <code class="literal">5.0</code> for the <code class="literal">:priceParam |
| </code> parameter, then executes the query with those values. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_overview_query_hints"></a>1.7. |
| Query Hints |
| </h3></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#jpa_hints_locking">1.7.1. |
| Locking Hints |
| </a></span></dt><dt><span class="section"><a href="#jpa_hints_resultset">1.7.2. |
| Result Set Size Hint |
| </a></span></dt><dt><span class="section"><a href="#jpa_hints_isolation">1.7.3. |
| Isolation Level Hint |
| </a></span></dt><dt><span class="section"><a href="#jpa_hints_fetchplan">1.7.4. |
| Other Fetchplan Hints |
| </a></span></dt><dt><span class="section"><a href="#d0e6512">1.7.5. |
| Oracle Query Hints |
| </a></span></dt><dt><span class="section"><a href="#jpa_hints_named">1.7.6. |
| Named Query Hints |
| </a></span></dt></dl></div><p> |
| JPQL provides support for hints which are name/value pairs used to control locking and optimization keywords in sql. |
| The following example shows how to use the JPA hint api to set the <code class="classname">ReadLockMode</code> and <code class="classname">ResultCount</code> in the OpenJPA fetch plan. This will result in the sql keywords OPTIMIZE FOR 2 ROWS and UPDATE to be emitted into the sql provided that a pessimistic LockManager is being used. |
| </p><div class="example"><a name="jpa_query_hint1"></a><p class="title"><b>Example 10.1. |
| Query Hints |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| ... |
| Query q = em.createQuery("select m from Magazine m where ... "); |
| q.setHint("openjpa.hint.OptimizeResultCount", new Integer(2)); |
| q.setHint("openjpa.FetchPlan.ReadLockMode","WRITE"); |
| List r = q.getResultList(); |
| ... |
| </pre></div></div><br class="example-break"><p> |
| Invalid hints or hints which can not be processed by a particular database are ignored. Otherwise, invalid hints will result in an ArgumentException being thrown. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="jpa_hints_locking"></a>1.7.1. |
| Locking Hints |
| </h4></div></div></div><p> |
| To avoid deadlock and optimistic update exceptions among multiple updaters, use a pessimistic LockManager, specified in the persistence unit definition, and use a hint name of "openjpa.FetchPlan.ReadLockMode" on queries for entities that must be locked for serialization. The value of <code class="classname">ReadLockMode</code> can be either "READ" or "WRITE". This results in FOR UPDATE or USE AND KEEP UPDATE LOCKS in sql. |
| </p><p> |
| Using a <code class="classname">ReadLockMode</code> hint with JPA optimistic locking ( i.e. specifying LockManager = "version") will result in the entity version field either being reread at end of transaction in the case of a value of "READ" or the version field updated at end of transaction in the case of "WRITE". You must define a version field in the entity mapping when using a version LockManager and using ReadLockMode. |
| </p><div class="table"><a name="d0e6436"></a><p class="title"><b>Table 10.1. |
| Interaction of ReadLockMode hint and LockManager |
| </b></p><div class="table-contents"><table summary="
 Interaction of ReadLockMode hint and LockManager
 " border="1"><colgroup><col align="left"><col align="left"><col align="left"></colgroup><thead><tr><th align="left"> |
| ReadLockMode |
| </th><th align="left"> |
| LockManager=pessimistic |
| </th><th align="left"> |
| LockManager=version |
| </th></tr></thead><tbody><tr><td align="left"> |
| READ |
| </td><td align="left"> |
| sql with UPDATE |
| </td><td align="left">sql without update; |
| <p> |
| reread version field at the end of transaction and check for no change. |
| </p> |
| </td></tr><tr><td align="left"> |
| WRITE |
| </td><td align="left"> |
| sql with UPDATE |
| </td><td align="left"> |
| sql without update; |
| <p> |
| force update version field at the end of transaction |
| </p> |
| </td></tr><tr><td align="left"> |
| not specified |
| </td><td align="left"> |
| sql without update |
| </td><td align="left"> |
| sql without update |
| </td></tr></tbody></table></div></div><br class="table-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="jpa_hints_resultset"></a>1.7.2. |
| Result Set Size Hint |
| </h4></div></div></div><p> |
| To specify a result set size hint to those databases that support it, specify a hint name of "openjpa.hint.OptimizeResultCount" with an integer value greater than zero. This causes the sql keyword OPTIMIZE FOR to be generated. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="jpa_hints_isolation"></a>1.7.3. |
| Isolation Level Hint |
| </h4></div></div></div><p> |
| To specify an isolation level, specify a hint name of "openjpa.FetchPlan.Isolation". The value will be used to specify isolation level using the sql WITH <isolation> clause for those databases that support it. This hint only works in conjunction with the ReadLockMode hint. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="jpa_hints_fetchplan"></a>1.7.4. |
| Other Fetchplan Hints |
| </h4></div></div></div><p> |
| Any property of an OpenJPA FetchPlan can be changed using a hint by using a name of the form "openjpa.FetchPlan."<property name>.Valid property names include : |
| <code class="classname">MaxFetchDepth</code>, <code class="classname">FetchBatchSize</code>, <code class="classname">LockTimeOut</code>, <code class="classname">EagerFetchMode</code>, <code class="classname">SubclassFetchMode</code> and <code class="classname">Isolation</code>. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e6512"></a>1.7.5. |
| Oracle Query Hints |
| </h4></div></div></div><p> |
| The hint name "openjpa.hint.OracleSelectHint" can be used to specify a string value of an Oracle query hint that will inserted into sql for an Oracle database.See <a href="#dbsupport_oracle_query_hints" title="15.1. Using Query Hints with Oracle">Section 15.1, “ |
| Using Query Hints with Oracle |
| ”</a> for an example. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="jpa_hints_named"></a>1.7.6. |
| Named Query Hints |
| </h4></div></div></div><p> |
| Hints can also be included as part of a NamedQuery definition. |
| </p><div class="example"><a name="jpa_query_hint2"></a><p class="title"><b>Example 10.2. |
| Named Query using Hints |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| ... |
| @NamedQuery(name=" magsOverPrice", |
| query="SELECT x FROM Magazine x WHERE x.price > ?1", |
| hints={ @QueryHint (name="openjpa.hint.OptimizeResultCount", value="2"), |
| @QueryHint (name="openjpa.FetchPlan.ReadLockMode",value="WRITE")} ) |
| ... |
| </pre></div></div><br class="example-break"></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_overview_query_ordering"></a>1.8. |
| Ordering |
| </h3></div></div></div><p> |
| JPQL queries may optionally contain an <code class="literal">order by</code> clause which |
| specifies one or more fields to order by when returning query results. You may |
| follow the <code class="literal">order by field</code> clause with the <code class="literal">asc |
| </code> or <code class="literal">desc</code> keywords, which indicate that ordering |
| should be ascending or descending, respectively. If the direction is omitted, |
| ordering is ascending by default. |
| </p><pre class="programlisting"> |
| SELECT x FROM Magazine x order by x.title asc, x.price desc |
| </pre><p> |
| The query above returns <code class="classname">Magazine</code> instances sorted by |
| their title in ascending order. In cases where the titles of two or more |
| magazines are the same, those instances will be sorted by price in descending |
| order. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_overview_query_aggregates"></a>1.9. |
| Aggregates |
| </h3></div></div></div><p> |
| JPQL queries can select aggregate data as well as objects. JPQL includes the |
| <code class="literal">min</code>, <code class="literal">max</code>, <code class="literal">avg</code>, and |
| <code class="literal">count</code> aggregates. These functions can be used for reporting |
| and summary queries. |
| </p><p> |
| The following query will return the average of all the prices of all the |
| magazines: |
| </p><pre class="programlisting"> |
| EntityManager em = ... |
| Query q = em.createQuery("SELECT AVG(x.price) FROM Magazine x"); |
| Number result = (Number) q.getSingleResult(); |
| </pre><p> |
| The following query will return the highest price of all the magazines titled |
| "JDJ": |
| </p><pre class="programlisting"> |
| EntityManager em = ... |
| Query q = em.createQuery("SELECT MAX(x.price) FROM Magazine x WHERE x.title = 'JDJ'"); |
| Number result = (Number) q.getSingleResult(); |
| </pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_overview_query_named"></a>1.10. |
| Named Queries |
| </h3></div></div></div><p> |
| Query templates can be statically declared using the <code class="literal"> NamedQuery |
| </code> and <code class="literal">NamedQueries</code> annotations. For example: |
| </p><pre class="programlisting"> |
| @Entity |
| @NamedQueries({ |
| @NamedQuery(name="magsOverPrice", |
| query="SELECT x FROM Magazine x WHERE x.price > ?1"), |
| @NamedQuery(name="magsByTitle", |
| query="SELECT x FROM Magazine x WHERE x.title = :titleParam") |
| }) |
| public class Magazine { |
| ... |
| } |
| </pre><p> |
| These declarations will define two named queries called <code class="literal">magsOverPrice |
| </code> and <code class="literal">magsByTitle</code>. |
| </p><pre class="programlisting"> |
| public Query createNamedQuery(String name); |
| </pre><p> |
| You retrieve named queries with the above <code class="classname">EntityManager</code> |
| method. For example: |
| </p><pre class="programlisting"> |
| EntityManager em = ... |
| Query q = em.createNamedQuery("magsOverPrice"); |
| q.setParameter(1, 5.0f); |
| List<Magazine> results = (List<Magazine>) q.getResultList(); |
| </pre><pre class="programlisting"> |
| EntityManager em = ... |
| Query q = em.createNamedQuery("magsByTitle"); |
| q.setParameter("titleParam", "JDJ"); |
| List<Magazine> results = (List<Magazine>) q.getResultList(); |
| </pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_overview_query_delete"></a>1.11. |
| Delete By Query |
| </h3></div></div></div><p> |
| Queries are useful not only for finding objects, but for efficiently deleting |
| them as well. For example, you might delete all records created before a certain |
| date. Rather than bring these objects into memory and delete them individually, |
| JPA allows you to perform a single bulk delete based on JPQL criteria. |
| </p><p> |
| Delete by query uses the same JPQL syntax as normal queries, with one exception: |
| begin your query string with the <code class="literal">delete</code> keyword instead of |
| the <code class="literal">select</code> keyword. To then execute the delete, you call the |
| following <code class="classname">Query</code> method: |
| </p><pre class="programlisting"> |
| public int executeUpdate(); |
| </pre><p> |
| This method returns the number of objects deleted. The following example deletes |
| all subscriptions whose expiration date has passed. |
| </p><div class="example"><a name="jpa_overview_query_deleteex"></a><p class="title"><b>Example 10.3. |
| Delete by Query |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| Query q = em.createQuery("DELETE FROM Subscription s WHERE s.subscriptionDate < :today"); |
| q.setParameter("today", new Date()); |
| int deleted = q.executeUpdate(); |
| </pre></div></div><br class="example-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_overview_query_update"></a>1.12. |
| Update By Query |
| </h3></div></div></div><p> |
| Similar to bulk deletes, it is sometimes necessary to perform updates against a |
| large number of queries in a single operation, without having to bring all the |
| instances down to the client. Rather than bring these objects into memory and |
| modifying them individually, JPA allows you to perform a single bulk update |
| based on JPQL criteria. |
| </p><p> |
| Update by query uses the same JPQL syntax as normal queries, except that the |
| query string begins with the <code class="literal">update</code> keyword instead of |
| <code class="literal">select</code>. To execute the update, you call the following |
| <code class="classname">Query</code> method: |
| </p><pre class="programlisting"> |
| public int executeUpdate(); |
| </pre><p> |
| This method returns the number of objects updated. The following example updates |
| all subscriptions whose expiration date has passed to have the "paid" field set |
| to true.. |
| </p><div class="example"><a name="jpa_overview_query_updateex"></a><p class="title"><b>Example 10.4. |
| Update by Query |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| Query q = em.createQuery("UPDATE Subscription s SET s.paid = :paid WHERE s.subscriptionDate < :today"); |
| q.setParameter("today", new Date()); |
| q.setParameter("paid", true); |
| int updated = q.executeUpdate(); |
| </pre></div></div><br class="example-break"></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="jpa_langref"></a>2. |
| JPQL Language Reference |
| </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#jpa_langref_stmnttypes">2.1. |
| JPQL Statement Types |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_langref_select">2.1.1. |
| JPQL Select Statement |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_bulk">2.1.2. |
| JPQL Update and Delete Statements |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_langref_schematypes">2.2. |
| JPQL Abstract Schema Types and Query Domains |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_langref_schemanaming">2.2.1. |
| JPQL Entity Naming |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_schemaexample">2.2.2. |
| JPQL Schema Example |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_langref_fromclause">2.3. |
| JPQL FROM Clause and Navigational Declarations |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_langref_from_identifiers">2.3.1. |
| JPQL FROM Identifiers |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_from_vars">2.3.2. |
| JPQL Identification Variables |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_range">2.3.3. |
| JPQL Range Declarations |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_path">2.3.4. |
| JPQL Path Expressions |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_Joins">2.3.5. |
| JPQL Joins |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_langref_inner_joins">2.3.5.1. |
| JPQL Inner Joins (Relationship Joins) |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_outer_joins">2.3.5.2. |
| JPQL Outer Joins |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_fetch_joins">2.3.5.3. |
| JPQL Fetch Joins |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_langref_collection_dec">2.3.6. |
| JPQL Collection Member Declarations |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_polymorph">2.3.7. |
| JPQL Polymorphism |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_langref_where">2.4. |
| JPQL WHERE Clause |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_cond">2.5. |
| JPQL Conditional Expressions |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_langref_lit">2.5.1. |
| JPQL Literals |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_idvar">2.5.2. |
| JPQL Identification Variables |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_path_exp">2.5.3. |
| JPQL Path Expressions |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_input_params">2.5.4. |
| JPQL Input Parameters |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_langref_pos_params">2.5.4.1. |
| JPQL Positional Parameters |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_named_params">2.5.4.2. |
| JPQL Named Parameters |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_langref_cond_comp">2.5.5. |
| JPQL Conditional Expression Composition |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_operators">2.5.6. |
| JPQL Operators and Operator Precedence |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_between">2.5.7. |
| JPQL Between Expressions |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_in">2.5.8. |
| JPQL In Expressions |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_like">2.5.9. |
| JPQL Like Expressions |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_null">2.5.10. |
| JPQL Null Comparison Expressions |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_empty_comp">2.5.11. |
| JPQL Empty Collection Comparison Expressions |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_collection_member">2.5.12. |
| JPQL Collection Member Expressions |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_exists">2.5.13. |
| JPQL Exists Expressions |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_all_any">2.5.14. |
| JPQL All or Any Expressions |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_subqueries">2.5.15. |
| JPQL Subqueries |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_functional">2.5.16. |
| JPQL Functional Expressions |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_langref_string_fun">2.5.16.1. |
| JPQL String Functions |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_arithmetic">2.5.16.2. |
| JPQL Arithmetic Functions |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_datetime">2.5.16.3. |
| JPQL Datetime Functions |
| </a></span></dt></dl></dd></dl></dd><dt><span class="section"><a href="#jpa_langref_group">2.6. |
| JPQL GROUP BY, HAVING |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_select_clause">2.7. |
| JPQL SELECT Clause |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_langref_resulttype">2.7.1. |
| JPQL Result Type of the SELECT Clause |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_constructor">2.7.2. |
| JPQL Constructor Expressions |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_null_select">2.7.3. |
| JPQL Null Values in the Query Result |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_aggregates">2.7.4. |
| JPQL Aggregate Functions |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_langref_agg_examples">2.7.4.1. |
| JPQL Aggregate Examples |
| </a></span></dt></dl></dd></dl></dd><dt><span class="section"><a href="#jpa_langref_orderby">2.8. |
| JPQL ORDER BY Clause |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_bulk_ops">2.9. |
| JPQL Bulk Update and Delete |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_null_values">2.10. |
| JPQL Null Values |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_equality">2.11. |
| JPQL Equality and Comparison Semantics |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_bnf">2.12. |
| JPQL BNF |
| </a></span></dt></dl></div><p> |
| The Java Persistence Query Language (JPQL) is used to define searches against |
| persistent entities independent of the mechanism used to store those entities. |
| As such, JPQL is "portable", and not constrained to any particular data store. |
| The Java Persistence query language is an extension of the Enterprise JavaBeans |
| query language, <code class="literal">EJB QL</code>, adding operations such as bulk |
| deletes and updates, join operations, aggregates, projections, and subqueries. |
| Furthermore, JPQL queries can be declared statically in metadata, or can be |
| dynamically built in code. This chapter provides the full definition of the |
| language. |
| </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| Much of this section is paraphrased or taken directly from Chapter 4 of the |
| JSR 220 specification. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_langref_stmnttypes"></a>2.1. |
| JPQL Statement Types |
| </h3></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#jpa_langref_select">2.1.1. |
| JPQL Select Statement |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_bulk">2.1.2. |
| JPQL Update and Delete Statements |
| </a></span></dt></dl></div><p> |
| A JPQL statement may be either a <code class="literal">SELECT</code> statement, an |
| <code class="literal">UPDATE</code> statement, or a <code class="literal">DELETE</code> statement. |
| This chapter refers to all such statements as "queries". Where it is important |
| to distinguish among statement types, the specific statement type is referenced. |
| In BNF syntax, a query language statement is defined as: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| QL_statement ::= select_statement | update_statement | delete_statement |
| </p></li></ul></div><p> |
| The complete BNF for JPQL is defined in <a href="#jpa_langref_bnf" title="2.12. JPQL BNF">Section 2.12, “ |
| JPQL BNF |
| ”</a>. |
| Any JPQL statement may be constructed dynamically or may be statically defined |
| in a metadata annotation or XML descriptor element. All statement types may |
| have parameters, as discussed in <a href="#jpa_langref_input_params" title="2.5.4. JPQL Input Parameters">Section 2.5.4, “ |
| JPQL Input Parameters |
| ”</a>. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="jpa_langref_select"></a>2.1.1. |
| JPQL Select Statement |
| </h4></div></div></div><p> |
| A select statement is a string which consists of the following clauses: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| a <code class="literal">SELECT</code> clause, which determines the type of the objects |
| or values to be selected. |
| </p></li><li><p> |
| a <code class="literal">FROM</code> clause, which provides declarations that designate the |
| domain to which the expressions specified in the other clauses of the query |
| apply. |
| </p></li><li><p> |
| an optional <code class="literal">WHERE</code> clause, which may be used to restrict the |
| results that are returned by the query. |
| </p></li><li><p> |
| an optional <code class="literal">GROUP BY</code> clause, which allows query results to be |
| aggregated in terms of groups. |
| </p></li><li><p> |
| an optional <code class="literal">HAVING</code> clause, which allows filtering over |
| aggregated groups. |
| </p></li><li><p> |
| an optional <code class="literal">ORDER BY</code> clause, which may be used to order the |
| results that are returned by the query. |
| </p></li></ul></div><p> |
| In BNF syntax, a select statement is defined as: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| select_statement ::= select_clause from_clause [where_clause] [groupby_clause] |
| [having_clause] [orderby_clause] |
| </p></li></ul></div><p> |
| A select statement must always have a <code class="literal">SELECT</code> and a |
| <code class="literal">FROM</code> clause. The square brackets [] indicate that the other |
| clauses are optional. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="jpa_langref_bulk"></a>2.1.2. |
| JPQL Update and Delete Statements |
| </h4></div></div></div><p> |
| Update and delete statements provide bulk operations over sets of entities. In |
| BNF syntax, these operations are defined as: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| update_statement ::= update_clause [where_clause] |
| </p></li><li><p> |
| delete_statement ::= delete_clause [where_clause] |
| </p></li></ul></div><p> |
| The update and delete clauses determine the type of the entities to be updated |
| or deleted. The <code class="literal">WHERE</code> clause may be used to restrict the |
| scope of the update or delete operation. Update and delete statements are |
| described further in <a href="#jpa_langref_bulk_ops" title="2.9. JPQL Bulk Update and Delete">Section 2.9, “ |
| JPQL Bulk Update and Delete |
| ”</a>. |
| </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_langref_schematypes"></a>2.2. |
| JPQL Abstract Schema Types and Query Domains |
| </h3></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#jpa_langref_schemanaming">2.2.1. |
| JPQL Entity Naming |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_schemaexample">2.2.2. |
| JPQL Schema Example |
| </a></span></dt></dl></div><p> |
| The Java Persistence query language is a typed language, and every expression |
| has a type. The type of an expression is derived from the structure of the |
| expression, the abstract schema types of the identification variable |
| declarations, the types to which the persistent fields and relationships |
| evaluate, and the types of literals. The abstract schema type of an entity is |
| derived from the entity class and the metadata information provided by Java |
| language annotations or in the XML descriptor. |
| </p><p> |
| Informally, the abstract schema type of an entity can be characterized as |
| follows: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| For every persistent field or get |
| accessor method (for a persistent property) of the entity class, there is a |
| field ("state-field") whose abstract schema type corresponds to that of the |
| field or the result type of the accessor method. |
| </p></li><li><p> |
| For every persistent relationship field or get accessor method (for a persistent |
| relationship property) of the entity class, there is a field |
| ("association-field") whose type is the abstract schema type of the related |
| entity (or, if the relationship is a one-to-many or many-to-many, a collection |
| of such). Abstract schema types are specific to the query language data model. |
| The persistence provider is not required to implement or otherwise materialize |
| an abstract schema type. The domain of a query consists of the abstract schema |
| types of all entities that are defined in the same persistence unit. The domain |
| of a query may be restricted by the navigability of the relationships of the |
| entity on which it is based. The association-fields of an entity's abstract |
| schema type determine navigability. Using the association-fields and their |
| values, a query can select related entities and use their abstract schema types |
| in the query. |
| </p></li></ul></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="jpa_langref_schemanaming"></a>2.2.1. |
| JPQL Entity Naming |
| </h4></div></div></div><p> |
| Entities are designated in query strings by their entity names. The entity name |
| is defined by the name element of the Entity annotation (or the entity-name XML |
| descriptor element), and defaults to the unqualified name of the entity class. |
| Entity names are scoped within the persistence unit and must be unique within |
| the persistence unit. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="jpa_langref_schemaexample"></a>2.2.2. |
| JPQL Schema Example |
| </h4></div></div></div><p> |
| This example assumes that the application developer provides several entity |
| classes, representing magazines, publishers, authors, and articles. The abstract |
| schema types for these entities are <code class="literal">Magazine</code>, <code class="literal"> |
| Publisher</code>, <code class="literal">Author</code>, and <code class="literal">Article</code>. |
| </p><p> |
| Several Entities with Abstract Persistence Schemas Defined in the Same |
| Persistence Unit. The entity <code class="literal">Publisher</code> has a one-to-many |
| relationships with <code class="literal">Magazine</code>. There is also a one-to-many |
| relationship between <code class="literal">Magazine</code> and <code class="literal">Article</code> |
| . The entity <code class="literal">Article</code> is related to <code class="literal">Author</code> |
| in a one-to-one relationship. |
| </p><p> |
| Queries to select magazines can be defined by navigating over the |
| association-fields and state-fields defined by Magazine and Author. A query to |
| find all magazines that have unpublished articles is as follows: |
| </p><pre class="programlisting"> |
| SELECT DISTINCT mag FROM Magazine AS mag JOIN mag.articles AS art WHERE art.published = FALSE |
| </pre><p> |
| This query navigates over the association-field authors of the |
| abstract schema type <code class="literal">Magazine</code> to find articles, and uses the |
| state-field <code class="literal">published</code> of <code class="literal">Article</code> to select |
| those magazines that have at least one article that is published. Although |
| predefined reserved identifiers, such as <code class="literal">DISTINCT</code>, <code class="literal"> |
| FROM</code>, <code class="literal">AS</code>, <code class="literal">JOIN</code>, <code class="literal"> |
| WHERE</code>, and <code class="literal">FALSE</code> appear in upper case in this |
| example, predefined reserved identifiers are case insensitive. The <code class="literal"> |
| SELECT</code> clause of this example designates the return type of this |
| query to be of type Magazine. Because the same persistence unit defines the |
| abstract persistence schemas of the related entities, the developer can also |
| specify a query over <code class="literal">articles</code> that utilizes the abstract |
| schema type for products, and hence the state-fields and association-fields of |
| both the abstract schema types Magazine and Author. For example, if the |
| abstract schema type Author has a state-field named firstName, a query over |
| articles can be specified using this state-field. Such a query might be to |
| find all magazines that have articles authored by someone with the first name |
| "John". |
| </p><pre class="programlisting"> |
| SELECT DISTINCT mag FROM Magazine mag JOIN mag.articles art JOIN art.author auth WHERE auth.firstName = 'John' |
| </pre><p> |
| Because Magazine is related to Author by means of the |
| relationships between Magazine and Article and between Article and Author, |
| navigation using the association-fields authors and product is used to express |
| the query. This query is specified by using the abstract schema name Magazine, |
| which designates the abstract schema type over which the query ranges. The basis |
| for the navigation is provided by the association-fields authors and product of |
| the abstract schema types Magazine and Article respectively. |
| </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_langref_fromclause"></a>2.3. |
| JPQL FROM Clause and Navigational Declarations |
| </h3></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#jpa_langref_from_identifiers">2.3.1. |
| JPQL FROM Identifiers |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_from_vars">2.3.2. |
| JPQL Identification Variables |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_range">2.3.3. |
| JPQL Range Declarations |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_path">2.3.4. |
| JPQL Path Expressions |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_Joins">2.3.5. |
| JPQL Joins |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_langref_inner_joins">2.3.5.1. |
| JPQL Inner Joins (Relationship Joins) |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_outer_joins">2.3.5.2. |
| JPQL Outer Joins |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_fetch_joins">2.3.5.3. |
| JPQL Fetch Joins |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_langref_collection_dec">2.3.6. |
| JPQL Collection Member Declarations |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_polymorph">2.3.7. |
| JPQL Polymorphism |
| </a></span></dt></dl></div><p> |
| The <code class="literal">FROM</code> clause of a query defines the domain of the query by |
| declaring identification variables. An identification variable is an identifier |
| declared in the <code class="literal">FROM</code> clause of a query. The domain of the |
| query may be constrained by path expressions. Identification variables designate |
| instances of a particular entity abstract schema type. The <code class="literal">FROM |
| </code> clause can contain multiple identification variable declarations |
| separated by a comma (,). |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| from_clause ::= FROM identification_variable_declaration {, |
| {identification_variable_declaration | collection_member_declaration}}* |
| </p></li><li><p> |
| identification_variable_declaration ::= range_variable_declaration { join | |
| fetch_join }* |
| </p></li><li><p> |
| range_variable_declaration ::= abstract_schema_name [AS] identification_variable |
| </p></li><li><p> |
| join ::= join_spec join_association_path_expression [AS] identification_variable |
| </p></li><li><p> |
| fetch_join ::= join_spec FETCH join_association_path_expression |
| </p></li><li><p> |
| join_association_path_expression ::= join_collection_valued_path_expression | |
| join_single_valued_association_path_expression |
| </p></li><li><p> |
| join_spec ::= [ LEFT [OUTER] | INNER ] JOIN |
| </p></li><li><p> |
| collection_member_declaration ::= IN (collection_valued_path_expression) [AS] |
| identification_variable |
| </p></li></ul></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="jpa_langref_from_identifiers"></a>2.3.1. |
| JPQL FROM Identifiers |
| </h4></div></div></div><p> |
| An identifier is a character sequence of unlimited length. The character |
| sequence must begin with a Java identifier start character, and all other |
| characters must be Java identifier part characters. An identifier start |
| character is any character for which the method <code class="methodname"> |
| Character.isJavaIdentifierStart</code> returns <code class="literal">true</code>. |
| This includes the underscore (_) character and the dollar sign ($) character. An |
| identifier part character is any character for which the method <code class="methodname"> |
| Character.isJavaIdentifierPart</code> returns <code class="literal">true</code>. |
| The question mark (?) character is reserved for use by the Java Persistence |
| query language. The following are reserved identifiers: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">SELECT</code> |
| </p></li><li><p> |
| <code class="literal">FROM</code> |
| </p></li><li><p> |
| <code class="literal">WHERE</code> |
| </p></li><li><p> |
| <code class="literal">UPDATE</code> |
| </p></li><li><p> |
| <code class="literal">DELETE</code> |
| </p></li><li><p> |
| <code class="literal">JOIN</code> |
| </p></li><li><p> |
| <code class="literal">OUTER</code> |
| </p></li><li><p> |
| <code class="literal">INNER</code> |
| </p></li><li><p> |
| <code class="literal">LEFT</code> |
| </p></li><li><p> |
| <code class="literal">GROUP</code> |
| </p></li><li><p> |
| <code class="literal">BY</code> |
| </p></li><li><p> |
| <code class="literal">HAVING</code> |
| </p></li><li><p> |
| <code class="literal">FETCH</code> |
| </p></li><li><p> |
| <code class="literal">DISTINCT</code> |
| </p></li><li><p> |
| <code class="literal">OBJECT</code> |
| </p></li><li><p> |
| <code class="literal">NULL</code> |
| </p></li><li><p> |
| <code class="literal">TRUE</code> |
| </p></li><li><p> |
| <code class="literal">FALSE</code> |
| </p></li><li><p> |
| <code class="literal">NOT</code> |
| </p></li><li><p> |
| <code class="literal">AND</code> |
| </p></li><li><p> |
| <code class="literal">OR</code> |
| </p></li><li><p> |
| <code class="literal">BETWEEN</code> |
| </p></li><li><p> |
| <code class="literal">LIKE</code> |
| </p></li><li><p> |
| <code class="literal">IN</code> |
| </p></li><li><p> |
| <code class="literal">AS</code> |
| </p></li><li><p> |
| <code class="literal">UNKNOWN</code> |
| </p></li><li><p> |
| <code class="literal">EMPTY</code> |
| </p></li><li><p> |
| <code class="literal">MEMBER</code> |
| </p></li><li><p> |
| <code class="literal">OF</code> |
| </p></li><li><p> |
| <code class="literal">IS</code> |
| </p></li><li><p> |
| <code class="literal">AVG</code> |
| </p></li><li><p> |
| <code class="literal">MAX</code> |
| </p></li><li><p> |
| <code class="literal">MIN</code> |
| </p></li><li><p> |
| <code class="literal">SUM</code> |
| </p></li><li><p> |
| <code class="literal">COUNT</code> |
| </p></li><li><p> |
| <code class="literal">ORDER</code> |
| </p></li><li><p> |
| <code class="literal">BY</code> |
| </p></li><li><p> |
| <code class="literal">ASC</code> |
| </p></li><li><p> |
| <code class="literal">DESC</code> |
| </p></li><li><p> |
| <code class="literal">MOD</code> |
| </p></li><li><p> |
| <code class="literal">UPPER</code> |
| </p></li><li><p> |
| <code class="literal">LOWER</code> |
| </p></li><li><p> |
| <code class="literal">TRIM</code> |
| </p></li><li><p> |
| <code class="literal">POSITION</code> |
| </p></li><li><p> |
| <code class="literal">CHARACTER_LENGTH</code> |
| </p></li><li><p> |
| <code class="literal">CHAR_LENGTH</code> |
| </p></li><li><p> |
| <code class="literal">BIT_LENGTH</code> |
| </p></li><li><p> |
| <code class="literal">CURRENT_TIME</code> |
| </p></li><li><p> |
| <code class="literal">CURRENT_DATE</code> |
| </p></li><li><p> |
| <code class="literal">CURRENT_TIMESTAMP</code> |
| </p></li><li><p> |
| <code class="literal">NEW</code> |
| </p></li><li><p> |
| <code class="literal">EXISTS</code> |
| </p></li><li><p> |
| <code class="literal">ALL</code> |
| </p></li><li><p> |
| <code class="literal">ANY</code> |
| </p></li><li><p> |
| <code class="literal">SOME</code> |
| </p></li></ul></div><p> |
| Reserved identifiers are case insensitive. Reserved identifiers must not be |
| used as identification variables. It is recommended that other SQL reserved |
| words also not be as identification variables in queries because they may be |
| used as reserved identifiers in future releases of the specification. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="jpa_langref_from_vars"></a>2.3.2. |
| JPQL Identification Variables |
| </h4></div></div></div><p> |
| An identification variable is a valid identifier declared in the <code class="literal">FROM |
| </code> clause of a query. All identification variables must be declared in |
| the <code class="literal">FROM</code> clause. Identification variables cannot be declared |
| in other clauses. An identification variable must not be a reserved identifier |
| or have the same name as any entity in the same persistence unit. Identification |
| variables are case insensitive. An identification variable evaluates to a value |
| of the type of the expression used in declaring the variable. For example, |
| consider the previous query: </p><pre class="programlisting">SELECT DISTINCT mag FROM Magazine mag JOIN mag.articles art JOIN art.author auth WHERE auth.firstName = 'John' |
| </pre><p> In the <code class="literal">FROM</code> clause declaration <code class="literal"> |
| mag.articles</code><code class="literal">art</code>, the identification variable |
| <code class="literal">art</code> evaluates to any <code class="literal">Article</code> value |
| directly reachable from <code class="literal">Magazine</code>. The association-field |
| <code class="literal">articles</code> is a collection of instances of the abstract schema |
| type <code class="literal">Article</code> and the identification variable <code class="literal">art |
| </code> refers to an element of this collection. The type of <code class="literal">auth |
| </code> is the abstract schema type of <code class="literal">Author</code>. An |
| identification variable ranges over the abstract schema type of an entity. An |
| identification variable designates an instance of an entity abstract schema type |
| or an element of a collection of entity abstract schema type instances. |
| Identification variables are existentially quantified in a query. An |
| identification variable always designates a reference to a single value. It is |
| declared in one of three ways: in a range variable declaration, in a join |
| clause, or in a collection member declaration. The identification variable |
| declarations are evaluated from left to right in the <code class="literal">FROM</code> |
| clause, and an identification variable declaration can use the result of a |
| preceding identification variable declaration of the query string. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="jpa_langref_range"></a>2.3.3. |
| JPQL Range Declarations |
| </h4></div></div></div><p> |
| The syntax for declaring an identification variable as a range variable is |
| similar to that of SQL; optionally, it uses the AS keyword. |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| range_variable_declaration ::= abstract_schema_name [AS] |
| identification_variable |
| </p></li></ul></div><p> |
| Range variable declarations allow the developer to designate a "root" for |
| objects which may not be reachable by navigation. In order to select values by |
| comparing more than one instance of an entity abstract schema type, more than |
| one identification variable ranging over the abstract schema type is needed in |
| the <code class="literal">FROM</code> clause. |
| </p><p> |
| The following query returns magazines whose price is greater than the price of |
| magazines published by "Adventure" publishers. This example illustrates the use |
| of two different identification variables in the <code class="literal">FROM</code> clause, |
| both of the abstract schema type Magazine. The <code class="literal">SELECT</code> clause |
| of this query determines that it is the magazines with prices greater than those |
| of "Adventure" publisher's that are returned. |
| </p><pre class="programlisting"> |
| SELECT DISTINCT mag1 FROM Magazine mag1, Magazine mag2 |
| WHERE mag1.price > mag2.price AND mag2.publisher.name = 'Adventure' |
| </pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="jpa_langref_path"></a>2.3.4. |
| JPQL Path Expressions |
| </h4></div></div></div><p> |
| An identification variable followed by the navigation operator (.) and a |
| state-field or association-field is a path expression. The type of the path |
| expression is the type computed as the result of navigation; that is, the type |
| of the state-field or association-field to which the expression navigates. |
| Depending on navigability, a path expression that leads to a association-field |
| may be further composed. Path expressions can be composed from other path |
| expressions if the original path expression evaluates to a single-valued type |
| (not a collection) corresponding to a association-field. Path expression |
| navigability is composed using "inner join" semantics. That is, if the value of |
| a non-terminal association-field in the path expression is null, the path is |
| considered to have no value, and does not participate in the determination of |
| the result. The syntax for single-valued path expressions and collection valued |
| path expressions is as follows: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| single_valued_path_expression ::= state_field_path_expression | |
| single_valued_association_path_expression |
| </p></li><li><p> |
| state_field_path_expression ::= {identification_variable | |
| single_valued_association_path_expression}.state_field |
| </p></li><li><p> |
| single_valued_association_path_expression ::= |
| identification_variable.{single_valued_association_field.}*single_valued_association_field |
| </p></li><li><p> |
| collection_valued_path_expression ::= |
| identification_variable.{single_valued_association_field.}*collection_valued_association_field |
| </p></li><li><p> |
| state_field ::= {embedded_class_state_field.}*simple_state_field |
| </p></li></ul></div><p> |
| A single_valued_association_field is designated by the name of an |
| association-field in a one-to-one or many-to-one relationship. The type of a |
| single_valued_association_field and thus a |
| single_valued_association_path_expression is the abstract schema type of the |
| related entity. A collection_valued_association_field is designated by the name |
| of an association-field in a one-to-many or a many-to-many relationship. The |
| type of a collection_valued_association_field is a collection of values of the |
| abstract schema type of the related entity. An embedded_class_state _field is |
| designated by the name of an entity state field that corresponds to an embedded |
| class. Navigation to a related entity results in a value of the related entity's |
| abstract schema type. |
| </p><p> |
| The evaluation of a path expression terminating in a state-field results in the |
| abstract schema type corresponding to the Java type designated by the |
| state-field. It is syntactically illegal to compose a path expression from a |
| path expression that evaluates to a collection. For example, if <code class="literal">mag |
| </code> designates <code class="literal">Magazine</code>, the path expression <code class="literal"> |
| mag.articles.author</code> is illegal since navigation to authors results in |
| a collection. This case should produce an error when the query string is |
| verified. To handle such a navigation, an identification variable must be |
| declared in the <code class="literal">FROM</code> clause to range over the elements of the |
| <code class="literal">articles</code> collection. Another path expression must be used to |
| navigate over each such element in the <code class="literal">WHERE</code> clause of the |
| query, as in the following query which returns all authors that have any |
| articles in any magazines: </p><pre class="programlisting">SELECT DISTINCT art.author FROM Magazine AS mag, IN(mag.articles) art |
| </pre><p> |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="jpa_langref_Joins"></a>2.3.5. |
| JPQL Joins |
| </h4></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#jpa_langref_inner_joins">2.3.5.1. |
| JPQL Inner Joins (Relationship Joins) |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_outer_joins">2.3.5.2. |
| JPQL Outer Joins |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_fetch_joins">2.3.5.3. |
| JPQL Fetch Joins |
| </a></span></dt></dl></div><p> |
| An inner join may be implicitly specified by the use of a cartesian product in |
| the <code class="literal">FROM</code> clause and a join condition in the <code class="literal">WHERE |
| </code> clause. |
| </p><p> |
| The syntax for explicit join operations is as follows: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| join ::= join_spec join_association_path_expression [AS] identification_variable |
| </p></li><li><p> |
| fetch_join ::= join_spec FETCH join_association_path_expression |
| </p></li><li><p> |
| join_association_path_expression ::= join_collection_valued_path_expression | |
| join_single_valued_association_path_expression |
| </p></li><li><p> |
| join_spec ::= [ LEFT [OUTER] | INNER ] JOIN |
| </p></li></ul></div><p> |
| The following inner and outer join operation types are supported. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="jpa_langref_inner_joins"></a>2.3.5.1. |
| JPQL Inner Joins (Relationship Joins) |
| </h5></div></div></div><p> |
| The syntax for the inner join operation is </p><pre class="programlisting"> |
| [ INNER ] JOIN join_association_path_expression [AS] identification_variable |
| </pre><p> For example, the query below joins over the relationship |
| between publishers and magazines. This type of join typically equates to a join |
| over a foreign key relationship in the database. |
| </p><pre class="programlisting"> |
| SELECT pub FROM Publisher pub JOIN pub.magazines mag WHERE pub.revenue > 1000000 |
| </pre><p> |
| The keyword <code class="literal">INNER</code> may optionally be used: |
| </p><pre class="programlisting"> |
| SELECT pub FROM Publisher pub INNER JOIN pub.magazines mag WHERE pub.revenue > 1000000 |
| </pre><p> |
| This is equivalent to the following query using the earlier |
| <code class="literal">IN</code> construct. It selects those publishers with revenue of |
| over 1 million for which at least one magazine exists: |
| </p><pre class="programlisting"> |
| SELECT OBJECT(pub) FROM Publisher pub, IN(pub.magazines) mag WHERE pub.revenue > 1000000 |
| </pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="jpa_langref_outer_joins"></a>2.3.5.2. |
| JPQL Outer Joins |
| </h5></div></div></div><p> |
| <code class="literal">LEFT JOIN</code> and <code class="literal">LEFT OUTER JOIN</code> are |
| synonymous. They enable the retrieval of a set of entities where matching values |
| in the join condition may be absent. The syntax for a left outer join is: |
| </p><pre class="programlisting">LEFT [OUTER] JOIN join_association_path_expression [AS] identification_variable |
| </pre><p> |
| </p><p> |
| For example: </p><pre class="programlisting">SELECT pub FROM Publisher pub LEFT JOIN pub.magazines mag WHERE pub.revenue > 1000000 |
| </pre><p> The keyword <code class="literal">OUTER</code> may optionally be used: |
| </p><pre class="programlisting">SELECT pub FROM Publisher pub LEFT OUTER JOIN pub.magazines mags WHERE pub.revenue > 1000000 |
| </pre><p> An important use case for <code class="literal">LEFT JOIN</code> is in |
| enabling the prefetching of related data items as a side effect of a query. This |
| is accomplished by specifying the <code class="literal">LEFT JOIN</code> as a <code class="literal"> |
| FETCH JOIN</code>. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="jpa_langref_fetch_joins"></a>2.3.5.3. |
| JPQL Fetch Joins |
| </h5></div></div></div><p> |
| A <code class="literal">FETCH JOIN</code> enables the fetching of an association as a side |
| effect of the execution of a query. A <code class="literal">FETCH JOIN</code> is specified |
| over an entity and its related entities. The syntax for a fetch join is |
| </p><div class="itemizedlist"><ul type="disc"><li><p>fetch_join ::= [ LEFT [OUTER] | INNER ] JOIN |
| FETCH join_association_path_expression |
| </p></li></ul></div><p> |
| </p><p> |
| The association referenced by the right side of the <code class="literal">FETCH JOIN |
| </code> clause must be an association that belongs to an entity that is |
| returned as a result of the query. It is not permitted to specify an |
| identification variable for the entities referenced by the right side of the |
| <code class="literal">FETCH JOIN</code> clause, and hence references to the implicitly |
| fetched entities cannot appear elsewhere in the query. The following query |
| returns a set of magazines. As a side effect, the associated articles for those |
| magazines are also retrieved, even though they are not part of the explicit |
| query result. The persistent fields or properties of the articles that are |
| eagerly fetched are fully initialized. The initialization of the relationship |
| properties of the <code class="literal">articles</code> that are retrieved is determined |
| by the metadata for the <code class="literal">Article</code> entity class. |
| </p><pre class="programlisting">SELECT mag FROM Magazine mag LEFT JOIN FETCH mag.articles WHERE mag.id = 1 |
| </pre><p> |
| </p><p> |
| A fetch join has the same join semantics as the corresponding inner or outer |
| join, except that the related objects specified on the right-hand side of the |
| join operation are not returned in the query result or otherwise referenced in |
| the query. Hence, for example, if magazine id 1 has five articles, the above |
| query returns five references to the magazine 1 entity. |
| </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="jpa_langref_collection_dec"></a>2.3.6. |
| JPQL Collection Member Declarations |
| </h4></div></div></div><p> |
| An identification variable declared by a collection_member_declaration ranges |
| over values of a collection obtained by navigation using a path expression. Such |
| a path expression represents a navigation involving the association-fields of an |
| entity abstract schema type. Because a path expression can be based on another |
| path expression, the navigation can use the association-fields of related |
| entities. An identification variable of a collection member declaration is |
| declared using a special operator, the reserved identifier <code class="literal">IN</code> |
| . The argument to the <code class="literal">IN</code> operator is a collection-valued path |
| expression. The path expression evaluates to a collection type specified as a |
| result of navigation to a collection-valued association-field of an entity |
| abstract schema type. The syntax for declaring a collection member |
| identification variable is as follows: |
| </p><p> |
| </p><div class="itemizedlist"><ul type="disc"><li><p>collection_member_declaration ::= IN |
| (collection_valued_path_expression) [AS] identification_variable |
| </p></li></ul></div><p> |
| </p><p> |
| For example, the query </p><pre class="programlisting">SELECT DISTINCT mag FROM Magazine mag |
| JOIN mag.articles art |
| JOIN art.author auth |
| WHERE auth.lastName = 'Grisham'</pre><p> may equivalently be |
| expressed as follows, using the <code class="literal">IN</code> operator: </p><pre class="programlisting">SELECT DISTINCT mag FROM Magazine mag, |
| IN(mag.articles) art |
| WHERE art.author.lastName = 'Grisham'</pre><p> In this example, |
| <code class="literal">articles</code> is the name of an association-field whose value is a |
| collection of instances of the abstract schema type <code class="literal">Article</code>. |
| The identification variable <code class="literal">art</code> designates a member of this |
| collection, a single <code class="literal">Article</code> abstract schema type instance. |
| In this example, <code class="literal">mag</code> is an identification variable of the |
| abstract schema type <code class="literal">Magazine</code>. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="jpa_langref_polymorph"></a>2.3.7. |
| JPQL Polymorphism |
| </h4></div></div></div><p> |
| Java Persistence queries are automatically polymorphic. The <code class="literal">FROM |
| </code> clause of a query designates not only instances of the specific |
| entity classes to which explicitly refers but of subclasses as well. The |
| instances returned by a query include instances of the subclasses that satisfy |
| the query criteria. |
| </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_langref_where"></a>2.4. |
| JPQL WHERE Clause |
| </h3></div></div></div><p> |
| The <code class="literal">WHERE</code> clause of a query consists of a conditional |
| expression used to select objects or values that satisfy the expression. The |
| <code class="literal">WHERE</code> clause restricts the result of a select statement or |
| the scope of an update or delete operation. A <code class="literal">WHERE</code> clause is |
| defined as follows: </p><div class="itemizedlist"><ul type="disc"><li><p>where_clause ::= WHERE |
| conditional_expression |
| </p></li></ul></div><p> |
| </p><p> |
| The <code class="literal">GROUP BY</code> construct enables the aggregation of values |
| according to the properties of an entity class. The <code class="literal">HAVING</code> |
| construct enables conditions to be specified that further restrict the query |
| result as restrictions upon the groups. The syntax of the <code class="literal">HAVING |
| </code> clause is as follows: </p><div class="itemizedlist"><ul type="disc"><li><p>having_clause |
| ::= HAVING conditional_expression |
| </p></li></ul></div><p> |
| </p><p> |
| The <code class="literal">GROUP BY</code> and <code class="literal">HAVING</code> constructs are |
| further discussed in <a href="#jpa_langref_group" title="2.6. JPQL GROUP BY, HAVING">Section 2.6, “ |
| JPQL GROUP BY, HAVING |
| ”</a>. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_langref_cond"></a>2.5. |
| JPQL Conditional Expressions |
| </h3></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#jpa_langref_lit">2.5.1. |
| JPQL Literals |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_idvar">2.5.2. |
| JPQL Identification Variables |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_path_exp">2.5.3. |
| JPQL Path Expressions |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_input_params">2.5.4. |
| JPQL Input Parameters |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_langref_pos_params">2.5.4.1. |
| JPQL Positional Parameters |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_named_params">2.5.4.2. |
| JPQL Named Parameters |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_langref_cond_comp">2.5.5. |
| JPQL Conditional Expression Composition |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_operators">2.5.6. |
| JPQL Operators and Operator Precedence |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_between">2.5.7. |
| JPQL Between Expressions |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_in">2.5.8. |
| JPQL In Expressions |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_like">2.5.9. |
| JPQL Like Expressions |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_null">2.5.10. |
| JPQL Null Comparison Expressions |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_empty_comp">2.5.11. |
| JPQL Empty Collection Comparison Expressions |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_collection_member">2.5.12. |
| JPQL Collection Member Expressions |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_exists">2.5.13. |
| JPQL Exists Expressions |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_all_any">2.5.14. |
| JPQL All or Any Expressions |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_subqueries">2.5.15. |
| JPQL Subqueries |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_functional">2.5.16. |
| JPQL Functional Expressions |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_langref_string_fun">2.5.16.1. |
| JPQL String Functions |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_arithmetic">2.5.16.2. |
| JPQL Arithmetic Functions |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_datetime">2.5.16.3. |
| JPQL Datetime Functions |
| </a></span></dt></dl></dd></dl></div><p> |
| The following sections describe the language constructs that can be used in a |
| conditional expression of the <code class="literal">WHERE</code> clause or <code class="literal"> |
| HAVING</code> clause. State-fields that are mapped in serialized form or as |
| lobs may not be portably used in conditional expressions. </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> The |
| implementation is not expected to perform such query operations involving such |
| fields in memory rather than in the database. |
| </p></div><p> |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="jpa_langref_lit"></a>2.5.1. |
| JPQL Literals |
| </h4></div></div></div><p> |
| A string literal is enclosed in single quotes--for example: 'literal'. A string |
| literal that includes a single quote is represented by two single quotes--for |
| example: 'literal''s'. String literals in queries, like Java String literals, |
| use unicode character encoding. The use of Java escape notation is not supported |
| in query string literals. Exact numeric literals support the use of Java integer |
| literal syntax as well as SQL exact numeric literal syntax. Approximate literals |
| support the use of Java floating point literal syntax as well as SQL approximate |
| numeric literal syntax. Enum literals support the use of Java enum literal |
| syntax. The enum class name must be specified. Appropriate suffixes may be used |
| to indicate the specific type of a numeric literal in accordance with the Java |
| Language Specification. The boolean literals are <code class="literal">TRUE</code> and |
| <code class="literal">FALSE</code>. Although predefined reserved literals appear in upper |
| case, they are case insensitive. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="jpa_langref_idvar"></a>2.5.2. |
| JPQL Identification Variables |
| </h4></div></div></div><p> |
| All identification variables used in the <code class="literal">WHERE</code> or <code class="literal"> |
| HAVING</code> clause of a <code class="literal">SELECT</code> or <code class="literal">DELETE |
| </code> statement must be declared in the <code class="literal">FROM</code> clause, as |
| described in <a href="#jpa_langref_from_vars" title="2.3.2. JPQL Identification Variables">Section 2.3.2, “ |
| JPQL Identification Variables |
| ”</a>. The identification |
| variables used in the <code class="literal">WHERE</code> clause of an <code class="literal">UPDATE |
| </code> statement must be declared in the <code class="literal">UPDATE</code> clause. |
| Identification variables are existentially quantified in the <code class="literal">WHERE |
| </code> and <code class="literal">HAVING</code> clause. This means that an |
| identification variable represents a member of a collection or an instance of an |
| entity's abstract schema type. An identification variable never designates a |
| collection in its entirety. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="jpa_langref_path_exp"></a>2.5.3. |
| JPQL Path Expressions |
| </h4></div></div></div><p> |
| It is illegal to use a collection_valued_path_expression within a <code class="literal"> |
| WHERE</code> or <code class="literal">HAVING</code> clause as part of a conditional |
| expression except in an empty_collection_comparison_expression, in a |
| collection_member_expression, or as an argument to the <code class="literal">SIZE</code> |
| operator. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="jpa_langref_input_params"></a>2.5.4. |
| JPQL Input Parameters |
| </h4></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#jpa_langref_pos_params">2.5.4.1. |
| JPQL Positional Parameters |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_named_params">2.5.4.2. |
| JPQL Named Parameters |
| </a></span></dt></dl></div><p> |
| Either positional or named parameters may be used. Positional and named |
| parameters may not be mixed in a single query. Input parameters can only be used |
| in the <code class="literal">WHERE</code> clause or <code class="literal">HAVING</code> clause of a |
| query. |
| </p><p> |
| Note that if an input parameter value is null, comparison operations or |
| arithmetic operations involving the input parameter will return an unknown |
| value. See <a href="#jpa_langref_null_values" title="2.10. JPQL Null Values">Section 2.10, “ |
| JPQL Null Values |
| ”</a>. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="jpa_langref_pos_params"></a>2.5.4.1. |
| JPQL Positional Parameters |
| </h5></div></div></div><p> |
| The following rules apply to positional parameters. </p><div class="itemizedlist"><ul type="disc"><li><p> Input parameters are designated by the question mark (?) prefix followed |
| by an integer. For example: ?1. |
| </p></li><li><p> |
| Input parameters are numbered starting from 1. Note that the same parameter can |
| be used more than once in the query string and that the ordering of the use of |
| parameters within the query string need not conform to the order of the |
| positional parameters. |
| </p></li></ul></div><p> |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="jpa_langref_named_params"></a>2.5.4.2. |
| JPQL Named Parameters |
| </h5></div></div></div><p> |
| A named parameter is an identifier that is prefixed by the ":" symbol. It |
| follows the rules for identifiers defined in |
| <a href="#jpa_langref_from_identifiers" title="2.3.1. JPQL FROM Identifiers">Section 2.3.1, “ |
| JPQL FROM Identifiers |
| ”</a>. Named parameters are case |
| sensitive. |
| </p><p> |
| Example: </p><pre class="programlisting">SELECT pub FROM Publisher pub WHERE pub.revenue > :rev |
| </pre><p> |
| </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="jpa_langref_cond_comp"></a>2.5.5. |
| JPQL Conditional Expression Composition |
| </h4></div></div></div><p> |
| Conditional expressions are composed of other conditional expressions, |
| comparison operations, logical operations, path expressions that evaluate to |
| boolean values, boolean literals, and boolean input parameters. Arithmetic |
| expressions can be used in comparison expressions. Arithmetic expressions are |
| composed of other arithmetic expressions, arithmetic operations, path |
| expressions that evaluate to numeric values, numeric literals, and numeric input |
| parameters. Arithmetic operations use numeric promotion. Standard bracketing () |
| for ordering expression evaluation is supported. Conditional expressions are |
| defined as follows: |
| </p><p> |
| </p><div class="itemizedlist"><ul type="disc"><li><p>conditional_expression ::= conditional_term | |
| conditional_expression OR conditional_term |
| </p></li><li><p> |
| conditional_term ::= conditional_factor | conditional_term AND |
| conditional_factor |
| </p></li><li><p> |
| conditional_factor ::= [ NOT ] conditional_primary |
| </p></li><li><p> |
| conditional_primary ::= simple_cond_expression | (conditional_expression) |
| </p></li><li><p> |
| simple_cond_expression ::= comparison_expression | between_expression | |
| like_expression | in_expression | null_comparison_expression | |
| empty_collection_comparison_expression | collection_member_expression | |
| exists_expression |
| </p></li></ul></div><p> |
| </p><p> |
| Aggregate functions can only be used in conditional expressions in a <code class="literal"> |
| HAVING</code> clause. See <a href="#jpa_langref_group" title="2.6. JPQL GROUP BY, HAVING">Section 2.6, “ |
| JPQL GROUP BY, HAVING |
| ”</a>. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="jpa_langref_operators"></a>2.5.6. |
| JPQL Operators and Operator Precedence |
| </h4></div></div></div><p> |
| The operators are listed below in order of decreasing precedence. </p><div class="itemizedlist"><ul type="disc"><li><p> Navigation operator (.) |
| </p></li><li><p> |
| Arithmetic operators: +, - unary *, / multiplication and division +, - addition |
| and subtraction |
| </p></li><li><p> |
| Comparison operators: =, >, >=, <, <=, <> (not equal), [ |
| <code class="literal">NOT</code> ] <code class="literal">BETWEEN</code>, [ <code class="literal">NOT</code> ] |
| <code class="literal">LIKE</code>, [ <code class="literal">NOT</code> ] <code class="literal">IN</code>, |
| <code class="literal">IS</code> [ <code class="literal">NOT</code> ] <code class="literal">NULL</code>, |
| <code class="literal">IS</code> [ <code class="literal">NOT</code> ] <code class="literal">EMPTY</code>, [ |
| <code class="literal">NOT</code> ] <code class="literal">MEMBER</code> [ <code class="literal">OF</code> ] |
| </p></li><li><p> |
| Logical operators: <code class="literal">NOT</code>, <code class="literal">AND</code>, |
| <code class="literal">OR</code> |
| </p></li></ul></div><p> |
| |
| |
| The following sections describe other operators used in specific expressions. |
| |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="jpa_langref_between"></a>2.5.7. |
| JPQL Between Expressions |
| </h4></div></div></div><p> |
| The syntax for the use of the comparison operator [ <code class="literal">NOT</code> ] |
| <code class="literal">BETWEEN</code> in a conditional expression is as follows: |
| </p><p> |
| 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 |
| </p><p> |
| The BETWEEN expression </p><pre class="programlisting">x BETWEEN y AND z</pre><p> is |
| semantically equivalent to: </p><pre class="programlisting">y <= x AND x <= z |
| </pre><p> The rules for unknown and <code class="literal">NULL</code> values in |
| comparison operations apply. See <a href="#jpa_langref_null_values" title="2.10. JPQL Null Values">Section 2.10, “ |
| JPQL Null Values |
| ”</a> |
| . Examples are: </p><pre class="programlisting">p.age BETWEEN 15 and 19</pre><p> is |
| equivalent to </p><pre class="programlisting">p.age >= 15 AND p.age <= 19</pre><p> |
| </p><p> |
| </p><pre class="programlisting">p.age NOT BETWEEN 15 and 19</pre><p> is equivalent to |
| </p><pre class="programlisting">p.age < 15 OR p.age > 19</pre><p> |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="jpa_langref_in"></a>2.5.8. |
| JPQL In Expressions |
| </h4></div></div></div><p> |
| The syntax for the use of the comparison operator [ <code class="literal">NOT</code> ] |
| <code class="literal">IN</code> in a conditional expression is as follows: |
| </p><p> |
| </p><div class="itemizedlist"><ul type="disc"><li><p>in_expression ::= state_field_path_expression |
| [NOT] IN ( in_item {, in_item}* | subquery) |
| </p></li><li><p> |
| in_item ::= literal | input_parameter |
| </p></li></ul></div><p> |
| </p><p> |
| The state_field_path_expression must have a string, numeric, or enum value. The |
| literal and/or input_parameter values must be like the same abstract schema type |
| of the state_field_path_expression in type. (See |
| <a href="#jpa_langref_equality" title="2.11. JPQL Equality and Comparison Semantics">Section 2.11, “ |
| JPQL Equality and Comparison Semantics |
| ”</a> ). |
| </p><p> |
| The results of the subquery must be like the same abstract schema type of the |
| state_field_path_expression in type. Subqueries are discussed in |
| <a href="#jpa_langref_subqueries" title="2.5.15. JPQL Subqueries">Section 2.5.15, “ |
| JPQL Subqueries |
| ”</a>. Examples are: </p><pre class="programlisting">o.country IN ('UK', 'US', 'France') |
| </pre><p> is true for UK and false for Peru, and is equivalent to the |
| expression: </p><pre class="programlisting">(o.country = 'UK') OR (o.country = 'US') OR (o.country = ' France') |
| </pre><p> In the following expression: </p><pre class="programlisting">o.country NOT IN ('UK', 'US', 'France') |
| </pre><p> is false for UK and true for Peru, and is equivalent to the |
| expression: </p><pre class="programlisting">NOT ((o.country = 'UK') OR (o.country = 'US') OR (o.country = 'France')) |
| </pre><p> There must be at least one element in the comma separated list |
| that defines the set of values for the <code class="literal">IN</code> expression. If the |
| value of a state_field_path_expression in an <code class="literal">IN</code> or <code class="literal"> |
| NOT IN</code> expression is <code class="literal">NULL</code> or unknown, the value of |
| the expression is unknown. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="jpa_langref_like"></a>2.5.9. |
| JPQL Like Expressions |
| </h4></div></div></div><p> |
| The syntax for the use of the comparison operator [ <code class="literal">NOT</code> ] |
| <code class="literal">LIKE</code> in a conditional expression is as follows: |
| </p><p> |
| string_expression [NOT] LIKE pattern_value [ESCAPE escape_character] |
| </p><p> |
| The string_expression must have a string value. The pattern_value is a string |
| literal or a string-valued input parameter in which an underscore (_) stands for |
| any single character, a percent (%) character stands for any sequence of |
| characters (including the empty sequence), and all other characters stand for |
| themselves. The optional escape_character is a single-character string literal |
| or a character-valued input parameter (i.e., char or Character) and is used to |
| escape the special meaning of the underscore and percent characters in |
| pattern_value. Examples are: |
| </p><p> |
| </p><div class="itemizedlist"><ul type="disc"><li><pre class="programlisting">address.phone LIKE '12%3' |
| </pre><p> is true for '123' '12993' and false for '1234' |
| </p></li><li><p> |
| </p><pre class="programlisting">asentence.word LIKE 'l_se'</pre><p> is true for 'lose' |
| and false for 'loose' |
| </p></li><li><p> |
| </p><pre class="programlisting">aword.underscored LIKE '\_%' ESCAPE '\'</pre><p> is true |
| for '_foo' and false for 'bar' |
| </p></li><li><p> |
| </p><pre class="programlisting">address.phone NOT LIKE '12%3'</pre><p> is false for |
| '123' and '12993' and true for '1234'. If the value of the string_expression or |
| pattern_value is <code class="literal">NULL</code> or unknown, the value of the <code class="literal"> |
| LIKE</code> expression is unknown. If the escape_character is specified and |
| is <code class="literal">NULL</code>, the value of the <code class="literal">LIKE</code> expression |
| is unknown. |
| </p></li></ul></div><p> |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="jpa_langref_null"></a>2.5.10. |
| JPQL Null Comparison Expressions |
| </h4></div></div></div><p> |
| The syntax for the use of the comparison operator <code class="literal">IS NULL</code> in |
| a conditional expression is as follows: |
| </p><p> |
| {single_valued_path_expression | input_parameter } IS [NOT] NULL |
| </p><p> |
| A null comparison expression tests whether or not the single-valued path |
| expression or input parameter is a <code class="literal">NULL</code> value. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="jpa_langref_empty_comp"></a>2.5.11. |
| JPQL Empty Collection Comparison Expressions |
| </h4></div></div></div><p> |
| The syntax for the use of the comparison operator <code class="literal">IS EMPTY</code> in |
| an empty_collection_comparison_expression is as follows: |
| </p><p> |
| collection_valued_path_expression IS [NOT] EMPTY |
| </p><p> |
| This expression tests whether or not the collection designated by the |
| collection-valued path expression is empty (i.e, has no elements). |
| </p><p> |
| For example, the following query will return all magazines that don't have any |
| articles at all: </p><pre class="programlisting">SELECT mag FROM Magazine mag WHERE mag.articles IS EMPTY |
| </pre><p> If the value of the collection-valued path expression in an |
| empty collection comparison expression is unknown, the value of the empty |
| comparison expression is unknown. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="jpa_langref_collection_member"></a>2.5.12. |
| JPQL Collection Member Expressions |
| </h4></div></div></div><p> |
| The use of the comparison collection_member_expression is as follows: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| collection_member_expression ::= entity_expression [NOT] MEMBER [OF] |
| collection_valued_path_expression |
| </p></li><li><p> |
| entity_expression ::= single_valued_association_path_expression | |
| simple_entity_expression |
| </p></li><li><p> |
| simple_entity_expression ::= identification_variable | input_parameter |
| </p></li></ul></div><p> |
| </p><p> |
| This expression tests whether the designated value is a member of the collection |
| specified by the collection-valued path expression. If the collection valued |
| path expression designates an empty collection, the value of the <code class="literal"> |
| MEMBER OF</code> expression is <code class="literal">FALSE</code> and the value of the |
| <code class="literal">NOT MEMBER OF</code> expression is <code class="literal">TRUE</code>. |
| Otherwise, if the value of the collection-valued path expression or |
| single-valued association-field path expression in the collection member |
| expression is <code class="literal">NULL</code> or unknown, the value of the collection |
| member expression is unknown. |
| </p><p> |
| The use of the reserved word OF is optional in this expression. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="jpa_langref_exists"></a>2.5.13. |
| JPQL Exists Expressions |
| </h4></div></div></div><p> |
| An <code class="literal">EXISTS</code> expression is a predicate that is true only if the |
| result of the subquery consists of one or more values and that is false |
| otherwise. The syntax of an exists expression is </p><div class="itemizedlist"><ul type="disc"><li><p> |
| exists_expression ::= [NOT] EXISTS (subquery) |
| </p></li></ul></div><p> |
| </p><p> |
| Example: </p><pre class="programlisting">SELECT DISTINCT auth FROM Author auth |
| WHERE EXISTS |
| (SELECT spouseAuthor FROM Author spouseAuthor WHERE spouseAuthor = auth.spouse) |
| </pre><p> The result of this query consists of all authors whose spouse |
| is also an author. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="jpa_langref_all_any"></a>2.5.14. |
| JPQL All or Any Expressions |
| </h4></div></div></div><p> |
| An <code class="literal">ALL</code> conditional expression is a predicate that is true if |
| the comparison operation is true for all values in the result of the subquery or |
| the result of the subquery is empty. An <code class="literal">ALL</code> conditional |
| expression is false if the result of the comparison is false for at least one |
| row, and is unknown if neither true nor false. An <code class="literal">ANY</code> |
| conditional expression is a predicate that is true if the comparison operation |
| is true for some value in the result of the subquery. An <code class="literal">ANY</code> |
| conditional expression is false if the result of the subquery is empty or if the |
| comparison operation is false for every value in the result of the subquery, and |
| is unknown if neither true nor false. The keyword <code class="literal">SOME</code> is |
| synonymous with <code class="literal">ANY</code>. The comparison operators used with |
| <code class="literal">ALL</code> or <code class="literal">ANY</code> conditional expressions are =, |
| <, <=, >, >=, <>. The result of the subquery must be like that |
| of the other argument to the comparison operator in type. See |
| <a href="#jpa_langref_equality" title="2.11. JPQL Equality and Comparison Semantics">Section 2.11, “ |
| JPQL Equality and Comparison Semantics |
| ”</a>. The syntax of an <code class="literal">ALL |
| </code> or <code class="literal">ANY</code> expression is specified as follows: |
| </p><div class="itemizedlist"><ul type="disc"><li><p>all_or_any_expression ::= { ALL | ANY | SOME} |
| (subquery) |
| </p></li></ul></div><p> |
| </p><p> |
| The following example select the authors who make the highest salary for their |
| magazine: </p><pre class="programlisting">SELECT auth FROM Author auth |
| WHERE auth.salary >= ALL(SELECT a.salary FROM Author a WHERE a.magazine = auth.magazine) |
| </pre><p> |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="jpa_langref_subqueries"></a>2.5.15. |
| JPQL Subqueries |
| </h4></div></div></div><p> |
| Subqueries may be used in the <code class="literal">WHERE</code> or <code class="literal">HAVING |
| </code> clause. The syntax for subqueries is as follows: </p><div class="itemizedlist"><ul type="disc"><li><p>subquery ::= simple_select_clause subquery_from_clause |
| [where_clause] [groupby_clause] [having_clause] |
| </p></li></ul></div><p> |
| </p><p> |
| Subqueries are restricted to the <code class="literal">WHERE</code> and <code class="literal">HAVING |
| </code> clauses in this release. Support for subqueries in the <code class="literal">FROM |
| </code> clause will be considered in a later release of the specification. |
| </p><div class="itemizedlist"><ul type="disc"><li><p>simple_select_clause ::= SELECT [DISTINCT] |
| simple_select_expression |
| </p></li><li><p> |
| subquery_from_clause ::= FROM subselect_identification_variable_declaration {, |
| subselect_identification_variable_declaration}* |
| </p></li><li><p> |
| subselect_identification_variable_declaration ::= |
| identification_variable_declaration | association_path_expression [AS] |
| identification_variable | collection_member_declaration |
| </p></li><li><p> |
| simple_select_expression ::= single_valued_path_expression | |
| aggregate_expression | identification_variable |
| </p></li></ul></div><p> |
| </p><p> |
| Examples: </p><pre class="programlisting">SELECT DISTINCT auth FROM Author auth |
| WHERE EXISTS (SELECT spouseAuth FROM Author spouseAuth WHERE spouseAuth = auth.spouse) |
| </pre><pre class="programlisting">SELECT mag FROM Magazine mag |
| WHERE (SELECT COUNT(art) FROM mag.articles art) > 10</pre><p> |
| Note that some contexts in which a subquery can be used require that the |
| subquery be a scalar subquery (i.e., produce a single result). This is |
| illustrated in the following example involving a numeric comparison operation. |
| </p><pre class="programlisting">SELECT goodPublisher FROM Publisher goodPublisher |
| WHERE goodPublisher.revenue < (SELECT AVG(p.revenue) FROM Publisher p) |
| </pre><p> |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="jpa_langref_functional"></a>2.5.16. |
| JPQL Functional Expressions |
| </h4></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#jpa_langref_string_fun">2.5.16.1. |
| JPQL String Functions |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_arithmetic">2.5.16.2. |
| JPQL Arithmetic Functions |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_datetime">2.5.16.3. |
| JPQL Datetime Functions |
| </a></span></dt></dl></div><p> |
| The JPQL includes the following built-in functions, which may be used in the |
| <code class="literal">WHERE</code> or <code class="literal">HAVING</code> clause of a query. If the |
| value of any argument to a functional expression is null or unknown, the value |
| of the functional expression is unknown. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="jpa_langref_string_fun"></a>2.5.16.1. |
| JPQL String Functions |
| </h5></div></div></div><p> |
| </p><div class="itemizedlist"><ul type="disc"><li><p>functions_returning_strings ::= |
| CONCAT(string_primar y, string_primary) | SUBSTRING(string_primar y, |
| simple_arithmetic_expression, simple_arithmetic_expression) | |
| TRIM([[trim_specification] [trim_character] FROM] string_primary) | |
| LOWER(string_primar y) | UPPER(string_primar y) |
| </p></li><li><p> |
| trim_specification ::= LEADING | TRAILING | BOTH |
| </p></li><li><p> |
| functions_returning_numerics ::= LENGTH(string_primar y) | LOCATE(string_primar |
| y, string_primar y[, simple_arithmetic_expression]) |
| </p></li></ul></div><p> |
| </p><p> |
| The <code class="literal">CONCAT</code> function returns a string that is a concatenation |
| of its arguments. The second and third arguments of the <code class="literal">SUBSTRING |
| </code> function denote the starting position and length of the substring to |
| be returned. These arguments are integers. The first position of a string is |
| denoted by 1. The <code class="literal">SUBSTRING</code> function returns a string. The |
| <code class="literal">TRIM</code> function trims the specified character from a string. If |
| the character to be trimmed is not specified, it is assumed to be space (or |
| blank). The optional trim_character is a single-character string literal or a |
| character-valued input parameter (i.e., char or Character). If a trim |
| specification is not provided, <code class="literal">BOTH</code> is assumed. The <code class="literal"> |
| TRIM</code> function returns the trimmed string. The <code class="literal">LOWER</code> |
| and <code class="literal">UPPER</code> functions convert a string to lower and upper case, |
| respectively. They return a string. The <code class="literal">LOCATE</code> function |
| returns the position of a given string within a string, starting the search at a |
| specified position. It returns the first position at which the string was found |
| as an integer. The first argument is the string to be located; the second |
| argument is the string to be searched; the optional third argument is an integer |
| that represents the string position at which the search is started (by default, |
| the beginning of the string to be searched). The first position in a string is |
| denoted by 1. If the string is not found, 0 is returned. The <code class="literal">LENGTH |
| </code> function returns the length of the string in characters as an |
| integer. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="jpa_langref_arithmetic"></a>2.5.16.2. |
| JPQL Arithmetic Functions |
| </h5></div></div></div><p> |
| </p><div class="itemizedlist"><ul type="disc"><li><p>functions_returning_numerics ::= |
| ABS(simple_arithmetic_expression) | SQRT(simple_arithmetic_expression) | |
| MOD(simple_arithmetic_expression, simple_arithmetic_expression) | |
| SIZE(collection_valued_path_expression) |
| </p></li></ul></div><p> |
| </p><p> |
| The <code class="literal">ABS</code> function takes a numeric argument and returns a |
| number (integer, float, or double) of the same type as the argument to the |
| function. The <code class="literal">SQRT</code> function takes a numeric argument and |
| returns a double. |
| </p><p> |
| Note that not all databases support the use of a trim character other than the |
| space character; use of this argument may result in queries that are not |
| portable. Note that not all databases support the use of the third argument to |
| <code class="literal">LOCATE</code>; use of this argument may result in queries that are |
| not portable. |
| </p><p> |
| The <code class="literal">MOD</code> function takes two integer arguments and returns an |
| integer. The <code class="literal">SIZE</code> function returns an integer value, the |
| number of elements of the collection. If the collection is empty, the <code class="literal"> |
| SIZE</code> function evaluates to zero. Numeric arguments to these functions |
| may correspond to the numeric Java object types as well as the primitive numeric |
| types. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="jpa_langref_datetime"></a>2.5.16.3. |
| JPQL Datetime Functions |
| </h5></div></div></div><p> |
| functions_returning_datetime:= CURRENT_DATE | CURRENT_TIME | CURRENT_TIMESTAMP |
| </p><p> |
| The datetime functions return the value of current date, time, and timestamp on |
| the database server. |
| </p></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_langref_group"></a>2.6. |
| JPQL GROUP BY, HAVING |
| </h3></div></div></div><p> |
| The <code class="literal">GROUP BY</code> construct enables the aggregation of values |
| according to a set of properties. The <code class="literal">HAVING</code> construct |
| enables conditions to be specified that further restrict the query result. Such |
| conditions are restrictions upon the groups. The syntax of the <code class="literal">GROUP |
| BY</code> and <code class="literal">HAVING</code> clauses is as follows: |
| </p><p> |
| </p><div class="itemizedlist"><ul type="disc"><li><p>groupby_clause ::= GROUP BY groupby_item {, |
| groupby_item}* |
| </p></li><li><p> |
| groupby_item ::= single_valued_path_expression | identification_variable |
| </p></li><li><p> |
| having_clause ::= HAVING conditional_expression |
| </p></li></ul></div><p> |
| </p><p> |
| If a query contains both a <code class="literal">WHERE</code> clause and a <code class="literal">GROUP |
| BY</code> clause, the effect is that of first applying the where clause, and |
| then forming the groups and filtering them according to the <code class="literal">HAVING |
| </code> clause. The <code class="literal">HAVING</code> clause causes those groups to |
| be retained that satisfy the condition of the <code class="literal">HAVING</code> clause. |
| The requirements for the <code class="literal">SELECT</code> clause when <code class="literal">GROUP |
| BY</code> is used follow those of SQL: namely, any item that appears in the |
| <code class="literal">SELECT</code> clause (other than as an argument to an aggregate |
| function) must also appear in the <code class="literal">GROUP BY</code> clause. In forming |
| the groups, null values are treated as the same for grouping purposes. Grouping |
| by an entity is permitted. In this case, the entity must contain no serialized |
| state fields or lob-valued state fields. The <code class="literal">HAVING</code> clause |
| must specify search conditions over the grouping items or aggregate functions |
| that apply to grouping items. |
| </p><p> |
| If there is no <code class="literal">GROUP BY</code> clause and the <code class="literal">HAVING |
| </code> clause is used, the result is treated as a single group, and the |
| select list can only consist of aggregate functions. When a query declares a |
| <code class="literal">HAVING</code> clause, it must always also declare a <code class="literal">GROUP |
| BY</code> clause. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_langref_select_clause"></a>2.7. |
| JPQL SELECT Clause |
| </h3></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#jpa_langref_resulttype">2.7.1. |
| JPQL Result Type of the SELECT Clause |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_constructor">2.7.2. |
| JPQL Constructor Expressions |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_null_select">2.7.3. |
| JPQL Null Values in the Query Result |
| </a></span></dt><dt><span class="section"><a href="#jpa_langref_aggregates">2.7.4. |
| JPQL Aggregate Functions |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_langref_agg_examples">2.7.4.1. |
| JPQL Aggregate Examples |
| </a></span></dt></dl></dd></dl></div><p> |
| The <code class="literal">SELECT</code> clause denotes the query result. More than one |
| value may be returned from the <code class="literal">SELECT</code> clause of a query. The |
| <code class="literal">SELECT</code> clause may contain one or more of the following |
| elements: a single range variable or identification variable that ranges over an |
| entity abstract schema type, a single-valued path expression, an aggregate |
| select expression, a constructor expression. The <code class="literal">SELECT</code> |
| clause has the following syntax: |
| </p><p> |
| </p><div class="itemizedlist"><ul type="disc"><li><p>select_clause ::= SELECT [DISTINCT] |
| select_expression {, select_expression}* |
| </p></li><li><p> |
| select_expression ::= single_valued_path_expression | aggregate_expression | |
| identification_variable | OBJECT(identification_variable) | |
| constructor_expression |
| </p></li><li><p> |
| constructor_expression ::= NEW constructor_name ( constructor_item {, |
| constructor_item}*) |
| </p></li><li><p> |
| constructor_item ::= single_valued_path_expression | aggregate_expression |
| </p></li><li><p> |
| aggregate_expression ::= { AVG | MAX | MIN | SUM } ([DISTINCT] |
| state_field_path_expression) | COUNT ([DISTINCT] identification_variable | |
| state_field_path_expression | single_valued_association_path_expression) |
| </p></li></ul></div><p> |
| </p><p> |
| For example: </p><pre class="programlisting">SELECT pub.id, pub.revenue |
| FROM Publisher pub JOIN pub.magazines mag WHERE mag.price > 5.00 |
| </pre><p> |
| </p><p> |
| Note that the <code class="literal">SELECT</code> clause must be specified to return only |
| single-valued expressions. The query below is therefore not valid: |
| </p><pre class="programlisting">SELECT mag.authors FROM Magazine AS mag</pre><p> The |
| <code class="literal">DISTINCT</code> keyword is used to specify that duplicate values |
| must be eliminated from the query result. If <code class="literal">DISTINCT</code> is not |
| specified, duplicate values are not eliminated. Standalone identification |
| variables in the <code class="literal">SELECT</code> clause may optionally be qualified by |
| the <code class="literal">OBJECT</code> operator. The <code class="literal">SELECT</code> clause |
| must not use the OBJECT operator to qualify path expressions. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="jpa_langref_resulttype"></a>2.7.1. |
| JPQL Result Type of the SELECT Clause |
| </h4></div></div></div><p> |
| The type of the query result specified by the <code class="literal">SELECT</code> clause |
| of a query is an entity abstract schema type, a state-field type, the result of |
| an aggregate function, the result of a construction operation, or some sequence |
| of these. The result type of the <code class="literal">SELECT</code> clause is defined by |
| the result types of the select_expressions contained in it. When multiple |
| select_expressions are used in the <code class="literal">SELECT</code> clause, the result |
| of the query is of type Object[], and the elements in this result correspond in |
| order to the order of their specification in the <code class="literal">SELECT</code> |
| clause and in type to the result types of each of the select_expressions. The |
| type of the result of a select_expression is as follows: </p><div class="itemizedlist"><ul type="disc"><li><p> A single_valued_path_expression that is a |
| state_field_path_expression results in an object of the same type as the |
| corresponding state field of the entity. If the state field of the entity is a |
| primitive type, the corresponding object type is returned. |
| </p></li><li><p> |
| single_valued_path_expression that is a |
| single_valued_association_path_expression results in an entity object of the |
| type of the relationship field or the subtype of the relationship field of the |
| entity object as determined by the object/relational mapping. |
| </p></li><li><p> |
| The result type of an identification_variable is the type of the entity to which |
| that identification variable corresponds or a subtype as determined by the |
| object/relational mapping. |
| </p></li><li><p> |
| The result type of aggregate_expression is defined in section |
| <a href="#jpa_langref_aggregates" title="2.7.4. JPQL Aggregate Functions">Section 2.7.4, “ |
| JPQL Aggregate Functions |
| ”</a>. |
| </p></li><li><p> |
| The result type of a constructor_expression is the type of the class for which |
| the constructor is defined. The types of the arguments to the constructor are |
| defined by the above rules. |
| </p></li></ul></div><p> |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="jpa_langref_constructor"></a>2.7.2. |
| JPQL Constructor Expressions |
| </h4></div></div></div><p> |
| A constructor may be used in the |
| <code class="literal">SELECT</code> list to return one or more Java instances. The |
| specified class is not required to be an entity or to be mapped to the database. |
| The constructor name must be fully qualified. |
| </p><p> |
| If an entity class name is specified in the <code class="literal">SELECT NEW</code> |
| clause, the resulting entity instances are in the new state. </p><pre class="programlisting">SELECT NEW com.company.PublisherInfo(pub.id, pub.revenue, mag.price) |
| FROM Publisher pub JOIN pub.magazines mag WHERE mag.price > 5.00 |
| </pre><p> |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="jpa_langref_null_select"></a>2.7.3. |
| JPQL Null Values in the Query Result |
| </h4></div></div></div><p> |
| If the result of a query corresponds to a association-field or state-field whose |
| value is null, that null value is returned in the result of the query method. |
| The <code class="literal">IS NOT NULL</code> construct can be used to eliminate such null |
| values from the result set of the query. Note, however, that state-field types |
| defined in terms of Java numeric primitive types cannot produce <code class="literal">NULL |
| </code> values in the query result. A query that returns such a state-field |
| type as a result type must not return a null value. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="jpa_langref_aggregates"></a>2.7.4. |
| JPQL Aggregate Functions |
| </h4></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#jpa_langref_agg_examples">2.7.4.1. |
| JPQL Aggregate Examples |
| </a></span></dt></dl></div><p> |
| The result of a query may be the result |
| of an aggregate function applied to a path expression. The following aggregate |
| functions can be used in the <code class="literal">SELECT</code> clause of a query: |
| <code class="literal">AVG</code>, <code class="literal">COUNT</code>, <code class="literal">MAX</code>, |
| <code class="literal">MIN</code>, <code class="literal">SUM</code>. For all aggregate functions |
| except <code class="literal">COUNT</code>, the path expression that is the argument to |
| the aggregate function must terminate in a state-field. The path expression |
| argument to <code class="literal">COUNT</code> may terminate in either a state-field or a |
| association-field, or the argument to <code class="literal">COUNT</code> may be an |
| identification variable. Arguments to the functions <code class="literal">SUM</code> and |
| <code class="literal">AVG</code> must be numeric. Arguments to the functions <code class="literal">MAX |
| </code> and <code class="literal">MIN</code> must correspond to orderable state-field |
| types (i.e., numeric types, string types, character types, or date types). The |
| Java type that is contained in the result of a query using an aggregate function |
| is as follows: </p><div class="itemizedlist"><ul type="disc"><li><p><code class="literal">COUNT</code> returns |
| Long. |
| </p></li><li><p> |
| <code class="literal">MAX</code>, <code class="literal">MIN</code> return the type of the |
| state-field to which they are applied. |
| </p></li><li><p> |
| <code class="literal">AVG</code> returns Double. |
| </p></li><li><p> |
| <code class="literal">SUM</code> returns Long when applied to state-fields of integral |
| types (other than BigInteger); Double when applied to state-fields of floating |
| point types; BigInteger when applied to state-fields of type BigInteger; and |
| BigDecimal when applied to state-fields of type BigDecimal. If <code class="literal">SUM |
| </code>, <code class="literal">AVG</code>, <code class="literal">MAX</code>, or <code class="literal">MIN |
| </code> is used, and there are no values to which the aggregate function can |
| be applied, the result of the aggregate function is <code class="literal">NULL</code>. If |
| <code class="literal">COUNT</code> is used, and there are no values to which <code class="literal"> |
| COUNT</code> can be applied, the result of the aggregate function is 0. |
| </p></li></ul></div><p> |
| </p><p> |
| The argument to an aggregate function may be preceded by the keyword <code class="literal"> |
| DISTINCT</code> to specify that duplicate values are to be eliminated before |
| the aggregate function is applied. |
| It is legal to specify <code class="literal">DISTINCT</code> with <code class="literal">MAX</code> |
| or <code class="literal">MIN</code>, but it does not affect the result. |
| Null values are eliminated before the |
| aggregate function is applied, regardless of whether the keyword <code class="literal"> |
| DISTINCT</code> is specified. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="jpa_langref_agg_examples"></a>2.7.4.1. |
| JPQL Aggregate Examples |
| </h5></div></div></div><p> |
| The following query returns the average price of all magazines: |
| </p><pre class="programlisting">SELECT AVG(mag.price) FROM Magazine mag</pre><p> The |
| following query returns the sum of all the prices from all the |
| magazines published by 'Larry': </p><pre class="programlisting">SELECT SUM(mag.price) FROM Publisher pub JOIN pub.magazines mag pub.firstName = 'Larry' |
| </pre><p> The following query returns the total number of magazines: |
| </p><pre class="programlisting">SELECT COUNT(mag) FROM Magazine mag</pre><p> |
| </p></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_langref_orderby"></a>2.8. |
| JPQL ORDER BY Clause |
| </h3></div></div></div><p> |
| The <code class="literal">ORDER BY</code> clause allows the objects or values that are |
| returned by the query to be ordered. The syntax of the <code class="literal">ORDER BY |
| </code> clause is |
| </p><p> |
| </p><div class="itemizedlist"><ul type="disc"><li><p>orderby_clause ::= ORDER BY orderby_item {, |
| orderby_item}* |
| </p></li><li><p> |
| orderby_item ::= state_field_path_expression [ASC | DESC] |
| </p></li></ul></div><p> |
| </p><p> |
| When the <code class="literal">ORDER BY</code> clause is used in a query, each element of |
| the <code class="literal">SELECT</code> clause of the query must be one of the following: |
| an identification variable x, optionally denoted as <code class="literal">OBJECT(x)</code> |
| , a single_valued_association_path_expression, or a state_field_path_expression. |
| For example: </p><pre class="programlisting"> |
| SELECT pub FROM Publisher pub ORDER BY pub.revenue, pub.name |
| </pre><p> If more than one orderby_item is specified, the left-to-right |
| sequence of the orderby_item elements determines the precedence, whereby the |
| leftmost orderby_item has highest precedence. The keyword <code class="literal">ASC</code> |
| specifies that ascending ordering be used; the keyword <code class="literal">DESC</code> |
| specifies that descending ordering be used. Ascending ordering is the default. |
| SQL rules for the ordering of null values apply: that is, all null values must |
| appear before all non-null values in the ordering or all null values must appear |
| after all non-null values in the ordering, but it is not specified which. The |
| ordering of the query result is preserved in the result of the query method if |
| the <code class="literal">ORDER BY</code> clause is used. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_langref_bulk_ops"></a>2.9. |
| JPQL Bulk Update and Delete |
| </h3></div></div></div><p> |
| Bulk update and delete operations apply to entities of a single |
| entity class (together with its subclasses, if any). Only one entity abstract |
| schema type may be specified in the <code class="literal">FROM</code> or <code class="literal">UPDATE |
| </code> clause. The syntax of these operations is as follows: |
| </p><p> |
| </p><div class="itemizedlist"><ul type="disc"><li><p>update_statement ::= update_clause [where_clause] |
| </p></li><li><p> |
| update_clause ::= UPDATE abstract_schema_name [[AS] identification_variable] SET |
| update_item {, update_item}* |
| </p></li><li><p> |
| update_item ::= [identification_variable.]{state_field | |
| single_valued_association_field} = new_value |
| </p></li><li><p> |
| new_value ::= simple_arithmetic_expression | string_primary | datetime_primary | |
| boolean_primary | enum_primary simple_entity_expression | NULL |
| </p></li><li><p> |
| delete_statement ::= delete_clause [where_clause] |
| </p></li><li><p> |
| delete_clause ::= DELETE FROM abstract_schema_name [[AS] |
| identification_variable] |
| </p></li></ul></div><p> |
| </p><p> |
| The syntax of the <code class="literal">WHERE</code> clause is described in |
| <a href="#jpa_langref_where" title="2.4. JPQL WHERE Clause">Section 2.4, “ |
| JPQL WHERE Clause |
| ”</a>. A delete operation only applies to |
| entities of the specified class and its subclasses. It does not cascade to |
| related entities. The new_value specified for an update operation must be |
| compatible in type with the state-field to which it is assigned. Bulk update |
| maps directly to a database update operation, bypassing optimistic locking |
| checks. Portable applications must manually update the value of the version |
| column, if desired, and/or manually validate the value of the version column. |
| The persistence context is not synchronized with the result of the bulk update |
| or delete. Caution should be used when executing bulk update or delete |
| operations because they may result in inconsistencies between the database and |
| the entities in the active persistence context. In general, bulk update and |
| delete operations should only be performed within a separate transaction or at |
| the beginning of a transaction (before entities have been accessed whose state |
| might be affected by such operations). |
| </p><p> |
| Examples: </p><pre class="programlisting">DELETE FROM Publisher pub WHERE pub.revenue > 1000000.0 |
| </pre><pre class="programlisting">DELETE FROM Publisher pub WHERE pub.revenue = 0 AND pub.magazines IS EMPTY |
| </pre><pre class="programlisting">UPDATE Publisher pub SET pub.status = 'outstanding' |
| WHERE pub.revenue < 1000000 AND 20 > (SELECT COUNT(mag) FROM pub.magazines mag) |
| </pre><p> |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_langref_null_values"></a>2.10. |
| JPQL Null Values |
| </h3></div></div></div><p> |
| When the target of a reference does not exist in the database, its value is |
| regarded as <code class="literal">NULL</code>. SQL 92 <code class="literal">NULL</code> semantics |
| defines the evaluation of conditional expressions containing <code class="literal">NULL |
| </code> values. The following is a brief description of these semantics: |
| </p><p> |
| </p><div class="itemizedlist"><ul type="disc"><li><p> Comparison or arithmetic operations with a |
| <code class="literal">NULL</code> value always yield an unknown value. |
| </p></li><li><p> |
| Two <code class="literal">NULL</code> values are not considered to be equal, the |
| comparison yields an unknown value. |
| </p></li><li><p> |
| Comparison or arithmetic operations with an unknown value always yield an |
| unknown value. |
| </p></li><li><p> |
| The <code class="literal">IS NULL</code> and <code class="literal">IS NOT NULL</code> operators |
| convert a <code class="literal">NULL</code> state-field or single-valued association-field |
| value into the respective <code class="literal">TRUE</code> or <code class="literal">FALSE</code> |
| value. |
| </p></li></ul></div><p> |
| </p><p> |
| Note: The JPQL defines the empty string, "", as a string with 0 length, which is |
| not equal to a <code class="literal">NULL</code> value. However, <code class="literal">NULL</code> |
| values and empty strings may not always be distinguished when queries are mapped |
| to some databases. Application developers should therefore not rely on the |
| semantics of query comparisons involving the empty string and <code class="literal">NULL |
| </code> value. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_langref_equality"></a>2.11. |
| JPQL Equality and Comparison Semantics |
| </h3></div></div></div><p> |
| Only the values of like types are permitted to be compared. A type is like |
| another type if they correspond to the same Java language type, or if one is a |
| primitive Java language type and the other is the wrappered Java class type |
| equivalent (e.g., int and Integer are like types in this sense). There is one |
| exception to this rule: it is valid to compare numeric values for which the |
| rules of numeric promotion apply. Conditional expressions attempting to compare |
| non-like type values are disallowed except for this numeric case. Note that the |
| arithmetic operators and comparison operators are permitted to be applied to |
| state-fields and input parameters of the wrappered Java class equivalents to the |
| primitive numeric Java types. Two entities of the same abstract schema type are |
| equal if and only if they have the same primary key value. Only |
| equality/inequality comparisons over enums are required to be supported. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_langref_bnf"></a>2.12. |
| JPQL BNF |
| </h3></div></div></div><p> |
| The following is the BNF for the Java Persistence query language, from section |
| 4.14 of the JSR 220 specification. |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| QL_statement ::= select_statement | update_statement | delete_statement |
| </p></li><li><p> |
| select_statement ::= select_clause from_clause [where_clause] [groupby_clause] |
| [having_clause] [orderby_clause] |
| </p></li><li><p> |
| update_statement ::= update_clause [where_clause] |
| </p></li><li><p> |
| delete_statement ::= delete_clause [where_clause] |
| </p></li><li><p> |
| from_clause ::= <code class="literal">FROM</code> identification_variable_declaration {, |
| {identification_variable_declaration | collection_member_declaration}}* |
| </p></li><li><p> |
| identification_variable_declaration ::= range_variable_declaration { join | |
| fetch_join }* |
| </p></li><li><p> |
| range_variable_declaration ::= abstract_schema_name [ <code class="literal">AS</code> ] |
| identification_variable |
| </p></li><li><p> |
| join ::= join_spec join_association_path_expression [ <code class="literal">AS</code> ] |
| identification_variable |
| </p></li><li><p> |
| fetch_join ::= join_spec <code class="literal">FETCH</code> |
| join_association_path_expression |
| </p></li><li><p> |
| association_path_expression ::= collection_valued_path_expression | |
| single_valued_association_path_expression |
| </p></li><li><p> |
| join_spec ::= [ <code class="literal">LEFT</code> [ <code class="literal">OUTER</code> ]| <code class="literal"> |
| INNER</code> ] <code class="literal">JOIN</code> |
| </p></li><li><p> |
| join_association_path_expression ::= join_collection_valued_path_expression | |
| join_single_valued_association_path_expression |
| </p></li><li><p> |
| join_collection_valued_path_expression ::= |
| identification_variable.collection_valued_association_field |
| </p></li><li><p> |
| join_single_valued_association_path_expression ::= |
| identification_variable.single_valued_association_field |
| </p></li><li><p> |
| collection_member_declaration ::= <code class="literal">IN</code> |
| (collection_valued_path_expression) [ <code class="literal">AS</code> ] |
| identification_variable |
| </p></li><li><p> |
| single_valued_path_expression ::= state_field_path_expression | |
| single_valued_association_path_expression |
| </p></li><li><p> |
| state_field_path_expression ::= {identification_variable | |
| single_valued_association_path_expression}.state_field |
| </p></li><li><p> |
| single_valued_association_path_expression ::= |
| identification_variable.{single_valued_association_field.}* |
| single_valued_association_field |
| </p></li><li><p> |
| collection_valued_path_expression ::= |
| identification_variable.{single_valued_association_field.}*collection_valued_association_field |
| </p></li><li><p> |
| state_field ::= {embedded_class_state_field.}*simple_state_field |
| </p></li><li><p> |
| update_clause ::= <code class="literal">UPDATE</code> abstract_schema_name [[ <code class="literal">AS |
| </code> ] identification_variable] <code class="literal">SET</code> update_item {, |
| update_item}* |
| </p></li><li><p> |
| update_item ::= [identification_variable.]{state_field | |
| single_valued_association_field}= new_value |
| </p></li><li><p> |
| new_value ::= simple_arithmetic_expression | string_primary | datetime_primary | |
| boolean_primary | enum_primary simple_entity_expression | <code class="literal">NULL |
| </code> |
| </p></li><li><p> |
| delete_clause ::= <code class="literal">DELETE</code><code class="literal">FROM</code> |
| abstract_schema_name [[ <code class="literal">AS</code> ] identification_variable] |
| </p></li><li><p> |
| select_clause ::= <code class="literal">SELECT</code> [ <code class="literal">DISTINCT</code> ] |
| select_expression {, select_expression}* |
| </p></li><li><p> |
| select_expression ::= single_valued_path_expression | aggregate_expression | |
| identification_variable | <code class="literal">OBJECT</code> (identification_variable)| |
| constructor_expression |
| </p></li><li><p> |
| constructor_expression ::= <code class="literal">NEW</code> constructor_name( |
| constructor_item {, constructor_item}*) |
| </p></li><li><p> |
| constructor_item ::= single_valued_path_expression | aggregate_expression |
| </p></li><li><p> |
| aggregate_expression ::= { <code class="literal">AVG</code> | <code class="literal">MAX</code> | |
| <code class="literal">MIN</code> | <code class="literal">SUM</code> }([ <code class="literal">DISTINCT</code> |
| ] state_field_path_expression) | <code class="literal">COUNT</code> ([ <code class="literal">DISTINCT |
| </code> ] identification_variable | state_field_path_expression | |
| single_valued_association_path_expression) |
| </p></li><li><p> |
| where_clause ::= <code class="literal">WHERE</code> conditional_expression |
| </p></li><li><p> |
| groupby_clause ::= <code class="literal">GROUP</code><code class="literal">BY</code> groupby_item {, |
| groupby_item}* |
| </p></li><li><p> |
| groupby_item ::= single_valued_path_expression | identification_variable |
| </p></li><li><p> |
| having_clause ::= <code class="literal">HAVING</code> conditional_expression |
| </p></li><li><p> |
| orderby_clause ::= <code class="literal">ORDER</code><code class="literal">BY</code> orderby_item {, |
| orderby_item}* |
| </p></li><li><p> |
| orderby_item ::= state_field_path_expression [ <code class="literal">ASC</code> | |
| <code class="literal">DESC</code> ] |
| </p></li><li><p> |
| subquery ::= simple_select_clause subquery_from_clause [where_clause] |
| [groupby_clause] [having_clause] |
| </p></li><li><p> |
| subquery_from_clause ::= <code class="literal">FROM</code> |
| subselect_identification_variable_declaration {, |
| subselect_identification_variable_declaration}* |
| </p></li><li><p> |
| subselect_identification_variable_declaration ::= |
| identification_variable_declaration | association_path_expression [ <code class="literal">AS |
| </code> ] identification_variable | collection_member_declaration |
| </p></li><li><p> |
| simple_select_clause ::= <code class="literal">SELECT</code> [ <code class="literal">DISTINCT</code> |
| ] simple_select_expression |
| </p></li><li><p> |
| simple_select_expression ::= single_valued_path_expression | |
| aggregate_expression | identification_variable |
| </p></li><li><p> |
| conditional_expression ::= conditional_term | conditional_expression <code class="literal"> |
| OR</code> conditional_term |
| </p></li><li><p> |
| conditional_term ::= conditional_factor | conditional_term <code class="literal">AND |
| </code> conditional_factor |
| </p></li><li><p> |
| conditional_factor ::= [ <code class="literal">NOT</code> ] conditional_primary |
| </p></li><li><p> |
| conditional_primary ::= simple_cond_expression |(conditional_expression) |
| </p></li><li><p> |
| simple_cond_expression ::= comparison_expression | between_expression | |
| like_expression | in_expression | null_comparison_expression | |
| empty_collection_comparison_expression | collection_member_expression | |
| exists_expression |
| </p></li><li><p> |
| between_expression ::= arithmetic_expression [ <code class="literal">NOT</code> ] |
| <code class="literal">BETWEEN</code> arithmetic_expression <code class="literal">AND</code> |
| arithmetic_expression | string_expression [ <code class="literal">NOT</code> ] <code class="literal"> |
| BETWEEN</code> string_expression <code class="literal">AND</code> string_expression | |
| datetime_expression [ <code class="literal">NOT</code> ] <code class="literal">BETWEEN</code> |
| datetime_expression <code class="literal">AND</code> datetime_expression |
| </p></li><li><p> |
| in_expression ::= state_field_path_expression [ <code class="literal">NOT</code> ] |
| <code class="literal">IN</code> ( in_item {, in_item}* | subquery) |
| </p></li><li><p> |
| in_item ::= literal | input_parameter |
| </p></li><li><p> |
| like_expression ::= string_expression [ <code class="literal">NOT</code> ] <code class="literal">LIKE |
| </code> pattern_value [ <code class="literal">ESCAPE</code> escape_character] |
| </p></li><li><p> |
| null_comparison_expression ::= {single_valued_path_expression | input_parameter} |
| <code class="literal">IS</code> [ <code class="literal">NOT</code> ] <code class="literal">NULL</code> |
| </p></li><li><p> |
| empty_collection_comparison_expression ::= collection_valued_path_expression |
| <code class="literal">IS</code> [ <code class="literal">NOT</code> ] <code class="literal">EMPTY</code> |
| </p></li><li><p> |
| collection_member_expression ::= entity_expression [ <code class="literal">NOT</code> ] |
| <code class="literal">MEMBER</code> [ <code class="literal">OF</code> ] |
| collection_valued_path_expression |
| </p></li><li><p> |
| exists_expression ::= [ <code class="literal">NOT</code> ] <code class="literal">EXISTS</code> |
| (subquery) |
| </p></li><li><p> |
| all_or_any_expression ::= { <code class="literal">ALL</code> | <code class="literal">ANY</code> | |
| <code class="literal">SOME</code> }(subquery) |
| </p></li><li><p> |
| comparison_expression ::= |
| string_expressioncomparison_operator{string_expression|all_or_any_expression}| |
| boolean_expression {=|<>} {boolean_expression | all_or_any_expression} | |
| enum_expression {=|<>} {enum_expression | all_or_any_expression} | |
| datetime_expression comparison_operator {datetime_expression | |
| all_or_any_expression} | entity_expression {= |<> } {entity_expression | |
| all_or_any_expression} | arithmetic_expression comparison_operator |
| {arithmetic_expression | all_or_any_expression} |
| </p></li><li><p> |
| comparison_operator ::== |> |>= |< |<= |<> |
| </p></li><li><p> |
| arithmetic_expression ::= simple_arithmetic_expression |(subquery) |
| </p></li><li><p> |
| simple_arithmetic_expression ::= arithmetic_term | simple_arithmetic_expression |
| {+ |- } arithmetic_term |
| </p></li><li><p> |
| arithmetic_term ::= arithmetic_factor | arithmetic_term {* |/ } |
| arithmetic_factor |
| </p></li><li><p> |
| arithmetic_factor ::= [{+ |-}] arithmetic_primary |
| </p></li><li><p> |
| arithmetic_primary ::= state_field_path_expression | numeric_literal | |
| (simple_arithmetic_expression) | input_parameter | functions_returning_numerics |
| | aggregate_expression |
| </p></li><li><p> |
| string_expression ::= string_primary |(subquery) |
| </p></li><li><p> |
| string_primary ::= state_field_path_expression | string_literal | |
| input_parameter | functions_returning_strings | aggregate_expression |
| </p></li><li><p> |
| datetime_expression ::= datetime_primary |(subquery) |
| </p></li><li><p> |
| datetime_primary ::= state_field_path_expression | input_parameter | |
| functions_returning_datetime | aggregate_expression |
| </p></li><li><p> |
| boolean_expression ::= boolean_primary |(subquery) |
| </p></li><li><p> |
| boolean_primary ::= state_field_path_expression | boolean_literal | |
| input_parameter | |
| </p></li><li><p> |
| enum_expression ::= enum_primary |(subquery) |
| </p></li><li><p> |
| enum_primary ::= state_field_path_expression | enum_literal | input_parameter | |
| </p></li><li><p> |
| entity_expression ::= single_valued_association_path_expression | |
| simple_entity_expression |
| </p></li><li><p> |
| simple_entity_expression ::= identification_variable | input_parameter |
| </p></li><li><p> |
| functions_returning_numerics ::= <code class="literal">LENGTH</code> (string_primary)| |
| <code class="literal">LOCATE</code> (string_primary,string_primary [, |
| simple_arithmetic_expression]) | <code class="literal">ABS</code> |
| (simple_arithmetic_expression) | <code class="literal">SQRT</code> |
| (simple_arithmetic_expression) | <code class="literal">MOD</code> |
| (simple_arithmetic_expression, simple_arithmetic_expression) | <code class="literal">SIZE |
| </code> (collection_valued_path_expression) |
| </p></li><li><p> |
| functions_returning_datetime ::= <code class="literal">CURRENT_DATE</code> | <code class="literal"> |
| CURRENT_TIME</code> | <code class="literal">CURRENT_TIMESTAMP</code> |
| </p></li><li><p> |
| functions_returning_strings ::= <code class="literal">CONCAT</code> (string_primary, |
| string_primary) | <code class="literal">SUBSTRING</code> (string_primary, |
| simple_arithmetic_expression,simple_arithmetic_expression)| <code class="literal">TRIM |
| </code> ([[trim_specification] [trim_character] <code class="literal">FROM</code> ] |
| string_primary) | <code class="literal">LOWER</code> (string_primary) | <code class="literal">UPPER |
| </code> (string_primary) |
| </p></li><li><p> |
| trim_specification ::= <code class="literal">LEADING</code> | <code class="literal">TRAILING</code> |
| | <code class="literal">BOTH</code> |
| </p></li></ul></div></div></div></div><div class="chapter" lang="en" id="jpa_overview_sqlquery"><div class="titlepage"><div><div><h2 class="title"><a name="jpa_overview_sqlquery"></a>Chapter 11. |
| SQL Queries |
| </h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#jpa_overview_sqlquery_create">1. |
| Creating SQL Queries |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_sqlquery_obj">2. |
| Retrieving Persistent Objects with SQL |
| </a></span></dt></dl></div><a class="indexterm" name="d0e9235"></a><a class="indexterm" name="d0e9240"></a><a class="indexterm" name="d0e9247"></a><a class="indexterm" name="d0e9254"></a><p> |
| JPQL is a powerful query language, but there are times when it is not enough. |
| Maybe you're migrating a JDBC application to JPA on a strict deadline, and you |
| don't have time to translate your existing SQL selects to JPQL. Or maybe a |
| certain query requires database-specific SQL your JPA implementation doesn't |
| support. Or maybe your DBA has spent hours crafting the perfect select statement |
| for a query in your application's critical path. Whatever the reason, SQL |
| queries can remain an essential part of an application. |
| </p><p> |
| You are probably familiar with executing SQL queries by obtaining a <code class="classname"> |
| java.sql.Connection</code>, using the JDBC APIs to create a <code class="classname"> |
| Statement</code>, and executing that <code class="classname">Statement</code> to |
| obtain a <code class="classname">ResultSet</code>. And of course, you are free to |
| continue using this low-level approach to SQL execution in your JPA |
| applications. However, JPA also supports executing SQL queries through the |
| <code class="classname">javax.persistence.Query</code> interface introduced in |
| <a href="#jpa_overview_query" title="Chapter 10. JPA Query">Chapter 10, <i xmlns:xlink="http://www.w3.org/1999/xlink"> |
| JPA Query |
| </i></a>. Using a JPA SQL query, you can |
| retrieve either persistent objects or projections of column values. The |
| following sections detail each use. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="jpa_overview_sqlquery_create"></a>1. |
| Creating SQL Queries |
| </h2></div></div></div><a class="indexterm" name="d0e9285"></a><p> |
| The <code class="classname">EntityManager</code> has two factory methods suitable for |
| creating SQL queries: |
| </p><pre class="programlisting"> |
| public Query createNativeQuery(String sqlString, Class resultClass); |
| public Query createNativeQuery(String sqlString, String resultSetMapping); |
| </pre><p> |
| The first method is used to create a new <code class="classname">Query</code> instance |
| that will return instances of the specified class. |
| </p><p> |
| The second method uses a <code class="literal">SqlResultSetMapping</code> to determine the |
| type of object or objects to return. The example below shows these methods in |
| action. |
| </p><div class="example"><a name="jpa_overview_sqlquery_createex"></a><p class="title"><b>Example 11.1. |
| Creating a SQL Query |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| EntityManager em = ...; |
| Query query = em.createNativeQuery("SELECT * FROM MAG", Magazine.class); |
| processMagazines(query.getResultList()); |
| </pre></div></div><br class="example-break"><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| <a class="indexterm" name="d0e9315"></a> |
| <a class="indexterm" name="d0e9321"></a> |
| In addition to SELECT statements, OpenJPA supports stored procedure invocations |
| as SQL queries. OpenJPA will assume any SQL that does not begin with the |
| <code class="literal">SELECT</code> keyword (ignoring case) is a stored procedure call, |
| and invoke it as such at the JDBC level. |
| </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="jpa_overview_sqlquery_obj"></a>2. |
| Retrieving Persistent Objects with SQL |
| </h2></div></div></div><a class="indexterm" name="d0e9335"></a><a class="indexterm" name="d0e9340"></a><p> |
| When you give a SQL <code class="classname">Query</code> a candidate class, it will |
| return persistent instances of that class. At a minimum, your SQL must select |
| the class' primary key columns, discriminator column (if mapped), and version |
| column (also if mapped). The JPA runtime uses the values of the primary key |
| columns to construct each result object's identity, and possibly to match it |
| with a persistent object already in the <code class="classname">EntityManager</code>'s |
| cache. When an object is not already cached, the implementation creates a new |
| object to represent the current result row. It might use the discriminator |
| column value to make sure it constructs an object of the correct subclass. |
| Finally, the query records available version column data for use in optimistic |
| concurrency checking, should you later change the result object and flush it |
| back to the database. |
| </p><p> |
| Aside from the primary key, discriminator, and version columns, any columns you |
| select are used to populate the persistent fields of each result object. JPA |
| implementations will compete on how effectively they map your selected data to |
| your persistent instance fields. |
| </p><p> |
| Let's make the discussion above concrete with an example. It uses the following |
| simple mapping between a class and the database: |
| </p><div class="mediaobject"><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="213"><tr><td><img src="img/sqlquery-model.png"></td></tr></table></div><div class="example"><a name="jpa_overview_sqlquery_objex"></a><p class="title"><b>Example 11.2. |
| Retrieving Persistent Objects |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| Query query = em.createNativeQuery("SELECT ISBN, TITLE, PRICE, " |
| + "VERS FROM MAG WHERE PRICE > 5 AND PRICE < 10", Magazine.class); |
| List<Magazine> results = (List<Magazine>) query.getResultList(); |
| for (Magazine mag : results) |
| processMagazine(mag); |
| </pre></div></div><br class="example-break"><p> |
| The query above works as advertised, but isn't very flexible. Let's update it to |
| take in parameters for the minimum and maximum price, so we can reuse it to find |
| magazines in any price range: |
| </p><div class="example"><a name="jpa_overview_sqlquery_obj_paramex"></a><p class="title"><b>Example 11.3. |
| SQL Query Parameters |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| Query query = em.createNativeQuery("SELECT ISBN, TITLE, PRICE, " |
| + "VERS FROM MAG WHERE PRICE > ?1 AND PRICE < ?2", Magazine.class); |
| |
| query.setParameter(1, 5d); |
| query.setParameter(2, 10d); |
| |
| List<Magazine> results = (List<Magazine>) query.getResultList(); |
| for (Magazine mag : results) |
| processMagazine (mag); |
| </pre></div></div><br class="example-break"><p> |
| <a class="indexterm" name="d0e9377"></a> |
| <a class="indexterm" name="d0e9383"></a> |
| Like JDBC prepared statements, SQL queries represent parameters with question |
| marks, but are followed by an integer to represent its index. |
| </p></div></div><div class="chapter" lang="en" id="jpa_overview_mapping"><div class="titlepage"><div><div><h2 class="title"><a name="jpa_overview_mapping"></a>Chapter 12. |
| Mapping Metadata |
| </h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#jpa_overview_mapping_table">1. |
| Table |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_mapping_unq">2. |
| Unique Constraints |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_mapping_column">3. |
| Column |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_mapping_id">4. |
| Identity Mapping |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_mapping_sequence">5. |
| Generators |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_mapping_sequence_seqgen">5.1. |
| Sequence Generator |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_mapping_sequence_tablegen">5.2. |
| TableGenerator |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_mapping_sequence_genex">5.3. |
| Example |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_overview_mapping_inher">6. |
| Inheritance |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_mapping_inher_single">6.1. |
| Single Table |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_mapping_inher_single_adv">6.1.1. |
| Advantages |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_mapping_inher_single_disadv">6.1.2. |
| Disadvantages |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_overview_mapping_inher_joined">6.2. |
| Joined |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_mapping_inher_joined_adv">6.2.1. |
| Advantages |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_mapping_inher_joined_disadv">6.2.2. |
| Disadvantages |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_overview_mapping_inher_tpc">6.3. |
| Table Per Class |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_mapping_inher_tpc_adv">6.3.1. |
| Advantages |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_mapping_inher_tpc_disadv">6.3.2. |
| Disadvantages |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_overview_mapping_inher_together">6.4. |
| Putting it All Together |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_overview_mapping_discrim">7. |
| Discriminator |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_mapping_field">8. |
| Field Mapping |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_mapping_basic">8.1. |
| Basic Mapping |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_mapping_lob">8.1.1. |
| LOBs |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_mapping_enum">8.1.2. |
| Enumerated |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_mapping_temporal">8.1.3. |
| Temporal Types |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_mapping_basic_example">8.1.4. |
| The Updated Mappings |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_overview_mapping_secondary">8.2. |
| Secondary Tables |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_mapping_embed">8.3. |
| Embedded Mapping |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_mapping_rel">8.4. |
| Direct Relations |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_mapping_assoccoll">8.5. |
| Join Table |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_mapping_bidi">8.6. |
| Bidirectional Mapping |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_mapping_map">8.7. |
| Map Mapping |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_overview_mapping_full">9. |
| The Complete Mappings |
| </a></span></dt></dl></div><a class="indexterm" name="d0e9395"></a><a class="indexterm" name="d0e9398"></a><a class="indexterm" name="d0e9405"></a><a class="indexterm" name="d0e9412"></a><a class="indexterm" name="d0e9417"></a><p> |
| <span class="emphasis"><em>Object-relational mapping</em></span> is the process of mapping |
| entities to relational database tables. In JPA, you perform |
| object/relational mapping through <span class="emphasis"><em>mapping metadata</em></span>. |
| Mapping metadata uses annotations to describe how to link your object model to |
| your relational model. |
| </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| OpenJPA offers tools to automate mapping and schema creation. See |
| <a href="#ref_guide_mapping" title="Chapter 7. Mapping">Chapter 7, <i xmlns:xlink="http://www.w3.org/1999/xlink"> |
| Mapping |
| </i></a> in the Reference Guide. |
| </p></div><p> |
| Throughout this chapter, we will draw on the object model introduced in |
| <a href="#jpa_overview_meta" title="Chapter 5. Metadata">Chapter 5, <i xmlns:xlink="http://www.w3.org/1999/xlink"> |
| Metadata |
| </i></a>. We present that model again below. |
| As we discuss various aspects of mapping metadata, we will zoom in on specific |
| areas of the model and show how we map the object layer to the relational layer. |
| </p><div class="mediaobject"><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="369"><tr><td><img src="img/jpa-meta-model.png"></td></tr></table></div><p> |
| All mapping metadata is optional. Where no explicit mapping metadata is given, |
| JPA uses the defaults defined by the specification. As we present |
| each mapping throughout this chapter, we also describe the defaults that apply |
| when the mapping is absent. |
| </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| Mapping metadata is used primarily with schema generation. This metadata should not |
| be relied upon for validation prior to communicating with the database. |
| For example using the @Column(nullable=false) annotation does not do up front validation |
| that the value in the entity is correct. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="jpa_overview_mapping_table"></a>1. |
| Table |
| </h2></div></div></div><a class="indexterm" name="d0e9453"></a><p> |
| The <code class="classname">Table</code> annotation specifies the table for an entity |
| class. If you omit the <code class="classname">Table</code> annotation, base entity |
| classes default to a table with their unqualified class name. The default table |
| of an entity subclass depends on the inheritance strategy, as you will see in |
| <a href="#jpa_overview_mapping_inher" title="6. Inheritance">Section 6, “ |
| Inheritance |
| ”</a>. |
| </p><p> |
| <code class="classname">Table</code>s have the following properties: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">String name</code>: The name of the table. Defaults to the |
| unqualified entity class name. |
| </p></li><li><p> |
| <code class="literal">String schema</code>: The table's schema. If you do not name a |
| schema, JPA uses the default schema for the database connection. |
| </p></li><li><p> |
| <code class="literal">String catalog</code>: The table's catalog. If you do not name a |
| catalog, JPA uses the default catalog for the database connection. |
| </p></li><li><p> |
| <code class="literal">UniqueConstraint[] uniqueConstraints</code>: An array of unique |
| constraints to place on the table. We cover unique constraints below. Defaults |
| to an empty array. |
| </p></li></ul></div><p> |
| The equivalent XML element is <code class="literal">table</code>. It has the following |
| attributes, which correspond to the annotation properties above: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">name</code> |
| </p></li><li><p> |
| <code class="literal">schema</code> |
| </p></li><li><p> |
| <code class="literal">catalog</code> |
| </p></li></ul></div><p> |
| The <code class="literal">table</code> element also accepts nested <code class="literal"> |
| unique-constraint</code> elements representing unique constraints. We will |
| detail unique constraints shortly. |
| </p><p> |
| Sometimes, some of the fields in a class are mapped to secondary tables. In that |
| case, use the class' <code class="classname">Table</code> annotation to name what you |
| consider the class' primary table. Later, we will see how to map certain fields |
| to other tables. |
| </p><p> |
| The example below maps classes to tables to separate schemas. The |
| <code class="literal">CONTRACT</code>, <code class="literal">SUB</code>, and <code class="literal">LINE_ITEM |
| </code> tables are in the <code class="literal">CNTRCT</code> schema; all other tables |
| are in the default schema. |
| </p><div class="example"><a name="jpa_overview_mapping_classex"></a><p class="title"><b>Example 12.1. |
| Mapping Classes |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| package org.mag; |
| |
| @Entity |
| @IdClass(Magazine.MagazineId.class) |
| @Table(name="MAG") |
| public class Magazine { |
| ... |
| |
| public static class MagazineId { |
| ... |
| } |
| } |
| |
| @Entity |
| @Table(name="ART") |
| public class Article { |
| ... |
| } |
| |
| |
| package org.mag.pub; |
| |
| @Entity |
| @Table(name="COMP") |
| public class Company { |
| ... |
| } |
| |
| @Entity |
| @Table(name="AUTH") |
| public class Author { |
| ... |
| } |
| |
| @Embeddable |
| public class Address { |
| ... |
| } |
| |
| |
| package org.mag.subscribe; |
| |
| @MappedSuperclass |
| public abstract class Document { |
| ... |
| } |
| |
| @Entity |
| @Table(schema="CNTRCT") |
| public class Contract |
| extends Document { |
| ... |
| } |
| |
| @Entity |
| @Table(name="SUB", schema="CNTRCT") |
| public class Subscription { |
| ... |
| |
| @Entity |
| @Table(name="LINE_ITEM", schema="CNTRCT") |
| public static class LineItem |
| extends Contract { |
| ... |
| } |
| } |
| |
| @Entity(name="Lifetime") |
| public class LifetimeSubscription |
| extends Subscription { |
| ... |
| } |
| |
| @Entity(name="Trial") |
| public class TrialSubscription |
| extends Subscription { |
| ... |
| } |
| </pre><p> |
| The same mapping information expressed in XML: |
| </p><pre class="programlisting"> |
| <entity-mappings 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_1_0.xsd" |
| version="1.0"> |
| <mapped-superclass class="org.mag.subscribe.Document"> |
| ... |
| </mapped-superclass> |
| <entity class="org.mag.Magazine"> |
| <table name="MAG"/> |
| <id-class="org.mag.Magazine.MagazineId"/> |
| ... |
| </entity> |
| <entity class="org.mag.Article"> |
| <table name="ART"/> |
| ... |
| </entity> |
| <entity class="org.mag.pub.Company"> |
| <table name="COMP"/> |
| ... |
| </entity> |
| <entity class="org.mag.pub.Author"> |
| <table name="AUTH"/> |
| ... |
| </entity> |
| <entity class="org.mag.subcribe.Contract"> |
| <table schema="CNTRCT"/> |
| ... |
| </entity> |
| <entity class="org.mag.subcribe.Subscription"> |
| <table name="SUB" schema="CNTRCT"/> |
| ... |
| </entity> |
| <entity class="org.mag.subscribe.Subscription.LineItem"> |
| <table name="LINE_ITEM" schema="CNTRCT"/> |
| ... |
| </entity> |
| <entity class="org.mag.subscribe.LifetimeSubscription" name="Lifetime"> |
| ... |
| </entity> |
| <entity class="org.mag.subscribe.TrialSubscription" name="Trial"> |
| ... |
| </entity> |
| <embeddable class="org.mag.pub.Address"> |
| ... |
| </embeddable> |
| </entity-mappings> |
| </pre></div></div><br class="example-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="jpa_overview_mapping_unq"></a>2. |
| Unique Constraints |
| </h2></div></div></div><a class="indexterm" name="d0e9563"></a><a class="indexterm" name="d0e9570"></a><p> |
| Unique constraints ensure that the data in a column or combination of columns is |
| unique for each row. A table's primary key, for example, functions as an |
| implicit unique constraint. In JPA, you represent other unique |
| constraints with an array of <code class="classname"> UniqueConstraint</code> |
| annotations within the table annotation. The unique constraints you define are |
| used during table creation to generate the proper database constraints, and may |
| also be used at runtime to order <code class="literal">INSERT</code>, <code class="literal">UPDATE |
| </code>, and <code class="literal">DELETE</code> statements. For example, suppose there |
| is a unique constraint on the columns of field <code class="literal">F</code>. In the |
| same transaction, you remove an object <code class="literal">A</code> and persist a new |
| object <code class="literal">B</code>, both with the same <code class="literal">F</code> value. The |
| JPA runtime must ensure that the SQL deleting <code class="literal">A</code> |
| is sent to the database before the SQL inserting <code class="literal">B</code> to avoid a |
| unique constraint violation. |
| </p><p> |
| <code class="classname">UniqueConstraint</code> has a single property: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">String[] columnNames</code>: The names of the columns the |
| constraint spans. |
| </p></li></ul></div><p> |
| In XML, unique constraints are represented by nesting <code class="literal"> |
| unique-constraint</code> elements within the <code class="literal"> table</code> |
| element. Each <code class="literal">unique-constraint</code> element in turn nests |
| <code class="literal">column-name</code> text elements to enumerate the contraint's |
| columns. |
| </p><div class="example"><a name="jpa_overview_mapping_unq_attrex"></a><p class="title"><b>Example 12.2. |
| Defining a Unique Constraint |
| </b></p><div class="example-contents"><p> |
| The following defines a unique constraint on the <code class="literal"> TITLE</code> |
| column of the <code class="literal">ART</code> table: |
| </p><pre class="programlisting"> |
| @Entity |
| @Table(name="ART", uniqueConstraints=@Unique(columnNames="TITLE")) |
| public class Article { |
| ... |
| } |
| </pre><p> |
| The same metadata expressed in XML form: |
| </p><pre class="programlisting"> |
| <entity class="org.mag.Article"> |
| <table name="ART"> |
| <unique-constraint> |
| <column-name>TITLE</column-name> |
| </unique-constraint> |
| </table> |
| ... |
| </entity> |
| </pre></div></div><br class="example-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="jpa_overview_mapping_column"></a>3. |
| Column |
| </h2></div></div></div><a class="indexterm" name="d0e9651"></a><a class="indexterm" name="d0e9656"></a><p> |
| In the previous section, we saw that a <code class="classname">UniqueConstraint</code> |
| uses an array of column names. Field mappings, however, use full-fledged |
| <code class="classname">Column</code> annotations. Column annotations have the following |
| properties: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <a class="indexterm" name="d0e9675"></a> |
| <code class="literal">String name</code>: The column name. Defaults to the field name. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e9689"></a> |
| <code class="literal">String columnDefinition</code>: The database-specific column type |
| name. This property is only used by vendors that support creating tables from |
| your mapping metadata. During table creation, the vendor will use the value of |
| the <code class="literal">columnDefinition</code> as the declared column type. If no |
| <code class="literal">columnDefinition</code> is given, the vendor will choose an |
| appropriate default based on the field type combined with the column's length, |
| precision, and scale. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e9709"></a> |
| <code class="literal">int length</code>: The column length. This property is typically |
| only used during table creation, though some vendors might use it to validate |
| data before flushing. <code class="literal">CHAR</code> and <code class="literal">VARCHAR</code> |
| columns typically default to a length of 255; other column types use the |
| database default. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e9729"></a> |
| <code class="literal">int precision</code>: The precision of a numeric column. This |
| property is often used in conjunction with <code class="literal">scale</code> to form the |
| proper column type name during table creation. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e9746"></a> |
| <code class="literal">int scale</code>: The number of decimal digits a numeric column can |
| hold. This property is often used in conjunction with <code class="literal">precision |
| </code> to form the proper column type name during table creation. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e9763"></a> |
| <code class="literal">boolean nullable</code>: Whether the column can store null values. |
| Vendors may use this property both for table creation and at runtime; however, |
| it is never required. Defaults to <code class="literal">true</code>. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e9780"></a> |
| <code class="literal">boolean insertable</code>: By setting this property to <code class="literal"> |
| false</code>, you can omit the column from SQL <code class="literal">INSERT</code> |
| statements. Defaults to <code class="literal">true</code>. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e9803"></a> |
| <code class="literal">boolean updatable</code>: By setting this property to <code class="literal"> |
| false</code>, you can omit the column from SQL <code class="literal">UPDATE</code> |
| statements. Defaults to <code class="literal">true</code>. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e9826"></a> |
| <code class="literal">String table</code>: Sometimes you will need to map fields to |
| tables other than the primary table. This property allows you specify that the |
| column resides in a secondary table. We will see how to map fields to secondary |
| tables later in the chapter. |
| </p></li></ul></div><p> |
| The equivalent XML element is <code class="literal">column</code>. This element has |
| attributes that are exactly equivalent to the <code class="classname"> Column</code> |
| annotation's properties described above: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">name</code> |
| </p></li><li><p> |
| <code class="literal">column-definition</code> |
| </p></li><li><p> |
| <code class="literal">length</code> |
| </p></li><li><p> |
| <code class="literal">precision</code> |
| </p></li><li><p> |
| <code class="literal">scale</code> |
| </p></li><li><p> |
| <code class="literal">insertable</code> |
| </p></li><li><p> |
| <code class="literal">updatable</code> |
| </p></li><li><p> |
| <code class="literal">table</code> |
| </p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="jpa_overview_mapping_id"></a>4. |
| Identity Mapping |
| </h2></div></div></div><a class="indexterm" name="d0e9897"></a><a class="indexterm" name="d0e9900"></a><a class="indexterm" name="d0e9905"></a><p> |
| With our new knowledge of columns, we can map the identity fields of our |
| entities. The diagram below now includes primary key columns for our model's |
| tables. The primary key column for <code class="classname">Author</code> uses |
| nonstandard type <code class="literal"> INTEGER64</code>, and the <code class="literal">Magazine.isbn |
| </code> field is mapped to a <code class="literal">VARCHAR(9)</code> column instead of |
| a <code class="literal">VARCHAR(255)</code> column, which is the default for string |
| fields. We do not need to point out either one of these oddities to the JPA |
| implementation for runtime use. If, however, we want to use the JPA |
| implementation to create our tables for us, it needs to know about |
| any desired non-default column types. Therefore, the example following the |
| diagram includes this data in its encoding of our mappings. |
| </p><div class="mediaobject"><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="341"><tr><td><img src="img/jpa-mapping-identity.png"></td></tr></table></div><p> |
| Note that many of our identity fields do not need to specify column information, |
| because they use the default column name and type. |
| </p><div class="example"><a name="jpa_overview_mapping_identityex"></a><p class="title"><b>Example 12.3. |
| Identity Mapping |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| package org.mag; |
| |
| @Entity |
| @IdClass(Magazine.MagazineId.class) |
| @Table(name="MAG") |
| public class Magazine { |
| |
| @Column(length=9) |
| @Id private String isbn; |
| @Id private String title; |
| |
| ... |
| |
| public static class MagazineId { |
| ... |
| } |
| } |
| |
| @Entity |
| @Table(name="ART", uniqueConstraints=@Unique(columnNames="TITLE")) |
| public class Article { |
| |
| @Id private long id; |
| |
| ... |
| } |
| |
| |
| package org.mag.pub; |
| |
| @Entity |
| @Table(name="COMP") |
| public class Company { |
| |
| @Column(name="CID") |
| @Id private long id; |
| |
| ... |
| } |
| |
| @Entity |
| @Table(name="AUTH") |
| public class Author { |
| |
| @Column(name="AID", columnDefinition="INTEGER64") |
| @Id private long id; |
| |
| ... |
| } |
| |
| @Embeddable |
| public class Address { |
| ... |
| } |
| |
| |
| package org.mag.subscribe; |
| |
| @MappedSuperclass |
| public abstract class Document { |
| |
| @Id |
| @GeneratedValue(strategy=GenerationType.IDENTITY) |
| private long id; |
| |
| ... |
| } |
| |
| @Entity |
| @Table(schema="CNTRCT") |
| public class Contract |
| extends Document { |
| ... |
| } |
| |
| @Entity |
| @Table(name="SUB", schema="CNTRCT") |
| public class Subscription { |
| |
| @Id private long id; |
| |
| ... |
| |
| @Entity |
| @Table(name="LINE_ITEM", schema="CNTRCT") |
| public static class LineItem |
| extends Contract { |
| ... |
| } |
| } |
| |
| @Entity(name="Lifetime") |
| public class LifetimeSubscription |
| extends Subscription { |
| ... |
| } |
| |
| @Entity(name="Trial") |
| public class TrialSubscription |
| extends Subscription { |
| ... |
| } |
| </pre><p> |
| The same metadata for <code class="literal">Magazine</code> and <code class="literal">Company</code> |
| expressed in XML form: |
| </p><pre class="programlisting"> |
| <entity class="org.mag.Magazine"> |
| <id-class class="org.mag.Magazine.Magazine.MagazineId"/> |
| <table name="MAG"/> |
| <attributes> |
| <id name="isbn"> |
| <column length="9"/> |
| </id> |
| <id name="title"/> |
| ... |
| </attributes> |
| </entity> |
| <entity class="org.mag.pub.Company"> |
| <table name="COMP"/> |
| <attributes> |
| <id name="id"> |
| <column name="CID"/> |
| </id> |
| ... |
| </attributes> |
| </entity> |
| </pre></div></div><br class="example-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="jpa_overview_mapping_sequence"></a>5. |
| Generators |
| </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#jpa_overview_mapping_sequence_seqgen">5.1. |
| Sequence Generator |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_mapping_sequence_tablegen">5.2. |
| TableGenerator |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_mapping_sequence_genex">5.3. |
| Example |
| </a></span></dt></dl></div><a class="indexterm" name="d0e9951"></a><a class="indexterm" name="d0e9956"></a><p> |
| One aspect of identity mapping not covered in the previous section is JPA's |
| ability to automatically assign a value to your numeric identity fields using |
| <span class="emphasis"><em>generators</em></span>. We discussed the available generator types in |
| <a href="#jpa_overview_meta_id" title="2.2. Id">Section 2.2, “ |
| Id |
| ”</a>. Now we show you how to define |
| named generators. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_overview_mapping_sequence_seqgen"></a>5.1. |
| Sequence Generator |
| </h3></div></div></div><a class="indexterm" name="d0e9975"></a><a class="indexterm" name="d0e9980"></a><p> |
| Most databases allow you to create native sequences. These are database |
| structures that generate increasing numeric values. The <code class="classname"> |
| SequenceGenerator</code> annotation represents a named database sequence. |
| You can place the annotation on any package, entity class, persistent field |
| declaration (if your entity uses field access), or getter method for a |
| persistent property (if your entity uses property access). <code class="classname"> |
| SequenceGenerator</code> has the following properties: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <a class="indexterm" name="d0e9995"></a> |
| <code class="literal">String name</code>: The generator name. This property is required. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e10007"></a> |
| <code class="literal">String sequenceName</code>: The name of the database sequence. If |
| you do not specify the database sequence, your vendor will choose an appropriate |
| default. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e10019"></a> |
| <code class="literal">int initialValue</code>: The initial sequence value. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e10031"></a> |
| <code class="literal">int allocationSize</code>: Some databases can pre-allocate groups |
| of sequence values. This allows the database to service sequence requests from |
| cache, rather than physically incrementing the sequence with every request. This |
| allocation size defaults to 50. |
| </p></li></ul></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| OpenJPA allows you to use one of OpenJPA's built-in generator |
| implementations in the <code class="literal">sequenceName</code> property. You can also |
| set the <code class="literal">sequenceName</code> to <code class="literal">system</code> to use the |
| system sequence defined by the <a href="#openjpa.Sequence" title="5.59. openjpa.Sequence"><code class="literal"> |
| openjpa.Sequence</code></a> configuration property. See the Reference |
| Guide's <a href="#ref_guide_sequence" title="6. Generators">Section 6, “ |
| Generators |
| ”</a> for details. |
| </p></div><p> |
| The XML element for a sequence generator is <code class="literal">sequence-generator |
| </code>. Its attributes mirror the above annotation's properties: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">name</code> |
| </p></li><li><p> |
| <code class="literal">sequence-name</code> |
| </p></li><li><p> |
| <code class="literal">initial-value</code> |
| </p></li><li><p> |
| <code class="literal">allocation-size</code> |
| </p></li></ul></div><p> |
| To use a sequence generator, set your <code class="classname">GeneratedValue</code> |
| annotation's <code class="literal">strategy</code> property to <code class="literal"> |
| GenerationType.SEQUENCE</code>, and its <code class="literal">generator</code> property |
| to the sequence generator's declared name. Or equivalently, set your <code class="literal"> |
| generated-value</code> XML element's <code class="literal">strategy</code> attribute to |
| <code class="literal">SEQUENCE</code> and its <code class="literal">generator</code> attribute to |
| the generator name. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_overview_mapping_sequence_tablegen"></a>5.2. |
| TableGenerator |
| </h3></div></div></div><a class="indexterm" name="d0e10117"></a><a class="indexterm" name="d0e10122"></a><p> |
| A <code class="classname">TableGenerator</code> refers to a database table used to store |
| increasing sequence values for one or more entities. As with <code class="classname"> |
| SequenceGenerator</code>, you can place the <code class="classname">TableGenerator |
| </code> annotation on any package, entity class, persistent field |
| declaration (if your entity uses field access), or getter method for a |
| persistent property (if your entity uses property access). <code class="classname"> |
| TableGenerator</code> has the following properties: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <a class="indexterm" name="d0e10143"></a> |
| <code class="literal">String name</code>: The generator name. This property is required. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e10155"></a> |
| <code class="literal">String table</code>: The name of the generator table. If left |
| unspecified, your vendor will choose a default table. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e10167"></a> |
| <code class="literal">String schema</code>: The named table's schema. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e10179"></a> |
| <code class="literal">String catalog</code>: The named table's catalog. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e10191"></a> |
| <code class="literal">String pkColumnName</code>: The name of the primary key column in |
| the generator table. If unspecified, your implementation will choose a default. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e10203"></a> |
| <code class="literal">String valueColumnName</code>: The name of the column that holds |
| the sequence value. If unspecified, your implementation will choose a default. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e10215"></a> |
| <code class="literal">String pkColumnValue</code>: The primary key column value of the |
| row in the generator table holding this sequence value. You can use the same |
| generator table for multiple logical sequences by supplying different <code class="literal"> |
| pkColumnValue</code> s. If you do not specify a value, the implementation |
| will supply a default. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e10230"></a> |
| <code class="literal">int initialValue</code>: The value of the generator's first issued |
| number. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e10242"></a> |
| <code class="literal">int allocationSize</code>: The number of values to allocate in |
| memory for each trip to the database. Allocating values in memory allows the JPA |
| runtime to avoid accessing the database for every sequence request. |
| This number also specifies the amount that the sequence value is incremented |
| each time the generator table is updated. Defaults to 50. |
| </p></li></ul></div><p> |
| The XML equivalent is the <code class="literal">table-generator</code> element. This |
| element's attributes correspond exactly to the above annotation's properties: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">name</code> |
| </p></li><li><p> |
| <code class="literal">table</code> |
| </p></li><li><p> |
| <code class="literal">schema</code> |
| </p></li><li><p> |
| <code class="literal">catalog</code> |
| </p></li><li><p> |
| <code class="literal">pk-column-name</code> |
| </p></li><li><p> |
| <code class="literal">value-column-name</code> |
| </p></li><li><p> |
| <code class="literal">pk-column-value</code> |
| </p></li><li><p> |
| <code class="literal">initial-value</code> |
| </p></li><li><p> |
| <code class="literal">allocation-size</code> |
| </p></li></ul></div><p> |
| To use a table generator, set your <code class="classname">GeneratedValue</code> |
| annotation's <code class="literal">strategy</code> property to <code class="literal"> |
| GenerationType.TABLE</code>, and its <code class="literal">generator</code> property to |
| the table generator's declared name. Or equivalently, set your <code class="literal"> |
| generated-value</code> XML element's <code class="literal">strategy</code> attribute to |
| <code class="literal">TABLE</code> and its <code class="literal">generator</code> attribute to the |
| generator name. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_overview_mapping_sequence_genex"></a>5.3. |
| Example |
| </h3></div></div></div><p> |
| Let's take advantage of generators in our entity model. Here are our updated |
| mappings. |
| </p><div class="example"><a name="jpa_overview_mapping_sequenceex"></a><p class="title"><b>Example 12.4. |
| Generator Mapping |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| package org.mag; |
| |
| @Entity |
| @IdClass(Magazine.MagazineId.class) |
| @Table(name="MAG") |
| public class Magazine { |
| |
| @Column(length=9) |
| @Id private String isbn; |
| @Id private String title; |
| |
| ... |
| |
| public static class MagazineId { |
| ... |
| } |
| } |
| |
| @Entity |
| @Table(name="ART", uniqueConstraints=@Unique(columnNames="TITLE")) |
| @SequenceGenerator(name="ArticleSeq", sequenceName="ART_SEQ") |
| public class Article { |
| |
| @Id |
| @GeneratedValue(strategy=GenerationType.SEQUENCE, generator="ArticleSeq") |
| private long id; |
| |
| ... |
| } |
| |
| |
| package org.mag.pub; |
| |
| @Entity |
| @Table(name="COMP") |
| public class Company { |
| |
| @Column(name="CID") |
| @Id private long id; |
| |
| ... |
| } |
| |
| @Entity |
| @Table(name="AUTH") |
| public class Author { |
| |
| @Id |
| @GeneratedValue(strategy=GenerationType.TABLE, generator="AuthorGen") |
| @TableGenerator(name="AuthorGen", table="AUTH_GEN", pkColumnName="PK", |
| valueColumnName="AID") |
| @Column(name="AID", columnDefinition="INTEGER64") |
| private long id; |
| |
| ... |
| } |
| |
| @Embeddable |
| public class Address { |
| ... |
| } |
| |
| |
| package org.mag.subscribe; |
| |
| @MappedSuperclass |
| public abstract class Document { |
| |
| @Id |
| @GeneratedValue(generate=GenerationType.IDENTITY) |
| private long id; |
| |
| ... |
| } |
| |
| @Entity |
| @Table(schema="CNTRCT") |
| public class Contract |
| extends Document { |
| |
| ... |
| } |
| |
| @Entity |
| @Table(name="SUB", schema="CNTRCT") |
| public class Subscription { |
| |
| @Id |
| @GeneratedValue(strategy=GenerationType.IDENTITY) |
| private long id; |
| |
| ... |
| |
| @Entity |
| @Table(name="LINE_ITEM", schema="CNTRCT") |
| public static class LineItem |
| extends Contract { |
| ... |
| } |
| } |
| |
| @Entity(name="Lifetime") |
| public class LifetimeSubscription |
| extends Subscription { |
| ... |
| } |
| |
| @Entity(name="Trial") |
| public class TrialSubscription |
| extends Subscription { |
| ... |
| } |
| </pre><p> |
| The same metadata for <code class="literal">Article</code> and <code class="literal">Author</code> |
| expressed in XML form: |
| </p><pre class="programlisting"> |
| <entity class="org.mag.Article"> |
| <table name="ART"> |
| <unique-constraint> |
| <column-name>TITLE</column-name> |
| </unique-constraint> |
| </table> |
| <sequence-generator name="ArticleSeq" sequence-name="ART_SEQ"/> |
| <attributes> |
| <id name="id"> |
| <generated-value strategy="SEQUENCE" generator="ArticleSeq"/> |
| </id> |
| ... |
| </attributes> |
| </entity> |
| <entity class="org.mag.pub.Author"> |
| <table name="AUTH"/> |
| <attributes> |
| <id name="id"> |
| <column name="AID" column-definition="INTEGER64"/> |
| <generated-value strategy="TABLE" generator="AuthorGen"/> |
| <table-generator name="AuthorGen" table="AUTH_GEN" |
| pk-column-name="PK" value-column-name="AID"/> |
| </id> |
| ... |
| </attributes> |
| </entity> |
| </pre></div></div><br class="example-break"></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="jpa_overview_mapping_inher"></a>6. |
| Inheritance |
| </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#jpa_overview_mapping_inher_single">6.1. |
| Single Table |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_mapping_inher_single_adv">6.1.1. |
| Advantages |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_mapping_inher_single_disadv">6.1.2. |
| Disadvantages |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_overview_mapping_inher_joined">6.2. |
| Joined |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_mapping_inher_joined_adv">6.2.1. |
| Advantages |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_mapping_inher_joined_disadv">6.2.2. |
| Disadvantages |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_overview_mapping_inher_tpc">6.3. |
| Table Per Class |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_mapping_inher_tpc_adv">6.3.1. |
| Advantages |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_mapping_inher_tpc_disadv">6.3.2. |
| Disadvantages |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_overview_mapping_inher_together">6.4. |
| Putting it All Together |
| </a></span></dt></dl></div><a class="indexterm" name="d0e10360"></a><a class="indexterm" name="d0e10367"></a><a class="indexterm" name="d0e10372"></a><a class="indexterm" name="d0e10379"></a><p> |
| In the 1990's programmers coined the term <span class="emphasis"><em>impedance mismatch |
| </em></span> to describe the difficulties in bridging the object and relational |
| worlds. Perhaps no feature of object modeling highlights the impedance mismatch |
| better than inheritance. There is no natural, efficient way to represent an |
| inheritance relationship in a relational database. |
| </p><p> |
| <a class="indexterm" name="d0e10389"></a> |
| Luckily, JPA gives you a choice of inheritance strategies, making |
| the best of a bad situation. The base entity class defines the inheritance |
| strategy for the hierarchy with the <code class="classname">Inheritance</code> |
| annotation. <code class="classname">Inheritance</code> has the following properties: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">InheritanceType strategy</code>: Enum value declaring the |
| inheritance strategy for the hierarchy. Defaults to <code class="literal"> |
| InheritanceType.SINGLE_TABLE</code>. We detail each of the available |
| strategies below. |
| </p></li></ul></div><p> |
| The corresponding XML element is <code class="literal">inheritance</code>, which has a |
| single attribute: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">strategy</code>: One of <code class="literal">SINGLE_TABLE</code>, <code class="literal"> |
| JOINED</code>, or <code class="literal">TABLE_PER_CLASS</code>. |
| </p></li></ul></div><p> |
| The following sections describe JPA's standard inheritance strategies. |
| </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| OpenJPA allows you to vary your inheritance strategy for each class, rather than |
| forcing a single strategy per inheritance hierarchy. See |
| <a href="#ref_guide_mapping_jpa" title="7. Additional JPA Mappings">Section 7, “ |
| Additional JPA Mappings |
| ”</a> in the Reference Guide for |
| details. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_overview_mapping_inher_single"></a>6.1. |
| Single Table |
| </h3></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#jpa_overview_mapping_inher_single_adv">6.1.1. |
| Advantages |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_mapping_inher_single_disadv">6.1.2. |
| Disadvantages |
| </a></span></dt></dl></div><a class="indexterm" name="d0e10444"></a><a class="indexterm" name="d0e10451"></a><p> |
| The <code class="literal">InheritanceType.SINGLE_TABLE</code> strategy maps all classes in |
| the hierarchy to the base class' table. |
| </p><div class="mediaobject"><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="177"><tr><td><img src="img/inher-superclass-table.png"></td></tr></table></div><p> |
| In our model, <code class="classname">Subscription</code> is mapped to the <code class="literal"> |
| CNTRCT.SUB</code> table. <code class="classname"> LifetimeSubscription</code>, which |
| extends <code class="classname"> Subscription</code>, adds its field data to this table |
| as well. |
| </p><div class="example"><a name="jpa_overview_mapping_inher_singleex"></a><p class="title"><b>Example 12.5. |
| Single Table Mapping |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| @Entity |
| @Table(name="SUB", schema="CNTRCT") |
| @Inheritance(strategy=InheritanceType.SINGLE_TABLE) |
| public class Subscription { |
| ... |
| } |
| |
| @Entity(name="Lifetime") |
| public class LifetimeSubscription |
| extends Subscription { |
| ... |
| } |
| </pre><p> |
| The same metadata expressed in XML form: |
| </p><pre class="programlisting"> |
| <entity class="org.mag.subcribe.Subscription"> |
| <table name="SUB" schema="CNTRCT"/> |
| <inheritance strategy="SINGLE_TABLE"/> |
| ... |
| </entity> |
| <entity class="org.mag.subscribe.LifetimeSubscription"> |
| ... |
| </entity> |
| </pre></div></div><br class="example-break"><p> |
| Single table inheritance is the default strategy. Thus, we could omit the |
| <code class="literal">@Inheritance</code> annotation in the example above and get the same |
| result. |
| </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| <a class="indexterm" name="d0e10496"></a> |
| <a class="indexterm" name="d0e10502"></a> |
| Mapping subclass state to the superclass table is often called <span class="emphasis"><em>flat |
| </em></span> inheritance mapping. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="jpa_overview_mapping_inher_single_adv"></a>6.1.1. |
| Advantages |
| </h4></div></div></div><a class="indexterm" name="d0e10514"></a><p> |
| Single table inheritance mapping is the fastest of all inheritance models, since |
| it never requires a join to retrieve a persistent instance from the database. |
| Similarly, persisting or updating a persistent instance requires only a single |
| <code class="literal">INSERT</code> or <code class="literal">UPDATE</code> statement. Finally, |
| relations to any class within a single table inheritance hierarchy are just as |
| efficient as relations to a base class. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="jpa_overview_mapping_inher_single_disadv"></a>6.1.2. |
| Disadvantages |
| </h4></div></div></div><a class="indexterm" name="d0e10532"></a><p> |
| The larger the inheritance model gets, the "wider" the mapped table gets, in |
| that for every field in the entire inheritance hierarchy, a column must exist in |
| the mapped table. This may have undesirable consequence on the database size, |
| since a wide or deep inheritance hierarchy will result in tables with many |
| mostly-empty columns. |
| </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_overview_mapping_inher_joined"></a>6.2. |
| Joined |
| </h3></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#jpa_overview_mapping_inher_joined_adv">6.2.1. |
| Advantages |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_mapping_inher_joined_disadv">6.2.2. |
| Disadvantages |
| </a></span></dt></dl></div><a class="indexterm" name="d0e10544"></a><a class="indexterm" name="d0e10551"></a><p> |
| The <code class="literal">InheritanceType.JOINED</code> strategy uses a different table |
| for each class in the hierarchy. Each table only includes state declared in its |
| class. Thus to load a subclass instance, the JPA implementation must |
| read from the subclass table as well as the table of each ancestor class, up to |
| the base entity class. |
| </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| <a class="indexterm" name="d0e10564"></a> |
| <a class="indexterm" name="d0e10570"></a> |
| Using joined subclass tables is also called <span class="emphasis"><em>vertical</em></span> |
| inheritance mapping. |
| </p></div><div class="mediaobject"><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="171"><tr><td><img src="img/jpa-inher-joined.png"></td></tr></table></div><p> |
| <code class="classname">PrimaryKeyJoinColumn</code> annotations tell the JPA |
| implementation how to join each subclass table record to the corresponding |
| record in its direct superclass table. In our model, the <code class="literal">LINE_ITEM.ID |
| </code> column joins to the <code class="literal">CONTRACT.ID</code> column. The |
| <code class="classname">PrimaryKeyJoinColumn</code> annotation has the following |
| properties: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">String name</code>: The name of the subclass table column. When |
| there is a single identity field, defaults to that field's column name. |
| </p></li><li><p> |
| <code class="literal">String referencedColumnName</code>: The name of the superclass |
| table column this subclass table column joins to. When there is a single |
| identity field, defaults to that field's column name. |
| </p></li><li><p> |
| <code class="literal">String columnDefinition</code>: This property has the same meaning |
| as the <code class="literal">columnDefinition</code> property on the <code class="classname">Column |
| </code> annotation, described in |
| <a href="#jpa_overview_mapping_column" title="3. Column">Section 3, “ |
| Column |
| ”</a>. |
| </p></li></ul></div><p> |
| The XML equivalent is the <code class="literal">primary-key-join-column</code> element. |
| Its attributes mirror the annotation properties described above: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">name</code> |
| </p></li><li><p> |
| <code class="literal">referenced-column-name</code> |
| </p></li><li><p> |
| <code class="literal">column-definition</code> |
| </p></li></ul></div><p> |
| The example below shows how we use <code class="literal">InheritanceTable.JOINED</code> |
| and a primary key join column to map our sample model according to the diagram |
| above. Note that a primary key join column is not strictly needed, because there |
| is only one identity column, and the subclass table column has the same name as |
| the superclass table column. In this situation, the defaults suffice. However, |
| we include the primary key join column for illustrative purposes. |
| </p><div class="example"><a name="jpa_overview_mapping_inher_joinedex"></a><p class="title"><b>Example 12.6. |
| Joined Subclass Tables |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| @Entity |
| @Table(schema="CNTRCT") |
| @Inheritance(strategy=InheritanceType.JOINED) |
| public class Contract |
| extends Document { |
| ... |
| } |
| |
| public class Subscription { |
| ... |
| |
| @Entity |
| @Table(name="LINE_ITEM", schema="CNTRCT") |
| @PrimaryKeyJoinColumn(name="ID", referencedColumnName="ID") |
| public static class LineItem |
| extends Contract { |
| ... |
| } |
| } |
| </pre><p> |
| The same metadata expressed in XML form: |
| </p><pre class="programlisting"> |
| <entity class="org.mag.subcribe.Contract"> |
| <table schema="CNTRCT"/> |
| <inheritance strategy="JOINED"/> |
| ... |
| </entity> |
| <entity class="org.mag.subscribe.Subscription.LineItem"> |
| <table name="LINE_ITEM" schema="CNTRCT"/> |
| <primary-key-join-column name="ID" referenced-column-name="PK"/> |
| ... |
| </entity> |
| </pre></div></div><br class="example-break"><p> |
| When there are multiple identity columns, you must define multiple <code class="classname"> |
| PrimaryKeyJoinColumn</code>s using the aptly-named <code class="classname"> |
| PrimaryKeyJoinColumns</code> annotation. This annotation's value is an |
| array of <code class="classname"> PrimaryKeyJoinColumn</code> s. We could rewrite |
| <code class="classname">LineItem</code>'s mapping as: |
| </p><pre class="programlisting"> |
| @Entity |
| @Table(name="LINE_ITEM", schema="CNTRCT") |
| @PrimaryKeyJoinColumns({ |
| @PrimaryKeyJoinColumn(name="ID", referencedColumnName="ID") |
| }) |
| public static class LineItem |
| extends Contract { |
| ... |
| } |
| </pre><p> |
| In XML, simply list as many <code class="literal"> primary-key-join-column</code> elements |
| as necessary. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="jpa_overview_mapping_inher_joined_adv"></a>6.2.1. |
| Advantages |
| </h4></div></div></div><a class="indexterm" name="d0e10686"></a><p> |
| The joined strategy has the following advantages: |
| </p><div class="orderedlist"><ol type="1"><li><p> |
| <a class="indexterm" name="d0e10699"></a> |
| Using joined subclass tables results in the most <span class="emphasis"><em>normalized</em></span> |
| database schema, meaning the schema with the least spurious or redundant data. |
| </p></li><li><p> |
| As more subclasses are added to the data model over time, the only schema |
| modification that needs to be made is the addition of corresponding subclass |
| tables in the database (rather than having to change the structure of existing |
| tables). |
| </p></li><li><p> |
| Relations to a base class using this strategy can be loaded through standard |
| joins and can use standard foreign keys, as opposed to the machinations required |
| to load polymorphic relations to table-per-class base types, described below. |
| </p></li></ol></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="jpa_overview_mapping_inher_joined_disadv"></a>6.2.2. |
| Disadvantages |
| </h4></div></div></div><a class="indexterm" name="d0e10715"></a><p> |
| Aside from certain uses of the table-per-class strategy described below, the |
| joined strategy is often the slowest of the inheritance models. Retrieving any |
| subclass requires one or more database joins, and storing subclasses requires |
| multiple <code class="literal">INSERT</code> or <code class="literal">UPDATE</code> statements. This |
| is only the case when persistence operations are performed on subclasses; if |
| most operations are performed on the least-derived persistent superclass, then |
| this mapping is very fast. |
| </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| When executing a select against a hierarchy that uses joined subclass table |
| inheritance, you must consider how to load subclass state. |
| <a href="#ref_guide_perfpack_eager" title="8. Eager Fetching">Section 8, “ |
| Eager Fetching |
| ”</a> in the Reference Guide |
| describes OpenJPA's options for efficient data loading. |
| </p></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_overview_mapping_inher_tpc"></a>6.3. |
| Table Per Class |
| </h3></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#jpa_overview_mapping_inher_tpc_adv">6.3.1. |
| Advantages |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_mapping_inher_tpc_disadv">6.3.2. |
| Disadvantages |
| </a></span></dt></dl></div><a class="indexterm" name="d0e10738"></a><a class="indexterm" name="d0e10745"></a><p> |
| Like the <code class="literal">JOINED</code> strategy, the <code class="literal"> |
| InheritanceType.TABLE_PER_CLASS</code> strategy uses a different table for |
| each class in the hierarchy. Unlike the <code class="literal">JOINED</code> strategy, |
| however, each table includes all state for an instance of the corresponding |
| class. Thus to load a subclass instance, the JPA implementation must |
| only read from the subclass table; it does not need to join to superclass |
| tables. |
| </p><div class="mediaobject"><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="189"><tr><td><img src="img/inher-tpc.png"></td></tr></table></div><p> |
| Suppose that our sample model's <code class="classname">Magazine</code> class has a |
| subclass <code class="classname">Tabloid</code>. The classes are mapped using the |
| table-per-class strategy, as in the diagram above. In a table-per-class mapping, |
| <code class="classname"> Magazine</code>'s table <code class="literal">MAG</code> contains all |
| state declared in the base <code class="classname">Magazine</code> class. <code class="classname"> |
| Tabloid</code> maps to a separate table, <code class="literal"> TABLOID</code>. This |
| table contains not only the state declared in the <code class="classname">Tabloid</code> |
| subclass, but all the base class state from <code class="classname">Magazine</code> as |
| well. Thus the <code class="literal">TABLOID</code> table would contain columns for |
| <code class="literal">isbn</code>, <code class="literal">title</code>, and other <code class="classname"> |
| Magazine</code> fields. These columns would default to the names used in |
| <code class="classname">Magazine</code>'s mapping metadata. |
| <a href="#jpa_overview_mapping_embed" title="8.3. Embedded Mapping">Section 8.3, “ |
| Embedded Mapping |
| ”</a> will show you how to use |
| <code class="literal">AttributeOverride</code>s and <code class="literal">AssociationOverride</code> |
| s to override superclass field mappings. |
| </p><div class="example"><a name="jpa_overview_mapping_inher_tpcex"></a><p class="title"><b>Example 12.7. |
| Table Per Class Mapping |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| @Entity |
| @Table(name="MAG") |
| @Inheritance(strategy=InheritanceType.TABLE_PER_CLASS) |
| public class Magazine { |
| ... |
| } |
| |
| @Entity |
| @Table(name="TABLOID") |
| public class Tabloid |
| extends Magazine { |
| ... |
| } |
| </pre><p> |
| And the same classes in XML: |
| </p><pre class="programlisting"> |
| <entity class="org.mag.Magazine"> |
| <table name="MAG"/> |
| <inheritance strategy="TABLE_PER_CLASS"/> |
| ... |
| </entity> |
| <entity class="org.mag.Tabloid"> |
| <table name="TABLOID"/> |
| ... |
| </entity> |
| </pre></div></div><br class="example-break"><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="jpa_overview_mapping_inher_tpc_adv"></a>6.3.1. |
| Advantages |
| </h4></div></div></div><a class="indexterm" name="d0e10829"></a><p> |
| The table-per-class strategy is very efficient when operating on instances of a |
| known class. Under these conditions, the strategy never requires joining to |
| superclass or subclass tables. Reads, joins, inserts, updates, and deletes are |
| all efficient in the absence of polymorphic behavior. Also, as in the joined |
| strategy, adding additional classes to the hierarchy does not require modifying |
| existing class tables. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="jpa_overview_mapping_inher_tpc_disadv"></a>6.3.2. |
| Disadvantages |
| </h4></div></div></div><a class="indexterm" name="d0e10841"></a><p> |
| Polymorphic relations to non-leaf classes in a table-per-class hierarchy have |
| many limitations. When the concrete subclass is not known, the related object |
| could be in any of the subclass tables, making joins through the relation |
| impossible. This ambiguity also affects identity lookups and queries; these |
| operations require multiple SQL <code class="literal">SELECT</code>s (one for each |
| possible subclass), or a complex <code class="literal">UNION</code>. |
| </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| <a href="#ref_guide_mapping_limits_tpc" title="12.1. Table Per Class">Section 12.1, “ |
| Table Per Class |
| ”</a> in the Reference Guide |
| describes the limitations OpenJPA places on table-per-class mapping. |
| </p></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_overview_mapping_inher_together"></a>6.4. |
| Putting it All Together |
| </h3></div></div></div><p> |
| Now that we have covered JPA's inheritance strategies, we can update our mapping |
| document with inheritance information. Here is the complete model: |
| </p><div class="mediaobject"><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="341"><tr><td><img src="img/jpa-inher-all.png"></td></tr></table></div><p> |
| And here is the corresponding mapping metadata: |
| </p><div class="example"><a name="jpa_overview_mapping_inher_togetherex"></a><p class="title"><b>Example 12.8. |
| Inheritance Mapping |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| package org.mag; |
| |
| @Entity |
| @IdClass(Magazine.MagazineId.class) |
| @Table(name="MAG") |
| public class Magazine { |
| |
| @Column(length=9) |
| @Id private String isbn; |
| @Id private String title; |
| |
| ... |
| |
| public static class MagazineId { |
| ... |
| } |
| } |
| |
| @Entity |
| @Table(name="ART", uniqueConstraints=@Unique(columnNames="TITLE")) |
| @SequenceGenerator(name="ArticleSeq", sequenceName="ART_SEQ") |
| public class Article { |
| |
| @Id |
| @GeneratedValue(strategy=GenerationType.SEQUENCE, generator="ArticleSeq") |
| private long id; |
| |
| ... |
| } |
| |
| |
| package org.mag.pub; |
| |
| @Entity |
| @Table(name="COMP") |
| public class Company { |
| |
| @Column(name="CID") |
| @Id private long id; |
| |
| ... |
| } |
| |
| @Entity |
| @Table(name="AUTH") |
| public class Author { |
| |
| @Id |
| @GeneratedValue(strategy=GenerationType.TABLE, generator="AuthorGen") |
| @TableGenerator(name="AuthorGen", table="AUTH_GEN", pkColumnName="PK", |
| valueColumnName="AID") |
| @Column(name="AID", columnDefinition="INTEGER64") |
| private long id; |
| |
| ... |
| } |
| |
| @Embeddable |
| public class Address { |
| ... |
| } |
| |
| |
| package org.mag.subscribe; |
| |
| @MappedSuperclass |
| public abstract class Document { |
| |
| @Id |
| @GeneratedValue(strategy=GenerationType.IDENTITY) |
| private long id; |
| |
| ... |
| } |
| |
| @Entity |
| @Table(schema="CNTRCT") |
| @Inheritance(strategy=InheritanceType.JOINED) |
| public class Contract |
| extends Document { |
| ... |
| } |
| |
| @Entity |
| @Table(name="SUB", schema="CNTRCT") |
| @Inheritance(strategy=InheritanceType.SINGLE_TABLE) |
| public class Subscription { |
| |
| @Id |
| @GeneratedValue(strategy=GenerationType.IDENTITY) |
| private long id; |
| |
| ... |
| |
| @Entity |
| @Table(name="LINE_ITEM", schema="CNTRCT") |
| @PrimaryKeyJoinColumn(name="ID", referencedColumnName="ID") |
| public static class LineItem |
| extends Contract { |
| ... |
| } |
| } |
| |
| @Entity(name="Lifetime") |
| public class LifetimeSubscription |
| extends Subscription { |
| ... |
| } |
| |
| @Entity(name="Trial") |
| public class TrialSubscription |
| extends Subscription { |
| ... |
| } |
| </pre><p> |
| The same metadata expressed in XML form: |
| </p><pre class="programlisting"> |
| <entity-mappings 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_1_0.xsd" |
| version="1.0"> |
| <mapped-superclass class="org.mag.subscribe.Document"> |
| <attributes> |
| <id name="id"> |
| <generated-value strategy="IDENTITY"/> |
| </id> |
| ... |
| </attributes> |
| </mapped-superclass> |
| <entity class="org.mag.Magazine"> |
| <table name="MAG"/> |
| <id-class="org.mag.Magazine.MagazineId"/> |
| <attributes> |
| <id name="isbn"> |
| <column length="9"/> |
| </id> |
| <id name="title"/> |
| ... |
| </attributes> |
| </entity> |
| <entity class="org.mag.Article"> |
| <table name="ART"> |
| <unique-constraint> |
| <column-name>TITLE</column-name> |
| </unique-constraint> |
| </table> |
| <sequence-generator name="ArticleSeq" sequence-name="ART_SEQ"/> |
| <attributes> |
| <id name="id"> |
| <generated-value strategy="SEQUENCE" generator="ArticleSeq"/> |
| </id> |
| ... |
| </attributes> |
| </entity> |
| <entity class="org.mag.pub.Company"> |
| <table name="COMP"/> |
| <attributes> |
| <id name="id"> |
| <column name="CID"/> |
| </id> |
| ... |
| </attributes> |
| </entity> |
| <entity class="org.mag.pub.Author"> |
| <table name="AUTH"/> |
| <attributes> |
| <id name="id"> |
| <column name="AID" column-definition="INTEGER64"/> |
| <generated-value strategy="TABLE" generator="AuthorGen"/> |
| <table-generator name="AuthorGen" table="AUTH_GEN" |
| pk-column-name="PK" value-column-name="AID"/> |
| </id> |
| ... |
| </attributes> |
| </entity> |
| <entity class="org.mag.subcribe.Contract"> |
| <table schema="CNTRCT"/> |
| <inheritance strategy="JOINED"/> |
| <attributes> |
| ... |
| </attributes> |
| </entity> |
| <entity class="org.mag.subcribe.Subscription"> |
| <table name="SUB" schema="CNTRCT"/> |
| <inheritance strategy="SINGLE_TABLE"/> |
| <attributes> |
| <id name="id"> |
| <generated-value strategy="IDENTITY"/> |
| </id> |
| ... |
| </attributes> |
| </entity> |
| <entity class="org.mag.subscribe.Subscription.LineItem"> |
| <table name="LINE_ITEM" schema="CNTRCT"/> |
| <primary-key-join-column name="ID" referenced-column-name="PK"/> |
| ... |
| </entity> |
| <entity class="org.mag.subscribe.LifetimeSubscription" name="Lifetime"> |
| ... |
| </entity> |
| <entity class="org.mag.subscribe.TrialSubscription" name="Trial"> |
| ... |
| </entity> |
| </entity-mappings> |
| </pre></div></div><br class="example-break"></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="jpa_overview_mapping_discrim"></a>7. |
| Discriminator |
| </h2></div></div></div><a class="indexterm" name="d0e10884"></a><a class="indexterm" name="d0e10887"></a><a class="indexterm" name="d0e10894"></a><p> |
| The <a href="#jpa_overview_mapping_inher_single" title="6.1. Single Table">single table</a> |
| inheritance strategy results in a single table containing records for two or |
| more different classes in an inheritance hierarchy. Similarly, using the |
| <a href="#jpa_overview_mapping_inher_joined" title="6.2. Joined"> joined</a> strategy |
| results in the superclass table holding records for superclass instances as well |
| as for the superclass state of subclass instances. When selecting data, JPA |
| needs a way to differentiate a row representing an object of one class from a |
| row representing an object of another. That is the job of the <span class="emphasis"><em> |
| discriminator</em></span> column. |
| </p><p> |
| The discriminator column is always in the table of the base entity. It holds a |
| different value for records of each class, allowing the JPA runtime |
| to determine what class of object each row represents. |
| </p><p> |
| The <code class="classname">DiscriminatorColumn</code> annotation represents a |
| discriminator column. It has these properties: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">String name</code>: The column name. Defaults to <code class="literal">DTYPE |
| </code>. |
| </p></li><li><p> |
| <code class="literal">length</code>: For string discriminator values, the length of the |
| column. Defaults to 31. |
| </p></li><li><p> |
| <code class="literal">String columnDefinition</code>: This property has the same meaning |
| as the <code class="literal">columnDefinition</code> property on the <code class="classname">Column |
| </code> annotation, described in |
| <a href="#jpa_overview_mapping_column" title="3. Column">Section 3, “ |
| Column |
| ”</a>. |
| </p></li><li><p> |
| <code class="literal">DiscriminatorType discriminatorType</code>: Enum value declaring |
| the discriminator strategy of the hierarchy. |
| </p></li></ul></div><p> |
| The corresponding XML element is <code class="literal"> discriminator-column</code>. Its |
| attribues mirror the annotation properties above: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">name</code> |
| </p></li><li><p> |
| <code class="literal">length</code> |
| </p></li><li><p> |
| <code class="literal">column-definition</code> |
| </p></li><li><p> |
| <code class="literal">discriminator-type</code>: One of <code class="literal">STRING</code>, |
| <code class="literal">CHAR</code>, or <code class="literal">INTEGER</code>. |
| </p></li></ul></div><p> |
| The <code class="classname">DiscriminatorValue</code> annotation specifies the |
| discriminator value for each class. Though this annotation's value is always a |
| string, the implementation will parse it according to the <code class="classname"> |
| DiscriminatorColumn</code>'s <code class="literal">discriminatorType</code> property |
| above. The type defaults to <code class="literal">DiscriminatorType.STRING</code>, but |
| may be <code class="literal"> DiscriminatorType.CHAR</code> or <code class="literal"> |
| DiscriminatorType.INTEGER</code>. If you do not specify a <code class="classname"> |
| DiscriminatorValue</code>, the provider will choose an appropriate |
| default. |
| </p><p> |
| The corresponding XML element is <code class="literal">discriminator-value</code>. The |
| text within this element is parsed as the discriminator value. |
| </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| OpenJPA assumes your model employs a discriminator column if any of the |
| following are true: |
| </p><div class="orderedlist"><ol type="1"><li><p> |
| The base entity explicitly declares an inheritance type of <code class="literal"> |
| SINGLE_TABLE</code>. |
| </p></li><li><p> |
| The base entity sets a discriminator value. |
| </p></li><li><p> |
| The base entity declares a discriminator column. |
| </p></li></ol></div><p> |
| Only <code class="literal">SINGLE_TABLE</code> inheritance hierarchies require a |
| discriminator column and values. <code class="literal"> JOINED</code> hierarchies can use |
| a discriminator to make some operations more efficient, but do not require one. |
| <code class="literal">TABLE_PER_CLASS</code> hierarchies have no use for a discriminator. |
| </p><p> |
| OpenJPA defines additional discriminator strategies; see |
| <a href="#ref_guide_mapping_jpa" title="7. Additional JPA Mappings">Section 7, “ |
| Additional JPA Mappings |
| ”</a> in the Reference Guide for |
| details. OpenJPA also supports final entity classes. OpenJPA does not use a |
| discriminator on final classes. |
| </p></div><p> |
| We can now translate our newfound knowledge of JPA discriminators into concrete |
| JPA mappings. We first extend our diagram with discriminator columns: |
| </p><div class="mediaobject"><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="341"><tr><td><img src="img/jpa-discrim-all.png"></td></tr></table></div><p> |
| Next, we present the updated mapping document. Notice that in this version, we |
| have removed explicit inheritance annotations when the defaults sufficed. Also, |
| notice that entities using the default <code class="literal">DTYPE</code> discriminator |
| column mapping do not need an explicit <code class="classname">DiscriminatorColumn |
| </code> annotation. |
| </p><div class="example"><a name="jpa_overview_mapping_discrimex"></a><p class="title"><b>Example 12.9. |
| Discriminator Mapping |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| package org.mag; |
| |
| @Entity |
| @IdClass(Magazine.MagazineId.class) |
| @Table(name="MAG") |
| @DiscriminatorValue("Mag") |
| public class Magazine { |
| |
| @Column(length=9) |
| @Id private String isbn; |
| @Id private String title; |
| |
| ... |
| |
| public static class MagazineId { |
| ... |
| } |
| } |
| |
| @Entity |
| @Table(name="ART", uniqueConstraints=@Unique(columnNames="TITLE")) |
| @SequenceGenerator(name="ArticleSeq", sequenceName="ART_SEQ") |
| public class Article { |
| |
| @Id |
| @GeneratedValue(strategy=GenerationType.SEQUENCE, generator="ArticleSeq") |
| private long id; |
| |
| ... |
| } |
| |
| |
| package org.mag.pub; |
| |
| @Entity |
| @Table(name="COMP") |
| public class Company { |
| |
| @Column(name="CID") |
| @Id private long id; |
| |
| ... |
| } |
| |
| @Entity |
| @Table(name="AUTH") |
| public class Author { |
| |
| @Id |
| @GeneratedValue(strategy=GenerationType.TABLE, generator="AuthorGen") |
| @TableGenerator(name="AuthorGen", table="AUTH_GEN", pkColumnName="PK", |
| valueColumnName="AID") |
| @Column(name="AID", columnDefinition="INTEGER64") |
| private long id; |
| |
| ... |
| } |
| |
| @Embeddable |
| public class Address { |
| ... |
| } |
| |
| |
| package org.mag.subscribe; |
| |
| @MappedSuperclass |
| public abstract class Document { |
| |
| @Id |
| @GeneratedValue(strategy=GenerationType.IDENTITY) |
| private long id; |
| |
| ... |
| } |
| |
| @Entity |
| @Table(schema="CNTRCT") |
| @Inheritance(strategy=InheritanceType.JOINED) |
| @DiscriminatorColumn(name="CTYPE") |
| public class Contract |
| extends Document { |
| ... |
| } |
| |
| @Entity |
| @Table(name="SUB", schema="CNTRCT") |
| @DiscriminatorColumn(name="KIND", discriminatorType=DiscriminatorType.INTEGER) |
| @DiscriminatorValue("1") |
| public class Subscription { |
| |
| @Id |
| @GeneratedValue(strategy=GenerationType.IDENTITY) |
| private long id; |
| |
| ... |
| |
| @Entity |
| @Table(name="LINE_ITEM", schema="CNTRCT") |
| public static class LineItem |
| extends Contract { |
| ... |
| } |
| } |
| |
| @Entity(name="Lifetime") |
| @DiscriminatorValue("2") |
| public class LifetimeSubscription |
| extends Subscription { |
| ... |
| } |
| |
| @Entity(name="Trial") |
| @DiscriminatorValue("3") |
| public class TrialSubscription |
| extends Subscription { |
| ... |
| } |
| </pre><p> |
| The same metadata expressed in XML: |
| </p><pre class="programlisting"> |
| <entity-mappings 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_1_0.xsd" |
| version="1.0"> |
| <mapped-superclass class="org.mag.subscribe.Document"> |
| <attributes> |
| <id name="id"> |
| <generated-value strategy="IDENTITY"/> |
| </id> |
| ... |
| </attributes> |
| </mapped-superclass> |
| <entity class="org.mag.Magazine"> |
| <table name="MAG"/> |
| <id-class="org.mag.Magazine.MagazineId"/> |
| <discriminator-value>Mag</discriminator-value> |
| <attributes> |
| <id name="isbn"> |
| <column length="9"/> |
| </id> |
| <id name="title"/> |
| ... |
| </attributes> |
| </entity> |
| <entity class="org.mag.Article"> |
| <table name="ART"> |
| <unique-constraint> |
| <column-name>TITLE</column-name> |
| </unique-constraint> |
| </table> |
| <sequence-generator name="ArticleSeq" sequence-name="ART_SEQ"/> |
| <attributes> |
| <id name="id"> |
| <generated-value strategy="SEQUENCE" generator="ArticleSeq"/> |
| </id> |
| ... |
| </attributes> |
| </entity> |
| <entity class="org.mag.pub.Company"> |
| <table name="COMP"/> |
| <attributes> |
| <id name="id"> |
| <column name="CID"/> |
| </id> |
| ... |
| </attributes> |
| </entity> |
| <entity class="org.mag.pub.Author"> |
| <table name="AUTH"/> |
| <attributes> |
| <id name="id"> |
| <column name="AID" column-definition="INTEGER64"/> |
| <generated-value strategy="TABLE" generator="AuthorGen"/> |
| <table-generator name="AuthorGen" table="AUTH_GEN" |
| pk-column-name="PK" value-column-name="AID"/> |
| </id> |
| ... |
| </attributes> |
| </entity> |
| <entity class="org.mag.subcribe.Contract"> |
| <table schema="CNTRCT"/> |
| <inheritance strategy="JOINED"/> |
| <discriminator-column name="CTYPE"/> |
| <attributes> |
| ... |
| </attributes> |
| </entity> |
| <entity class="org.mag.subcribe.Subscription"> |
| <table name="SUB" schema="CNTRCT"/> |
| <inheritance strategy="SINGLE_TABLE"/> |
| <discriminator-value>1</discriminator-value> |
| <discriminator-column name="KIND" discriminator-type="INTEGER"/> |
| <attributes> |
| <id name="id"> |
| <generated-value strategy="IDENTITY"/> |
| </id> |
| ... |
| </attributes> |
| </entity> |
| <entity class="org.mag.subscribe.Subscription.LineItem"> |
| <table name="LINE_ITEM" schema="CNTRCT"/> |
| <primary-key-join-column name="ID" referenced-column-name="PK"/> |
| ... |
| </entity> |
| <entity class="org.mag.subscribe.LifetimeSubscription" name="Lifetime"> |
| <discriminator-value>2</discriminator-value> |
| ... |
| </entity> |
| <entity class="org.mag.subscribe.TrialSubscription" name="Trial"> |
| <discriminator-value>3</discriminator-value> |
| ... |
| </entity> |
| </entity-mappings> |
| </pre></div></div><br class="example-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="jpa_overview_mapping_field"></a>8. |
| Field Mapping |
| </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#jpa_overview_mapping_basic">8.1. |
| Basic Mapping |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#jpa_overview_mapping_lob">8.1.1. |
| LOBs |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_mapping_enum">8.1.2. |
| Enumerated |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_mapping_temporal">8.1.3. |
| Temporal Types |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_mapping_basic_example">8.1.4. |
| The Updated Mappings |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#jpa_overview_mapping_secondary">8.2. |
| Secondary Tables |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_mapping_embed">8.3. |
| Embedded Mapping |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_mapping_rel">8.4. |
| Direct Relations |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_mapping_assoccoll">8.5. |
| Join Table |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_mapping_bidi">8.6. |
| Bidirectional Mapping |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_mapping_map">8.7. |
| Map Mapping |
| </a></span></dt></dl></div><a class="indexterm" name="d0e11079"></a><a class="indexterm" name="d0e11086"></a><p> |
| The following sections enumerate the myriad of field mappings JPA |
| supports. JPA augments the persistence metadata covered in |
| <a href="#jpa_overview_meta" title="Chapter 5. Metadata">Chapter 5, <i xmlns:xlink="http://www.w3.org/1999/xlink"> |
| Metadata |
| </i></a> with many new object-relational |
| annotations. As we explore the library of standard mappings, we introduce each |
| of these enhancements in context. |
| </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| OpenJPA supports many additional field types, and allows you to create custom |
| mappings for unsupported field types or database schemas. See the Reference |
| Guide's <a href="#ref_guide_mapping" title="Chapter 7. Mapping">Chapter 7, <i xmlns:xlink="http://www.w3.org/1999/xlink"> |
| Mapping |
| </i></a> for complete coverage of |
| OpenJPA's mapping capabilities. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_overview_mapping_basic"></a>8.1. |
| Basic Mapping |
| </h3></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#jpa_overview_mapping_lob">8.1.1. |
| LOBs |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_mapping_enum">8.1.2. |
| Enumerated |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_mapping_temporal">8.1.3. |
| Temporal Types |
| </a></span></dt><dt><span class="section"><a href="#jpa_overview_mapping_basic_example">8.1.4. |
| The Updated Mappings |
| </a></span></dt></dl></div><a class="indexterm" name="d0e11103"></a><a class="indexterm" name="d0e11110"></a><p> |
| A <span class="emphasis"><em>basic</em></span> field mapping stores the field value directly into |
| a database column. The following field metadata types use basic mapping. These |
| types were defined in <a href="#jpa_overview_meta_field" title="2. Field and Property Metadata">Section 2, “ |
| Field and Property Metadata |
| ”</a>. |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <a href="#jpa_overview_meta_id" title="2.2. Id"><code class="classname">Id</code></a> fields. |
| </p></li><li><p> |
| <a href="#jpa_overview_meta_version" title="2.5. Version"><code class="classname"> Version</code></a> |
| fields. |
| </p></li><li><p> |
| <a href="#jpa_overview_meta_basic" title="2.6. Basic"><code class="classname">Basic</code></a> |
| fields. |
| </p></li></ul></div><p> |
| In fact, you have already seen examples of basic field mappings in this chapter |
| - the mapping of all identity fields in |
| <a href="#jpa_overview_mapping_identityex" title="Example 12.3. Identity Mapping">Example 12.3, “ |
| Identity Mapping |
| ”</a>. As you saw in that |
| section, to write a basic field mapping you use the <code class="classname">Column |
| </code> annotation to describe the column the field value is stored in. We |
| discussed the <code class="classname">Column</code> annotation in |
| <a href="#jpa_overview_mapping_column" title="3. Column">Section 3, “ |
| Column |
| ”</a>. Recall that the name of |
| the column defaults to the field name, and the type of the column defaults to an |
| appropriate type for the field type. These defaults allow you to sometimes omit |
| the annotation altogether. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="jpa_overview_mapping_lob"></a>8.1.1. |
| LOBs |
| </h4></div></div></div><a class="indexterm" name="d0e11159"></a><a class="indexterm" name="d0e11162"></a><a class="indexterm" name="d0e11167"></a><p> |
| Adding the <code class="classname">Lob</code> marker annotation to a basic field signals |
| that the data is to be stored as a LOB (Large OBject). If the field holds string |
| or character data, it will map to a <code class="literal">CLOB</code> (Character Large |
| OBject) database column. If the field holds any other data type, it will be |
| stored as binary data in a <code class="literal">BLOB</code> (Binary Large OBject) column. |
| The implementation will serialize the Java value if needed. |
| </p><p> |
| The equivalent XML element is <code class="literal">lob</code>, which has no children or |
| attributes. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="jpa_overview_mapping_enum"></a>8.1.2. |
| Enumerated |
| </h4></div></div></div><a class="indexterm" name="d0e11191"></a><a class="indexterm" name="d0e11194"></a><a class="indexterm" name="d0e11199"></a><p> |
| You can apply the <code class="classname">Enumerated</code> annotation to your |
| <code class="classname">Enum</code> fields to control how they map to the database. The |
| <code class="classname">Enumerated</code> annotation's value one of the following |
| constants from the <code class="classname">EnumType</code> enum: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">EnumType.ORDINAL</code>: The default. The persistence |
| implementation places the ordinal value of the enum in a numeric column. This is |
| an efficient mapping, but may break if you rearrange the Java enum declaration. |
| </p></li><li><p> |
| <code class="literal">EnumType.STRING</code>: Store the name of the enum value rather |
| than the ordinal. This mapping uses a <code class="literal">VARCHAR</code> column rather |
| than a numeric one. |
| </p></li></ul></div><p> |
| The <code class="classname">Enumerated</code> annotation is optional. Any un-annotated |
| enumeration field defaults to <code class="literal">ORDINAL</code> mapping. |
| </p><p> |
| The corresponding XML element is <code class="literal">enumerated</code>. Its embedded |
| text must be one of <code class="literal">STRING</code> or <code class="literal">ORIDINAL</code>. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="jpa_overview_mapping_temporal"></a>8.1.3. |
| Temporal Types |
| </h4></div></div></div><a class="indexterm" name="d0e11256"></a><a class="indexterm" name="d0e11261"></a><p> |
| The <code class="classname">Temporal</code> annotation determines how the implementation |
| handles your basic <code class="classname"> java.util.Date</code> and <code class="classname"> |
| java.util.Calendar</code> fields at the JDBC level. The <code class="classname"> |
| Temporal</code> annotation's value is a constant from the <code class="classname"> |
| TemporalType</code> enum. Available values are: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">TemporalType.TIMESTAMP</code>: The default. Use JDBC's timestamp |
| APIs to manipulate the column data. |
| </p></li><li><p> |
| <code class="literal">TemporalType.DATE</code>: Use JDBC's SQL date APIs to manipulate |
| the column data. |
| </p></li><li><p> |
| <code class="literal">TemporalType.TIME</code>: Use JDBC's time APIs to manipulate the |
| column data. |
| </p></li></ul></div><p> |
| If the <code class="classname">Temporal</code> annotation is omitted, the implementation |
| will treat the data as a timestamp. |
| </p><p> |
| The corresponding XML element is <code class="literal">temporal</code>, whose text value |
| must be one of: <code class="literal">TIME</code>, <code class="literal">DATE</code>, or <code class="literal"> |
| TIMESTAMP</code>. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="jpa_overview_mapping_basic_example"></a>8.1.4. |
| The Updated Mappings |
| </h4></div></div></div><p> |
| Below we present an updated diagram of our model and its associated database |
| schema, followed by the corresponding mapping metadata. Note that the mapping |
| metadata relies on defaults where possible. Also note that as a mapped |
| superclass, <code class="classname">Document</code> can define mappings that will |
| automatically transfer to its subclass' tables. In |
| <a href="#jpa_overview_mapping_embed" title="8.3. Embedded Mapping">Section 8.3, “ |
| Embedded Mapping |
| ”</a>, you will see how a subclass |
| can override its mapped superclass' mappings. |
| </p><div class="mediaobject"><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="387"><tr><td><img src="img/jpa-basic-field.png"></td></tr></table></div><div class="example"><a name="jpa_overview_mapping_basicex"></a><p class="title"><b>Example 12.10. |
| Basic Field Mapping |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| package org.mag; |
| |
| @Entity |
| @IdClass(Magazine.MagazineId.class) |
| @Table(name="MAG") |
| @DiscriminatorValue("Mag") |
| public class Magazine { |
| |
| @Column(length=9) |
| @Id private String isbn; |
| @Id private String title; |
| |
| @Column(name="VERS") |
| @Version private int version; |
| |
| private String name; |
| private double price; |
| |
| @Column(name="COPIES") |
| private int copiesSold; |
| |
| ... |
| |
| public static class MagazineId { |
| ... |
| } |
| } |
| |
| @Entity |
| @Table(name="ART", uniqueConstraints=@Unique(columnNames="TITLE")) |
| @SequenceGenerator(name="ArticleSeq", sequenceName="ART_SEQ") |
| public class Article { |
| |
| @Id |
| @GeneratedValue(strategy=GenerationType.SEQUENCE, generator="ArticleSeq") |
| private long id; |
| |
| @Column(name="VERS") |
| @Version private int version; |
| |
| private String title; |
| private byte[] content; |
| |
| ... |
| } |
| |
| |
| package org.mag.pub; |
| |
| @Entity |
| @Table(name="COMP") |
| public class Company { |
| |
| @Column(name="CID") |
| @Id private long id; |
| |
| @Column(name="VERS") |
| @Version private int version; |
| |
| private String name; |
| |
| @Column(name="REV") |
| private double revenue; |
| |
| ... |
| } |
| |
| @Entity |
| @Table(name="AUTH") |
| public class Author { |
| |
| @Id |
| @GeneratedValue(strategy=GenerationType.TABLE, generator="AuthorGen") |
| @TableGenerator(name="AuthorGen", table="AUTH_GEN", pkColumnName="PK", |
| valueColumnName="AID") |
| @Column(name="AID", columnDefinition="INTEGER64") |
| private long id; |
| |
| @Column(name="VERS") |
| @Version private int version; |
| |
| @Column(name="FNAME") |
| private String firstName; |
| |
| @Column(name="LNAME") |
| private String lastName; |
| |
| ... |
| } |
| |
| @Embeddable |
| public class Address { |
| ... |
| } |
| |
| package org.mag.subscribe; |
| |
| @MappedSuperclass |
| public abstract class Document { |
| |
| @Id |
| @GeneratedValue(strategy=GenerationType.IDENTITY) |
| private long id; |
| |
| @Column(name="VERS") |
| @Version private int version; |
| |
| ... |
| } |
| |
| @Entity |
| @Table(schema="CNTRCT") |
| @Inheritance(strategy=InheritanceType.JOINED) |
| @DiscriminatorColumn(name="CTYPE") |
| public class Contract |
| extends Document { |
| |
| @Lob |
| private String terms; |
| |
| ... |
| } |
| |
| @Entity |
| @Table(name="SUB", schema="CNTRCT") |
| @DiscriminatorColumn(name="KIND", discriminatorType=DiscriminatorType.INTEGER) |
| @DiscriminatorValue("1") |
| public class Subscription { |
| |
| @Id |
| @GeneratedValue(strategy=GenerationType.IDENTITY) |
| private long id; |
| |
| @Column(name="VERS") |
| @Version private int version; |
| |
| @Column(name="START") |
| private Date startDate; |
| |
| @Column(name="PAY") |
| private double payment; |
| |
| ... |
| |
| @Entity |
| @Table(name="LINE_ITEM", schema="CNTRCT") |
| public static class LineItem |
| extends Contract { |
| |
| @Column(name="COMM") |
| private String comments; |
| |
| private double price; |
| private long num; |
| ... |
| } |
| } |
| |
| @Entity(name="Lifetime") |
| @DiscriminatorValue("2") |
| public class LifetimeSubscription |
| extends Subscription { |
| |
| @Basic(fetch=FetchType.LAZY) |
| @Column(name="ELITE") |
| private boolean getEliteClub () { ... } |
| public void setEliteClub (boolean elite) { ... } |
| |
| ... |
| } |
| |
| @Entity(name="Trial") |
| @DiscriminatorValue("3") |
| public class TrialSubscription |
| extends Subscription { |
| |
| @Column(name="END") |
| public Date getEndDate () { ... } |
| public void setEndDate (Date end) { ... } |
| |
| ... |
| } |
| </pre><p> |
| The same metadata expressed in XML: |
| </p><pre class="programlisting"> |
| <entity-mappings 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_1_0.xsd" |
| version="1.0"> |
| <mapped-superclass class="org.mag.subscribe.Document"> |
| <attributes> |
| <id name="id"> |
| <generated-value strategy="IDENTITY"/> |
| </id> |
| <version name="version"> |
| <column name="VERS"/> |
| </version> |
| ... |
| </attributes> |
| </mapped-superclass> |
| <entity class="org.mag.Magazine"> |
| <table name="MAG"/> |
| <id-class="org.mag.Magazine.MagazineId"/> |
| <discriminator-value>Mag</discriminator-value> |
| <attributes> |
| <id name="isbn"> |
| <column length="9"/> |
| </id> |
| <id name="title"/> |
| <basic name="name"/> |
| <basic name="price"/> |
| <basic name="copiesSold"> |
| <column name="COPIES"/> |
| </basic> |
| <version name="version"> |
| <column name="VERS"/> |
| </version> |
| ... |
| </attributes> |
| </entity> |
| <entity class="org.mag.Article"> |
| <table name="ART"> |
| <unique-constraint> |
| <column-name>TITLE</column-name> |
| </unique-constraint> |
| </table> |
| <sequence-generator name="ArticleSeq", sequenceName="ART_SEQ"/> |
| <attributes> |
| <id name="id"> |
| <generated-value strategy="SEQUENCE" generator="ArticleSeq"/> |
| </id> |
| <basic name="title"/> |
| <basic name="content"/> |
| <version name="version"> |
| <column name="VERS"/> |
| </version> |
| ... |
| </attributes> |
| </entity> |
| <entity class="org.mag.pub.Company"> |
| <table name="COMP"/> |
| <attributes> |
| <id name="id"> |
| <column name="CID"/> |
| </id> |
| <basic name="name"/> |
| <basic name="revenue"> |
| <column name="REV"/> |
| </basic> |
| </attributes> |
| </entity> |
| <entity class="org.mag.pub.Author"> |
| <table name="AUTH"/> |
| <attributes> |
| <id name="id"> |
| <column name="AID" column-definition="INTEGER64"/> |
| <generated-value strategy="TABLE" generator="AuthorGen"/> |
| <table-generator name="AuthorGen" table="AUTH_GEN" |
| pk-column-name="PK" value-column-name="AID"/> |
| </id> |
| <basic name="firstName"> |
| <column name="FNAME"/> |
| </basic> |
| <basic name="lastName"> |
| <column name="LNAME"/> |
| </basic> |
| <version name="version"> |
| <column name="VERS"/> |
| </version> |
| ... |
| </attributes> |
| </entity> |
| <entity class="org.mag.subcribe.Contract"> |
| <table schema="CNTRCT"/> |
| <inheritance strategy="JOINED"/> |
| <discriminator-column name="CTYPE"/> |
| <attributes> |
| <basic name="terms"> |
| <lob/> |
| </basic> |
| ... |
| </attributes> |
| </entity> |
| <entity class="org.mag.subcribe.Subscription"> |
| <table name="SUB" schema="CNTRCT"/> |
| <inheritance strategy="SINGLE_TABLE"/> |
| <discriminator-value>1</discriminator-value> |
| <discriminator-column name="KIND" discriminator-type="INTEGER"/> |
| <attributes> |
| <id name="id"> |
| <generated-value strategy="IDENTITY"/> |
| </id> |
| <basic name="payment"> |
| <column name="PAY"/> |
| </basic> |
| <basic name="startDate"> |
| <column name="START"/> |
| </basic> |
| <version name="version"> |
| <column name="VERS"/> |
| </version> |
| ... |
| </attributes> |
| </entity> |
| <entity class="org.mag.subscribe.Subscription.LineItem"> |
| <table name="LINE_ITEM" schema="CNTRCT"/> |
| <primary-key-join-column name="ID" referenced-column-name="PK"/> |
| <attributes> |
| <basic name="comments"> |
| <column name="COMM"/> |
| </basic> |
| <basic name="price"/> |
| <basic name="num"/> |
| ... |
| </attributes> |
| </entity> |
| <entity class="org.mag.subscribe.LifetimeSubscription" name="Lifetime"> |
| <discriminator-value>2</discriminator-value> |
| <attributes> |
| <basic name="eliteClub" fetch="LAZY"> |
| <column name="ELITE"/> |
| </basic> |
| ... |
| </attributes> |
| </entity> |
| <entity class="org.mag.subscribe.TrialSubscription" name="Trial"> |
| <discriminator-value>3</discriminator-value> |
| <attributes> |
| <basic name="endDate"> |
| <column name="END"/> |
| </basic> |
| ... |
| </attributes> |
| </entity> |
| </entity-mappings> |
| </pre></div></div><br class="example-break"></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_overview_mapping_secondary"></a>8.2. |
| Secondary Tables |
| </h3></div></div></div><a class="indexterm" name="d0e11347"></a><a class="indexterm" name="d0e11354"></a><p> |
| Sometimes a logical record is spread over multiple database tables. JPA |
| calls a class' declared table the <span class="emphasis"><em>primary</em></span> |
| table, and calls other tables that make up a logical record <span class="emphasis"><em>secondary |
| </em></span> tables. You can map any persistent field to a secondary table. Just |
| write the standard field mapping, then perform these two additional steps: |
| </p><div class="orderedlist"><ol type="1"><li><p> |
| Set the <code class="literal">table</code> attribute of each of the field's columns or |
| join columns to the name of the secondary table. |
| </p></li><li><p> |
| Define the secondary table on the entity class declaration. |
| </p></li></ol></div><p> |
| You define secondary tables with the <code class="classname">SecondaryTable</code> |
| annotation. This annotation has all the properties of the <code class="classname">Table |
| </code> annotation covered in <a href="#jpa_overview_mapping_table" title="1. Table">Section 1, “ |
| Table |
| ”</a> |
| , plus a <code class="literal"> pkJoinColumns</code> property. |
| </p><p> |
| The <code class="literal">pkJoinColumns</code> property is an array of <code class="classname"> |
| PrimaryKeyJoinColumn</code>s dictating how to join secondary table records |
| to their owning primary table records. Each <code class="classname">PrimaryKeyJoinColumn |
| </code> joins a secondary table column to a primary key column in the |
| primary table. See <a href="#jpa_overview_mapping_inher_joined" title="6.2. Joined">Section 6.2, “ |
| Joined |
| ”</a> |
| above for coverage of <code class="classname">PrimaryKeyJoinColumn</code>'s properties. |
| </p><p> |
| The corresponding XML element is <code class="literal">secondary-table</code>. This |
| element has all the attributes of the <code class="literal">table</code> element, but also |
| accepts nested <code class="literal">primary-key-join-column</code> elements. |
| </p><p> |
| In the following example, we move the <code class="literal">Article.content</code> field |
| we mapped in <a href="#jpa_overview_mapping_basic" title="8.1. Basic Mapping">Section 8.1, “ |
| Basic Mapping |
| ”</a> into a joined |
| secondary table, like so: |
| </p><div class="mediaobject"><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="189"><tr><td><img src="img/secondary-table.png"></td></tr></table></div><div class="example"><a name="jpa_overview_mapping_secondaryex"></a><p class="title"><b>Example 12.11. |
| Secondary Table Field Mapping |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| package org.mag; |
| |
| @Entity |
| @Table(name="ART") |
| @SecondaryTable(name="ART_DATA", |
| pkJoinColumns=@PrimaryKeyJoinColumn(name="ART_ID", referencedColumnName="ID")) |
| public class Article { |
| |
| @Id private long id; |
| |
| @Column(table="ART_DATA") |
| private byte[] content; |
| |
| ... |
| } |
| </pre><p> |
| And in XML: |
| </p><pre class="programlisting"> |
| <entity class="org.mag.Article"> |
| <table name="ART"/> |
| <secondary-table name="ART_DATA"> |
| <primary-key-join-column name="ART_ID" referenced-column-name="ID"/> |
| </secondary-table> |
| <attributes> |
| <id name="id"/> |
| <basic name="content"> |
| <column table="ART_DATA"/> |
| </basic> |
| ... |
| </attributes> |
| </entity> |
| </pre></div></div><br class="example-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_overview_mapping_embed"></a>8.3. |
| Embedded Mapping |
| </h3></div></div></div><a class="indexterm" name="d0e11440"></a><a class="indexterm" name="d0e11447"></a><p> |
| <a href="#jpa_overview_meta" title="Chapter 5. Metadata">Chapter 5, <i xmlns:xlink="http://www.w3.org/1999/xlink"> |
| Metadata |
| </i></a> describes JPA's concept of <span class="emphasis"><em> |
| embeddable</em></span> objects. The field values of embedded objects are stored |
| as part of the owning record, rather than as a separate database record. Thus, |
| instead of mapping a relation to an embeddable object as a foreign key, you map |
| all the fields of the embeddable instance to columns in the owning field's |
| table. |
| </p><div class="mediaobject"><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="309"><tr><td><img src="img/jpa-embedded.png"></td></tr></table></div><p> |
| JPA defaults the embedded column names and descriptions to those of |
| the embeddable class' field mappings. The <code class="classname"> AttributeOverride |
| </code> annotation overrides a basic embedded mapping. This annotation has |
| the following properties: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">String name</code>: The name of the embedded class' field being |
| mapped to this class' table. |
| </p></li><li><p> |
| <code class="literal">Column column</code>: The column defining the mapping of the |
| embedded class' field to this class' table. |
| </p></li></ul></div><p> |
| The corresponding XML element is <code class="literal"> attribute-override</code>. It has |
| a single <code class="literal">name</code> attribute to name the field being overridden, |
| and a single <code class="literal">column</code> child element. |
| </p><p> |
| To declare multiple overrides, use the <code class="classname">AttributeOverrides</code> |
| annotation, whose value is an array of <code class="classname">AttributeOverride</code> |
| s. In XML, simply list multiple <code class="literal">attribute-override</code> elements |
| in succession. |
| </p><p> |
| To override a many to one or one to one relationship, use the <code class="classname"> |
| AssociationOverride</code> annotation in place of <code class="classname"> |
| AttributeOverride</code>. <code class="classname"> AssociationOverride</code> has |
| the following properties: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">String name</code>: The name of the embedded class' field being |
| mapped to this class' table. |
| </p></li><li><p> |
| <code class="literal">JoinColumn[] joinColumns</code>: The foreign key columns joining to |
| the related record. |
| </p></li></ul></div><p> |
| The corresponding XML element is <code class="literal"> association-override</code>. It |
| has a single <code class="literal">name</code> attribute to name the field being |
| overridden, and one or more <code class="literal">join-column</code> child elements. |
| </p><p> |
| To declare multiple relation overrides, use the <code class="classname"> AssociationOverrides |
| </code> annotation, whose value is an array of <code class="classname"> |
| AssociationOverride</code> s. In XML, simply list multiple <code class="literal"> |
| association-override</code> elements in succession. |
| </p><div class="example"><a name="jpa_overview_mapping_embedex"></a><p class="title"><b>Example 12.12. |
| Embedded Field Mapping |
| </b></p><div class="example-contents"><p> |
| In this example, <code class="classname">Company</code> overrides the default mapping of |
| <code class="literal">Address.street</code> and <code class="literal">Address.city</code>. All |
| other embedded mappings are taken from the <code class="classname">Address</code> |
| embeddable class. |
| </p><pre class="programlisting"> |
| package org.mag.pub; |
| |
| @Entity |
| @Table(name="COMP") |
| public class Company { |
| |
| @Embedded |
| @AttributeOverrides({ |
| @AttributeOverride(name="street", column=@Column(name="STRT")), |
| @AttributeOverride(name="city", column=@Column(name="ACITY")) |
| }) |
| private Address address; |
| |
| ... |
| } |
| |
| @Entity |
| @Table(name="AUTH") |
| public class Author { |
| |
| // use all defaults from Address class mappings |
| private Address address; |
| |
| ... |
| } |
| |
| @Embeddable |
| public class Address { |
| |
| private String street; |
| private String city; |
| @Column(columnDefinition="CHAR(2)") |
| private String state; |
| private String zip; |
| } |
| </pre><p> |
| The same metadata expressed in XML: |
| </p><pre class="programlisting"> |
| <entity class="org.mag.pub.Company"> |
| <table name="COMP"/> |
| <attributes> |
| ... |
| <embedded name="address"> |
| <attribute-override name="street"> |
| <column name="STRT"/> |
| </attribute-override> |
| <attribute-override name="city"> |
| <column name="ACITY"/> |
| </attribute-override> |
| </embedded> |
| </attributes> |
| </entity> |
| <entity class="org.mag.pub.Author"> |
| <table name="AUTH"/> |
| <attributes> |
| <embedded name="address"> |
| <!-- use all defaults from Address --> |
| </embedded> |
| </attributes> |
| </entity> |
| <embeddable class="org.mag.pub.Address"> |
| <attributes> |
| <basic name="street"/> |
| <basic name="city"/> |
| <basic name="state"> |
| <column column-definition="CHAR(2)"/> |
| </basic> |
| <basic name="zip"/> |
| </attributes> |
| </embeddable> |
| </pre></div></div><br class="example-break"><p> |
| You can also use attribute overrides on an entity class to override mappings |
| defined by its mapped superclass or table-per-class superclass. The example |
| below re-maps the <code class="literal">Document.version</code> field to the <code class="classname"> |
| Contract</code> table's <code class="literal">CVERSION</code> column. |
| </p><div class="example"><a name="jpa_overview_mapping_joined_overex"></a><p class="title"><b>Example 12.13. |
| Mapping Mapped Superclass Field |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| @MappedSuperclass |
| public abstract class Document { |
| |
| @Column(name="VERS") |
| @Version private int version; |
| |
| ... |
| } |
| |
| @Entity |
| @Table(schema="CNTRCT") |
| @Inheritance(strategy=InheritanceType.JOINED) |
| @DiscriminatorColumn(name="CTYPE") |
| @AttributeOverride(name="version", column=@Column(name="CVERSION")) |
| public class Contract |
| extends Document { |
| ... |
| } |
| </pre><p> |
| The same metadata expressed in XML form: |
| </p><pre class="programlisting"> |
| <mapped-superclass class="org.mag.subcribe.Document"> |
| <attributes> |
| <version name="version"> |
| <column name="VERS"> |
| </version> |
| ... |
| </attributes> |
| </mapped-superclass> |
| <entity class="org.mag.subcribe.Contract"> |
| <table schema="CNTRCT"/> |
| <inheritance strategy="JOINED"/> |
| <discriminator-column name="CTYPE"/> |
| <attribute-override name="version"> |
| <column name="CVERSION"/> |
| </attribute-override> |
| <attributes> |
| ... |
| </attributes> |
| </entity> |
| </pre></div></div><br class="example-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_overview_mapping_rel"></a>8.4. |
| Direct Relations |
| </h3></div></div></div><a class="indexterm" name="d0e11595"></a><a class="indexterm" name="d0e11602"></a><a class="indexterm" name="d0e11607"></a><a class="indexterm" name="d0e11612"></a><p> |
| A direct relation is a non-embedded persistent field that holds a reference to |
| another entity. <a href="#jpa_overview_meta_manytoone" title="2.8. Many To One">many to one</a> |
| and <a href="#jpa_overview_meta_onetoone" title="2.10. One To One">one to one</a> metadata field |
| types are mapped as direct relations. Our model has three direct relations: |
| <code class="classname">Magazine</code>'s <code class="literal">publisher</code> field is a direct |
| relation to a <code class="classname">Company</code>, <code class="classname">Magazine</code>'s |
| <code class="literal">coverArticle</code> field is a direct relation to <code class="classname"> |
| Article</code>, and the <code class="literal">LineItem.magazine</code> field is a |
| direct relation to a <code class="classname">Magazine</code>. Direct relations are |
| represented in the database by foreign key columns: |
| </p><div class="mediaobject"><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="249"><tr><td><img src="img/jpa-direct-relation.png"></td></tr></table></div><p> |
| You typically map a direct relation with <code class="classname">JoinColumn</code> |
| annotations describing how the local foreign key columns join to the primary key |
| columns of the related record. The <code class="classname">JoinColumn</code> annotation |
| exposes the following properties: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">String name</code>: The name of the foreign key column. Defaults to |
| the relation field name, plus an underscore, plus the name of the referenced |
| primary key column. |
| </p></li><li><p> |
| <code class="literal">String referencedColumnName</code>: The name of the primary key |
| column being joined to. If there is only one identity field in the related |
| entity class, the join column name defaults to the name of the identity field's |
| column. |
| </p></li><li><p> |
| <code class="literal">boolean unique</code>: Whether this column is guaranteed to hold |
| unique values for all rows. Defaults to false. |
| </p></li></ul></div><p> |
| <code class="classname">JoinColumn</code> also has the same <code class="literal"> nullable</code> |
| , <code class="literal">insertable</code>, <code class="literal"> updatable</code>, <code class="literal"> |
| columnDefinition</code>, and <code class="literal">table</code> properties as the |
| <code class="classname"> Column</code> annotation. See |
| <a href="#jpa_overview_mapping_column" title="3. Column">Section 3, “ |
| Column |
| ”</a> for details on these |
| properties. |
| </p><p> |
| The <code class="literal">join-column</code> element represents a join column in XML. Its |
| attributes mirror the above annotation's properties: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">name</code> |
| </p></li><li><p> |
| <code class="literal">referenced-column-name</code> |
| </p></li><li><p> |
| <code class="literal">unique</code> |
| </p></li><li><p> |
| <code class="literal">nullable</code> |
| </p></li><li><p> |
| <code class="literal">insertable</code> |
| </p></li><li><p> |
| <code class="literal">updatable</code> |
| </p></li><li><p> |
| <code class="literal">column-definition</code> |
| </p></li><li><p> |
| <code class="literal">table</code> |
| </p></li></ul></div><p> |
| When there are multiple columns involved in the join, as when a <code class="classname"> |
| LineItem</code> references a <code class="classname">Magazine</code> in our model, |
| the <code class="classname">JoinColumns</code> annotation allows you to specify an array |
| of <code class="classname">JoinColumn</code> values. In XML, simply list multiple |
| <code class="literal">join-column</code> elements. |
| </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| OpenJPA supports many non-standard joins. See |
| <a href="#ref_guide_mapping_notes_nonstdjoins" title="6. Non-Standard Joins">Section 6, “ |
| Non-Standard Joins |
| ”</a> in the Reference |
| Guide for details. |
| </p></div><div class="example"><a name="jpa_overview_mapping_relex"></a><p class="title"><b>Example 12.14. |
| Direct Relation Field Mapping |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| package org.mag; |
| |
| @Table(name="AUTH") |
| public class Magazine { |
| |
| @Column(length=9) |
| @Id private String isbn; |
| @Id private String title; |
| |
| @OneToOne |
| @JoinColumn(name="COVER_ID" referencedColumnName="ID") |
| private Article coverArticle; |
| |
| @ManyToOne |
| @JoinColumn(name="PUB_ID" referencedColumnName="CID") |
| private Company publisher; |
| |
| ... |
| } |
| |
| @Table(name="ART") |
| public class Article { |
| |
| @Id private long id; |
| |
| ... |
| } |
| |
| |
| package org.mag.pub; |
| |
| @Table(name="COMP") |
| public class Company { |
| |
| @Column(name="CID") |
| @Id private long id; |
| |
| ... |
| } |
| |
| |
| package org.mag.subscribe; |
| |
| public class Subscription { |
| ... |
| |
| @Table(name="LINE_ITEM", schema="CNTRCT") |
| public static class LineItem |
| extends Contract { |
| |
| @ManyToOne |
| @JoinColumns({ |
| @JoinColumn(name="MAG_ISBN" referencedColumnName="ISBN"), |
| @JoinColumn(name="MAG_TITLE" referencedColumnName="TITLE") |
| }) |
| private Magazine magazine; |
| |
| ... |
| } |
| } |
| </pre><p> |
| The same metadata expressed in XML form: |
| </p><pre class="programlisting"> |
| <entity class="org.mag.Magazine"> |
| <table name="MAG"/> |
| <id-class="org.mag.Magazine.MagazineId"/> |
| <attributes> |
| <id name="isbn"> |
| <column length="9"/> |
| </id> |
| <id name="title"/> |
| <one-to-one name="coverArticle"> |
| <join-column name="COVER_ID" referenced-column-name="ID"/> |
| </one-to-one> |
| <many-to-one name="publisher"> |
| <join-column name="PUB_IC" referenced-column-name="CID"/> |
| </many-to-one> |
| ... |
| </attributes> |
| </entity> |
| <entity class="org.mag.Article"> |
| <table name="ART"/> |
| <attributes> |
| <id name="id"/> |
| ... |
| </attributes> |
| </entity> |
| <entity class="org.mag.pub.Company"> |
| <table name="COMP"/> |
| <attributes> |
| <id name="id"> |
| <column name="CID"/> |
| </id> |
| ... |
| </attributes> |
| </entity> |
| <entity class="org.mag.subscribe.Subscription.LineItem"> |
| <table name="LINE_ITEM" schema="CNTRCT"/> |
| <primary-key-join-column name="ID" referenced-column-name="PK"/> |
| <attributes> |
| <many-to-one name="magazine"> |
| <join-column name="MAG_ISBN" referenced-column-name="ISBN"/> |
| <join-column name="MAG_TITLE" referenced-column-name="TITLE"/> |
| </many-to-one> |
| ... |
| </attributes> |
| </entity> |
| </pre></div></div><br class="example-break"><p> |
| When the entities in a one to one relation join on shared primary key values |
| rather than separate foreign key columns, use the <code class="classname"> |
| PrimaryKeyJoinColumn(s)</code> annotation or <code class="literal"> |
| primary-key-join-column</code> elements in place of <code class="classname">JoinColumn(s) |
| </code> / <code class="literal"> join-column</code> elements. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_overview_mapping_assoccoll"></a>8.5. |
| Join Table |
| </h3></div></div></div><a class="indexterm" name="d0e11807"></a><a class="indexterm" name="d0e11814"></a><a class="indexterm" name="d0e11819"></a><a class="indexterm" name="d0e11822"></a><a class="indexterm" name="d0e11827"></a><p> |
| A <span class="emphasis"><em>join table</em></span> consists of two foreign keys. Each row of a |
| join table associates two objects together. JPA uses join tables to |
| represent collections of entity objects: one foreign key refers back to the |
| collection's owner, and the other refers to a collection element. |
| </p><p> |
| <a href="#jpa_overview_meta_onetomany" title="2.9. One To Many">one to many</a> and |
| <a href="#jpa_overview_meta_manytomany" title="2.11. Many To Many">many to many</a> metadata field |
| types can map to join tables. Several fields in our model use join table |
| mappings, including <code class="literal">Magazine.articles</code> and <code class="literal"> |
| Article.authors</code>. |
| </p><div class="mediaobject"><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="261"><tr><td><img src="img/jpa-assoc-table.png"></td></tr></table></div><p> |
| You define join tables with the <code class="classname">JoinTable</code> annotation. |
| This annotation has the following properties: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">String name</code>: Table name. If not given, the name of the table |
| defaults to the name of the owning entity's table, plus an underscore, plus the |
| name of the related entity's table. |
| </p></li><li><p> |
| <code class="literal">String catalog</code>: Table catalog. |
| </p></li><li><p> |
| <code class="literal">String schema</code>: Table schema. |
| </p></li><li><p> |
| <code class="literal">JoinColumn[] joinColumns</code>: Array of <code class="classname">JoinColumn |
| </code> showing how to associate join table records with the owning row in |
| the primary table. This property mirrors the <code class="literal">pkJoinColumns</code> |
| property of the <code class="classname"> SecondaryTable</code> annotation in |
| functionality. See <a href="#jpa_overview_mapping_secondary" title="8.2. Secondary Tables">Section 8.2, “ |
| Secondary Tables |
| ”</a> to |
| refresh your memory on secondary tables. |
| </p><p> |
| If this is a bidirectional relation (see |
| <a href="#jpa_overview_meta_mappedby" title="2.9.1. Bidirectional Relations">Section 2.9.1, “ |
| Bidirectional Relations |
| ”</a> ), the name of a join column |
| defaults to the inverse field name, plus an underscore, plus the referenced |
| primary key column name. Otherwise, the join column name defaults to the field's |
| owning entity name, plus an underscore, plus the referenced primary key column |
| name. |
| </p></li><li><p> |
| <code class="literal">JoinColumn[] inverseJoinColumns</code>: Array of <code class="classname"> |
| JoinColumns</code> showing how to associate join table records with the |
| records that form the elements of the collection. These join columns are used |
| just like the join columns for direct relations, and they have the same naming |
| defaults. Read <a href="#jpa_overview_mapping_rel" title="8.4. Direct Relations">Section 8.4, “ |
| Direct Relations |
| ”</a> for a review of |
| direct relation mapping. |
| </p></li></ul></div><p> |
| <code class="literal">join-table</code> is the corresponding XML element. It has the same |
| attributes as the <code class="literal">table</code> element, but includes the ability to |
| nest <code class="literal">join-column</code> and <code class="literal">inverse-join-column</code> |
| elements as children. We have seen <code class="literal">join-column</code> elements |
| already; <code class="literal">inverse-join-column</code> elements have the same |
| attributes. |
| </p><p> |
| Here are the join table mappings for the diagram above. |
| </p><div class="example"><a name="jpa_overview_mapping_assoccollex"></a><p class="title"><b>Example 12.15. |
| Join Table Mapping |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| package org.mag; |
| |
| @Entity |
| @Table(name="MAG") |
| public class Magazine { |
| |
| @Column(length=9) |
| @Id private String isbn; |
| @Id private String title; |
| |
| @OneToMany(...) |
| @OrderBy |
| @JoinTable(name="MAG_ARTS", |
| joinColumns={ |
| @JoinColumn(name="MAG_ISBN", referencedColumnName="ISBN"), |
| @JoinColumn(name="MAG_TITLE", referencedColumnName="TITLE") |
| }, |
| inverseJoinColumns=@JoinColumn(name="ART_ID", referencedColumnName="ID")) |
| private Collection<Article> articles; |
| |
| ... |
| } |
| |
| @Entity |
| @Table(name="ART") |
| public class Article { |
| |
| @Id private long id; |
| |
| @ManyToMany(cascade=CascadeType.PERSIST) |
| @OrderBy("lastName, firstName") |
| @JoinTable(name="ART_AUTHS", |
| joinColumns=@JoinColumn(name="ART_ID", referencedColumnName="ID"), |
| inverseJoinColumns=@JoinColumn(name="AUTH_ID", referencedColumnName="AID")) |
| private Collection<Author> authors; |
| |
| ... |
| } |
| |
| |
| package org.mag.pub; |
| |
| @Entity |
| @Table(name="AUTH") |
| public class Author { |
| |
| @Column(name="AID", columnDefinition="INTEGER64") |
| @Id private long id; |
| |
| ... |
| } |
| </pre><p> |
| The same metadata expressed in XML: |
| </p><pre class="programlisting"> |
| <entity class="org.mag.Magazine"> |
| <table name="MAG"/> |
| <attributes> |
| <id name="isbn"> |
| <column length="9"/> |
| </id> |
| <id name="title"/> |
| <one-to-many name="articles"> |
| <order-by/> |
| <join-table name="MAG_ARTS"> |
| <join-column name="MAG_ISBN" referenced-column-name="ISBN"/> |
| <join-column name="MAG_TITLE" referenced-column-name="TITLE"/> |
| <inverse-join-column name="ART_ID" referenced-column-name="ID"/> |
| </join-table> |
| </one-to-many> |
| ... |
| </attributes> |
| </entity> |
| <entity class="org.mag.Article"> |
| <table name="ART"/> |
| <attributes> |
| <id name="id"/> |
| <many-to-many name="authors"> |
| <order-by>lastName, firstName</order-by> |
| <join-table name="ART_AUTHS"> |
| <join-column name="ART_ID" referenced-column-name="ID"/> |
| <inverse-join-column name="AUTH_ID" referenced-column-name="AID"/> |
| </join-table> |
| <cascade> |
| <cascade-persist/> |
| </cascade> |
| </many-to-many> |
| ... |
| </attributes> |
| </entity> |
| <entity class="org.mag.pub.Author"> |
| <table name="AUTH"/> |
| <attributes> |
| <id name="id"> |
| <column name="AID" column-definition="INTEGER64"/> |
| </id> |
| ... |
| </attributes> |
| </entity> |
| </pre></div></div><br class="example-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_overview_mapping_bidi"></a>8.6. |
| Bidirectional Mapping |
| </h3></div></div></div><a class="indexterm" name="d0e11945"></a><p> |
| <a href="#jpa_overview_meta_mappedby" title="2.9.1. Bidirectional Relations">Section 2.9.1, “ |
| Bidirectional Relations |
| ”</a> introduced bidirectional |
| relations. To map a bidirectional relation, you map one field normally using the |
| annotations we have covered throughout this chapter. Then you use the <code class="literal"> |
| mappedBy</code> property of the other field's metadata annotation or the |
| corresponding <code class="literal">mapped-by</code> XML attribute to refer to the mapped |
| field. Look for this pattern in these bidirectional relations as you peruse the |
| complete mappings below: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">Magazine.publisher</code> and <code class="literal">Company.mags</code>. |
| </p></li><li><p> |
| <code class="literal">Article.authors</code> and <code class="literal">Author.articles</code>. |
| </p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_overview_mapping_map"></a>8.7. |
| Map Mapping |
| </h3></div></div></div><a class="indexterm" name="d0e11982"></a><a class="indexterm" name="d0e11987"></a><p> |
| All map fields in JPA are modeled on either one to many or many to |
| many associations. The map key is always derived from an associated entity's |
| field. Thus map fields use the same mappings as any one to many or many to many |
| fields, namely dedicated <a href="#jpa_overview_mapping_assoccoll" title="8.5. Join Table">join |
| tables</a> or <a href="#jpa_overview_mapping_bidi" title="8.6. Bidirectional Mapping">bidirectional |
| relations</a>. The only additions are the <code class="classname">MapKey</code> |
| annotation and <code class="literal">map-key</code> element to declare the key field. We |
| covered these additions in in <a href="#jpa_overview_meta_mapkey" title="2.13. Map Key">Section 2.13, “ |
| Map Key |
| ”</a>. |
| </p><div class="mediaobject"><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="255"><tr><td><img src="img/jpa-map.png"></td></tr></table></div><p> |
| The example below maps <code class="classname">Subscription</code>'s map of <code class="classname"> |
| LineItem</code>s to the <code class="literal">SUB_ITEMS</code> join table. The key |
| for each map entry is the <code class="classname"> LineItem</code>'s <code class="literal">num |
| </code> field value. |
| </p><div class="example"><a name="jpa_overview_mapping_mapex"></a><p class="title"><b>Example 12.16. |
| Join Table Map Mapping |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| package org.mag.subscribe; |
| |
| @Entity |
| @Table(name="SUB", schema="CNTRCT") |
| public class Subscription { |
| |
| @OneToMany(cascade={CascadeType.PERSIST,CascadeType.REMOVE}) |
| @MapKey(name="num") |
| @JoinTable(name="SUB_ITEMS", schema="CNTRCT", |
| joinColumns=@JoinColumn(name="SUB_ID"), |
| inverseJoinColumns=@JoinColumn(name="ITEM_ID")) |
| private Map<Long,LineItem> items; |
| |
| ... |
| |
| @Entity |
| @Table(name="LINE_ITEM", schema="CNTRCT") |
| public static class LineItem |
| extends Contract { |
| |
| private long num; |
| |
| ... |
| } |
| } |
| </pre><p> |
| The same metadata expressed in XML: |
| </p><pre class="programlisting"> |
| <entity class="org.mag.subscribe.Subscription"> |
| <table name="SUB" schema="CNTRCT"/> |
| <attributes> |
| ... |
| <one-to-many name="items"> |
| <map-key name="num"> |
| <join-table name="SUB_ITEMS" schema="CNTRCT"> |
| <join-column name="SUB_ID"/> |
| <inverse-join-column name="ITEM_ID"/> |
| </join-table> |
| <cascade> |
| <cascade-persist/> |
| <cascade-remove/> |
| </cascade> |
| </one-to-many> |
| ... |
| </attributes> |
| </entity> |
| <entity class="org.mag.subscribe.Subscription.LineItem"> |
| <table name="LINE_ITEM" schema="CNTRCT"/> |
| <attributes> |
| ... |
| <basic name="num"/> |
| ... |
| </attributes> |
| </entity> |
| </pre></div></div><br class="example-break"></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="jpa_overview_mapping_full"></a>9. |
| The Complete Mappings |
| </h2></div></div></div><p> |
| We began this chapter with the goal of mapping the following object model: |
| </p><div class="mediaobject"><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="369"><tr><td><img src="img/jpa-meta-model.png"></td></tr></table></div><p> |
| That goal has now been met. In the course of explaining JPA's object-relational |
| mapping metadata, we slowly built the requisite schema and mappings for the |
| complete model. First, the database schema: |
| </p><div class="mediaobject"><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="326"><tr><td><img src="img/jpa-data-model.png"></td></tr></table></div><p> |
| And finally, the complete entity mappings. We have trimmed the mappings to take |
| advantage of JPA defaults where possible. |
| </p><div class="example"><a name="jpa_overview_mapping_fullex"></a><p class="title"><b>Example 12.17. |
| Full Entity Mappings |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| package org.mag; |
| |
| @Entity |
| @IdClass(Magazine.MagazineId.class) |
| @Table(name="MAG") |
| @DiscriminatorValue("Mag") |
| public class Magazine { |
| |
| @Column(length=9) |
| @Id private String isbn; |
| @Id private String title; |
| |
| @Column(name="VERS") |
| @Version private int version; |
| |
| private String name; |
| private double price; |
| |
| @Column(name="COPIES") |
| private int copiesSold; |
| |
| @OneToOne(fetch=FetchType.LAZY, |
| cascade={CascadeType.PERSIST,CascadeType.REMOVE}) |
| @JoinColumn(name="COVER_ID") |
| private Article coverArticle; |
| |
| @OneToMany(cascade={CascadeType.PERSIST,CascadeType.REMOVE}) |
| @OrderBy |
| @JoinTable(name="MAG_ARTS", |
| joinColumns={ |
| @JoinColumn(name="MAG_ISBN", referencedColumnName="ISBN"), |
| @JoinColumn(name="MAG_TITLE", referencedColumnName="TITLE") |
| }, |
| inverseJoinColumns=@JoinColumn(name="ART_ID")) |
| private Collection<Article> articles; |
| |
| @ManyToOne(fetch=FetchType.LAZY, cascade=CascadeType.PERSIST) |
| @JoinColumn(name="PUB_ID") |
| private Company publisher; |
| |
| @Transient private byte[] data; |
| |
| |
| ... |
| |
| public static class MagazineId { |
| ... |
| } |
| } |
| |
| @Entity |
| @Table(name="ART", uniqueConstraints=@Unique(columnNames="TITLE")) |
| @SequenceGenerator(name="ArticleSeq", sequenceName="ART_SEQ") |
| public class Article { |
| |
| @Id |
| @GeneratedValue(strategy=GenerationType.SEQUENCE, generator="ArticleSeq") |
| private long id; |
| |
| @Column(name="VERS") |
| @Version private int version; |
| |
| private String title; |
| private byte[] content; |
| |
| @ManyToMany(cascade=CascadeType.PERSIST) |
| @OrderBy("lastName, firstName") |
| @JoinTable(name="ART_AUTHS", |
| joinColumns=@JoinColumn(name="ART_ID"), |
| inverseJoinColumns=@JoinColumn(name="AUTH_ID")) |
| private Collection<Author> authors; |
| |
| ... |
| } |
| |
| |
| package org.mag.pub; |
| |
| @Entity |
| @Table(name="COMP") |
| public class Company { |
| |
| @Column(name="CID") |
| @Id private long id; |
| |
| @Column(name="VERS") |
| @Version private int version; |
| |
| private String name; |
| |
| @Column(name="REV") |
| private double revenue; |
| |
| @Embedded |
| @AttributeOverrides({ |
| @AttributeOverride(name="street", column=@Column(name="STRT")), |
| @AttributeOverride(name="city", column=@Column(name="ACITY")) |
| }) |
| private Address address; |
| |
| @OneToMany(mappedBy="publisher", cascade=CascadeType.PERSIST) |
| private Collection<Magazine> mags; |
| |
| @OneToMany(cascade=CascadeType.PERSIST,CascadeType.REMOVE) |
| @JoinTable(name="COMP_SUBS", |
| joinColumns=@JoinColumn(name="COMP_ID"), |
| inverseJoinColumns=@JoinColumn(name="SUB_ID")) |
| private Collection<Subscription> subscriptions; |
| |
| ... |
| } |
| |
| @Entity |
| @Table(name="AUTH") |
| public class Author { |
| |
| @Id |
| @GeneratedValue(strategy=GenerationType.TABLE, generator="AuthorGen") |
| @TableGenerator(name="AuthorGen", tableName="AUTH_GEN", pkColumnName="PK", |
| valueColumnName="AID") |
| @Column(name="AID", columnDefinition="INTEGER64") |
| private long id; |
| |
| @Column(name="VERS") |
| @Version private int version; |
| |
| @Column(name="FNAME") |
| private String firstName; |
| |
| @Column(name="LNAME") |
| private String lastName; |
| |
| private Address address; |
| |
| @ManyToMany(mappedBy="authors", cascade=CascadeType.PERSIST) |
| private Collection<Article> arts; |
| |
| ... |
| } |
| |
| @Embeddable |
| public class Address { |
| |
| private String street; |
| private String city; |
| @Column(columnDefinition="CHAR(2)") |
| private String state; |
| private String zip; |
| } |
| |
| |
| package org.mag.subscribe; |
| |
| @MappedSuperclass |
| public abstract class Document { |
| |
| @Id |
| @GeneratedValue(strategy=GenerationType.IDENTITY) |
| private long id; |
| |
| @Column(name="VERS") |
| @Version private int version; |
| |
| ... |
| } |
| |
| @Entity |
| @Table(schema="CNTRCT") |
| @Inheritance(strategy=InheritanceType.JOINED) |
| @DiscriminatorColumn(name="CTYPE") |
| public class Contract |
| extends Document { |
| |
| @Lob |
| private String terms; |
| |
| ... |
| } |
| |
| @Entity |
| @Table(name="SUB", schema="CNTRCT") |
| @DiscriminatorColumn(name="KIND", discriminatorType=DiscriminatorType.INTEGER) |
| @DiscriminatorValue("1") |
| public class Subscription { |
| |
| @Id |
| @GeneratedValue(strategy=GenerationType.IDENTITY) |
| private long id; |
| |
| @Column(name="VERS") |
| @Version private int version; |
| |
| @Column(name="START") |
| private Date startDate; |
| |
| @Column(name="PAY") |
| private double payment; |
| |
| @OneToMany(cascade={CascadeType.PERSIST,CascadeType.REMOVE}) |
| @MapKey(name="num") |
| @JoinTable(name="SUB_ITEMS", schema="CNTRCT", |
| joinColumns=@JoinColumn(name="SUB_ID"), |
| inverseJoinColumns=@JoinColumn(name="ITEM_ID")) |
| private Map<Long,LineItem> items; |
| |
| ... |
| |
| @Entity |
| @Table(name="LINE_ITEM", schema="CNTRCT") |
| public static class LineItem |
| extends Contract { |
| |
| @Column(name="COMM") |
| private String comments; |
| |
| private double price; |
| private long num; |
| |
| @ManyToOne |
| @JoinColumns({ |
| @JoinColumn(name="MAG_ISBN", referencedColumnName="ISBN"), |
| @JoinColumn(name="MAG_TITLE", referencedColumnName="TITLE") |
| }) |
| private Magazine magazine; |
| ... |
| } |
| } |
| |
| @Entity(name="Lifetime") |
| @DiscriminatorValue("2") |
| public class LifetimeSubscription |
| extends Subscription { |
| |
| @Basic(fetch=FetchType.LAZY) |
| @Column(name="ELITE") |
| private boolean getEliteClub () { ... } |
| public void setEliteClub (boolean elite) { ... } |
| |
| ... |
| } |
| |
| @Entity(name="Trial") |
| @DiscriminatorValue("3") |
| public class TrialSubscription |
| extends Subscription { |
| |
| @Column(name="END") |
| public Date getEndDate () { ... } |
| public void setEndDate (Date end) { ... } |
| |
| ... |
| } |
| </pre><p> |
| The same metadata expressed in XML form: |
| </p><pre class="programlisting"> |
| <entity-mappings 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_1_0.xsd" |
| version="1.0"> |
| <mapped-superclass class="org.mag.subscribe.Document"> |
| <attributes> |
| <id name="id"> |
| <generated-value strategy="IDENTITY"/> |
| </id> |
| <version name="version"> |
| <column name="VERS"/> |
| </version> |
| </attributes> |
| </mapped-superclass> |
| <entity class="org.mag.Magazine"> |
| <table name="MAG"/> |
| <id-class="org.mag.Magazine.MagazineId"/> |
| <discriminator-value>Mag</discriminator-value> |
| <attributes> |
| <id name="isbn"> |
| <column length="9"/> |
| </id> |
| <id name="title"/> |
| <basic name="name"/> |
| <basic name="price"/> |
| <basic name="copiesSold"> |
| <column name="COPIES"/> |
| </basic> |
| <version name="version"> |
| <column name="VERS"/> |
| </version> |
| <many-to-one name="publisher" fetch="LAZY"> |
| <join-column name="PUB_ID"/> |
| <cascade> |
| <cascade-persist/> |
| </cascade> |
| </many-to-one> |
| <one-to-many name="articles"> |
| <order-by/> |
| <join-table name="MAG_ARTS"> |
| <join-column name="MAG_ISBN" referenced-column-name="ISBN"/> |
| <join-column name="MAG_TITLE" referenced-column-name="TITLE"/> |
| <inverse-join-column name="ART_ID"/> |
| </join-table> |
| <cascade> |
| <cascade-persist/> |
| <cascade-remove/> |
| </cascade> |
| </one-to-many> |
| <one-to-one name="coverArticle" fetch="LAZY"> |
| <join-column name="COVER_ID"/> |
| <cascade> |
| <cascade-persist/> |
| <cascade-remove/> |
| </cascade> |
| </one-to-one> |
| <transient name="data"/> |
| </attributes> |
| </entity> |
| <entity class="org.mag.Article"> |
| <table name="ART"> |
| <unique-constraint> |
| <column-name>TITLE</column-name> |
| </unique-constraint> |
| </table> |
| <sequence-generator name="ArticleSeq", sequenceName="ART_SEQ"/> |
| <attributes> |
| <id name="id"> |
| <generated-value strategy="SEQUENCE" generator="ArticleSeq"/> |
| </id> |
| <basic name="title"/> |
| <basic name="content"/> |
| <version name="version"> |
| <column name="VERS"/> |
| </version> |
| <many-to-many name="articles"> |
| <order-by>lastName, firstName</order-by> |
| <join-table name="ART_AUTHS"> |
| <join-column name="ART_ID" referenced-column-name="ID"/> |
| <inverse-join-column name="AUTH_ID" referenced-column-name="AID"/> |
| </join-table> |
| </many-to-many> |
| </attributes> |
| </entity> |
| <entity class="org.mag.pub.Company"> |
| <table name="COMP"/> |
| <attributes> |
| <id name="id"> |
| <column name="CID"/> |
| </id> |
| <basic name="name"/> |
| <basic name="revenue"> |
| <column name="REV"/> |
| </basic> |
| <version name="version"> |
| <column name="VERS"/> |
| </version> |
| <one-to-many name="mags" mapped-by="publisher"> |
| <cascade> |
| <cascade-persist/> |
| </cascade> |
| </one-to-many> |
| <one-to-many name="subscriptions"> |
| <join-table name="COMP_SUBS"> |
| <join-column name="COMP_ID"/> |
| <inverse-join-column name="SUB_ID"/> |
| </join-table> |
| <cascade> |
| <cascade-persist/> |
| <cascade-remove/> |
| </cascade> |
| </one-to-many> |
| <embedded name="address"> |
| <attribute-override name="street"> |
| <column name="STRT"/> |
| </attribute-override> |
| <attribute-override name="city"> |
| <column name="ACITY"/> |
| </attribute-override> |
| </embedded> |
| </attributes> |
| </entity> |
| <entity class="org.mag.pub.Author"> |
| <table name="AUTH"/> |
| <attributes> |
| <id name="id"> |
| <column name="AID" column-definition="INTEGER64"/> |
| <generated-value strategy="TABLE" generator="AuthorGen"/> |
| <table-generator name="AuthorGen" table="AUTH_GEN" |
| pk-column-name="PK" value-column-name="AID"/> |
| </id> |
| <basic name="firstName"> |
| <column name="FNAME"/> |
| </basic> |
| <basic name="lastName"> |
| <column name="LNAME"/> |
| </basic> |
| <version name="version"> |
| <column name="VERS"/> |
| </version> |
| <many-to-many name="arts" mapped-by="authors"> |
| <cascade> |
| <cascade-persist/> |
| </cascade> |
| </many-to-many> |
| <embedded name="address"/> |
| </attributes> |
| </entity> |
| <entity class="org.mag.subcribe.Contract"> |
| <table schema="CNTRCT"/> |
| <inheritance strategy="JOINED"/> |
| <discriminator-column name="CTYPE"/> |
| <attributes> |
| <basic name="terms"> |
| <lob/> |
| </basic> |
| </attributes> |
| </entity> |
| <entity class="org.mag.subcribe.Subscription"> |
| <table name="SUB" schema="CNTRCT"/> |
| <inheritance strategy="SINGLE_TABLE"/> |
| <discriminator-value>1</discriminator-value> |
| <discriminator-column name="KIND" discriminator-type="INTEGER"/> |
| <attributes> |
| <id name="id"> |
| <generated-value strategy="IDENTITY"/> |
| </id> |
| <basic name="payment"> |
| <column name="PAY"/> |
| </basic> |
| <basic name="startDate"> |
| <column name="START"/> |
| </basic> |
| <version name="version"> |
| <column name="VERS"/> |
| </version> |
| <one-to-many name="items"> |
| <map-key name="num"> |
| <join-table name="SUB_ITEMS" schema="CNTRCT"> |
| <join-column name="SUB_ID"/> |
| <inverse-join-column name="ITEM_ID"/> |
| </join-table> |
| <cascade> |
| <cascade-persist/> |
| <cascade-remove/> |
| </cascade> |
| </one-to-many> |
| </attributes> |
| </entity> |
| <entity class="org.mag.subscribe.Subscription.LineItem"> |
| <table name="LINE_ITEM" schema="CNTRCT"/> |
| <attributes> |
| <basic name="comments"> |
| <column name="COMM"/> |
| </basic> |
| <basic name="price"/> |
| <basic name="num"/> |
| <many-to-one name="magazine"> |
| <join-column name="MAG_ISBN" referenced-column-name="ISBN"/> |
| <join-column name="MAG_TITLE" referenced-column-name="TITLE"/> |
| </many-to-one> |
| </attributes> |
| </entity> |
| <entity class="org.mag.subscribe.LifetimeSubscription" name="Lifetime"> |
| <discriminator-value>2</discriminator-value> |
| <attributes> |
| <basic name="eliteClub" fetch="LAZY"> |
| <column name="ELITE"/> |
| </basic> |
| </attributes> |
| </entity> |
| <entity class="org.mag.subscribe.TrialSubscription" name="Trial"> |
| <discriminator-value>3</discriminator-value> |
| <attributes> |
| <basic name="endDate"> |
| <column name="END"/> |
| </basic> |
| </attributes> |
| </entity> |
| <embeddable class="org.mag.pub.Address"> |
| <attributes> |
| <basic name="street"/> |
| <basic name="city"/> |
| <basic name="state"> |
| <column column-definition="CHAR(2)"/> |
| </basic> |
| <basic name="zip"/> |
| </attributes> |
| </embeddable> |
| </entity-mappings> |
| </pre></div></div><br class="example-break"></div></div><div class="chapter" lang="en" id="jpa_overview_conclusion"><div class="titlepage"><div><div><h2 class="title"><a name="jpa_overview_conclusion"></a>Chapter 13. |
| Conclusion |
| </h2></div></div></div><p> |
| This concludes our overview of the JPA specification. |
| |
| The <a href="#ref_guide_intro" title="Chapter 1. Introduction">OpenJPA Reference Guide</a> |
| contains detailed documentation on all aspects of the OpenJPA implementation |
| and core development tools. |
| </p></div></div><div class="part" lang="en" id="ref_guide"><div class="titlepage"><div><div><h1 class="title"><a name="ref_guide"></a>Part 3. Reference Guide</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="chapter"><a href="#ref_guide_intro">1. |
| Introduction |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_intro_audience">1. |
| Intended Audience |
| </a></span></dt></dl></dd><dt><span class="chapter"><a href="#ref_guide_conf">2. |
| Configuration |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_conf_intro">1. |
| Introduction |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_conf_specify">2. |
| Runtime Configuration |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_conf_devtools">3. |
| Command Line Configuration |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_conf_devtools_format">3.1. |
| Code Formatting |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_conf_plugins">4. |
| Plugin Configuration |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_conf_openjpa">5. |
| OpenJPA Properties |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#openjpa.AutoClear">5.1. |
| openjpa.AutoClear |
| </a></span></dt><dt><span class="section"><a href="#openjpa.AutoDetach">5.2. |
| openjpa.AutoDetach |
| </a></span></dt><dt><span class="section"><a href="#openjpa.BrokerFactory">5.3. |
| openjpa.BrokerFactory |
| </a></span></dt><dt><span class="section"><a href="#openjpa.BrokerImpl">5.4. |
| openjpa.BrokerImpl |
| </a></span></dt><dt><span class="section"><a href="#openjpa.ClassResolver">5.5. |
| openjpa.ClassResolver |
| </a></span></dt><dt><span class="section"><a href="#openjpa.Compatibility">5.6. |
| openjpa.Compatibility |
| </a></span></dt><dt><span class="section"><a href="#openjpa.ConnectionDriverName">5.7. |
| openjpa.ConnectionDriverName |
| </a></span></dt><dt><span class="section"><a href="#openjpa.Connection2DriverName">5.8. |
| openjpa.Connection2DriverName |
| </a></span></dt><dt><span class="section"><a href="#openjpa.ConnectionFactory">5.9. |
| openjpa.ConnectionFactory |
| </a></span></dt><dt><span class="section"><a href="#openjpa.ConnectionFactory2">5.10. |
| openjpa.ConnectionFactory2 |
| </a></span></dt><dt><span class="section"><a href="#openjpa.ConnectionFactoryName">5.11. |
| openjpa.ConnectionFactoryName |
| </a></span></dt><dt><span class="section"><a href="#openjpa.ConnectionFactory2Name">5.12. |
| openjpa.ConnectionFactory2Name |
| </a></span></dt><dt><span class="section"><a href="#openjpa.ConnectionFactoryMode">5.13. |
| openjpa.ConnectionFactoryMode |
| </a></span></dt><dt><span class="section"><a href="#openjpa.ConnectionFactoryProperties">5.14. |
| openjpa.ConnectionFactoryProperties |
| </a></span></dt><dt><span class="section"><a href="#openjpa.ConnectionFactory2Properties">5.15. |
| openjpa.ConnectionFactory2Properties |
| </a></span></dt><dt><span class="section"><a href="#openjpa.ConnectionPassword">5.16. |
| openjpa.ConnectionPassword |
| </a></span></dt><dt><span class="section"><a href="#openjpa.Connection2Password">5.17. |
| openjpa.Connection2Password |
| </a></span></dt><dt><span class="section"><a href="#openjpa.ConnectionProperties">5.18. |
| openjpa.ConnectionProperties |
| </a></span></dt><dt><span class="section"><a href="#openjpa.Connection2Properties">5.19. |
| openjpa.Connection2Properties |
| </a></span></dt><dt><span class="section"><a href="#openjpa.ConnectionURL">5.20. |
| openjpa.ConnectionURL |
| </a></span></dt><dt><span class="section"><a href="#openjpa.Connection2URL">5.21. |
| openjpa.Connection2URL |
| </a></span></dt><dt><span class="section"><a href="#openjpa.ConnectionUserName">5.22. |
| openjpa.ConnectionUserName |
| </a></span></dt><dt><span class="section"><a href="#openjpa.Connection2UserName">5.23. |
| openjpa.Connection2UserName |
| </a></span></dt><dt><span class="section"><a href="#openjpa.ConnectionRetainMode">5.24. |
| openjpa.ConnectionRetainMode |
| </a></span></dt><dt><span class="section"><a href="#openjpa.DataCache">5.25. |
| openjpa.DataCache |
| </a></span></dt><dt><span class="section"><a href="#openjpa.DataCacheManager">5.26. |
| openjpa.DataCacheManager |
| </a></span></dt><dt><span class="section"><a href="#openjpa.DataCacheTimeout">5.27. |
| openjpa.DataCacheTimeout |
| </a></span></dt><dt><span class="section"><a href="#openjpa.DetachState">5.28. |
| openjpa.DetachState |
| </a></span></dt><dt><span class="section"><a href="#openjpa.DynamicDataStructs">5.29. |
| openjpa.DynamicDataStructs |
| </a></span></dt><dt><span class="section"><a href="#openjpa.FetchBatchSize">5.30. |
| openjpa.FetchBatchSize |
| </a></span></dt><dt><span class="section"><a href="#openjpa.FetchGroups">5.31. |
| openjpa.FetchGroups |
| </a></span></dt><dt><span class="section"><a href="#openjpa.FlushBeforeQueries">5.32. |
| openjpa.FlushBeforeQueries |
| </a></span></dt><dt><span class="section"><a href="#openjpa.IgnoreChanges">5.33. |
| openjpa.IgnoreChanges |
| </a></span></dt><dt><span class="section"><a href="#openjpa.Id">5.34. openjpa.Id</a></span></dt><dt><span class="section"><a href="#openjpa.InverseManager">5.35. |
| openjpa.InverseManager |
| </a></span></dt><dt><span class="section"><a href="#openjpa.LockManager">5.36. |
| openjpa.LockManager |
| </a></span></dt><dt><span class="section"><a href="#openjpa.LockTimeout">5.37. |
| openjpa.LockTimeout |
| </a></span></dt><dt><span class="section"><a href="#openjpa.Log">5.38. |
| openjpa.Log |
| </a></span></dt><dt><span class="section"><a href="#openjpa.ManagedRuntime">5.39. |
| openjpa.ManagedRuntime |
| </a></span></dt><dt><span class="section"><a href="#openjpa.Mapping">5.40. |
| openjpa.Mapping |
| </a></span></dt><dt><span class="section"><a href="#openjpa.MaxFetchDepth">5.41. |
| openjpa.MaxFetchDepth |
| </a></span></dt><dt><span class="section"><a href="#openjpa.MetaDataFactory">5.42. |
| openjpa.MetaDataFactory |
| </a></span></dt><dt><span class="section"><a href="#openjpa.MetaDataRepository">5.43. |
| openjpa.MetaDataRepository |
| </a></span></dt><dt><span class="section"><a href="#openjpa.Multithreaded">5.44. |
| openjpa.Multithreaded |
| </a></span></dt><dt><span class="section"><a href="#openjpa.Optimistic">5.45. |
| openjpa.Optimistic |
| </a></span></dt><dt><span class="section"><a href="#openjpa.OrphanedKeyAction">5.46. |
| openjpa.OrphanedKeyAction |
| </a></span></dt><dt><span class="section"><a href="#openjpa.NontransactionalRead">5.47. |
| openjpa.NontransactionalRead |
| </a></span></dt><dt><span class="section"><a href="#openjpa.NontransactionalWrite">5.48. |
| openjpa.NontransactionalWrite |
| </a></span></dt><dt><span class="section"><a href="#openjpa.ProxyManager">5.49. |
| openjpa.ProxyManager |
| </a></span></dt><dt><span class="section"><a href="#openjpa.QueryCache">5.50. |
| openjpa.QueryCache |
| </a></span></dt><dt><span class="section"><a href="#openjpa.QueryCompilationCache">5.51. |
| openjpa.QueryCompilationCache |
| </a></span></dt><dt><span class="section"><a href="#openjpa.ReadLockLevel">5.52. |
| openjpa.ReadLockLevel |
| </a></span></dt><dt><span class="section"><a href="#openjpa.RemoteCommitProvider">5.53. |
| openjpa.RemoteCommitProvider |
| </a></span></dt><dt><span class="section"><a href="#openjpa.RestoreState">5.54. |
| openjpa.RestoreState |
| </a></span></dt><dt><span class="section"><a href="#openjpa.RetainState">5.55. |
| openjpa.RetainState |
| </a></span></dt><dt><span class="section"><a href="#openjpa.RetryClassRegistration">5.56. |
| openjpa.RetryClassRegistration |
| </a></span></dt><dt><span class="section"><a href="#openjpa.RuntimeUnenhancedClasses">5.57. openjpa.RuntimeUnenhancedClasses</a></span></dt><dt><span class="section"><a href="#openjpa.SavepointManager">5.58. |
| openjpa.SavepointManager |
| </a></span></dt><dt><span class="section"><a href="#openjpa.Sequence">5.59. |
| openjpa.Sequence |
| </a></span></dt><dt><span class="section"><a href="#openjpa.TransactionMode">5.60. |
| openjpa.TransactionMode |
| </a></span></dt><dt><span class="section"><a href="#openjpa.WriteLockLevel">5.61. |
| openjpa.WriteLockLevel |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_conf_jdbc">6. |
| OpenJPA JDBC Properties |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#openjpa.jdbc.ConnectionDecorators">6.1. |
| openjpa.jdbc.ConnectionDecorators |
| </a></span></dt><dt><span class="section"><a href="#openjpa.jdbc.DBDictionary">6.2. |
| openjpa.jdbc.DBDictionary |
| </a></span></dt><dt><span class="section"><a href="#openjpa.jdbc.DriverDataSource">6.3. |
| openjpa.jdbc.DriverDataSource |
| </a></span></dt><dt><span class="section"><a href="#openjpa.jdbc.EagerFetchMode">6.4. |
| openjpa.jdbc.EagerFetchMode |
| </a></span></dt><dt><span class="section"><a href="#openjpa.jdbc.FetchDirection">6.5. |
| openjpa.jdbc.FetchDirection |
| </a></span></dt><dt><span class="section"><a href="#openjpa.jdbc.JDBCListeners">6.6. |
| openjpa.jdbc.JDBCListeners |
| </a></span></dt><dt><span class="section"><a href="#openjpa.jdbc.LRSSize">6.7. |
| openjpa.jdbc.LRSSize |
| </a></span></dt><dt><span class="section"><a href="#openjpa.jdbc.MappingDefaults">6.8. |
| openjpa.jdbc.MappingDefaults |
| </a></span></dt><dt><span class="section"><a href="#openjpa.jdbc.MappingFactory">6.9. |
| openjpa.jdbc.MappingFactory |
| </a></span></dt><dt><span class="section"><a href="#openjpa.jdbc.QuerySQLCache">6.10. |
| openjpa.jdbc.QuerySQLCache |
| </a></span></dt><dt><span class="section"><a href="#openjpa.jdbc.ResultSetType">6.11. |
| openjpa.jdbc.ResultSetType |
| </a></span></dt><dt><span class="section"><a href="#openjpa.jdbc.Schema">6.12. |
| openjpa.jdbc.Schema |
| </a></span></dt><dt><span class="section"><a href="#openjpa.jdbc.SchemaFactory">6.13. |
| openjpa.jdbc.SchemaFactory |
| </a></span></dt><dt><span class="section"><a href="#openjpa.jdbc.Schemas">6.14. |
| openjpa.jdbc.Schemas |
| </a></span></dt><dt><span class="section"><a href="#openjpa.jdbc.SQLFactory">6.15. |
| openjpa.jdbc.SQLFactory |
| </a></span></dt><dt><span class="section"><a href="#openjpa.jdbc.SubclassFetchMode">6.16. |
| openjpa.jdbc.SubclassFetchMode |
| </a></span></dt><dt><span class="section"><a href="#openjpa.jdbc.SynchronizeMappings">6.17. |
| openjpa.jdbc.SynchronizeMappings |
| </a></span></dt><dt><span class="section"><a href="#openjpa.jdbc.TransactionIsolation">6.18. |
| openjpa.jdbc.TransactionIsolation |
| </a></span></dt><dt><span class="section"><a href="#openjpa.jdbc.UpdateManager">6.19. |
| openjpa.jdbc.UpdateManager |
| </a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#ref_guide_logging">3. |
| Logging |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_logging_channels">1. |
| Logging Channels |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_logging_openjpa">2. |
| OpenJPA Logging |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_logging_noop">3. |
| Disabling Logging |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_logging_log4j">4. |
| Log4J |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_logging_commons">5. |
| Apache Commons Logging |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_logging_jdk14">5.1. |
| JDK 1.4 java.util.logging |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_logging_custom">6. |
| Custom Log |
| </a></span></dt></dl></dd><dt><span class="chapter"><a href="#ref_guide_dbsetup">4. |
| JDBC |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_dbsetup_builtin">1. |
| Using the OpenJPA DataSource |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_dbsetup_thirdparty">2. |
| Using a Third-Party DataSource |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_dbsetup_thirdparty_enlist">2.1. |
| Managed and XA DataSources |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_dbsetup_sqlconn">3. |
| Runtime Access to DataSource |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_dbsetup_dbsupport">4. |
| Database Support |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_dbsetup_dbdictprops">4.1. |
| DBDictionary Properties |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_dbsetup_dbsupport_mysql">4.2. |
| MySQLDictionary Properties |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_dbsetup_dbsupport_oracle">4.3. |
| OracleDictionary Properties |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_dbsetup_isolation">5. |
| Setting the Transaction Isolation |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_dbsetup_sql92">6. |
| Setting the SQL Join Syntax |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_dbsetup_multidb">7. |
| Accessing Multiple Databases |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_dbsetup_retain">8. |
| Configuring the Use of JDBC Connections |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_dbsetup_stmtbatch">9. |
| Statement Batching |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_dbsetup_lrs">10. |
| Large Result Sets |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_schema_def">11. |
| Default Schema |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_schema_info">12. |
| Schema Reflection |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_schema_info_list">12.1. |
| Schemas List |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_schema_info_factory">12.2. |
| Schema Factory |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_schema_schematool">13. |
| Schema Tool |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_schema_xml">14. |
| XML Schema Format |
| </a></span></dt></dl></dd><dt><span class="chapter"><a href="#ref_guide_pc">5. |
| Persistent Classes |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_pc_pcclasses">1. |
| Persistent Class List |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_pc_enhance">2. |
| Enhancement |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_pc_enhance_build">2.1. |
| Enhancing at Build Time |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_pc_enhance_runtime_container">2.2. |
| Enhancing JPA Entities on Deployment |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_pc_enhance_runtime">2.3. |
| Enhancing at Runtime |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_pc_enhance_unenhanced_types">2.4. |
| Omitting the OpenJPA enhancer |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_pc_interfaces">3. Managed Interfaces</a></span></dt><dt><span class="section"><a href="#ref_guide_pc_oid">4. |
| Object Identity |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_pc_oid_datastore">4.1. |
| Datastore Identity |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_pc_oid_entitypk">4.2. |
| Entities as Identity Fields |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_pc_oid_application">4.3. |
| Application Identity Tool |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_pc_oid_pkgen_autoinc">4.4. |
| Autoassign / Identity Strategy Caveats |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_inverses">5. |
| Managed Inverses |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_pc_scos">6. |
| Persistent Fields |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_pc_scos_restore">6.1. |
| Restoring State |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_pc_scos_order">6.2. |
| Typing and Ordering |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_pc_calendar_timezone">6.3. |
| Calendar Fields and TimeZones |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_pc_scos_proxy">6.4. |
| Proxies |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_pc_scos_proxy_smart">6.4.1. |
| Smart Proxies |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_pc_scos_proxy_lrs">6.4.2. |
| Large Result Set Proxies |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_pc_scos_proxy_custom">6.4.3. |
| Custom Proxies |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_pc_extern">6.5. |
| Externalization |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_pc_extern_values">6.5.1. |
| External Values |
| </a></span></dt></dl></dd></dl></dd><dt><span class="section"><a href="#ref_guide_fetch">7. |
| Fetch Groups |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_fetch_custom">7.1. |
| Custom Fetch Groups |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_fetch_conf">7.2. |
| Custom Fetch Group Configuration |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_fetch_single_field">7.3. |
| Per-field Fetch Configuration |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_fetch_impl">7.4. |
| Implementation Notes |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_perfpack_eager">8. |
| Eager Fetching |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_perfpack_eager_conf">8.1. |
| Configuring Eager Fetching |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_perfpack_eager_consider">8.2. |
| Eager Fetching Considerations and Limitations |
| </a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#ref_guide_meta">6. |
| Metadata |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_meta_factory">1. |
| Metadata Factory |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_meta_repository">2. Metadata Repository</a></span></dt><dt><span class="section"><a href="#ref_guide_meta_jpa">3. |
| Additional JPA Metadata |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_meta_jpa_datastoreid">3.1. |
| Datastore Identity |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_meta_jpa_version">3.2. |
| Surrogate Version |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_meta_jpa_persistent">3.3. |
| Persistent Field Values |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_meta_jpa_persistent_coll">3.4. Persistent Collection Fields</a></span></dt><dt><span class="section"><a href="#ref_guide_meta_jpa_persistent_map">3.5. Persistent Map Fields</a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_meta_ext">4. |
| Metadata Extensions |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_meta_class">4.1. |
| Class Extensions |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#fetch-groups">4.1.1. |
| Fetch Groups |
| </a></span></dt><dt><span class="section"><a href="#data-cache">4.1.2. |
| Data Cache |
| </a></span></dt><dt><span class="section"><a href="#detached-state-field">4.1.3. |
| Detached State |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_meta_field">4.2. |
| Field Extensions |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#dependent">4.2.1. |
| Dependent |
| </a></span></dt><dt><span class="section"><a href="#load-fetch-group">4.2.2. |
| Load Fetch Group |
| </a></span></dt><dt><span class="section"><a href="#lrs">4.2.3. |
| LRS |
| </a></span></dt><dt><span class="section"><a href="#inverse-logical">4.2.4. |
| Inverse-Logical |
| </a></span></dt><dt><span class="section"><a href="#read-only">4.2.5. |
| Read-Only |
| </a></span></dt><dt><span class="section"><a href="#type">4.2.6. |
| Type |
| </a></span></dt><dt><span class="section"><a href="#externalizer">4.2.7. |
| Externalizer |
| </a></span></dt><dt><span class="section"><a href="#factory">4.2.8. |
| Factory |
| </a></span></dt><dt><span class="section"><a href="#external-values">4.2.9. |
| External Values |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_meta_example">4.3. |
| Example |
| </a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#ref_guide_mapping">7. |
| Mapping |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_mapping_mappingtool">1. |
| Forward Mapping |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_mapping_mappingtool_examples">1.1. |
| Using the Mapping Tool |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_ddl_examples">1.2. |
| Generating DDL SQL |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_synch">1.3. |
| Runtime Forward Mapping |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_pc_reverse">2. |
| Reverse Mapping |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_pc_reverse_custom">2.1. |
| Customizing Reverse Mapping |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_mapping_middle">3. |
| Meet-in-the-Middle Mapping |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_defaults">4. |
| Mapping Defaults |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_factory">5. |
| Mapping Factory |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_notes_nonstdjoins">6. |
| Non-Standard Joins |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_jpa">7. |
| Additional JPA Mappings |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_mapping_jpa_datastoreid">7.1. |
| Datastore Identity Mapping |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_jpa_version">7.2. |
| Surrogate Version Mapping |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_jpa_columns">7.3. |
| Multi-Column Mappings |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_jpa_fieldjoin">7.4. |
| Join Column Attribute Targets |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_jpa_embed">7.5. |
| Embedded Mapping |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_jpa_coll">7.6. |
| Collections |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_mapping_jpa_coll_table">7.6.1. |
| Container Table |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_jpa_coll_joincols">7.6.2. |
| Element Join Columns |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_jpa_coll_order">7.6.3. |
| Order Column |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_mapping_jpa_onemany">7.7. |
| One-Sided One-Many Mapping |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_jpa_map">7.8. |
| Maps |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_jpa_constraints">7.9. |
| Indexes and Constraints |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_mapping_jpa_index">7.9.1. |
| Indexes |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_jpa_fk">7.9.2. |
| Foreign Keys |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_jpa_unique">7.9.3. |
| Unique Constraints |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_xmlmapping">7.10. |
| XML Column Mapping |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_streamsupport">7.11. |
| Stream LOB Support |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_mapping_jpa_map_keycols">8. Key Columns</a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_jpa_map_keyjoincols">9. Key Join Columns</a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_jpa_map_embedkey">10. Key Embedded Mapping</a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_jpa_map_ex">11. Examples</a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_limits">12. |
| Mapping Limitations |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_mapping_limits_tpc">12.1. |
| Table Per Class |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_mapping_ext">13. |
| Mapping Extensions |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_mapping_ext_cls">13.1. |
| Class Extensions |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#subclass-fetch-mode">13.1.1. |
| Subclass Fetch Mode |
| </a></span></dt><dt><span class="section"><a href="#class-strategy">13.1.2. |
| Strategy |
| </a></span></dt><dt><span class="section"><a href="#discriminator-strategy">13.1.3. |
| Discriminator Strategy |
| </a></span></dt><dt><span class="section"><a href="#version-strategy">13.1.4. |
| Version Strategy |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_mapping_ext_field">13.2. |
| Field Extensions |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#eager-fetch-mode">13.2.1. |
| Eager Fetch Mode |
| </a></span></dt><dt><span class="section"><a href="#nonpolymorphic">13.2.2. |
| Nonpolymorphic |
| </a></span></dt><dt><span class="section"><a href="#class-criteria">13.2.3. |
| Class Criteria |
| </a></span></dt><dt><span class="section"><a href="#strategy">13.2.4. |
| Strategy |
| </a></span></dt></dl></dd></dl></dd><dt><span class="section"><a href="#ref_guide_mapping_custom">14. |
| Custom Mappings |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_mapping_custom_class">14.1. |
| Custom Class Mapping |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_custom_versdiscrim">14.2. |
| Custom Discriminator and Version Strategies |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_custom_field">14.3. |
| Custom Field Mapping |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_mapping_custom_vhandler">14.3.1. |
| Value Handlers |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_custom_fieldstrat">14.3.2. |
| Field Strategies |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_custom_field_conf">14.3.3. |
| Configuration |
| </a></span></dt></dl></dd></dl></dd><dt><span class="section"><a href="#ref_guide_orphan">15. |
| Orphaned Keys |
| </a></span></dt></dl></dd><dt><span class="chapter"><a href="#ref_guide_deploy">8. |
| Deployment |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_deploy_factory">1. |
| Factory Deployment |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_deploy_factory_standalone">1.1. |
| Standalone Deployment |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_deploy_inject">1.2. |
| EntityManager Injection |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_enterprise_trans">2. |
| Integrating with the Transaction Manager |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_enterprise_xa">3. |
| XA Transactions |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_enterprise_xa_req">3.1. |
| Using OpenJPA with XA Transactions |
| </a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#ref_guide_runtime">9. |
| Runtime Extensions |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_runtime_arch">1. |
| Architecture |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_runtime_broker_finalization">1.1. |
| Broker Finalization |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_runtime_broker_extension">1.2. |
| Broker Customization and Eviction |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_runtime_jpa">2. |
| JPA Extensions |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_runtime_emfactory">2.1. |
| OpenJPAEntityManagerFactory |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_runtime_em">2.2. |
| OpenJPAEntityManager |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_runtime_jpaquery">2.3. |
| OpenJPAQuery |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_runtime_jpaextent">2.4. |
| Extent |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_runtime_jpacache">2.5. |
| StoreCache |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_runtime_jpaquerycache">2.6. |
| QueryResultCache |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_runtime_jpafetch">2.7. |
| FetchPlan |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_runtime_openjpaentitytransaction">2.8. |
| OpenJPAEntityTransaction |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_runtime_openjpapersistence">2.9. |
| OpenJPAPersistence |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_locking">3. |
| Object Locking |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_locking_default">3.1. |
| Configuring Default Locking |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_locking_runtime">3.2. |
| Configuring Lock Levels at Runtime |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_locking_apis">3.3. |
| Object Locking APIs |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_locking_lockmgr">3.4. |
| Lock Manager |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_locking_rules">3.5. |
| Rules for Locking Behavior |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_locking_issues">3.6. |
| Known Issues and Limitations |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_savepoints">4. |
| Savepoints |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#reg_guide_savepoints_using">4.1. |
| Using Savepoints |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_savepoints_conf">4.2. |
| Configuring Savepoints |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_enterprise_methodql">5. |
| MethodQL |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_sequence">6. |
| Generators |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_sequence_runtime">6.1. |
| Runtime Access |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_runtime_pm_event">7. |
| Transaction Events |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_enterprise_abstractstore">8. |
| Non-Relational Stores |
| </a></span></dt></dl></dd><dt><span class="chapter"><a href="#ref_guide_caching">10. |
| Caching |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_cache">1. |
| Data Cache |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_cache_conf">1.1. |
| Data Cache Configuration |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_cache_use">1.2. |
| Data Cache Usage |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_cache_query">1.3. |
| Query Cache |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_cache_extension">1.4. |
| Cache Extension |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_cache_notes">1.5. |
| Important Notes |
| </a></span></dt><dt><span class="section"><a href="#datastore_cache_issues">1.6. |
| Known Issues and Limitations |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_cache_querycomp">2. |
| Query Compilation Cache |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_cache_querysql">3. |
| Query SQL Cache |
| </a></span></dt></dl></dd><dt><span class="chapter"><a href="#ref_guide_remote">11. |
| Remote and Offline Operation |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_detach">1. |
| Detach and Attach |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_detach_behavior">1.1. |
| Detach Behavior |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_attach_behavior">1.2. |
| Attach Behavior |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_detach_graph">1.3. |
| Defining the Detached Object Graph |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_detach_field">1.3.1. |
| Detached State Field |
| </a></span></dt></dl></dd></dl></dd><dt><span class="section"><a href="#ref_guide_event">2. |
| Remote Event Notification Framework |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_event_conf">2.1. |
| Remote Commit Provider Configuration |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_event_conf_jms">2.1.1. |
| JMS |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_event_conf_tcp">2.1.2. |
| TCP |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_event_conf_common">2.1.3. |
| Common Properties |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_event_customization">2.2. |
| Customization |
| </a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#ref_guide_slice">12. |
| Distributed Persistence |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#slice_overview">1. Overview</a></span></dt><dt><span class="section"><a href="#Features and Limitations">2. Salient Features</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e31151">2.1. Transparency</a></span></dt><dt><span class="section"><a href="#d0e31159">2.2. Custom Distribution Policy</a></span></dt><dt><span class="section"><a href="#d0e31188">2.3. Heterogeneous Database</a></span></dt><dt><span class="section"><a href="#d0e31193">2.4. Parallel Execution</a></span></dt><dt><span class="section"><a href="#d0e31198">2.5. Distributed Query</a></span></dt><dt><span class="section"><a href="#d0e31232">2.6. Targeted Query</a></span></dt><dt><span class="section"><a href="#d0e31249">2.7. Distributed Transaction</a></span></dt><dt><span class="section"><a href="#collocation_constraint">2.8. Collocation Constraint</a></span></dt></dl></dd><dt><span class="section"><a href="#slice_configuration">3. Usage</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e31286">3.1. How to activate Slice Runtime?</a></span></dt><dt><span class="section"><a href="#d0e31297">3.2. How to configure each database slice?</a></span></dt><dt><span class="section"><a href="#distribution_policy">3.3. Implement DistributionPolicy interface</a></span></dt><dt><span class="section"><a href="#d0e31411">3.4. </a></span></dt></dl></dd><dt><span class="section"><a href="#d0e31422">4. Global Properties</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e31425">4.1. openjpa.slice.DistributionPolicy</a></span></dt><dt><span class="section"><a href="#d0e31439">4.2. openjpa.slice.Lenient</a></span></dt><dt><span class="section"><a href="#d0e31455">4.3. openjpa.slice.Master</a></span></dt><dt><span class="section"><a href="#d0e31467">4.4. openjpa.slice.Names</a></span></dt><dt><span class="section"><a href="#d0e31482">4.5. openjpa.slice.ThreadingPolicy</a></span></dt><dt><span class="section"><a href="#d0e31553">4.6. openjpa.slice.TransactionPolicy</a></span></dt></dl></dd><dt><span class="section"><a href="#d0e31599">5. Per-Slice Properties</a></span></dt></dl></dd><dt><span class="chapter"><a href="#ref_guide_integration">13. |
| Third Party Integration |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_integration_ant">1. |
| Apache Ant |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_integration_conf">1.1. |
| Common Ant Configuration Options |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_integration_enhance">1.2. |
| Enhancer Ant Task |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_integration_appidtool">1.3. |
| Application Identity Tool Ant Task |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_integration_mappingtool">1.4. |
| Mapping Tool Ant Task |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_integration_revmappingtool">1.5. |
| Reverse Mapping Tool Ant Task |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_integration_schematool">1.6. |
| Schema Tool Ant Task |
| </a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#ref_guide_optimization">14. |
| Optimization Guidelines |
| </a></span></dt></dl></div><div class="chapter" lang="en" id="ref_guide_intro"><div class="titlepage"><div><div><h2 class="title"><a name="ref_guide_intro"></a>Chapter 1. |
| Introduction |
| </h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#ref_guide_intro_audience">1. |
| Intended Audience |
| </a></span></dt></dl></div><p> |
| OpenJPA is a JDBC-based implementation of the JPA standard. |
| This document is a reference for the configuration and use of OpenJPA. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_intro_audience"></a>1. |
| Intended Audience |
| </h2></div></div></div><p> |
| This document is intended for OpenJPA developers. It |
| assumes strong knowledge of Java, familiarity with the eXtensible Markup |
| Language (XML), and an understanding of JPA. If you are not familiar with JPA, |
| please read the <a href="#jpa_overview_intro" title="Chapter 1. Introduction">JPA Overview</a> before |
| proceeding. |
| |
| </p><p> |
| Certain sections of this guide cover advanced topics such as custom |
| object-relational mapping, enterprise integration, and using OpenJPA with |
| third-party tools. These sections assume prior experience with the relevant |
| subject. |
| </p></div></div><div class="chapter" lang="en" id="ref_guide_conf"><div class="titlepage"><div><div><h2 class="title"><a name="ref_guide_conf"></a>Chapter 2. |
| Configuration |
| </h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#ref_guide_conf_intro">1. |
| Introduction |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_conf_specify">2. |
| Runtime Configuration |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_conf_devtools">3. |
| Command Line Configuration |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_conf_devtools_format">3.1. |
| Code Formatting |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_conf_plugins">4. |
| Plugin Configuration |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_conf_openjpa">5. |
| OpenJPA Properties |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#openjpa.AutoClear">5.1. |
| openjpa.AutoClear |
| </a></span></dt><dt><span class="section"><a href="#openjpa.AutoDetach">5.2. |
| openjpa.AutoDetach |
| </a></span></dt><dt><span class="section"><a href="#openjpa.BrokerFactory">5.3. |
| openjpa.BrokerFactory |
| </a></span></dt><dt><span class="section"><a href="#openjpa.BrokerImpl">5.4. |
| openjpa.BrokerImpl |
| </a></span></dt><dt><span class="section"><a href="#openjpa.ClassResolver">5.5. |
| openjpa.ClassResolver |
| </a></span></dt><dt><span class="section"><a href="#openjpa.Compatibility">5.6. |
| openjpa.Compatibility |
| </a></span></dt><dt><span class="section"><a href="#openjpa.ConnectionDriverName">5.7. |
| openjpa.ConnectionDriverName |
| </a></span></dt><dt><span class="section"><a href="#openjpa.Connection2DriverName">5.8. |
| openjpa.Connection2DriverName |
| </a></span></dt><dt><span class="section"><a href="#openjpa.ConnectionFactory">5.9. |
| openjpa.ConnectionFactory |
| </a></span></dt><dt><span class="section"><a href="#openjpa.ConnectionFactory2">5.10. |
| openjpa.ConnectionFactory2 |
| </a></span></dt><dt><span class="section"><a href="#openjpa.ConnectionFactoryName">5.11. |
| openjpa.ConnectionFactoryName |
| </a></span></dt><dt><span class="section"><a href="#openjpa.ConnectionFactory2Name">5.12. |
| openjpa.ConnectionFactory2Name |
| </a></span></dt><dt><span class="section"><a href="#openjpa.ConnectionFactoryMode">5.13. |
| openjpa.ConnectionFactoryMode |
| </a></span></dt><dt><span class="section"><a href="#openjpa.ConnectionFactoryProperties">5.14. |
| openjpa.ConnectionFactoryProperties |
| </a></span></dt><dt><span class="section"><a href="#openjpa.ConnectionFactory2Properties">5.15. |
| openjpa.ConnectionFactory2Properties |
| </a></span></dt><dt><span class="section"><a href="#openjpa.ConnectionPassword">5.16. |
| openjpa.ConnectionPassword |
| </a></span></dt><dt><span class="section"><a href="#openjpa.Connection2Password">5.17. |
| openjpa.Connection2Password |
| </a></span></dt><dt><span class="section"><a href="#openjpa.ConnectionProperties">5.18. |
| openjpa.ConnectionProperties |
| </a></span></dt><dt><span class="section"><a href="#openjpa.Connection2Properties">5.19. |
| openjpa.Connection2Properties |
| </a></span></dt><dt><span class="section"><a href="#openjpa.ConnectionURL">5.20. |
| openjpa.ConnectionURL |
| </a></span></dt><dt><span class="section"><a href="#openjpa.Connection2URL">5.21. |
| openjpa.Connection2URL |
| </a></span></dt><dt><span class="section"><a href="#openjpa.ConnectionUserName">5.22. |
| openjpa.ConnectionUserName |
| </a></span></dt><dt><span class="section"><a href="#openjpa.Connection2UserName">5.23. |
| openjpa.Connection2UserName |
| </a></span></dt><dt><span class="section"><a href="#openjpa.ConnectionRetainMode">5.24. |
| openjpa.ConnectionRetainMode |
| </a></span></dt><dt><span class="section"><a href="#openjpa.DataCache">5.25. |
| openjpa.DataCache |
| </a></span></dt><dt><span class="section"><a href="#openjpa.DataCacheManager">5.26. |
| openjpa.DataCacheManager |
| </a></span></dt><dt><span class="section"><a href="#openjpa.DataCacheTimeout">5.27. |
| openjpa.DataCacheTimeout |
| </a></span></dt><dt><span class="section"><a href="#openjpa.DetachState">5.28. |
| openjpa.DetachState |
| </a></span></dt><dt><span class="section"><a href="#openjpa.DynamicDataStructs">5.29. |
| openjpa.DynamicDataStructs |
| </a></span></dt><dt><span class="section"><a href="#openjpa.FetchBatchSize">5.30. |
| openjpa.FetchBatchSize |
| </a></span></dt><dt><span class="section"><a href="#openjpa.FetchGroups">5.31. |
| openjpa.FetchGroups |
| </a></span></dt><dt><span class="section"><a href="#openjpa.FlushBeforeQueries">5.32. |
| openjpa.FlushBeforeQueries |
| </a></span></dt><dt><span class="section"><a href="#openjpa.IgnoreChanges">5.33. |
| openjpa.IgnoreChanges |
| </a></span></dt><dt><span class="section"><a href="#openjpa.Id">5.34. openjpa.Id</a></span></dt><dt><span class="section"><a href="#openjpa.InverseManager">5.35. |
| openjpa.InverseManager |
| </a></span></dt><dt><span class="section"><a href="#openjpa.LockManager">5.36. |
| openjpa.LockManager |
| </a></span></dt><dt><span class="section"><a href="#openjpa.LockTimeout">5.37. |
| openjpa.LockTimeout |
| </a></span></dt><dt><span class="section"><a href="#openjpa.Log">5.38. |
| openjpa.Log |
| </a></span></dt><dt><span class="section"><a href="#openjpa.ManagedRuntime">5.39. |
| openjpa.ManagedRuntime |
| </a></span></dt><dt><span class="section"><a href="#openjpa.Mapping">5.40. |
| openjpa.Mapping |
| </a></span></dt><dt><span class="section"><a href="#openjpa.MaxFetchDepth">5.41. |
| openjpa.MaxFetchDepth |
| </a></span></dt><dt><span class="section"><a href="#openjpa.MetaDataFactory">5.42. |
| openjpa.MetaDataFactory |
| </a></span></dt><dt><span class="section"><a href="#openjpa.MetaDataRepository">5.43. |
| openjpa.MetaDataRepository |
| </a></span></dt><dt><span class="section"><a href="#openjpa.Multithreaded">5.44. |
| openjpa.Multithreaded |
| </a></span></dt><dt><span class="section"><a href="#openjpa.Optimistic">5.45. |
| openjpa.Optimistic |
| </a></span></dt><dt><span class="section"><a href="#openjpa.OrphanedKeyAction">5.46. |
| openjpa.OrphanedKeyAction |
| </a></span></dt><dt><span class="section"><a href="#openjpa.NontransactionalRead">5.47. |
| openjpa.NontransactionalRead |
| </a></span></dt><dt><span class="section"><a href="#openjpa.NontransactionalWrite">5.48. |
| openjpa.NontransactionalWrite |
| </a></span></dt><dt><span class="section"><a href="#openjpa.ProxyManager">5.49. |
| openjpa.ProxyManager |
| </a></span></dt><dt><span class="section"><a href="#openjpa.QueryCache">5.50. |
| openjpa.QueryCache |
| </a></span></dt><dt><span class="section"><a href="#openjpa.QueryCompilationCache">5.51. |
| openjpa.QueryCompilationCache |
| </a></span></dt><dt><span class="section"><a href="#openjpa.ReadLockLevel">5.52. |
| openjpa.ReadLockLevel |
| </a></span></dt><dt><span class="section"><a href="#openjpa.RemoteCommitProvider">5.53. |
| openjpa.RemoteCommitProvider |
| </a></span></dt><dt><span class="section"><a href="#openjpa.RestoreState">5.54. |
| openjpa.RestoreState |
| </a></span></dt><dt><span class="section"><a href="#openjpa.RetainState">5.55. |
| openjpa.RetainState |
| </a></span></dt><dt><span class="section"><a href="#openjpa.RetryClassRegistration">5.56. |
| openjpa.RetryClassRegistration |
| </a></span></dt><dt><span class="section"><a href="#openjpa.RuntimeUnenhancedClasses">5.57. openjpa.RuntimeUnenhancedClasses</a></span></dt><dt><span class="section"><a href="#openjpa.SavepointManager">5.58. |
| openjpa.SavepointManager |
| </a></span></dt><dt><span class="section"><a href="#openjpa.Sequence">5.59. |
| openjpa.Sequence |
| </a></span></dt><dt><span class="section"><a href="#openjpa.TransactionMode">5.60. |
| openjpa.TransactionMode |
| </a></span></dt><dt><span class="section"><a href="#openjpa.WriteLockLevel">5.61. |
| openjpa.WriteLockLevel |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_conf_jdbc">6. |
| OpenJPA JDBC Properties |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#openjpa.jdbc.ConnectionDecorators">6.1. |
| openjpa.jdbc.ConnectionDecorators |
| </a></span></dt><dt><span class="section"><a href="#openjpa.jdbc.DBDictionary">6.2. |
| openjpa.jdbc.DBDictionary |
| </a></span></dt><dt><span class="section"><a href="#openjpa.jdbc.DriverDataSource">6.3. |
| openjpa.jdbc.DriverDataSource |
| </a></span></dt><dt><span class="section"><a href="#openjpa.jdbc.EagerFetchMode">6.4. |
| openjpa.jdbc.EagerFetchMode |
| </a></span></dt><dt><span class="section"><a href="#openjpa.jdbc.FetchDirection">6.5. |
| openjpa.jdbc.FetchDirection |
| </a></span></dt><dt><span class="section"><a href="#openjpa.jdbc.JDBCListeners">6.6. |
| openjpa.jdbc.JDBCListeners |
| </a></span></dt><dt><span class="section"><a href="#openjpa.jdbc.LRSSize">6.7. |
| openjpa.jdbc.LRSSize |
| </a></span></dt><dt><span class="section"><a href="#openjpa.jdbc.MappingDefaults">6.8. |
| openjpa.jdbc.MappingDefaults |
| </a></span></dt><dt><span class="section"><a href="#openjpa.jdbc.MappingFactory">6.9. |
| openjpa.jdbc.MappingFactory |
| </a></span></dt><dt><span class="section"><a href="#openjpa.jdbc.QuerySQLCache">6.10. |
| openjpa.jdbc.QuerySQLCache |
| </a></span></dt><dt><span class="section"><a href="#openjpa.jdbc.ResultSetType">6.11. |
| openjpa.jdbc.ResultSetType |
| </a></span></dt><dt><span class="section"><a href="#openjpa.jdbc.Schema">6.12. |
| openjpa.jdbc.Schema |
| </a></span></dt><dt><span class="section"><a href="#openjpa.jdbc.SchemaFactory">6.13. |
| openjpa.jdbc.SchemaFactory |
| </a></span></dt><dt><span class="section"><a href="#openjpa.jdbc.Schemas">6.14. |
| openjpa.jdbc.Schemas |
| </a></span></dt><dt><span class="section"><a href="#openjpa.jdbc.SQLFactory">6.15. |
| openjpa.jdbc.SQLFactory |
| </a></span></dt><dt><span class="section"><a href="#openjpa.jdbc.SubclassFetchMode">6.16. |
| openjpa.jdbc.SubclassFetchMode |
| </a></span></dt><dt><span class="section"><a href="#openjpa.jdbc.SynchronizeMappings">6.17. |
| openjpa.jdbc.SynchronizeMappings |
| </a></span></dt><dt><span class="section"><a href="#openjpa.jdbc.TransactionIsolation">6.18. |
| openjpa.jdbc.TransactionIsolation |
| </a></span></dt><dt><span class="section"><a href="#openjpa.jdbc.UpdateManager">6.19. |
| openjpa.jdbc.UpdateManager |
| </a></span></dt></dl></dd></dl></div><a class="indexterm" name="d0e12101"></a><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_conf_intro"></a>1. |
| Introduction |
| </h2></div></div></div><p> |
| This chapter describes the OpenJPA configuration framework. It concludes with |
| descriptions of all the configuration properties recognized by OpenJPA. You may |
| want to browse these properties now, but it is not necessary. Most of them will |
| be referenced later in the documentation as we explain the various features they |
| apply to. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_conf_specify"></a>2. |
| Runtime Configuration |
| </h2></div></div></div><a class="indexterm" name="d0e12112"></a><p> |
| The OpenJPA runtime includes a comprehensive system of configuration defaults |
| and overrides: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <a class="indexterm" name="d0e12123"></a> |
| OpenJPA first looks for an optional <code class="filename">openjpa.xml</code> resource. |
| OpenJPA searches for this resource in each top-level directory of your <code class="literal"> |
| CLASSPATH</code>. OpenJPA will also find the resource if you place it within |
| a <code class="filename">META-INF</code> directory in any top-level directory of the |
| <code class="literal">CLASSPATH</code>. The <code class="filename">openjpa.xml</code> resource |
| contains property settings in <a href="#jpa_overview_persistence_xml" title="1. persistence.xml"> |
| JPA's XML format</a>. |
| </p></li><li><p> |
| You can customize the name or location of the above resource by specifying the |
| correct resource path in the <code class="literal">openjpa.properties</code> System |
| property. |
| </p></li><li><p> |
| You can override any value defined in the above resource by setting the System |
| property of the same name to the desired value. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e12157"></a> |
| In JPA, the values in the standard <code class="filename"> META-INF/persistence.xml |
| </code> bootstrapping file used by the |
| <a href="#jpa_overview_persistence" title="Chapter 6. Persistence"><code class="classname">Persistence</code> |
| </a> class at runtime override the values in the above resource, as well as |
| any System property settings. The <code class="classname">Map</code> passed to |
| <code class="methodname">Persistence.createEntityManagerFactory</code> at runtime also |
| overrides previous settings, including properties defined in <code class="filename"> |
| persistence.xml</code>. |
| </p></li><li><p> |
| When using JCA deployment the <code class="literal">config-property</code> values in your |
| <code class="filename">ra.xml</code> file override other settings. |
| </p></li><li><p> |
| All OpenJPA command-line tools accept flags that allow you to specify the |
| configuration resource to use, and to override any property. |
| <a href="#ref_guide_conf_devtools" title="3. Command Line Configuration">Section 3, “ |
| Command Line Configuration |
| ”</a> describes these flags. |
| </p></li></ul></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| Internally, the OpenJPA runtime environment and development |
| tools manipulate property settings through a general |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/ResultObjectProvider/lib/conf/Configuration.html" target="_top"> |
| <code class="classname">Configuration</code></a> interface, and in particular its |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/conf/OpenJPAConfiguration.html" target="_top"> |
| <code class="classname">OpenJPAConfiguration</code></a> and |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/conf/JDBCConfiguration.html" target="_top"> |
| <code class="classname">JDBCConfiguration</code></a> subclasses. For advanced |
| customization, OpenJPA's extended runtime interfaces and its development tools |
| allow you to access these interfaces directly. See the <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc" target="_top"> |
| Javadoc</a> for details. |
| </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_conf_devtools"></a>3. |
| Command Line Configuration |
| </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#ref_guide_conf_devtools_format">3.1. |
| Code Formatting |
| </a></span></dt></dl></div><a class="indexterm" name="d0e12218"></a><p> |
| OpenJPA development tools share the same set of configuration defaults and |
| overrides as the runtime system. They also allow you to specify property values |
| on the command line: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">-properties/-p <configuration file or resource></code>: Use |
| the <code class="literal">-properties</code> flag, or its shorter <code class="literal">-p</code> |
| form, to specify a configuration file to use. Note that OpenJPA always searches |
| the default file locations described above, so this flag is only needed when you |
| do not have a default resource in place, or when you wish to override the |
| defaults. The given value can be the path to a file, or the resource name of a |
| file somewhere in the <code class="literal">CLASSPATH</code>. OpenJPA will search the |
| given location as well as the location prefixed by <code class="filename"> META-INF/ |
| </code>. Thus, to point an OpenJPA tool at <code class="filename"> |
| META-INF/my-persistence.xml</code>, you can use: |
| </p><pre class="programlisting"> |
| <tool> -p my-persistence.xml |
| </pre><p> |
| If you want to run a tool against just one particular persistence unit in |
| a configuration file, you can do so by specifying an anchor along with the |
| resource. If you do not specify an anchor, the tools will run against all |
| the persistence units defined within the specified resource, or the default |
| resource if none is specified. If the persistence unit is defined within |
| the default resource location, then you can just specify the raw anchor itself: |
| </p><pre class="programlisting"> |
| <tool> -p my-persistence.xml#sales-persistence-unit |
| <tool> -p #invoice-persistence-unit |
| </pre></li><li><p> |
| <code class="literal">-<property name> <property value></code>: Any |
| configuration property that you can specify in a configuration file can be |
| overridden with a command line flag. The flag name is always the last token of |
| the corresponding property name, with the first letter in either upper or lower |
| case. For example, to override the <code class="literal">openjpa.ConnectionUserName</code> |
| property, you could pass the <code class="literal">-connectionUserName <value> |
| </code> flag to any tool. Values set this way override both the values in the |
| configuration file and values set via System properties. |
| </p></li></ul></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_conf_devtools_format"></a>3.1. |
| Code Formatting |
| </h3></div></div></div><a class="indexterm" name="d0e12268"></a><p> |
| Some OpenJPA development tools generate Java code. These tools share a common |
| set of command-line flags for formatting their output to match your coding |
| style. All code formatting flags can begin with either the <code class="literal">codeFormat |
| </code> or <code class="literal">cf</code> prefix. |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">-codeFormat./-cf.tabSpaces <spaces></code>: The number of |
| spaces that make up a tab, or 0 to use tab characters. Defaults to using tab |
| characters. |
| </p></li><li><p> |
| <code class="literal">-codeFormat./-cf.spaceBeforeParen <true/t | false/f></code>: |
| Whether or not to place a space before opening parentheses on method calls, if |
| statements, loops, etc. Defaults to <code class="literal">false</code>. |
| </p></li><li><p> |
| <code class="literal">-codeFormat./-cf.spaceInParen <true/t | false/f></code>: |
| Whether or not to place a space within parentheses; i.e. <code class="literal">method( arg) |
| </code>. Defaults to <code class="literal">false</code>. |
| </p></li><li><p> |
| <code class="literal">-codeFormat./-cf.braceOnSameLine <true/t | false/f></code>: |
| Whether or not to place opening braces on the same line as the declaration that |
| begins the code block, or on the next line. Defaults to <code class="literal">true</code> |
| . |
| </p></li><li><p> |
| <code class="literal">-codeFormat./-cf.braceAtSameTabLevel <true/t | false/f></code> |
| : When the <code class="literal">braceOnSameLine</code> option is disabled, you can choose |
| whether to place the brace at the same tab level of the contained code. Defaults |
| to <code class="literal">false</code>. |
| </p></li><li><p> |
| <code class="literal">-codeFormat./-cf.scoreBeforeFieldName <true/t | false/f> |
| </code>: Whether to prefix an underscore to names of private member |
| variables. Defaults to <code class="literal">false</code>. |
| </p></li><li><p> |
| <code class="literal">-codeFormat./-cf.linesBetweenSections <lines></code>: The |
| number of lines to skip between sections of code. Defaults to 1. |
| </p></li></ul></div><div class="example"><a name="ref_guide_conf_devtools_format_ex"></a><p class="title"><b>Example 2.1. |
| Code Formatting with the Application Id Tool |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| java org.apache.openjpa.enhance.ApplicationIdTool -cf.spaceBeforeParen true -cf.tabSpaces 4 |
| </pre></div></div><br class="example-break"></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_conf_plugins"></a>4. |
| Plugin Configuration |
| </h2></div></div></div><a class="indexterm" name="d0e12351"></a><a class="indexterm" name="d0e12356"></a><p> |
| Because OpenJPA is a highly customizable environment, many configuration |
| properties relate to the creation and configuration of system plugins. Plugin |
| properties have a syntax very similar to that of Java 5 annotations. They allow |
| you to specify both what class to use for the plugin and how to configure the |
| public fields or bean properties of the instantiated plugin instance. The |
| easiest way to describe the plugin syntax is by example: |
| </p><p> |
| OpenJPA has a pluggable L2 caching mechanism that is controlled by the <code class="literal"> |
| openjpa.DataCache</code> configuration property. Suppose that you have |
| created a new class, <code class="classname">com.xyz.MyDataCache</code>, that you want |
| OpenJPA to use for caching. You've made instances of <code class="literal">MyDataCache |
| </code> configurable via two methods, <code class="methodname">setCacheSize(int size) |
| </code> and <code class="methodname">setRemoteHost(String host)</code>. The |
| sample below shows how you would tell OpenJPA to use an instance of your custom |
| plugin with a max size of 1000 and a remote host of <code class="literal">cacheserver |
| </code>. |
| </p><pre class="programlisting"> |
| <property name="openjpa.DataCache" |
| value="com.xyz.MyDataCache(CacheSize=1000, RemoteHost=cacheserver)"/> |
| </pre><p> |
| As you can see, plugin properties take a class name, followed by a |
| comma-separated list of values for the plugin's public fields or bean properties |
| in parentheses. OpenJPA will match each named property to a field or setter |
| method in the instantiated plugin instance, and set the field or invoke the |
| method with the given value (after converting the value to the right type, of |
| course). The first letter of the property names can be in either upper or lower |
| case. The following would also have been valid: |
| </p><pre class="programlisting"> |
| com.xyz.MyDataCache(cacheSize=1000, remoteHost=cacheserver) |
| </pre><p> |
| If you do not need to pass any property settings to a plugin, you can just name |
| the class to use: |
| </p><pre class="programlisting"> |
| com.xyz.MyDataCache |
| </pre><p> |
| Similarly, if the plugin has a default class that you do not want to change, you |
| can simply specify a list of property settings, without a class name. For |
| example, OpenJPA's query cache companion to the data cache has a default |
| implementation suitable to most users, but you still might want to change the |
| query cache's size. It has a <code class="literal">CacheSize</code> property for this |
| purpose: |
| </p><pre class="programlisting"> |
| CacheSize=1000 |
| </pre><p> |
| Finally, many of OpenJPA's built-in options for plugins have short alias names |
| that you can use in place of the full class name. The data cache property, for |
| example, has an available alias of <code class="literal">true</code> for the standard |
| cache implementation. The property value simply becomes: |
| </p><pre class="programlisting"> |
| true |
| </pre><p> |
| The standard cache implementation class also has a <code class="literal">CacheSize</code> |
| property, so to use the standard implementation and configure the size, specify: |
| </p><pre class="programlisting"> |
| true(CacheSize=1000) |
| </pre><p> |
| The remainder of this chapter reviews the set of configuration properties |
| OpenJPA recognizes. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_conf_openjpa"></a>5. |
| OpenJPA Properties |
| </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#openjpa.AutoClear">5.1. |
| openjpa.AutoClear |
| </a></span></dt><dt><span class="section"><a href="#openjpa.AutoDetach">5.2. |
| openjpa.AutoDetach |
| </a></span></dt><dt><span class="section"><a href="#openjpa.BrokerFactory">5.3. |
| openjpa.BrokerFactory |
| </a></span></dt><dt><span class="section"><a href="#openjpa.BrokerImpl">5.4. |
| openjpa.BrokerImpl |
| </a></span></dt><dt><span class="section"><a href="#openjpa.ClassResolver">5.5. |
| openjpa.ClassResolver |
| </a></span></dt><dt><span class="section"><a href="#openjpa.Compatibility">5.6. |
| openjpa.Compatibility |
| </a></span></dt><dt><span class="section"><a href="#openjpa.ConnectionDriverName">5.7. |
| openjpa.ConnectionDriverName |
| </a></span></dt><dt><span class="section"><a href="#openjpa.Connection2DriverName">5.8. |
| openjpa.Connection2DriverName |
| </a></span></dt><dt><span class="section"><a href="#openjpa.ConnectionFactory">5.9. |
| openjpa.ConnectionFactory |
| </a></span></dt><dt><span class="section"><a href="#openjpa.ConnectionFactory2">5.10. |
| openjpa.ConnectionFactory2 |
| </a></span></dt><dt><span class="section"><a href="#openjpa.ConnectionFactoryName">5.11. |
| openjpa.ConnectionFactoryName |
| </a></span></dt><dt><span class="section"><a href="#openjpa.ConnectionFactory2Name">5.12. |
| openjpa.ConnectionFactory2Name |
| </a></span></dt><dt><span class="section"><a href="#openjpa.ConnectionFactoryMode">5.13. |
| openjpa.ConnectionFactoryMode |
| </a></span></dt><dt><span class="section"><a href="#openjpa.ConnectionFactoryProperties">5.14. |
| openjpa.ConnectionFactoryProperties |
| </a></span></dt><dt><span class="section"><a href="#openjpa.ConnectionFactory2Properties">5.15. |
| openjpa.ConnectionFactory2Properties |
| </a></span></dt><dt><span class="section"><a href="#openjpa.ConnectionPassword">5.16. |
| openjpa.ConnectionPassword |
| </a></span></dt><dt><span class="section"><a href="#openjpa.Connection2Password">5.17. |
| openjpa.Connection2Password |
| </a></span></dt><dt><span class="section"><a href="#openjpa.ConnectionProperties">5.18. |
| openjpa.ConnectionProperties |
| </a></span></dt><dt><span class="section"><a href="#openjpa.Connection2Properties">5.19. |
| openjpa.Connection2Properties |
| </a></span></dt><dt><span class="section"><a href="#openjpa.ConnectionURL">5.20. |
| openjpa.ConnectionURL |
| </a></span></dt><dt><span class="section"><a href="#openjpa.Connection2URL">5.21. |
| openjpa.Connection2URL |
| </a></span></dt><dt><span class="section"><a href="#openjpa.ConnectionUserName">5.22. |
| openjpa.ConnectionUserName |
| </a></span></dt><dt><span class="section"><a href="#openjpa.Connection2UserName">5.23. |
| openjpa.Connection2UserName |
| </a></span></dt><dt><span class="section"><a href="#openjpa.ConnectionRetainMode">5.24. |
| openjpa.ConnectionRetainMode |
| </a></span></dt><dt><span class="section"><a href="#openjpa.DataCache">5.25. |
| openjpa.DataCache |
| </a></span></dt><dt><span class="section"><a href="#openjpa.DataCacheManager">5.26. |
| openjpa.DataCacheManager |
| </a></span></dt><dt><span class="section"><a href="#openjpa.DataCacheTimeout">5.27. |
| openjpa.DataCacheTimeout |
| </a></span></dt><dt><span class="section"><a href="#openjpa.DetachState">5.28. |
| openjpa.DetachState |
| </a></span></dt><dt><span class="section"><a href="#openjpa.DynamicDataStructs">5.29. |
| openjpa.DynamicDataStructs |
| </a></span></dt><dt><span class="section"><a href="#openjpa.FetchBatchSize">5.30. |
| openjpa.FetchBatchSize |
| </a></span></dt><dt><span class="section"><a href="#openjpa.FetchGroups">5.31. |
| openjpa.FetchGroups |
| </a></span></dt><dt><span class="section"><a href="#openjpa.FlushBeforeQueries">5.32. |
| openjpa.FlushBeforeQueries |
| </a></span></dt><dt><span class="section"><a href="#openjpa.IgnoreChanges">5.33. |
| openjpa.IgnoreChanges |
| </a></span></dt><dt><span class="section"><a href="#openjpa.Id">5.34. openjpa.Id</a></span></dt><dt><span class="section"><a href="#openjpa.InverseManager">5.35. |
| openjpa.InverseManager |
| </a></span></dt><dt><span class="section"><a href="#openjpa.LockManager">5.36. |
| openjpa.LockManager |
| </a></span></dt><dt><span class="section"><a href="#openjpa.LockTimeout">5.37. |
| openjpa.LockTimeout |
| </a></span></dt><dt><span class="section"><a href="#openjpa.Log">5.38. |
| openjpa.Log |
| </a></span></dt><dt><span class="section"><a href="#openjpa.ManagedRuntime">5.39. |
| openjpa.ManagedRuntime |
| </a></span></dt><dt><span class="section"><a href="#openjpa.Mapping">5.40. |
| openjpa.Mapping |
| </a></span></dt><dt><span class="section"><a href="#openjpa.MaxFetchDepth">5.41. |
| openjpa.MaxFetchDepth |
| </a></span></dt><dt><span class="section"><a href="#openjpa.MetaDataFactory">5.42. |
| openjpa.MetaDataFactory |
| </a></span></dt><dt><span class="section"><a href="#openjpa.MetaDataRepository">5.43. |
| openjpa.MetaDataRepository |
| </a></span></dt><dt><span class="section"><a href="#openjpa.Multithreaded">5.44. |
| openjpa.Multithreaded |
| </a></span></dt><dt><span class="section"><a href="#openjpa.Optimistic">5.45. |
| openjpa.Optimistic |
| </a></span></dt><dt><span class="section"><a href="#openjpa.OrphanedKeyAction">5.46. |
| openjpa.OrphanedKeyAction |
| </a></span></dt><dt><span class="section"><a href="#openjpa.NontransactionalRead">5.47. |
| openjpa.NontransactionalRead |
| </a></span></dt><dt><span class="section"><a href="#openjpa.NontransactionalWrite">5.48. |
| openjpa.NontransactionalWrite |
| </a></span></dt><dt><span class="section"><a href="#openjpa.ProxyManager">5.49. |
| openjpa.ProxyManager |
| </a></span></dt><dt><span class="section"><a href="#openjpa.QueryCache">5.50. |
| openjpa.QueryCache |
| </a></span></dt><dt><span class="section"><a href="#openjpa.QueryCompilationCache">5.51. |
| openjpa.QueryCompilationCache |
| </a></span></dt><dt><span class="section"><a href="#openjpa.ReadLockLevel">5.52. |
| openjpa.ReadLockLevel |
| </a></span></dt><dt><span class="section"><a href="#openjpa.RemoteCommitProvider">5.53. |
| openjpa.RemoteCommitProvider |
| </a></span></dt><dt><span class="section"><a href="#openjpa.RestoreState">5.54. |
| openjpa.RestoreState |
| </a></span></dt><dt><span class="section"><a href="#openjpa.RetainState">5.55. |
| openjpa.RetainState |
| </a></span></dt><dt><span class="section"><a href="#openjpa.RetryClassRegistration">5.56. |
| openjpa.RetryClassRegistration |
| </a></span></dt><dt><span class="section"><a href="#openjpa.RuntimeUnenhancedClasses">5.57. openjpa.RuntimeUnenhancedClasses</a></span></dt><dt><span class="section"><a href="#openjpa.SavepointManager">5.58. |
| openjpa.SavepointManager |
| </a></span></dt><dt><span class="section"><a href="#openjpa.Sequence">5.59. |
| openjpa.Sequence |
| </a></span></dt><dt><span class="section"><a href="#openjpa.TransactionMode">5.60. |
| openjpa.TransactionMode |
| </a></span></dt><dt><span class="section"><a href="#openjpa.WriteLockLevel">5.61. |
| openjpa.WriteLockLevel |
| </a></span></dt></dl></div><a class="indexterm" name="d0e12419"></a><p> |
| OpenJPA defines many configuration properties. Most of these properties are |
| provided for advanced users who wish to customize OpenJPA's behavior; the |
| majority of developers can omit them. The following properties apply to any |
| OpenJPA back-end, though the given descriptions are tailored to OpenJPA's |
| default JDBC store. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.AutoClear"></a>5.1. |
| openjpa.AutoClear |
| </h3></div></div></div><a class="indexterm" name="d0e12430"></a><a class="indexterm" name="d0e12433"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal">openjpa.AutoClear |
| </code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/conf/OpenJPAConfiguration.html#getAutoClear()" target="_top"> |
| <code class="methodname">org.apache.openjpa.conf.OpenJPAConfiguration.getAutoClear |
| </code></a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| AutoClear</code> |
| </p><p> |
| <span class="bold"><strong>Default: </strong></span><code class="literal">datastore</code> |
| </p><p> |
| <span class="bold"><strong>Possible values: </strong></span><code class="literal">datastore</code>, |
| <code class="literal">all</code> |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> When to automatically clear |
| instance state: on entering a datastore transaction, or on entering any |
| transaction. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.AutoDetach"></a>5.2. |
| openjpa.AutoDetach |
| </h3></div></div></div><a class="indexterm" name="d0e12489"></a><a class="indexterm" name="d0e12492"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal">openjpa.AutoDetach |
| </code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/conf/OpenJPAConfiguration.html#getAutoDetach()" target="_top"> |
| <code class="methodname">org.apache.openjpa.conf.OpenJPAConfiguration.getAutoDetach |
| </code></a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| AutoDetach</code> |
| </p><p> |
| <span class="bold"><strong>Default:</strong></span> - |
| </p><p> |
| <span class="bold"><strong>Possible values: </strong></span><code class="literal">close</code>, |
| <code class="literal">commit</code>, <code class="literal">nontx-read</code> |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> A comma-separated list of events |
| when managed instances will be automatically detached. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.BrokerFactory"></a>5.3. |
| openjpa.BrokerFactory |
| </h3></div></div></div><a class="indexterm" name="d0e12549"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal">openjpa.BrokerFactory |
| </code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/conf/OpenJPAConfiguration.html#getBrokerFactory()" target="_top"> |
| <code class="methodname">org.apache.openjpa.conf.OpenJPAConfiguration.getBrokerFactory |
| </code></a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| BrokerFactory</code> |
| </p><p> |
| <span class="bold"><strong>Default: </strong></span><code class="literal">jdbc</code> |
| </p><p> |
| <span class="bold"><strong>Possible values: </strong></span><code class="literal">jdbc</code>, |
| <code class="literal">abstractstore</code>, <code class="literal">remote</code> |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> A plugin string (see |
| <a href="#ref_guide_conf_plugins" title="4. Plugin Configuration">Section 4, “ |
| Plugin Configuration |
| ”</a>) describing the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/kernel/BrokerFactory.html" target="_top"> |
| <code class="classname">org.apache.openjpa.kernel.BrokerFactory</code></a> type to |
| use. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.BrokerImpl"></a>5.4. |
| openjpa.BrokerImpl |
| </h3></div></div></div><a class="indexterm" name="d0e12611"></a><a class="indexterm" name="d0e12614"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal">openjpa.BrokerImpl |
| </code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/conf/OpenJPAConfiguration.html#getBrokerImpl()" target="_top"> |
| <code class="methodname">org.apache.openjpa.conf.OpenJPAConfiguration.getBrokerImpl |
| </code></a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| BrokerImpl</code> |
| </p><p> |
| <span class="bold"><strong>Default: </strong></span><code class="literal">default</code> |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> A plugin string (see |
| <a href="#ref_guide_conf_plugins" title="4. Plugin Configuration">Section 4, “ |
| Plugin Configuration |
| ”</a>) describing the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/kernel/Broker.html" target="_top"><code class="classname"> |
| org.apache.openjpa.kernel.Broker</code></a> type to use at runtime. See |
| <a href="#ref_guide_runtime_broker_extension" title="1.2. Broker Customization and Eviction">Section 1.2, “ |
| Broker Customization and Eviction |
| ”</a> on for details. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.ClassResolver"></a>5.5. |
| openjpa.ClassResolver |
| </h3></div></div></div><a class="indexterm" name="d0e12666"></a><a class="indexterm" name="d0e12669"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal">openjpa.ClassResolver |
| </code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/conf/OpenJPAConfiguration.html#getClassResolver()" target="_top"> |
| <code class="methodname">org.apache.openjpa.conf.OpenJPAConfiguration.getClassResolver |
| </code></a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| ClassResolver</code> |
| </p><p> |
| <span class="bold"><strong>Default: </strong></span><code class="literal">default</code> |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> A plugin string (see |
| <a href="#ref_guide_conf_plugins" title="4. Plugin Configuration">Section 4, “ |
| Plugin Configuration |
| ”</a>) describing the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/util/ClassResolver.html" target="_top"><code class="classname"> |
| org.apache.openjpa.util.ClassResolver</code></a> implementation to use |
| for class name resolution. You may wish to plug in your own resolver if you have |
| special classloading needs. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.Compatibility"></a>5.6. |
| openjpa.Compatibility |
| </h3></div></div></div><a class="indexterm" name="d0e12719"></a><a class="indexterm" name="d0e12722"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal">openjpa.Compatibility |
| </code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/conf/OpenJPAConfiguration.html#getCompatibility()" target="_top"> |
| <code class="methodname">org.apache.openjpa.conf.OpenJPAConfiguration.getCompatibility |
| </code></a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| Compatibility</code> |
| </p><p> |
| <span class="bold"><strong>Default:</strong></span> - |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> Encapsulates options to mimic the |
| behavior of previous OpenJPA releases. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.ConnectionDriverName"></a>5.7. |
| openjpa.ConnectionDriverName |
| </h3></div></div></div><a class="indexterm" name="d0e12762"></a><a class="indexterm" name="d0e12765"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal"> |
| openjpa.ConnectionDriverName</code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/conf/OpenJPAConfiguration.html#getConnectionDriverName()" target="_top"> |
| <code class="methodname"> |
| org.apache.openjpa.conf.OpenJPAConfiguration.getConnectionDriverName |
| </code></a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| ConnectionDriverName</code> |
| </p><p> |
| <span class="bold"><strong>Default:</strong></span> - |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> The full class name of either the |
| JDBC <code class="classname">java.sql.Driver</code>, or a <code class="classname"> |
| javax.sql.DataSource</code> implementation to use to connect to the |
| database. See <a href="#ref_guide_dbsetup" title="Chapter 4. JDBC">Chapter 4, <i xmlns:xlink="http://www.w3.org/1999/xlink"> |
| JDBC |
| </i></a> for details. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.Connection2DriverName"></a>5.8. |
| openjpa.Connection2DriverName |
| </h3></div></div></div><a class="indexterm" name="d0e12815"></a><a class="indexterm" name="d0e12818"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal"> |
| openjpa.Connection2DriverName</code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/conf/OpenJPAConfiguration.html#getConnection2DriverName()" target="_top"> |
| <code class="methodname"> |
| org.apache.openjpa.conf.OpenJPAConfiguration.getConnection2DriverName |
| </code></a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| Connection2DriverName</code> |
| </p><p> |
| <span class="bold"><strong>Default:</strong></span> - |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> This property is equivalent to the |
| <code class="literal">openjpa.ConnectionDriverName</code> property described in |
| <a href="#openjpa.ConnectionDriverName" title="5.7. openjpa.ConnectionDriverName">Section 5.7, “ |
| openjpa.ConnectionDriverName |
| ”</a>, but applies to the |
| alternate connection factory used for unmanaged connections. See |
| <a href="#ref_guide_dbsetup_thirdparty_enlist" title="2.1. Managed and XA DataSources">Section 2.1, “ |
| Managed and XA DataSources |
| ”</a> for details. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.ConnectionFactory"></a>5.9. |
| openjpa.ConnectionFactory |
| </h3></div></div></div><a class="indexterm" name="d0e12867"></a><a class="indexterm" name="d0e12870"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal"> |
| openjpa.ConnectionFactory</code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/conf/OpenJPAConfiguration.html#getConnectionFactory()" target="_top"> |
| <code class="methodname">org.apache.openjpa.conf.OpenJPAConfiguration.getConnectionFactory |
| </code></a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| ConnectionFactory</code> |
| </p><p> |
| <span class="bold"><strong>Default:</strong></span> - |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> A <code class="classname">javax.sql.DataSource |
| </code> to use to connect to the database. See |
| <a href="#ref_guide_dbsetup" title="Chapter 4. JDBC">Chapter 4, <i xmlns:xlink="http://www.w3.org/1999/xlink"> |
| JDBC |
| </i></a> for details. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.ConnectionFactory2"></a>5.10. |
| openjpa.ConnectionFactory2 |
| </h3></div></div></div><a class="indexterm" name="d0e12917"></a><a class="indexterm" name="d0e12920"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal"> |
| openjpa.ConnectionFactory2</code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/conf/OpenJPAConfiguration.html#getConnectionFactory2()" target="_top"> |
| <code class="methodname">org.apache.openjpa.conf.OpenJPAConfiguration.getConnectionFactory2 |
| </code></a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| ConnectionFactory2</code> |
| </p><p> |
| <span class="bold"><strong>Default:</strong></span> - |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> An unmanaged <code class="classname"> |
| javax.sql.DataSource</code> to use to connect to the database. See |
| <a href="#ref_guide_dbsetup" title="Chapter 4. JDBC">Chapter 4, <i xmlns:xlink="http://www.w3.org/1999/xlink"> |
| JDBC |
| </i></a> for details. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.ConnectionFactoryName"></a>5.11. |
| openjpa.ConnectionFactoryName |
| </h3></div></div></div><a class="indexterm" name="d0e12967"></a><a class="indexterm" name="d0e12970"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal"> |
| openjpa.ConnectionFactoryName</code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/conf/OpenJPAConfiguration.html#getConnectionFactoryName()" target="_top"> |
| <code class="methodname"> |
| org.apache.openjpa.conf.OpenJPAConfiguration.getConnectionFactoryName |
| </code></a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| ConnectionFactoryName</code> |
| </p><p> |
| <span class="bold"><strong>Default:</strong></span> - |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> The JNDI location of a <code class="classname"> |
| javax.sql.DataSource</code> to use to connect to the database. See |
| <a href="#ref_guide_dbsetup" title="Chapter 4. JDBC">Chapter 4, <i xmlns:xlink="http://www.w3.org/1999/xlink"> |
| JDBC |
| </i></a> for details. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.ConnectionFactory2Name"></a>5.12. |
| openjpa.ConnectionFactory2Name |
| </h3></div></div></div><a class="indexterm" name="d0e13017"></a><a class="indexterm" name="d0e13020"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal"> |
| openjpa.ConnectionFactory2Name</code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/conf/OpenJPAConfiguration.html#getConnectionFactory2Name()" target="_top"> |
| <code class="methodname"> |
| org.apache.openjpa.conf.OpenJPAConfiguration.getConnectionFactory2Name |
| </code></a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| ConnectionFactory2Name</code> |
| </p><p> |
| <span class="bold"><strong>Default:</strong></span> - |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> The JNDI location of an unmanaged |
| <code class="classname">javax.sql.DataSource</code> to use to connect to the database. |
| See <a href="#ref_guide_enterprise_xa" title="3. XA Transactions">Section 3, “ |
| XA Transactions |
| ”</a> for details. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.ConnectionFactoryMode"></a>5.13. |
| openjpa.ConnectionFactoryMode |
| </h3></div></div></div><a class="indexterm" name="d0e13067"></a><a class="indexterm" name="d0e13070"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal"> |
| openjpa.ConnectionFactoryMode</code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/conf/OpenJPAConfiguration.html#getConnectionFactoryMode()" target="_top"> |
| <code class="methodname"> |
| org.apache.openjpa.conf.OpenJPAConfiguration.getConnectionFactoryMode |
| </code></a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| ConnectionFactoryMode</code> |
| </p><p> |
| <span class="bold"><strong>Default: </strong></span><code class="literal">local</code> |
| </p><p> |
| <span class="bold"><strong>Possible values: </strong></span><code class="literal">local</code>, |
| <code class="literal">managed</code> |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> The connection factory mode to use |
| when integrating with the application server's managed transactions. See |
| <a href="#ref_guide_dbsetup_thirdparty_enlist" title="2.1. Managed and XA DataSources">Section 2.1, “ |
| Managed and XA DataSources |
| ”</a> for details. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.ConnectionFactoryProperties"></a>5.14. |
| openjpa.ConnectionFactoryProperties |
| </h3></div></div></div><a class="indexterm" name="d0e13126"></a><a class="indexterm" name="d0e13129"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal"> |
| openjpa.ConnectionFactoryProperties</code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/conf/OpenJPAConfiguration.html#getConnectionFactoryProperties()" target="_top"> |
| <code class="methodname"> |
| org.apache.openjpa.conf.OpenJPAConfiguration.getConnectionFactoryProperties |
| </code></a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| ConnectionFactoryProperties</code> |
| </p><p> |
| <span class="bold"><strong>Default:</strong></span> - |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> A plugin string (see |
| <a href="#ref_guide_conf_plugins" title="4. Plugin Configuration">Section 4, “ |
| Plugin Configuration |
| ”</a>) listing properties for |
| configuration of the datasource in use. See the |
| <a href="#ref_guide_dbsetup" title="Chapter 4. JDBC">Chapter 4, <i xmlns:xlink="http://www.w3.org/1999/xlink"> |
| JDBC |
| </i></a> for details. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.ConnectionFactory2Properties"></a>5.15. |
| openjpa.ConnectionFactory2Properties |
| </h3></div></div></div><a class="indexterm" name="d0e13175"></a><a class="indexterm" name="d0e13178"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal"> |
| openjpa.ConnectionFactory2Properties</code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/conf/OpenJPAConfiguration.html#getConnectionFactory2Properties()" target="_top"> |
| <code class="methodname"> |
| org.apache.openjpa.conf.OpenJPAConfiguration.getConnectionFactory2Properties |
| </code></a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| ConnectionFactory2Properties</code> |
| </p><p> |
| <span class="bold"><strong>Default:</strong></span> - |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> This property is equivalent to the |
| <code class="literal">openjpa.ConnectionFactoryProperties</code> property described in |
| <a href="#openjpa.ConnectionFactoryProperties" title="5.14. openjpa.ConnectionFactoryProperties">Section 5.14, “ |
| openjpa.ConnectionFactoryProperties |
| ”</a>, but applies to the |
| alternate connection factory used for unmanaged connections. See |
| <a href="#ref_guide_dbsetup_thirdparty_enlist" title="2.1. Managed and XA DataSources">Section 2.1, “ |
| Managed and XA DataSources |
| ”</a> for details. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.ConnectionPassword"></a>5.16. |
| openjpa.ConnectionPassword |
| </h3></div></div></div><a class="indexterm" name="d0e13227"></a><a class="indexterm" name="d0e13230"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal"> |
| openjpa.ConnectionPassword</code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/conf/OpenJPAConfiguration.html#getConnectionPassword()" target="_top"> |
| <code class="methodname">org.apache.openjpa.conf.OpenJPAConfiguration.getConnectionPassword |
| </code></a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| ConnectionPassword</code> |
| </p><p> |
| <span class="bold"><strong>Default:</strong></span> - |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> The password for the user |
| specified in the <code class="literal">ConnectionUserName</code> property. See |
| <a href="#ref_guide_dbsetup" title="Chapter 4. JDBC">Chapter 4, <i xmlns:xlink="http://www.w3.org/1999/xlink"> |
| JDBC |
| </i></a> for details. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.Connection2Password"></a>5.17. |
| openjpa.Connection2Password |
| </h3></div></div></div><a class="indexterm" name="d0e13277"></a><a class="indexterm" name="d0e13280"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal"> |
| openjpa.Connection2Password</code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/conf/OpenJPAConfiguration.html#getConnection2Password()" target="_top"> |
| <code class="methodname">org.apache.openjpa.conf.OpenJPAConfiguration.getConnection2Password |
| </code></a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| Connection2Password</code> |
| </p><p> |
| <span class="bold"><strong>Default:</strong></span> - |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> This property is equivalent to the |
| <code class="literal">openjpa.ConnectionPassword</code> property described in |
| <a href="#openjpa.ConnectionPassword" title="5.16. openjpa.ConnectionPassword">Section 5.16, “ |
| openjpa.ConnectionPassword |
| ”</a>, but applies to the |
| alternate connection factory used for unmanaged connections. See |
| <a href="#ref_guide_dbsetup_thirdparty_enlist" title="2.1. Managed and XA DataSources">Section 2.1, “ |
| Managed and XA DataSources |
| ”</a> for details. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.ConnectionProperties"></a>5.18. |
| openjpa.ConnectionProperties |
| </h3></div></div></div><a class="indexterm" name="d0e13329"></a><a class="indexterm" name="d0e13332"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal"> |
| openjpa.ConnectionProperties</code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/conf/OpenJPAConfiguration.html#getConnectionProperties()" target="_top"> |
| <code class="methodname"> |
| org.apache.openjpa.conf.OpenJPAConfiguration.getConnectionProperties |
| </code></a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| ConnectionProperties</code> |
| </p><p> |
| <span class="bold"><strong>Default:</strong></span> - |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> A plugin string (see |
| <a href="#ref_guide_conf_plugins" title="4. Plugin Configuration">Section 4, “ |
| Plugin Configuration |
| ”</a>) listing properties to configure |
| the driver listed in the <code class="literal">ConnectionDriverName</code> property |
| described below. See <a href="#ref_guide_dbsetup" title="Chapter 4. JDBC">Chapter 4, <i xmlns:xlink="http://www.w3.org/1999/xlink"> |
| JDBC |
| </i></a> for details. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.Connection2Properties"></a>5.19. |
| openjpa.Connection2Properties |
| </h3></div></div></div><a class="indexterm" name="d0e13381"></a><a class="indexterm" name="d0e13384"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal"> |
| openjpa.Connection2Properties</code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/conf/OpenJPAConfiguration.html#getConnection2Properties()" target="_top"> |
| <code class="methodname"> |
| org.apache.openjpa.conf.OpenJPAConfiguration.getConnection2Properties |
| </code></a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| Connection2Properties</code> |
| </p><p> |
| <span class="bold"><strong>Default:</strong></span> - |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> This property is equivalent to the |
| <code class="literal">openjpa.ConnectionProperties</code> property described in |
| <a href="#openjpa.ConnectionProperties" title="5.18. openjpa.ConnectionProperties">Section 5.18, “ |
| openjpa.ConnectionProperties |
| ”</a>, but applies to the |
| alternate connection factory used for unmanaged connections. See |
| <a href="#ref_guide_dbsetup_thirdparty_enlist" title="2.1. Managed and XA DataSources">Section 2.1, “ |
| Managed and XA DataSources |
| ”</a> for details. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.ConnectionURL"></a>5.20. |
| openjpa.ConnectionURL |
| </h3></div></div></div><a class="indexterm" name="d0e13433"></a><a class="indexterm" name="d0e13436"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal">openjpa.ConnectionURL |
| </code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/conf/OpenJPAConfiguration.html#getConnectionURL()" target="_top"> |
| <code class="methodname">org.apache.openjpa.conf.OpenJPAConfiguration.getConnectionURL |
| </code></a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| ConnectionURL</code> |
| </p><p> |
| <span class="bold"><strong>Default:</strong></span> - |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> The JDBC URL for the database. See |
| <a href="#ref_guide_dbsetup" title="Chapter 4. JDBC">Chapter 4, <i xmlns:xlink="http://www.w3.org/1999/xlink"> |
| JDBC |
| </i></a> for details. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.Connection2URL"></a>5.21. |
| openjpa.Connection2URL |
| </h3></div></div></div><a class="indexterm" name="d0e13480"></a><a class="indexterm" name="d0e13483"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal">openjpa.Connection2URL |
| </code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/conf/OpenJPAConfiguration.html#getConnection2URL()" target="_top"> |
| <code class="methodname">org.apache.openjpa.conf.OpenJPAConfiguration.getConnection2URL |
| </code></a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| Connection2URL</code> |
| </p><p> |
| <span class="bold"><strong>Default:</strong></span> - |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> This property is equivalent to the |
| <code class="literal">openjpa.ConnectionURL</code> property described in |
| <a href="#openjpa.ConnectionURL" title="5.20. openjpa.ConnectionURL">Section 5.20, “ |
| openjpa.ConnectionURL |
| ”</a>, but applies to the alternate |
| connection factory used for unmanaged connections. See |
| <a href="#ref_guide_dbsetup_thirdparty_enlist" title="2.1. Managed and XA DataSources">Section 2.1, “ |
| Managed and XA DataSources |
| ”</a> for details. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.ConnectionUserName"></a>5.22. |
| openjpa.ConnectionUserName |
| </h3></div></div></div><a class="indexterm" name="d0e13532"></a><a class="indexterm" name="d0e13535"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal"> |
| openjpa.ConnectionUserName</code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/conf/OpenJPAConfiguration.html#getConnectionUserName()" target="_top"> |
| <code class="methodname">org.apache.openjpa.conf.OpenJPAConfiguration.getConnectionUserName |
| </code></a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| ConnectionUserName</code> |
| </p><p> |
| <span class="bold"><strong>Default:</strong></span> - |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> The user name to use when |
| connecting to the database. See the <a href="#ref_guide_dbsetup" title="Chapter 4. JDBC">Chapter 4, <i xmlns:xlink="http://www.w3.org/1999/xlink"> |
| JDBC |
| </i></a> |
| for details. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.Connection2UserName"></a>5.23. |
| openjpa.Connection2UserName |
| </h3></div></div></div><a class="indexterm" name="d0e13579"></a><a class="indexterm" name="d0e13582"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal"> |
| openjpa.Connection2UserName</code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/conf/OpenJPAConfiguration.html#getConnection2UserName()" target="_top"> |
| <code class="methodname">org.apache.openjpa.conf.OpenJPAConfiguration.getConnection2UserName |
| </code></a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| Connection2UserName</code> |
| </p><p> |
| <span class="bold"><strong>Default:</strong></span> - |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> This property is equivalent to the |
| <code class="literal">openjpa.ConnectionUserName</code> property described in |
| <a href="#openjpa.ConnectionUserName" title="5.22. openjpa.ConnectionUserName">Section 5.22, “ |
| openjpa.ConnectionUserName |
| ”</a>, but applies to the |
| alternate connection factory used for unmanaged connections. See |
| <a href="#ref_guide_dbsetup_thirdparty_enlist" title="2.1. Managed and XA DataSources">Section 2.1, “ |
| Managed and XA DataSources |
| ”</a> for details. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.ConnectionRetainMode"></a>5.24. |
| openjpa.ConnectionRetainMode |
| </h3></div></div></div><a class="indexterm" name="d0e13631"></a><a class="indexterm" name="d0e13634"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal"> |
| openjpa.ConnectionRetainMode</code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/conf/OpenJPAConfiguration.html#getConnectionRetainMode()" target="_top"> |
| <code class="methodname"> |
| org.apache.openjpa.conf.OpenJPAConfiguration.getConnectionRetainMode |
| </code></a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| ConnectionRetainMode</code> |
| </p><p> |
| <span class="bold"><strong>Default: </strong></span><code class="literal">on-demand</code> |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> Controls how OpenJPA uses |
| datastore connections. This property can also be specified for individual |
| sessions. See <a href="#ref_guide_dbsetup_retain" title="8. Configuring the Use of JDBC Connections">Section 8, “ |
| Configuring the Use of JDBC Connections |
| ”</a> for details. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.DataCache"></a>5.25. |
| openjpa.DataCache |
| </h3></div></div></div><a class="indexterm" name="d0e13680"></a><a class="indexterm" name="d0e13683"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal">openjpa.DataCache |
| </code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/conf/OpenJPAConfiguration.html#getDataCache()" target="_top"> |
| <code class="methodname">org.apache.openjpa.conf.OpenJPAConfiguration.getDataCache |
| </code></a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| DataCache</code> |
| </p><p> |
| <span class="bold"><strong>Default: </strong></span><code class="literal">false</code> |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> A plugin list string (see |
| <a href="#ref_guide_conf_plugins" title="4. Plugin Configuration">Section 4, “ |
| Plugin Configuration |
| ”</a>) describing the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/datacache/DataCache.html" target="_top"><code class="classname"> |
| org.apache.openjpa.datacache.DataCache</code></a>s to use for data |
| caching. See <a href="#ref_guide_cache_conf" title="1.1. Data Cache Configuration">Section 1.1, “ |
| Data Cache Configuration |
| ”</a> for details. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.DataCacheManager"></a>5.26. |
| openjpa.DataCacheManager |
| </h3></div></div></div><a class="indexterm" name="d0e13735"></a><a class="indexterm" name="d0e13738"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal"> |
| openjpa.DataCacheManager</code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/conf/OpenJPAConfiguration.html#getDataCacheManager()" target="_top"> |
| <code class="methodname">org.apache.openjpa.conf.OpenJPAConfiguration.getDataCacheManager |
| </code></a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| DataCacheManager</code> |
| </p><p> |
| <span class="bold"><strong>Default: </strong></span><code class="literal">default</code> |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> A plugin string (see |
| <a href="#ref_guide_conf_plugins" title="4. Plugin Configuration">Section 4, “ |
| Plugin Configuration |
| ”</a>) describing the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/datacache/DataCacheManager.html" target="_top"> |
| <code class="classname">openjpa.datacache.DataCacheManager</code></a> that manages |
| the system data caches. See <a href="#ref_guide_cache" title="1. Data Cache">Section 1, “ |
| Data Cache |
| ”</a> for details |
| on data caching. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.DataCacheTimeout"></a>5.27. |
| openjpa.DataCacheTimeout |
| </h3></div></div></div><a class="indexterm" name="d0e13791"></a><a class="indexterm" name="d0e13794"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal"> |
| openjpa.DataCacheTimeout</code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/conf/OpenJPAConfiguration.html#getDataCacheTimeout()" target="_top"> |
| <code class="methodname">org.apache.openjpa.conf.OpenJPAConfiguration.getDataCacheTimeout |
| </code></a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| DataCacheTimeout</code> |
| </p><p> |
| <span class="bold"><strong>Default: </strong></span><code class="literal">-1</code> |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> The number of milliseconds that |
| data in the data cache is valid. Set this to -1 to indicate that data should not |
| expire from the cache. This property can also be specified for individual |
| classes. See <a href="#ref_guide_cache_conf" title="1.1. Data Cache Configuration">Section 1.1, “ |
| Data Cache Configuration |
| ”</a> for details. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.DetachState"></a>5.28. |
| openjpa.DetachState |
| </h3></div></div></div><a class="indexterm" name="d0e13840"></a><a class="indexterm" name="d0e13843"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal">openjpa.DetachState |
| </code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/conf/OpenJPAConfiguration.html#getDetachState()" target="_top"> |
| <code class="methodname">org.apache.openjpa.conf.OpenJPAConfiguration.getDetachState |
| </code></a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| DetachState</code> |
| </p><p> |
| <span class="bold"><strong>Default: </strong></span><code class="literal">loaded</code> |
| </p><p> |
| <span class="bold"><strong>Possible values: </strong></span><code class="literal">loaded</code>, |
| <code class="literal">fetch-groups</code>, <code class="literal">all</code> |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> Determines which fields are part |
| of the detached graph and related options. For more details, see |
| <a href="#ref_guide_detach_graph" title="1.3. Defining the Detached Object Graph">Section 1.3, “ |
| Defining the Detached Object Graph |
| ”</a>. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.DynamicDataStructs"></a>5.29. |
| openjpa.DynamicDataStructs |
| </h3></div></div></div><a class="indexterm" name="d0e13904"></a><a class="indexterm" name="d0e13907"></a><a class="indexterm" name="d0e13912"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal"> |
| openjpa.DynamicDataStructs</code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/conf/OpenJPAConfiguration.html#getDynamicDataStructs()" target="_top"> |
| <code class="methodname">org.apache.openjpa.conf.OpenJPAConfiguration.getDynamicDataStructs |
| </code></a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| DynamicDataStructs</code> |
| </p><p> |
| <span class="bold"><strong>Default: </strong></span><code class="literal">false</code> |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> Whether to dynamically generate |
| customized structs to hold persistent data. Both the OpenJPA data cache and the |
| remote framework rely on data structs to cache and transfer persistent state. |
| With dynamic structs, OpenJPA can customize data storage for each class, |
| eliminating the need to generate primitive wrapper objects. This saves memory |
| and speeds up certain runtime operations. The price is a longer warm-up time for |
| the application - generating and loading custom classes into the JVM takes time. |
| Therefore, only set this property to <code class="literal">true</code> if you have a |
| long-running application where the initial cost of class generation is offset by |
| memory and speed optimization over time. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.FetchBatchSize"></a>5.30. |
| openjpa.FetchBatchSize |
| </h3></div></div></div><a class="indexterm" name="d0e13959"></a><a class="indexterm" name="d0e13962"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal">openjpa.FetchBatchSize |
| </code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/conf/OpenJPAConfiguration.html#getFetchBatchSize()" target="_top"> |
| <code class="methodname">org.apache.openjpa.conf.OpenJPAConfiguration.getFetchBatchSize |
| </code></a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| FetchBatchSize</code> |
| </p><p> |
| <span class="bold"><strong>Default: </strong></span><code class="literal">-1</code> |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> The number of rows to fetch at |
| once when scrolling through a result set. The fetch size can also be set at |
| runtime. See <a href="#ref_guide_dbsetup_lrs" title="10. Large Result Sets">Section 10, “ |
| Large Result Sets |
| ”</a> for details. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.FetchGroups"></a>5.31. |
| openjpa.FetchGroups |
| </h3></div></div></div><a class="indexterm" name="d0e14008"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal">openjpa.FetchGroups |
| </code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/conf/OpenJPAConfiguration.html#getFetchGroups()" target="_top"> |
| <code class="methodname">org.apache.openjpa.conf.OpenJPAConfiguration.getFetchGroups |
| </code></a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| FetchGroups</code> |
| </p><p> |
| <span class="bold"><strong>Default:</strong></span> - |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> A comma-separated list of fetch |
| group names that are to be loaded when retrieving objects from the datastore. |
| Fetch groups can also be set at runtime. See <a href="#ref_guide_fetch" title="7. Fetch Groups">Section 7, “ |
| Fetch Groups |
| ”</a> |
| for details. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.FlushBeforeQueries"></a>5.32. |
| openjpa.FlushBeforeQueries |
| </h3></div></div></div><a class="indexterm" name="d0e14053"></a><a class="indexterm" name="d0e14056"></a><a class="indexterm" name="d0e14061"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal"> |
| openjpa.FlushBeforeQueries</code> |
| </p><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal"> |
| openjpa.FlushBeforeQueries</code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/conf/OpenJPAConfiguration.html#getFlushBeforeQueries()" target="_top"> |
| <code class="methodname">org.apache.openjpa.conf.OpenJPAConfiguration.getFlushBeforeQueries |
| </code></a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| FlushBeforeQueries</code> |
| </p><p> |
| <span class="bold"><strong>Default: </strong></span><code class="literal">true</code> |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> Whether or not to flush any |
| changes made in the current transaction to the datastore before executing a |
| query. See <a href="#ref_guide_dbsetup_retain" title="8. Configuring the Use of JDBC Connections">Section 8, “ |
| Configuring the Use of JDBC Connections |
| ”</a> for details. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.IgnoreChanges"></a>5.33. |
| openjpa.IgnoreChanges |
| </h3></div></div></div><a class="indexterm" name="d0e14114"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal">openjpa.IgnoreChanges |
| </code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/conf/OpenJPAConfiguration.html#getIgnoreChanges()" target="_top"> |
| <code class="methodname">org.apache.openjpa.conf.OpenJPAConfiguration.getIgnoreChanges |
| </code></a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| IgnoreChanges</code> |
| </p><p> |
| <span class="bold"><strong>Default: </strong></span><code class="literal">false</code> |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> Whether to consider modifications |
| to persistent objects made in the current transaction when evaluating queries. |
| Setting this to <code class="literal">true</code> allows OpenJPA to ignore changes and |
| execute the query directly against the datastore. A value of <code class="literal">false |
| </code> forces OpenJPA to consider whether the changes in the current |
| transaction affect the query, and if so to either evaluate the query in-memory |
| or flush before running it against the datastore. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.Id"></a>5.34. openjpa.Id</h3></div></div></div><a class="indexterm" name="d0e14162"></a><p> |
| <span class="bold"><strong>Property name:</strong></span> |
| <code class="literal">openjpa.Id</code> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property:</strong></span> |
| <code class="literal">Id</code> |
| </p><p> |
| <span class="bold"><strong>Default:</strong></span> none |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> An |
| environment-specific identifier for this configuration. This |
| might correspond to a JPA persistence-unit name, or to some other |
| more-unique value available in the current environment. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.InverseManager"></a>5.35. |
| openjpa.InverseManager |
| </h3></div></div></div><a class="indexterm" name="d0e14194"></a><a class="indexterm" name="d0e14197"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal">openjpa.InverseManager |
| </code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/conf/OpenJPAConfiguration.html#getInverseManager()" target="_top"> |
| <code class="methodname">org.apache.openjpa.conf.OpenJPAConfiguration.getInverseManager |
| </code></a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| InverseManager</code> |
| </p><p> |
| <span class="bold"><strong>Default: </strong></span><code class="literal">false</code> |
| </p><p> |
| <span class="bold"><strong>Possible values: </strong></span><code class="literal">false</code>, |
| <code class="literal">true</code> |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> A plugin string (see |
| <a href="#ref_guide_conf_plugins" title="4. Plugin Configuration">Section 4, “ |
| Plugin Configuration |
| ”</a>) describing a |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/kernel/InverseManager.html" target="_top"> |
| <code class="classname">org.apache.openjpa.kernel.InverseManager</code></a> to use |
| for managing bidirectional relations upon a flush. See |
| <a href="#ref_guide_inverses" title="5. Managed Inverses">Section 5, “ |
| Managed Inverses |
| ”</a> for usage documentation. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.LockManager"></a>5.36. |
| openjpa.LockManager |
| </h3></div></div></div><a class="indexterm" name="d0e14260"></a><a class="indexterm" name="d0e14263"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal">openjpa.LockManager |
| </code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/conf/OpenJPAConfiguration.html#getLockManager()" target="_top"> |
| <code class="methodname">org.apache.openjpa.conf.OpenJPAConfiguration.getLockManager |
| </code></a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| LockManager</code> |
| </p><p> |
| <span class="bold"><strong>Default: </strong></span><code class="literal">version</code> |
| </p><p> |
| <span class="bold"><strong>Possible values: </strong></span><code class="literal">none</code>, |
| <code class="literal">sjvm</code>, <code class="literal">pessimistic</code>, |
| <code class="literal">version</code> |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> A plugin string (see |
| <a href="#ref_guide_conf_plugins" title="4. Plugin Configuration">Section 4, “ |
| Plugin Configuration |
| ”</a>) describing a |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/kernel/LockManager.html" target="_top"><code class="classname"> |
| org.apache.openjpa.kernel.LockManager</code></a> to use for acquiring |
| locks on persistent instances during transactions. See |
| <a href="#ref_guide_locking_lockmgr" title="3.4. Lock Manager">Section 3.4, “ |
| Lock Manager |
| ”</a> for more information. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.LockTimeout"></a>5.37. |
| openjpa.LockTimeout |
| </h3></div></div></div><a class="indexterm" name="d0e14331"></a><a class="indexterm" name="d0e14334"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal">openjpa.LockTimeout |
| </code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/conf/OpenJPAConfiguration.html#getLockTimeout()" target="_top"> |
| <code class="methodname">org.apache.openjpa.conf.OpenJPAConfiguration.getLockTimeout |
| </code></a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| LockTimeout</code> |
| </p><p> |
| <span class="bold"><strong>Default: </strong></span><code class="literal">-1</code> |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> The number of milliseconds to wait |
| for an object lock before throwing an exception, or -1 for no limit. See |
| <a href="#ref_guide_locking" title="3. Object Locking">Section 3, “ |
| Object Locking |
| ”</a> for details. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.Log"></a>5.38. |
| openjpa.Log |
| </h3></div></div></div><a class="indexterm" name="d0e14380"></a><a class="indexterm" name="d0e14383"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal">openjpa.Log</code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/conf/OpenJPAConfiguration.html#getLog()" target="_top"> |
| <code class="methodname">org.apache.openjpa.conf.OpenJPAConfiguration.getLog</code> |
| </a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal">Log |
| </code> |
| </p><p> |
| <span class="bold"><strong>Default: </strong></span><code class="literal">true</code> |
| </p><p> |
| <span class="bold"><strong>Possible values: </strong></span><code class="literal">openjpa</code>, |
| <code class="literal">commons</code>, <code class="literal">log4j</code>, <code class="literal">none</code> |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> A plugin string (see |
| <a href="#ref_guide_conf_plugins" title="4. Plugin Configuration">Section 4, “ |
| Plugin Configuration |
| ”</a>) describing a |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/lib/log/LogFactory.html" target="_top"><code class="classname"> |
| org.apache.openjpa.lib.log.LogFactory</code></a> to use for logging. |
| For details on logging, see <a href="#ref_guide_logging" title="Chapter 3. Logging">Chapter 3, <i xmlns:xlink="http://www.w3.org/1999/xlink"> |
| Logging |
| </i></a>. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.ManagedRuntime"></a>5.39. |
| openjpa.ManagedRuntime |
| </h3></div></div></div><a class="indexterm" name="d0e14452"></a><a class="indexterm" name="d0e14455"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal">openjpa.ManagedRuntime |
| </code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/conf/OpenJPAConfiguration.html#getManagedRuntime()" target="_top"> |
| <code class="methodname">org.apache.openjpa.conf.OpenJPAConfiguration.getManagedRuntime |
| </code></a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| ManagedRuntime</code> |
| </p><p> |
| <span class="bold"><strong>Default: </strong></span><code class="literal">auto</code> |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> A plugin string (see |
| <a href="#ref_guide_conf_plugins" title="4. Plugin Configuration">Section 4, “ |
| Plugin Configuration |
| ”</a>) describing the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/ee/ManagedRuntime.html" target="_top"><code class="classname"> |
| org.apache.openjpa.ee.ManagedRuntime</code></a> implementation to use |
| for obtaining a reference to the <code class="classname">TransactionManager</code> in an |
| enterprise environment. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.Mapping"></a>5.40. |
| openjpa.Mapping |
| </h3></div></div></div><a class="indexterm" name="d0e14510"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal">openjpa.Mapping |
| </code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/conf/OpenJPAConfiguration.html#getMapping()" target="_top"> |
| <code class="methodname">org.apache.openjpa.conf.OpenJPAConfiguration.getMapping</code> |
| </a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| Mapping</code> |
| </p><p> |
| <span class="bold"><strong>Default:</strong></span> - |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> The symbolic name of the |
| object-to-datastore mapping to use. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.MaxFetchDepth"></a>5.41. |
| openjpa.MaxFetchDepth |
| </h3></div></div></div><a class="indexterm" name="d0e14551"></a><a class="indexterm" name="d0e14554"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal">openjpa.MaxFetchDepth |
| </code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/conf/OpenJPAConfiguration.html#getMaxFetchDepth()" target="_top"> |
| <code class="methodname">org.apache.openjpa.conf.OpenJPAConfiguration.getMaxFetchDepth |
| </code></a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| MaxFetchDepth</code> |
| </p><p> |
| <span class="bold"><strong>Default: </strong></span><code class="literal">-1</code> |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> The maximum depth of relations to |
| traverse when eager fetching. Use -1 for no limit. Defaults to no limit. See |
| <a href="#ref_guide_perfpack_eager" title="8. Eager Fetching">Section 8, “ |
| Eager Fetching |
| ”</a> for details on eager fetching. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.MetaDataFactory"></a>5.42. |
| openjpa.MetaDataFactory |
| </h3></div></div></div><a class="indexterm" name="d0e14600"></a><a class="indexterm" name="d0e14603"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal">openjpa.MetaDataFactory |
| </code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/conf/OpenJPAConfiguration.html#getMetaDataFactory()" target="_top"> |
| <code class="methodname">org.apache.openjpa.conf.OpenJPAConfiguration.getMetaDataFactory |
| </code></a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| MetaDataFactory</code> |
| </p><p> |
| <span class="bold"><strong>Default:</strong></span> <code class="literal">jpa</code> |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> A plugin string (see |
| <a href="#ref_guide_conf_plugins" title="4. Plugin Configuration">Section 4, “ |
| Plugin Configuration |
| ”</a>) describing the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/meta/MetaDataFactory.html" target="_top"> |
| <code class="classname">openjpa.meta.MetaDataFactory</code></a> to use to store and |
| retrieve metadata for your persistent classes. See |
| <a href="#ref_guide_meta_factory" title="1. Metadata Factory">Section 1, “ |
| Metadata Factory |
| ”</a> for details. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.MetaDataRepository"></a>5.43. |
| openjpa.MetaDataRepository |
| </h3></div></div></div><a class="indexterm" name="d0e14658"></a><a class="indexterm" name="d0e14661"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal">openjpa.MetaDataRepository |
| </code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/conf/OpenJPAConfiguration.html#getMetaDataRepository()" target="_top"> |
| <code class="methodname">org.apache.openjpa.conf.OpenJPAConfiguration.getMetaDataRepository |
| </code></a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| MetaDataRepository</code> |
| </p><p> |
| <span class="bold"><strong>Default:</strong></span>none<code class="literal"></code> |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> A plugin string (see |
| <a href="#ref_guide_conf_plugins" title="4. Plugin Configuration">Section 4, “ |
| Plugin Configuration |
| ”</a>) describing the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/meta/MetaDataRepository.html" target="_top"> |
| <code class="classname">openjpa.meta.MetaDataRepository</code></a> to use to store and |
| retrieve metadata for your persistent classes. See |
| <a href="#ref_guide_meta_repository" title="2. Metadata Repository">Section 2, “Metadata Repository”</a> for details. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.Multithreaded"></a>5.44. |
| openjpa.Multithreaded |
| </h3></div></div></div><a class="indexterm" name="d0e14715"></a><a class="indexterm" name="d0e14718"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal">openjpa.Multithreaded |
| </code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/conf/OpenJPAConfiguration.html#getMultithreaded()" target="_top"> |
| <code class="methodname">org.apache.openjpa.conf.OpenJPAConfiguration.getMultithreaded |
| </code></a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| Multithreaded</code> |
| </p><p> |
| <span class="bold"><strong>Default: </strong></span><code class="literal">false</code> |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> Whether persistent instances and |
| OpenJPA components other than the <code class="classname">EntityManagerFactory</code> |
| will be accessed by multiple threads at once. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.Optimistic"></a>5.45. |
| openjpa.Optimistic |
| </h3></div></div></div><a class="indexterm" name="d0e14765"></a><a class="indexterm" name="d0e14768"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal">openjpa.Optimistic |
| </code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/conf/OpenJPAConfiguration.html#getOptimistic()" target="_top"> |
| <code class="methodname">org.apache.openjpa.conf.OpenJPAConfiguration.getOptimistic |
| </code></a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| Optimistic</code> |
| </p><p> |
| <span class="bold"><strong>Default: </strong></span><code class="literal">true</code> |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> Selects between optimistic and |
| pessimistic (datastore) transactional modes. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.OrphanedKeyAction"></a>5.46. |
| openjpa.OrphanedKeyAction |
| </h3></div></div></div><a class="indexterm" name="d0e14812"></a><a class="indexterm" name="d0e14815"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal"> |
| openjpa.OrphanedKeyAction</code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/conf/OpenJPAConfiguration.html#getOrphanedKeyAction()" target="_top"> |
| <code class="methodname">org.apache.openjpa.conf.OpenJPAConfiguration.getOrphanedKeyAction |
| </code></a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| OrphanedKeyAction</code> |
| </p><p> |
| <span class="bold"><strong>Default: </strong></span><code class="literal">log</code> |
| </p><p> |
| <span class="bold"><strong>Possible values: </strong></span><code class="literal">log</code>, |
| <code class="literal">exception</code>, <code class="literal">none</code> |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> A plugin string (see |
| <a href="#ref_guide_conf_plugins" title="4. Plugin Configuration">Section 4, “ |
| Plugin Configuration |
| ”</a>) describing a |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/event/OrphanedKeyAction.html" target="_top"> |
| <code class="classname">org.apache.openjpa.event.OrphanedKeyAction</code></a> to |
| invoke when OpenJPA discovers an orphaned datastore key. See |
| <a href="#ref_guide_orphan" title="15. Orphaned Keys">Section 15, “ |
| Orphaned Keys |
| ”</a> for details. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.NontransactionalRead"></a>5.47. |
| openjpa.NontransactionalRead |
| </h3></div></div></div><a class="indexterm" name="d0e14881"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal"> |
| openjpa.NontransactionalRead</code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/conf/OpenJPAConfiguration.html#getNontransactionalRead()" target="_top"> |
| <code class="methodname"> |
| org.apache.openjpa.conf.OpenJPAConfiguration.getNontransactionalRead |
| </code></a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| NontransactionalRead</code> |
| </p><p> |
| <span class="bold"><strong>Default: </strong></span><code class="literal">true</code> |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> Whether the OpenJPA runtime will |
| allow you to read data outside of a transaction. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.NontransactionalWrite"></a>5.48. |
| openjpa.NontransactionalWrite |
| </h3></div></div></div><a class="indexterm" name="d0e14923"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal"> |
| openjpa.NontransactionalWrite</code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/conf/OpenJPAConfiguration.html#getNontransactionalWrite()" target="_top"> |
| <code class="methodname"> |
| org.apache.openjpa.conf.OpenJPAConfiguration.getNontransactionalWrite |
| </code></a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| NontransactionalWrite</code> |
| </p><p> |
| <span class="bold"><strong>Default:</strong></span> <code class="literal">true</code> |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> Whether you can modify persistent |
| objects and perform persistence operations outside of a transaction. Changes |
| will take effect on the next transaction. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.ProxyManager"></a>5.49. |
| openjpa.ProxyManager |
| </h3></div></div></div><a class="indexterm" name="d0e14966"></a><a class="indexterm" name="d0e14969"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal">openjpa.ProxyManager |
| </code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/conf/OpenJPAConfiguration.html#getProxyManager()" target="_top"> |
| <code class="methodname">org.apache.openjpa.conf.OpenJPAConfiguration.getProxyManager |
| </code></a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| ProxyManager</code> |
| </p><p> |
| <span class="bold"><strong>Default: </strong></span><code class="literal">default</code> |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> A plugin string (see |
| <a href="#ref_guide_conf_plugins" title="4. Plugin Configuration">Section 4, “ |
| Plugin Configuration |
| ”</a>) describing a |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/util/ProxyManager.html" target="_top"><code class="classname"> |
| org.apache.openjpa.util.ProxyManager</code></a> to use for proxying |
| mutable second class objects. See |
| <a href="#ref_guide_pc_scos_proxy_custom" title="6.4.3. Custom Proxies">Section 6.4.3, “ |
| Custom Proxies |
| ”</a> for details. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.QueryCache"></a>5.50. |
| openjpa.QueryCache |
| </h3></div></div></div><a class="indexterm" name="d0e15021"></a><a class="indexterm" name="d0e15024"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal">openjpa.QueryCache |
| </code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/conf/OpenJPAConfiguration.html#getQueryCache()" target="_top"> |
| <code class="methodname">org.apache.openjpa.conf.OpenJPAConfiguration.getQueryCache |
| </code></a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| QueryCache</code> |
| </p><p> |
| <span class="bold"><strong>Default: </strong></span><code class="literal">true</code>, when the data |
| cache (see <a href="#openjpa.DataCache" title="5.25. openjpa.DataCache">Section 5.25, “ |
| openjpa.DataCache |
| ”</a>) is also enabled, <code class="literal"> |
| false</code> otherwise. |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> A plugin string (see |
| <a href="#ref_guide_conf_plugins" title="4. Plugin Configuration">Section 4, “ |
| Plugin Configuration |
| ”</a>) describing the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/datacache/QueryCache.html" target="_top"> |
| <code class="classname">org.apache.openjpa.datacache.QueryCache</code></a> |
| implementation to use for caching of queries loaded from the data store. See |
| <a href="#ref_guide_cache_query" title="1.3. Query Cache">Section 1.3, “ |
| Query Cache |
| ”</a> for details. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.QueryCompilationCache"></a>5.51. |
| openjpa.QueryCompilationCache |
| </h3></div></div></div><a class="indexterm" name="d0e15082"></a><a class="indexterm" name="d0e15085"></a><p> |
| <span class="bold"><strong>Property name:</strong></span> |
| <code class="literal">openjpa.QueryCompilationCache</code> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property:</strong></span> |
| <code class="literal">QueryCompilationCache</code> |
| </p><p> |
| <span class="bold"><strong>Default:</strong></span> <code class="literal">true</code>. |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> A plugin string (see |
| <a href="#ref_guide_conf_plugins" title="4. Plugin Configuration">Section 4, “ |
| Plugin Configuration |
| ”</a>) describing the |
| <code class="classname">java.util.Map</code> to use for caching of data used during |
| query compilation. See <a href="#ref_guide_cache_querycomp" title="2. Query Compilation Cache">Section 2, “ |
| Query Compilation Cache |
| ”</a> for details. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.ReadLockLevel"></a>5.52. |
| openjpa.ReadLockLevel |
| </h3></div></div></div><a class="indexterm" name="d0e15129"></a><a class="indexterm" name="d0e15132"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal">openjpa.ReadLockLevel |
| </code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/conf/OpenJPAConfiguration.html#getReadLockLevel()" target="_top"> |
| <code class="methodname">org.apache.openjpa.conf.OpenJPAConfiguration.getReadLockLevel |
| </code></a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| ReadLockLevel</code> |
| </p><p> |
| <span class="bold"><strong>Default: </strong></span><code class="literal">read</code> |
| </p><p> |
| <span class="bold"><strong>Possible values: </strong></span><code class="literal">none</code>, |
| <code class="literal">read</code>, <code class="literal">write</code>, numeric values for |
| lock-manager specific lock levels |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> The default level at which to lock |
| objects retrieved during a non-optimistic transaction. Note that for the default |
| JDBC lock manager, <code class="literal"> read</code> and <code class="literal">write</code> lock |
| levels are equivalent. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.RemoteCommitProvider"></a>5.53. |
| openjpa.RemoteCommitProvider |
| </h3></div></div></div><a class="indexterm" name="d0e15195"></a><a class="indexterm" name="d0e15198"></a><a class="indexterm" name="d0e15203"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal"> |
| openjpa.RemoteCommitProvider</code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/conf/OpenJPAConfiguration.html#getRemoteCommitProvider()" target="_top"> |
| <code class="methodname"> |
| org.apache.openjpa.conf.OpenJPAConfiguration.getRemoteCommitProvider |
| </code></a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| RemoteCommitProvider</code> |
| </p><p> |
| <span class="bold"><strong>Default:</strong></span> - |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> A plugin string (see |
| <a href="#ref_guide_conf_plugins" title="4. Plugin Configuration">Section 4, “ |
| Plugin Configuration |
| ”</a>) describing the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/event/RemoteCommitProvider.html" target="_top"> |
| <code class="classname">org.apache.openjpa.event.RemoteCommitProvider</code></a> |
| implementation to use for distributed event notification. See |
| <a href="#ref_guide_event_conf" title="2.1. Remote Commit Provider Configuration">Section 2.1, “ |
| Remote Commit Provider Configuration |
| ”</a> for more information. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.RestoreState"></a>5.54. |
| openjpa.RestoreState |
| </h3></div></div></div><a class="indexterm" name="d0e15254"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal">openjpa.RestoreState |
| </code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/conf/OpenJPAConfiguration.html#getRestoreState()" target="_top"> |
| <code class="methodname">org.apache.openjpa.conf.OpenJPAConfiguration.getRestoreState |
| </code></a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| RestoreState</code> |
| </p><p> |
| <span class="bold"><strong>Default: </strong></span><code class="literal">none</code> |
| </p><p> |
| <span class="bold"><strong>Possible values: </strong></span><code class="literal">none</code>, |
| <code class="literal">immutable</code>, <code class="literal">all</code> |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> Whether to restore managed fields |
| to their pre-transaction values when a rollback occurs. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.RetainState"></a>5.55. |
| openjpa.RetainState |
| </h3></div></div></div><a class="indexterm" name="d0e15309"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal">openjpa.RetainState |
| </code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/conf/OpenJPAConfiguration.html#getRetainState()" target="_top"> |
| <code class="methodname">org.apache.openjpa.conf.OpenJPAConfiguration.getRetainState |
| </code></a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| RetainState</code> |
| </p><p> |
| <span class="bold"><strong>Default: </strong></span><code class="literal">true</code> |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> Whether persistent fields retain |
| their values on transaction commit. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.RetryClassRegistration"></a>5.56. |
| openjpa.RetryClassRegistration |
| </h3></div></div></div><a class="indexterm" name="d0e15351"></a><a class="indexterm" name="d0e15354"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal"> |
| openjpa.RetryClassRegistration</code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/conf/OpenJPAConfiguration.html#getRetryClassRegistration()" target="_top"> |
| <code class="methodname"> |
| org.apache.openjpa.conf.OpenJPAConfiguration.getRetryClassRegistration |
| </code></a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| RetryClassRegistration</code> |
| </p><p> |
| <span class="bold"><strong>Default: </strong></span><code class="literal">false</code> |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> Controls whether to log a warning |
| and defer registration instead of throwing an exception when a persistent class |
| cannot be fully processed. This property should <span class="emphasis"><em>only</em></span> be |
| used in complex classloader situations where security is preventing OpenJPA from |
| reading registered classes. Setting this to true unnecessarily may obscure more |
| serious problems. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.RuntimeUnenhancedClasses"></a>5.57. openjpa.RuntimeUnenhancedClasses</h3></div></div></div><p> |
| <span class="bold"><strong>Property name: </strong></span> |
| <code class="literal">openjpa.RuntimeUnenhancedClasses</code> |
| </p><p> |
| <span class="bold"><strong>Configuration API: </strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/conf/OpenJPAConfiguration.html#getRuntimeUnenhancedClasses()" target="_top">org.apache.openjpa.conf.OpenJPAConfiguration.getRuntimeUnenhancedClasses</a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config property:</strong></span> |
| RuntimeUnenhancedClasses |
| </p><p> |
| <span class="bold"><strong>Default: </strong></span> |
| <code class="literal">supported</code> |
| |
| </p><p> |
| <span class="bold"><strong>Possible values:</strong></span> |
| <code class="literal">supported</code>, |
| <code class="literal">unsupported</code>, |
| <code class="literal">warn</code> |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> |
| The RuntimeUnenhancedClasses property controls how OpenJPA |
| handles classes that have not been enhanced byt the PCEnhancer |
| tool or automatically by a javaagent. If RuntimeUnenhanced is |
| set to <code class="literal">supported</code> OpenJPA will automatically |
| create subclasses for unenhanced entity classes. If set to |
| <code class="literal">unsupported</code>OpenJPA will not create subclasses |
| for unenhanced entity classes and will throw an exception when |
| they are detected. If set to <code class="literal">warn</code> OpenJPA |
| will not create subclasses for unenhanced entity classes |
| but will log a warning message. |
| </p><p> |
| See the reference guide section on unenhanced types for more |
| information |
| <a href="#ref_guide_pc_enhance_unenhanced_types" title="2.4. Omitting the OpenJPA enhancer">Section 2.4, “ |
| Omitting the OpenJPA enhancer |
| ”</a> |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.SavepointManager"></a>5.58. |
| openjpa.SavepointManager |
| </h3></div></div></div><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal"> |
| openjpa.SavepointManager</code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/conf/OpenJPAConfiguration.html#getSavepointManager()" target="_top"> |
| org.apache.openjpa.conf.OpenJPAConfiguration.getSavepointManager</a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property:</strong></span> |
| SavepointManager |
| </p><p> |
| <span class="bold"><strong>Default: </strong></span><code class="literal">in-mem</code> |
| </p><p> |
| <span class="bold"><strong>Possible values: </strong></span><code class="literal">in-mem</code>, |
| <code class="literal">jdbc</code>, <code class="literal">oracle</code> |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> A plugin string (see |
| <a href="#ref_guide_conf_plugins" title="4. Plugin Configuration">Section 4, “ |
| Plugin Configuration |
| ”</a>) describing a |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/kernel/SavepointManager.html" target="_top"> |
| <code class="classname">org.apache.openjpa.kernel.SavepointManager</code></a> to |
| use for managing transaction savepoints. See |
| <a href="#ref_guide_savepoints" title="4. Savepoints">Section 4, “ |
| Savepoints |
| ”</a> for details. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.Sequence"></a>5.59. |
| openjpa.Sequence |
| </h3></div></div></div><a class="indexterm" name="d0e15522"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal">openjpa.Sequence |
| </code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/conf/OpenJPAConfiguration.html#getSequence()" target="_top"> |
| <code class="methodname">org.apache.openjpa.conf.OpenJPAConfiguration.getSequence |
| </code></a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| Sequence</code> |
| </p><p> |
| <span class="bold"><strong>Default: </strong></span><code class="literal">table</code> |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> A plugin string (see |
| <a href="#ref_guide_conf_plugins" title="4. Plugin Configuration">Section 4, “ |
| Plugin Configuration |
| ”</a>) describing the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/kernel/Seq.html" target="_top"><code class="classname"> |
| org.apache.openjpa.kernel.Seq</code></a> implementation to use for the |
| system sequence. See <a href="#ref_guide_sequence" title="6. Generators">Section 6, “ |
| Generators |
| ”</a> for more |
| information. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.TransactionMode"></a>5.60. |
| openjpa.TransactionMode |
| </h3></div></div></div><a class="indexterm" name="d0e15572"></a><a class="indexterm" name="d0e15575"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal">openjpa.TransactionMode |
| </code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/conf/OpenJPAConfiguration.html#getTransactionMode()" target="_top"> |
| <code class="methodname">org.apache.openjpa.conf.OpenJPAConfiguration.getTransactionMode |
| </code></a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| TransactionMode</code> |
| </p><p> |
| <span class="bold"><strong>Default: </strong></span><code class="literal">local</code> |
| </p><p> |
| <span class="bold"><strong>Possible values: </strong></span><code class="literal">local</code>, |
| <code class="literal">managed</code> |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> The default transaction mode to |
| use. You can override this setting per-session. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.WriteLockLevel"></a>5.61. |
| openjpa.WriteLockLevel |
| </h3></div></div></div><a class="indexterm" name="d0e15629"></a><a class="indexterm" name="d0e15632"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal">openjpa.WriteLockLevel |
| </code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/conf/OpenJPAConfiguration.html#getWriteLockLevel()" target="_top"> |
| <code class="methodname">org.apache.openjpa.conf.OpenJPAConfiguration.getWriteLockLevel |
| </code></a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| WriteLockLevel</code> |
| </p><p> |
| <span class="bold"><strong>Default: </strong></span><code class="literal">write</code> |
| </p><p> |
| <span class="bold"><strong>Possible values: </strong></span><code class="literal">none</code>, |
| <code class="literal">read</code>, <code class="literal">write</code>, numeric values for |
| lock-manager specific lock levels |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> The default level at which to lock |
| objects changed during a non-optimistic transaction. Note that for the default |
| JDBC lock manager, <code class="literal"> read</code> and <code class="literal">write</code> lock |
| levels are equivalent. |
| </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_conf_jdbc"></a>6. |
| OpenJPA JDBC Properties |
| </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#openjpa.jdbc.ConnectionDecorators">6.1. |
| openjpa.jdbc.ConnectionDecorators |
| </a></span></dt><dt><span class="section"><a href="#openjpa.jdbc.DBDictionary">6.2. |
| openjpa.jdbc.DBDictionary |
| </a></span></dt><dt><span class="section"><a href="#openjpa.jdbc.DriverDataSource">6.3. |
| openjpa.jdbc.DriverDataSource |
| </a></span></dt><dt><span class="section"><a href="#openjpa.jdbc.EagerFetchMode">6.4. |
| openjpa.jdbc.EagerFetchMode |
| </a></span></dt><dt><span class="section"><a href="#openjpa.jdbc.FetchDirection">6.5. |
| openjpa.jdbc.FetchDirection |
| </a></span></dt><dt><span class="section"><a href="#openjpa.jdbc.JDBCListeners">6.6. |
| openjpa.jdbc.JDBCListeners |
| </a></span></dt><dt><span class="section"><a href="#openjpa.jdbc.LRSSize">6.7. |
| openjpa.jdbc.LRSSize |
| </a></span></dt><dt><span class="section"><a href="#openjpa.jdbc.MappingDefaults">6.8. |
| openjpa.jdbc.MappingDefaults |
| </a></span></dt><dt><span class="section"><a href="#openjpa.jdbc.MappingFactory">6.9. |
| openjpa.jdbc.MappingFactory |
| </a></span></dt><dt><span class="section"><a href="#openjpa.jdbc.QuerySQLCache">6.10. |
| openjpa.jdbc.QuerySQLCache |
| </a></span></dt><dt><span class="section"><a href="#openjpa.jdbc.ResultSetType">6.11. |
| openjpa.jdbc.ResultSetType |
| </a></span></dt><dt><span class="section"><a href="#openjpa.jdbc.Schema">6.12. |
| openjpa.jdbc.Schema |
| </a></span></dt><dt><span class="section"><a href="#openjpa.jdbc.SchemaFactory">6.13. |
| openjpa.jdbc.SchemaFactory |
| </a></span></dt><dt><span class="section"><a href="#openjpa.jdbc.Schemas">6.14. |
| openjpa.jdbc.Schemas |
| </a></span></dt><dt><span class="section"><a href="#openjpa.jdbc.SQLFactory">6.15. |
| openjpa.jdbc.SQLFactory |
| </a></span></dt><dt><span class="section"><a href="#openjpa.jdbc.SubclassFetchMode">6.16. |
| openjpa.jdbc.SubclassFetchMode |
| </a></span></dt><dt><span class="section"><a href="#openjpa.jdbc.SynchronizeMappings">6.17. |
| openjpa.jdbc.SynchronizeMappings |
| </a></span></dt><dt><span class="section"><a href="#openjpa.jdbc.TransactionIsolation">6.18. |
| openjpa.jdbc.TransactionIsolation |
| </a></span></dt><dt><span class="section"><a href="#openjpa.jdbc.UpdateManager">6.19. |
| openjpa.jdbc.UpdateManager |
| </a></span></dt></dl></div><a class="indexterm" name="d0e15695"></a><p> |
| The following properties apply exclusively to the OpenJPA JDBC back-end. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.jdbc.ConnectionDecorators"></a>6.1. |
| openjpa.jdbc.ConnectionDecorators |
| </h3></div></div></div><a class="indexterm" name="d0e15705"></a><a class="indexterm" name="d0e15708"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal"> |
| openjpa.jdbc.ConnectionDecorators</code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/conf/JDBCConfiguration.html#getConnectionDecorators()" target="_top"> |
| <code class="methodname"> |
| org.apache.openjpa.jdbc.conf.JDBCConfiguration.getConnectionDecorators |
| </code></a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| ConnectionDecorators</code> |
| </p><p> |
| <span class="bold"><strong>Default:</strong></span> - |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> A comma-separated list of plugin |
| strings (see <a href="#ref_guide_conf_plugins" title="4. Plugin Configuration">Section 4, “ |
| Plugin Configuration |
| ”</a>) describing |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/lib/jdbc/ConnectionDecorator.html" target="_top"> |
| <code class="classname">org.apache.openjpa.lib.jdbc.ConnectionDecorator</code></a> |
| instances to install on the connection factory. These decorators can wrap |
| connections passed from the underlying <code class="classname">DataSource</code> to add |
| functionality. OpenJPA will pass all connections through the list of decorators |
| before using them. Note that by default OpenJPA employs all |
| of the built-in decorators in the <code class="classname">org.apache.openjpa.lib.jdbc |
| </code> package already; you do not need to list them here. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.jdbc.DBDictionary"></a>6.2. |
| openjpa.jdbc.DBDictionary |
| </h3></div></div></div><a class="indexterm" name="d0e15763"></a><a class="indexterm" name="d0e15766"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal"> |
| openjpa.jdbc.DBDictionary</code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/conf/JDBCConfiguration.html#getDBDictionary()" target="_top"> |
| <code class="methodname">org.apache.openjpa.jdbc.conf.JDBCConfiguration.getDBDictionary |
| </code></a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| DBDictionary</code> |
| </p><p> |
| <span class="bold"><strong>Default:</strong></span> Based on the |
| <a href="#openjpa.ConnectionURL" title="5.20. openjpa.ConnectionURL"><code class="literal">openjpa.ConnectionURL</code> |
| </a><a href="#openjpa.ConnectionDriverName" title="5.7. openjpa.ConnectionDriverName"><code class="literal"> |
| openjpa.ConnectionDriverName</code></a> |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> A plugin string (see |
| <a href="#ref_guide_conf_plugins" title="4. Plugin Configuration">Section 4, “ |
| Plugin Configuration |
| ”</a>) describing the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/sql/DBDictionary.html" target="_top"> |
| <code class="classname">org.apache.openjpa.jdbc.sql.DBDictionary</code></a> to use |
| for database interaction. OpenJPA typically auto-configures the dictionary based |
| on the JDBC URL, but you may have to set this property explicitly if you are |
| using an unrecognized driver, or to plug in your own dictionary for a database |
| OpenJPA does not support out-of-the-box. See |
| <a href="#ref_guide_dbsetup_dbsupport" title="4. Database Support">Section 4, “ |
| Database Support |
| ”</a> for details. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.jdbc.DriverDataSource"></a>6.3. |
| openjpa.jdbc.DriverDataSource |
| </h3></div></div></div><a class="indexterm" name="d0e15825"></a><a class="indexterm" name="d0e15828"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal"> |
| openjpa.jdbc.DriverDataSource</code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/conf/JDBCConfiguration.html#getDriverDataSource()" target="_top"> |
| <code class="methodname">org.apache.openjpa.jdbc.conf.JDBCConfiguration.getDriverDataSource |
| </code></a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| DriverDataSource</code> |
| </p><p> |
| <span class="bold"><strong>Default: </strong></span><code class="literal">pooling</code> |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> The alias or full class name of |
| the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/schema/DriverDataSource.html" target="_top"> |
| <code class="classname">org.apache.openjpa.jdbc.schema.DriverDataSource</code></a> |
| implementation to use to wrap JDBC Driver classes with javax.sql.DataSource |
| instances. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.jdbc.EagerFetchMode"></a>6.4. |
| openjpa.jdbc.EagerFetchMode |
| </h3></div></div></div><a class="indexterm" name="d0e15877"></a><a class="indexterm" name="d0e15880"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal"> |
| openjpa.jdbc.EagerFetchMode</code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/conf/JDBCConfiguration.html#getEagerFetchMode()" target="_top"> |
| <code class="methodname">org.apache.openjpa.jdbc.conf.JDBCConfiguration.getEagerFetchMode |
| </code></a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| EagerFetchMode</code> |
| </p><p> |
| <span class="bold"><strong>Default: </strong></span><code class="literal">parallel</code> |
| </p><p> |
| <span class="bold"><strong>Possible values: </strong></span><code class="literal">parallel</code>, |
| <code class="literal">join</code>, <code class="literal">none</code> |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> Optimizes how OpenJPA loads |
| persistent relations. This setting can also be varied at runtime. See |
| <a href="#ref_guide_perfpack_eager" title="8. Eager Fetching">Section 8, “ |
| Eager Fetching |
| ”</a> for details. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.jdbc.FetchDirection"></a>6.5. |
| openjpa.jdbc.FetchDirection |
| </h3></div></div></div><a class="indexterm" name="d0e15939"></a><a class="indexterm" name="d0e15942"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal"> |
| openjpa.jdbc.FetchDirection</code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/conf/JDBCConfiguration.html#getFetchDirection()" target="_top"> |
| <code class="methodname">org.apache.openjpa.jdbc.conf.JDBCConfiguration.getFetchDirection |
| </code></a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| FetchDirection</code> |
| </p><p> |
| <span class="bold"><strong>Default: </strong></span><code class="literal">forward</code> |
| </p><p> |
| <span class="bold"><strong>Possible values: </strong></span><code class="literal">forward</code>, |
| <code class="literal">reverse</code>, <code class="literal">unknown</code> |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> The expected order in which query |
| result lists will be accessed. This property can also be varied at runtime. See |
| <a href="#ref_guide_dbsetup_lrs" title="10. Large Result Sets">Section 10, “ |
| Large Result Sets |
| ”</a> for details. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.jdbc.JDBCListeners"></a>6.6. |
| openjpa.jdbc.JDBCListeners |
| </h3></div></div></div><a class="indexterm" name="d0e16001"></a><a class="indexterm" name="d0e16004"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal"> |
| openjpa.jdbc.JDBCListeners</code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/conf/JDBCConfiguration.html#getJDBCListeners()" target="_top"> |
| <code class="methodname">org.apache.openjpa.jdbc.conf.JDBCConfiguration.getJDBCListeners |
| </code></a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| JDBCListeners</code> |
| </p><p> |
| <span class="bold"><strong>Default:</strong></span> - |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> A comma-separated list of plugin |
| strings (see <a href="#ref_guide_conf_plugins" title="4. Plugin Configuration">Section 4, “ |
| Plugin Configuration |
| ”</a>) describing |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/lib/jdbc/JDBCListener.html" target="_top"> |
| <code class="classname">org.apache.openjpa.lib.jdbc.JDBCListener</code></a> event |
| listeners to install. These listeners will be notified on various JDBC-related |
| events. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.jdbc.LRSSize"></a>6.7. |
| openjpa.jdbc.LRSSize |
| </h3></div></div></div><a class="indexterm" name="d0e16053"></a><a class="indexterm" name="d0e16056"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal">openjpa.jdbc.LRSSize |
| </code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/conf/JDBCConfiguration.html#getLRSSize()" target="_top"> |
| <code class="methodname">org.apache.openjpa.jdbc.conf.JDBCConfiguration.getLRSSize |
| </code></a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| LRSSize</code> |
| </p><p> |
| <span class="bold"><strong>Default: </strong></span><code class="literal">query</code> |
| </p><p> |
| <span class="bold"><strong>Possible values: </strong></span><code class="literal">query</code>, |
| <code class="literal">last</code>, <code class="literal">unknown</code> |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> The strategy to use to calculate |
| the size of a result list. This property can also be varied at runtime. See |
| <a href="#ref_guide_dbsetup_lrs" title="10. Large Result Sets">Section 10, “ |
| Large Result Sets |
| ”</a> for details. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.jdbc.MappingDefaults"></a>6.8. |
| openjpa.jdbc.MappingDefaults |
| </h3></div></div></div><a class="indexterm" name="d0e16115"></a><a class="indexterm" name="d0e16118"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal"> |
| openjpa.jdbc.MappingDefaults</code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/conf/JDBCConfiguration.html#getMappingDefaults()" target="_top"> |
| <code class="methodname">org.apache.openjpa.jdbc.conf.JDBCConfiguration.getMappingDefaults |
| </code></a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| MappingDefaults</code> |
| </p><p> |
| <span class="bold"><strong>Default:</strong></span> jpa |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> A plugin string (see |
| <a href="#ref_guide_conf_plugins" title="4. Plugin Configuration">Section 4, “ |
| Plugin Configuration |
| ”</a>) describing the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/meta/MappingDefaults.html" target="_top"> |
| <code class="classname">org.apache.openjpa.jdbc.meta.MappingDefaults</code></a> to |
| use to define default column names, table names, and constraints for your |
| persistent classes. See <a href="#ref_guide_mapping_factory" title="5. Mapping Factory">Section 5, “ |
| Mapping Factory |
| ”</a> for |
| details. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.jdbc.MappingFactory"></a>6.9. |
| openjpa.jdbc.MappingFactory |
| </h3></div></div></div><a class="indexterm" name="d0e16169"></a><a class="indexterm" name="d0e16172"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal"> |
| openjpa.jdbc.MappingFactory</code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/conf/JDBCConfiguration.html#getMappingFactory()" target="_top"> |
| <code class="methodname">org.apache.openjpa.jdbc.conf.JDBCConfiguration.getMappingFactory |
| </code></a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| MappingFactory</code> |
| </p><p> |
| <span class="bold"><strong>Default:</strong></span> - |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> A plugin string (see |
| <a href="#ref_guide_conf_plugins" title="4. Plugin Configuration">Section 4, “ |
| Plugin Configuration |
| ”</a>) describing the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/meta/MetaDataFactory.html" target="_top"> |
| <code class="classname">org.apache.openjpa.meta.MetaDataFactory</code></a> to use to |
| store and retrieve object-relational mapping information for your persistent |
| classes. See <a href="#ref_guide_mapping_factory" title="5. Mapping Factory">Section 5, “ |
| Mapping Factory |
| ”</a> for details. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.jdbc.QuerySQLCache"></a>6.10. |
| openjpa.jdbc.QuerySQLCache |
| </h3></div></div></div><a class="indexterm" name="d0e16223"></a><a class="indexterm" name="d0e16226"></a><p> |
| <span class="bold"><strong>Property name:</strong></span> |
| <code class="literal">openjpa.jdbc.QuerySQLCache</code> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property:</strong></span> |
| <code class="literal">QuerySQLCache</code> |
| </p><p> |
| <span class="bold"><strong>Default:</strong></span> <code class="literal">true</code>. |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> A plugin string (see |
| <a href="#ref_guide_conf_plugins" title="4. Plugin Configuration">Section 4, “ |
| Plugin Configuration |
| ”</a>) describing the |
| <code class="classname">java.util.Map</code> to use for caching of the SQL string |
| used by the find operation. See <a href="#ref_guide_cache_querysql" title="3. Query SQL Cache">Section 3, “ |
| Query SQL Cache |
| ”</a> for |
| details. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.jdbc.ResultSetType"></a>6.11. |
| openjpa.jdbc.ResultSetType |
| </h3></div></div></div><a class="indexterm" name="d0e16270"></a><a class="indexterm" name="d0e16273"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal"> |
| openjpa.jdbc.ResultSetType</code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/conf/JDBCConfiguration.html#getResultSetType()" target="_top"> |
| <code class="methodname">org.apache.openjpa.jdbc.conf.JDBCConfiguration.getResultSetType |
| </code></a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| ResultSetType</code> |
| </p><p> |
| <span class="bold"><strong>Default: </strong></span><code class="literal">forward-only</code> |
| </p><p> |
| <span class="bold"><strong>Possible values: </strong></span><code class="literal">forward-only</code> |
| , <code class="literal">scroll-sensitive</code>, <code class="literal">scroll-insensitive</code> |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> The JDBC result set type to use |
| when fetching result lists. This property can also be varied at runtime. See |
| <a href="#ref_guide_dbsetup_lrs" title="10. Large Result Sets">Section 10, “ |
| Large Result Sets |
| ”</a> for details. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.jdbc.Schema"></a>6.12. |
| openjpa.jdbc.Schema |
| </h3></div></div></div><a class="indexterm" name="d0e16332"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal">openjpa.jdbc.Schema |
| </code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/conf/JDBCConfiguration.html#getSchema()" target="_top"> |
| <code class="methodname">org.apache.openjpa.jdbc.conf.JDBCConfiguration.getSchema |
| </code></a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| Schema</code> |
| </p><p> |
| <span class="bold"><strong>Default:</strong></span> - |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> The default schema name to prepend |
| to unqualified table names. Also, the schema in which OpenJPA will create new |
| tables. See <a href="#ref_guide_schema_def" title="11. Default Schema">Section 11, “ |
| Default Schema |
| ”</a> for details. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.jdbc.SchemaFactory"></a>6.13. |
| openjpa.jdbc.SchemaFactory |
| </h3></div></div></div><a class="indexterm" name="d0e16376"></a><a class="indexterm" name="d0e16379"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal"> |
| openjpa.jdbc.SchemaFactory</code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/conf/JDBCConfiguration.html#getSchemaFactory()" target="_top"> |
| <code class="methodname">org.apache.openjpa.jdbc.conf.JDBCConfiguration.getSchemaFactory |
| </code></a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| SchemaFactory</code> |
| </p><p> |
| <span class="bold"><strong>Default: </strong></span><code class="literal">dynamic</code> |
| </p><p> |
| <span class="bold"><strong>Possible values: </strong></span><code class="literal">dynamic</code>, |
| <code class="literal">native</code>, <code class="literal">file</code>, <code class="literal">table</code>, |
| others |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> A plugin string (see |
| <a href="#ref_guide_conf_plugins" title="4. Plugin Configuration">Section 4, “ |
| Plugin Configuration |
| ”</a>) describing the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/schema/SchemaFactory.html" target="_top"> |
| <code class="classname">org.apache.openjpa.jdbc.schema.SchemaFactory</code></a> to |
| use to store and retrieve information about the database schema. See |
| <a href="#ref_guide_schema_info_factory" title="12.2. Schema Factory">Section 12.2, “ |
| Schema Factory |
| ”</a> for details. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.jdbc.Schemas"></a>6.14. |
| openjpa.jdbc.Schemas |
| </h3></div></div></div><a class="indexterm" name="d0e16448"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal">openjpa.jdbc.Schemas |
| </code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/conf/JDBCConfiguration.html#getSchemas()" target="_top"> |
| <code class="methodname">org.apache.openjpa.jdbc.conf.JDBCConfiguration.getSchemas |
| </code></a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| Schemas</code> |
| </p><p> |
| <span class="bold"><strong>Default:</strong></span> - |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> A comma-separated list of the |
| schemas and/or tables used for your persistent data. See |
| <a href="#ref_guide_schema_info_list" title="12.1. Schemas List">Section 12.1, “ |
| Schemas List |
| ”</a> for details. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.jdbc.SQLFactory"></a>6.15. |
| openjpa.jdbc.SQLFactory |
| </h3></div></div></div><a class="indexterm" name="d0e16492"></a><a class="indexterm" name="d0e16495"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal">openjpa.jdbc.SQLFactory |
| </code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/conf/JDBCConfiguration.html#getSQLFactory()" target="_top"> |
| <code class="methodname">org.apache.openjpa.jdbc.conf.JDBCConfiguration.getSQLFactory |
| </code></a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| SQLFactory</code> |
| </p><p> |
| <span class="bold"><strong>Default: </strong></span><code class="literal">default</code> |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> A plugin string (see |
| <a href="#ref_guide_conf_plugins" title="4. Plugin Configuration">Section 4, “ |
| Plugin Configuration |
| ”</a>) describing the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/sql/SQLFactory.html" target="_top"><code class="classname"> |
| org.apache.openjpa.jdbc.sql.SQLFactory</code></a> to use to abstract |
| common SQL constructs. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.jdbc.SubclassFetchMode"></a>6.16. |
| openjpa.jdbc.SubclassFetchMode |
| </h3></div></div></div><a class="indexterm" name="d0e16545"></a><a class="indexterm" name="d0e16548"></a><a class="indexterm" name="d0e16553"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal"> |
| openjpa.jdbc.SubclassFetchMode</code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/conf/JDBCConfiguration.html#getSubclassFetchMode()" target="_top"> |
| <code class="methodname">org.apache.openjpa.jdbc.conf.JDBCConfiguration.getSubclassFetchMode |
| </code></a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| SubclassFetchMode</code> |
| </p><p> |
| <span class="bold"><strong>Default: </strong></span><code class="literal">parallel</code> |
| </p><p> |
| <span class="bold"><strong>Possible values: </strong></span><code class="literal">parallel</code>, |
| <code class="literal">join</code>, <code class="literal">none</code> |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> How to select subclass data when |
| it is in other tables. This setting can also be varied at runtime. See |
| <a href="#ref_guide_perfpack_eager" title="8. Eager Fetching">Section 8, “ |
| Eager Fetching |
| ”</a>. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.jdbc.SynchronizeMappings"></a>6.17. |
| openjpa.jdbc.SynchronizeMappings |
| </h3></div></div></div><a class="indexterm" name="d0e16612"></a><a class="indexterm" name="d0e16615"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal"> |
| openjpa.jdbc.SynchronizeMappings</code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/conf/JDBCConfiguration.html#getSynchronizeMappings()" target="_top"> |
| <code class="methodname"> |
| org.apache.openjpa.jdbc.conf.JDBCConfiguration.getSynchronizeMappings |
| </code></a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| SynchronizeMappings</code> |
| </p><p> |
| <span class="bold"><strong>Default:</strong></span> - |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> Controls whether OpenJPA will |
| attempt to run the mapping tool on all persistent classes to synchronize their |
| mappings and schema at runtime. Useful for rapid test/debug cycles. See |
| <a href="#ref_guide_mapping_synch" title="1.3. Runtime Forward Mapping">Section 1.3, “ |
| Runtime Forward Mapping |
| ”</a> for more information. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.jdbc.TransactionIsolation"></a>6.18. |
| openjpa.jdbc.TransactionIsolation |
| </h3></div></div></div><a class="indexterm" name="d0e16659"></a><a class="indexterm" name="d0e16662"></a><a class="indexterm" name="d0e16667"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal"> |
| openjpa.jdbc.TransactionIsolation</code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/conf/JDBCConfiguration.html#getTransactionIsolation()" target="_top"> |
| <code class="methodname"> |
| org.apache.openjpa.jdbc.conf.JDBCConfiguration.getTransactionIsolation |
| </code></a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| TransactionIsolation</code> |
| </p><p> |
| <span class="bold"><strong>Default: </strong></span><code class="literal">default</code> |
| </p><p> |
| <span class="bold"><strong>Possible values: </strong></span><code class="literal">default</code>, |
| <code class="literal">none</code>, <code class="literal">read-committed</code>, <code class="literal"> |
| read-uncommitted</code>, <code class="literal">repeatable-read</code>, <code class="literal"> |
| serializable</code> |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> The JDBC transaction isolation |
| level to use. See <a href="#ref_guide_dbsetup_isolation" title="5. Setting the Transaction Isolation">Section 5, “ |
| Setting the Transaction Isolation |
| ”</a> for |
| details. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="openjpa.jdbc.UpdateManager"></a>6.19. |
| openjpa.jdbc.UpdateManager |
| </h3></div></div></div><a class="indexterm" name="d0e16735"></a><a class="indexterm" name="d0e16738"></a><p> |
| <span class="bold"><strong>Property name: </strong></span><code class="literal"> |
| openjpa.jdbc.UpdateManager</code> |
| </p><p> |
| <span class="bold"><strong>Configuration API:</strong></span> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/conf/JDBCConfiguration.html#getUpdateManager()" target="_top"> |
| <code class="methodname">org.apache.openjpa.jdbc.conf.JDBCConfiguration.getUpdateManager |
| </code></a> |
| </p><p> |
| <span class="bold"><strong>Resource adaptor config-property: </strong></span><code class="literal"> |
| UpdateManager</code> |
| </p><p> |
| <span class="bold"><strong>Default: </strong></span><code class="literal">batching-constraint</code> |
| </p><p> |
| <span class="bold"><strong>Possible values: </strong></span><code class="literal">default</code>, |
| <code class="literal">operation-order</code>, <code class="literal">constraint</code>, <code class="literal"> |
| batching-constraint</code>, <code class="literal">batching-operation-order</code> |
| </p><p> |
| <span class="bold"><strong>Description:</strong></span> The full class name of the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/kernel/UpdateManager.html" target="_top"> |
| <code class="classname">org.apache.openjpa.jdbc.kernel.UpdateManager</code></a> to |
| use to flush persistent object changes to the datastore. The provided default |
| implementation is |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/kernel/BatchingConstraintUpdateManager" target="_top"> |
| <code class="classname">org.apache.openjpa.jdbc.kernel.BatchingConstraintUpdateManager</code> |
| </a>. |
| |
| </p></div></div></div><div class="chapter" lang="en" id="ref_guide_logging"><div class="titlepage"><div><div><h2 class="title"><a name="ref_guide_logging"></a>Chapter 3. |
| Logging |
| </h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#ref_guide_logging_channels">1. |
| Logging Channels |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_logging_openjpa">2. |
| OpenJPA Logging |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_logging_noop">3. |
| Disabling Logging |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_logging_log4j">4. |
| Log4J |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_logging_commons">5. |
| Apache Commons Logging |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_logging_jdk14">5.1. |
| JDK 1.4 java.util.logging |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_logging_custom">6. |
| Custom Log |
| </a></span></dt></dl></div><a class="indexterm" name="d0e16813"></a><a class="indexterm" name="d0e16816"></a><p> |
| Logging is an important means of gaining insight into your application's runtime |
| behavior. OpenJPA provides a flexible logging system that integrates with many |
| existing runtime systems, such as application servers and servlet runners. |
| </p><p> |
| There are four built-in logging plugins: a |
| <a href="#ref_guide_logging_openjpa" title="2. OpenJPA Logging">default logging framework</a> that |
| covers most needs, a <a href="#ref_guide_logging_log4j" title="4. Log4J"> Log4J</a> |
| delegate, an <a href="#ref_guide_logging_commons" title="5. Apache Commons Logging"> Apache Commons Logging |
| </a> delegate, and a <a href="#ref_guide_logging_noop" title="3. Disabling Logging">no-op</a> |
| implementation for disabling logging. |
| </p><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3><p> |
| Logging can have a negative impact on performance. Disable verbose logging (such |
| as logging of SQL statements) before running any performance tests. It is |
| advisable to limit or disable logging for a production system. You can disable |
| logging altogether by setting the <code class="literal">openjpa.Log</code> property to |
| <code class="literal">none</code>. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_logging_channels"></a>1. |
| Logging Channels |
| </h2></div></div></div><a class="indexterm" name="d0e16847"></a><p> |
| Logging is done over a number of <span class="emphasis"><em>logging channels</em></span>, each of |
| which has a <span class="emphasis"><em>logging level</em></span> which controls the verbosity of |
| log messages recorded for the channel. OpenJPA uses the following logging |
| channels: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">openjpa.Tool</code>: Messages issued by the OpenJPA command line |
| and Ant tools. Most messages are basic statements detailing which classes or |
| files the tools are running on. Detailed output is only available via the |
| logging category the tool belongs to, such as <code class="literal">openjpa.Enhance</code> |
| for the enhancer (see <a href="#ref_guide_pc_enhance" title="2. Enhancement">Section 2, “ |
| Enhancement |
| ”</a>) or <code class="literal"> |
| openjpa.MetaData</code> for the mapping tool (see |
| <a href="#ref_guide_mapping_mappingtool" title="1. Forward Mapping">Section 1, “ |
| Forward Mapping |
| ”</a>). This logging category |
| is provided so that you can get a general idea of what a tool is doing without |
| having to manipulate logging settings that might also affect runtime behavior. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e16880"></a> |
| <code class="literal">openjpa.Enhance</code>: Messages pertaining to enhancement and |
| runtime class generation. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e16892"></a> |
| <code class="literal">openjpa.MetaData</code>: Details about the generation of metadata |
| and object-relational mappings. |
| </p></li><li><p> |
| <code class="literal">openjpa.Runtime</code>: General OpenJPA runtime messages. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e16910"></a> |
| <code class="literal">openjpa.Query</code>: Messages about queries. Query strings and any |
| parameter values, if applicable, will be logged to the <code class="literal">TRACE</code> |
| level at execution time. Information about possible performance concerns will be |
| logged to the <code class="literal">INFO</code> level. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e16928"></a> |
| <code class="literal">openjpa.DataCache</code>: Messages from the L2 data cache plugins. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e16940"></a> |
| <code class="literal">openjpa.jdbc.JDBC</code>: JDBC connection information. General JDBC |
| information will be logged to the <code class="literal">TRACE</code> level. Information |
| about possible performance concerns will be logged to the <code class="literal">INFO |
| </code> level. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e16958"></a> |
| <code class="literal">openjpa.jdbc.SQL</code>: This is the most common logging channel to |
| use. Detailed information about the execution of SQL statements will be sent to |
| the <code class="literal">TRACE</code> level. It is useful to enable this channel if you |
| are curious about the exact SQL that OpenJPA issues to the datastore. |
| </p><p> |
| When using the built-in OpenJPA logging facilities, you can enable SQL logging |
| by adding <code class="literal">SQL=TRACE</code> to your <code class="literal">openjpa.Log</code> |
| property. |
| </p><p> |
| OpenJPA can optionally reformat the logged SQL to make it easier to read. To |
| enable pretty-printing, add <code class="literal">PrettyPrint=true</code> to the |
| <a href="#openjpa.ConnectionFactoryProperties" title="5.14. openjpa.ConnectionFactoryProperties"><code class="literal"> |
| openjpa.ConnectionFactoryProperties</code></a> property. You can control |
| how many columns wide the pretty-printed SQL will be with the <code class="literal"> |
| PrettyPrintLineLength</code> property. The default line length is 60 columns. |
| </p><p> |
| While pretty printing makes things easier to read, it can make output harder to |
| process with tools like grep. |
| </p><p> |
| Pretty-printing properties configuration might look like so: |
| </p><pre class="programlisting"> |
| <property name="openjpa.Log" value="SQL=TRACE"/> |
| <property name="openjpa.ConnectionFactoryProperties" |
| value="PrettyPrint=true, PrettyPrintLineLength=72"/> |
| </pre></li><li><p> |
| <a class="indexterm" name="d0e16999"></a> |
| <code class="literal">openjpa.jdbc.Schema</code>: Details about operations on the |
| database schema. |
| </p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_logging_openjpa"></a>2. |
| OpenJPA Logging |
| </h2></div></div></div><a class="indexterm" name="d0e17011"></a><p> |
| By default, OpenJPA uses a basic logging framework with the following output |
| format: |
| </p><p> |
| <code class="literal">millis</code> <code class="literal">diagnostic context</code> <code class="literal">level</code> [<code class="literal">thread name</code>] <code class="literal">channel</code> - <code class="literal">message</code> |
| </p><p> |
| For example, when loading an application that uses OpenJPA, a message like the |
| following will be sent to the <code class="literal">openjpa.Runtime</code> channel: |
| </p><pre class="programlisting"> |
| 2107 INFO [main] openjpa.Runtime - Starting OpenJPA 0.9.7 |
| </pre><p> |
| The default logging system accepts the following parameters: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">File</code>: The name of the file to log to, or <code class="literal">stdout |
| </code> or <code class="literal">stderr</code> to send messages to standard out and |
| standard error, respectively. By default, OpenJPA sends log messages to standard |
| error. |
| </p></li><li><p> |
| <code class="literal">DefaultLevel</code>: The default logging level of unconfigured |
| channels. Recognized values are <code class="literal"> TRACE, DEBUG, INFO, WARN,</code> |
| and <code class="literal">ERROR</code>. Defaults to <code class="literal">INFO</code>. |
| </p></li><li><p> |
| <code class="literal">DiagnosticContext</code>: A string that will be prepended to all |
| log messages. If this is not supplied and an <code class="literal">openjpa.Id</code> |
| property value is available, that value will be used. |
| </p></li><li><p> |
| <code class="literal"><channel></code>: Using the last token of the |
| <a href="#ref_guide_logging_channels" title="1. Logging Channels">logging channel</a> name, you can |
| configure the log level to use for that channel. See the examples below. |
| </p></li></ul></div><div class="example"><a name="ref_guide_logging_openjpa_std_ex"></a><p class="title"><b>Example 3.1. |
| Standard OpenJPA Log Configuration |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| <property name="openjpa.Log" value="DefaultLevel=WARN, Runtime=INFO, Tool=INFO"/> |
| </pre></div></div><br class="example-break"><div class="example"><a name="ref_guide_logging_openjpa_sql_ex"></a><p class="title"><b>Example 3.2. |
| Standard OpenJPA Log Configuration + All SQL Statements |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| <property name="openjpa.Log" value="DefaultLevel=WARN, Runtime=INFO, Tool=INFO, SQL=TRACE"/> |
| </pre></div></div><br class="example-break"><div class="example"><a name="ref_guide_logging_openjpa_file"></a><p class="title"><b>Example 3.3. |
| Logging to a File |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| <property name="openjpa.Log" value="File=/tmp/org.apache.openjpa.log, DefaultLevel=WARN, Runtime=INFO, Tool=INFO"/> |
| </pre></div></div><br class="example-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_logging_noop"></a>3. |
| Disabling Logging |
| </h2></div></div></div><a class="indexterm" name="d0e17111"></a><p> |
| Disabling logging can be useful to analyze performance without any I/O overhead |
| or to reduce verbosity at the console. To do this, set the <code class="literal">openjpa.Log |
| </code> property to <code class="literal">none</code>. |
| </p><p> |
| Disabling logging permanently, however, will cause all warnings to be consumed. |
| We recommend using one of the more sophisticated mechanisms described in this |
| chapter. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_logging_log4j"></a>4. |
| Log4J |
| </h2></div></div></div><a class="indexterm" name="d0e17129"></a><p> |
| When <code class="literal">openjpa.Log</code> is set to <code class="literal">log4j</code>, OpenJPA |
| will delegate to Log4J for logging. In a standalone application, Log4J logging |
| levels are controlled by a resource named <code class="filename">log4j.properties</code> |
| , which should be available as a top-level resource (either at the top level of |
| a jar file, or in the root of one of the <code class="literal">CLASSPATH</code> |
| directories). When deploying to a web or EJB application server, Log4J |
| configuration is often performed in a <code class="filename">log4j.xml</code> file |
| instead of a properties file. For further details on configuring Log4J, please |
| see the <a xmlns:xlink="http://www.w3.org/1999/xlink" href="http://jakarta.apache.org/log4j/docs/manual.html" target="_top">Log4J |
| Manual</a>. We present an example <code class="filename">log4j.properties</code> file |
| below. |
| </p><div class="example"><a name="ref_guide_logging_log4j_ex"></a><p class="title"><b>Example 3.4. |
| Standard Log4J Logging |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| log4j.rootCategory=WARN, console |
| log4j.category.openjpa.Tool=INFO |
| log4j.category.openjpa.Runtime=INFO |
| log4j.category.openjpa.Remote=WARN |
| log4j.category.openjpa.DataCache=WARN |
| log4j.category.openjpa.MetaData=WARN |
| log4j.category.openjpa.Enhance=WARN |
| log4j.category.openjpa.Query=WARN |
| log4j.category.openjpa.jdbc.SQL=WARN |
| log4j.category.openjpa.jdbc.JDBC=WARN |
| log4j.category.openjpa.jdbc.Schema=WARN |
| |
| log4j.appender.console=org.apache.log4j.ConsoleAppender |
| </pre></div></div><br class="example-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_logging_commons"></a>5. |
| Apache Commons Logging |
| </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#ref_guide_logging_jdk14">5.1. |
| JDK 1.4 java.util.logging |
| </a></span></dt></dl></div><a class="indexterm" name="d0e17165"></a><p> |
| Set the <code class="literal">openjpa.Log</code> property to <code class="literal">commons</code> to |
| use the <a xmlns:xlink="http://www.w3.org/1999/xlink" href="http://jakarta.apache.org/commons/logging.html" target="_top"> Apache |
| Jakarta Commons Logging</a> thin library for issuing log messages. The |
| Commons Logging libraries act as a wrapper around a number of popular logging |
| APIs, including the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="http://jakarta.apache.org/log4j/docs/index.html" target="_top"> Jakarta Log4J |
| </a> project, and the native |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="http://java.sun.com/j2se/1.4/docs/api/java/util/logging/package-summary.html" target="_top"> |
| java.util.logging</a> package in JDK 1.4. If neither of these libraries are |
| available, then logging will fall back to using simple console logging. |
| </p><p> |
| When using the Commons Logging framework in conjunction with Log4J, |
| configuration will be the same as was discussed in the Log4J section above. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_logging_jdk14"></a>5.1. |
| JDK 1.4 java.util.logging |
| </h3></div></div></div><a class="indexterm" name="d0e17192"></a><p> |
| When using JDK 1.4 or higher in conjunction with OpenJPA's Commons Logging |
| support, logging will proceed through Java's built-in logging provided by the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="http://java.sun.com/j2se/1.4/docs/api/java/util/logging/package-summary.html" target="_top"> |
| java.util.logging</a> package. For details on configuring the built-in |
| logging system, please see the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="http://java.sun.com/j2se/1.4/docs/guide/util/logging/overview.html" target="_top"> |
| Java Logging Overview</a>. |
| </p><p> |
| By default, JDK 1.4's logging package looks in the <code class="filename"> |
| JAVA_HOME/lib/logging.properties</code> file for logging configuration. This |
| can be overridden with the <code class="literal"> java.util.logging.config.file</code> |
| system property. For example: |
| </p><pre class="programlisting"> |
| java -Djava.util.logging.config.file=mylogging.properties com.company.MyClass |
| </pre><div class="example"><a name="ref_guide_logging_jdk14_propfile"></a><p class="title"><b>Example 3.5. |
| JDK 1.4 Log Properties |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| # specify the handlers to create in the root logger |
| # (all loggers are children of the root logger) |
| # the following creates two handlers |
| handlers=java.util.logging.ConsoleHandler, java.util.logging.FileHandler |
| |
| # set the default logging level for the root logger |
| .level=ALL |
| |
| # set the default logging level for new ConsoleHandler instances |
| java.util.logging.ConsoleHandler.level=INFO |
| |
| # set the default logging level for new FileHandler instances |
| java.util.logging.FileHandler.level=ALL |
| |
| # set the default formatter for new ConsoleHandler instances |
| java.util.logging.ConsoleHandler.formatter=java.util.logging.SimpleFormatter |
| |
| # set the default logging level for all OpenJPA logs |
| openjpa.Tool.level=INFO |
| openjpa.Runtime.level=INFO |
| openjpa.Remote.level=INFO |
| openjpa.DataCache.level=INFO |
| openjpa.MetaData.level=INFO |
| openjpa.Enhance.level=INFO |
| openjpa.Query.level=INFO |
| openjpa.jdbc.SQL.level=INFO |
| openjpa.jdbc.JDBC.level=INFO |
| openjpa.jdbc.Schema.level=INFO |
| </pre></div></div><br class="example-break"></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_logging_custom"></a>6. |
| Custom Log |
| </h2></div></div></div><a class="indexterm" name="d0e17223"></a><p> |
| If none of available logging systems meet your needs, you can configure the |
| logging system with a custom logger. You might use custom logging to integrate |
| with a proprietary logging framework used by some applications servers, or for |
| logging to a graphical component for GUI applications. |
| </p><p> |
| A custom logging framework must include an implementation of the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/lib/log/LogFactory.html" target="_top"><code class="classname"> |
| org.apache.openjpa.lib.log.LogFactory</code></a> interface. We present |
| a custom <code class="classname">LogFactory</code> below. |
| </p><div class="example"><a name="ref_guide_logging_custom_ex"></a><p class="title"><b>Example 3.6. |
| Custom Logging Class |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| package com.xyz; |
| |
| import org.apache.openjpa.lib.log.*; |
| |
| public class CustomLogFactory |
| implements LogFactory { |
| |
| private String _prefix = "CUSTOM LOG"; |
| |
| public void setPrefix (String prefix) { |
| _prefix = prefix; |
| } |
| |
| public Log getLog(String channel) { |
| // Return a simple extension of AbstractLog that will log |
| // everything to the System.err stream. Note that this is |
| // roughly equivalent to OpenJPA's default logging behavior. |
| return new AbstractLog() { |
| |
| protected boolean isEnabled(short logLevel) { |
| // log all levels |
| return true; |
| } |
| |
| protected void log (short type, String message, Throwable t) { |
| // just send everything to System.err |
| System.err.println(_prefix + ": " + type + ": " |
| + message + ": " + t); |
| } |
| }; |
| } |
| } |
| </pre></div></div><br class="example-break"><p> |
| To make OpenJPA use your custom log factory, set the |
| <a href="#openjpa.Log" title="5.38. openjpa.Log"><code class="literal">openjpa.Log</code></a> configuration |
| property to your factory's full class name. Because this property is a plugin |
| property (see <a href="#ref_guide_conf_plugins" title="4. Plugin Configuration">Section 4, “ |
| Plugin Configuration |
| ”</a> ), you can also |
| pass parameters to your factory. For example, to use the example factory above |
| and set its prefix to "LOG MSG", you would set the <code class="literal">openjpa.Log |
| </code> property to the following string: |
| </p><pre class="programlisting"> |
| com.xyz.CustomLogFactory(Prefix="LOG MSG") |
| </pre></div></div><div class="chapter" lang="en" id="ref_guide_dbsetup"><div class="titlepage"><div><div><h2 class="title"><a name="ref_guide_dbsetup"></a>Chapter 4. |
| JDBC |
| </h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#ref_guide_dbsetup_builtin">1. |
| Using the OpenJPA DataSource |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_dbsetup_thirdparty">2. |
| Using a Third-Party DataSource |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_dbsetup_thirdparty_enlist">2.1. |
| Managed and XA DataSources |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_dbsetup_sqlconn">3. |
| Runtime Access to DataSource |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_dbsetup_dbsupport">4. |
| Database Support |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_dbsetup_dbdictprops">4.1. |
| DBDictionary Properties |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_dbsetup_dbsupport_mysql">4.2. |
| MySQLDictionary Properties |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_dbsetup_dbsupport_oracle">4.3. |
| OracleDictionary Properties |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_dbsetup_isolation">5. |
| Setting the Transaction Isolation |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_dbsetup_sql92">6. |
| Setting the SQL Join Syntax |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_dbsetup_multidb">7. |
| Accessing Multiple Databases |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_dbsetup_retain">8. |
| Configuring the Use of JDBC Connections |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_dbsetup_stmtbatch">9. |
| Statement Batching |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_dbsetup_lrs">10. |
| Large Result Sets |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_schema_def">11. |
| Default Schema |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_schema_info">12. |
| Schema Reflection |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_schema_info_list">12.1. |
| Schemas List |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_schema_info_factory">12.2. |
| Schema Factory |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_schema_schematool">13. |
| Schema Tool |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_schema_xml">14. |
| XML Schema Format |
| </a></span></dt></dl></div><a class="indexterm" name="d0e17261"></a><p> |
| OpenJPA uses a relational database for object persistence. |
| It communicates with the database using the Java DataBase Connectivity (JDBC) |
| APIs. This chapter describes how to configure OpenJPA to work with the JDBC |
| driver for your database, and how to access JDBC functionality at runtime. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_dbsetup_builtin"></a>1. |
| Using the OpenJPA DataSource |
| </h2></div></div></div><a class="indexterm" name="d0e17269"></a><a class="indexterm" name="d0e17274"></a><p> |
| OpenJPA includes its own simple <code class="classname">javax.sql.DataSource</code> |
| implementation. If you choose to use OpenJPA's <code class="classname">DataSource |
| </code>, then you must specify the following properties: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <a class="indexterm" name="d0e17291"></a> |
| <code class="literal">openjpa.ConnectionUserName</code>: The JDBC user name for |
| connecting to the database. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e17301"></a> |
| <code class="literal">openjpa.ConnectionPassword</code>: The JDBC password for the above |
| user. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e17311"></a> |
| <code class="literal">openjpa.ConnectionURL</code>: The JDBC URL for the database. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e17321"></a> |
| <code class="literal">openjpa.ConnectionDriverName</code>: The JDBC driver class. |
| </p></li></ul></div><p> |
| To configure advanced features, use the following optional |
| properties. The syntax of these property strings follows the syntax of OpenJPA |
| plugin parameters described in <a href="#ref_guide_conf_plugins" title="4. Plugin Configuration">Section 4, “ |
| Plugin Configuration |
| ”</a>. |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <a class="indexterm" name="d0e17336"></a> |
| <a href="#openjpa.ConnectionProperties" title="5.18. openjpa.ConnectionProperties"> |
| <code class="literal">openjpa.ConnectionProperties</code></a>: If the listed driver is an |
| instance of <code class="classname">java.sql.Driver</code>, this string will be parsed |
| into a <code class="classname">Properties</code> instance, which will then be used to |
| obtain database connections through the <code class="methodname">Driver.connect(String url, |
| Properties props)</code> method. If, on the other hand, the listed driver |
| is a <code class="classname"> javax.sql.DataSource</code>, the string will be treated |
| as a plugin properties string, and matched to the bean setter methods of the |
| <code class="classname">DataSource</code> instance. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e17363"></a> |
| <a href="#openjpa.ConnectionFactoryProperties" title="5.14. openjpa.ConnectionFactoryProperties"> |
| <code class="literal">openjpa.ConnectionFactoryProperties</code></a>: OpenJPA's built-in |
| <code class="classname">DataSource</code> allows you to set the following options via |
| this plugin string: |
| </p><div class="itemizedlist"><ul type="circle"><li><p> |
| <a class="indexterm" name="d0e17379"></a> |
| <code class="literal">QueryTimeout</code>: The maximum number of seconds the JDBC driver |
| will wait for a statement to execute. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e17391"></a> |
| <code class="literal">PrettyPrint</code>: Boolean indicating whether to pretty-print |
| logged SQL statements. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e17403"></a> |
| <code class="literal">PrettyPrintLineLength</code>: The maximum number of characters in |
| each pretty-printed SQL line. |
| </p></li></ul></div></li></ul></div><div class="example"><a name="ref_guide_dbsetup_builtin_ex"></a><p class="title"><b>Example 4.1. |
| Properties for the OpenJPA DataSource |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| <property name="openjpa.ConnectionUserName" value="user"/> |
| <property name="openjpa.ConnectionPassword" value="pass"/> |
| <property name="openjpa.ConnectionURL" value="jdbc:hsqldb:db-hypersonic"/> |
| <property name="openjpa.ConnectionDriverName" value="org.hsqldb.jdbcDriver"/> |
| <property name="openjpa.ConnectionFactoryProperties" |
| value="PrettyPrint=true, PrettyPrintLineLength=80"/> |
| </pre></div></div><br class="example-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_dbsetup_thirdparty"></a>2. |
| Using a Third-Party DataSource |
| </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#ref_guide_dbsetup_thirdparty_enlist">2.1. |
| Managed and XA DataSources |
| </a></span></dt></dl></div><a class="indexterm" name="d0e17420"></a><p> |
| You can use OpenJPA with any third-party <code class="classname">javax.sql.DataSource |
| </code>. There are multiple ways of telling OpenJPA about a <code class="classname"> |
| DataSource</code>: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <a class="indexterm" name="d0e17437"></a> |
| Set the <code class="classname">DataSource</code> into the map passed to <code class="methodname"> |
| Persistence.createEntityManagerFactory</code> under the |
| <a href="#openjpa.ConnectionFactory" title="5.9. openjpa.ConnectionFactory"><code class="literal">openjpa.ConnectionFactory |
| </code></a> key. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e17454"></a> |
| Bind the <code class="classname">DataSource</code> into JNDI, and then specify its |
| location in the <code class="literal">jta-data-source</code> or |
| <code class="literal">non-jta-data-source</code> element of the |
| <a href="#jpa_overview_persistence_xml" title="1. persistence.xml">JPA XML format</a> (depending on |
| whether the <code class="classname">DataSource</code> is managed by JTA), or in the |
| <a href="#openjpa.ConnectionFactoryName" title="5.11. openjpa.ConnectionFactoryName"> |
| <code class="literal">openjpa.ConnectionFactoryName</code></a> property. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e17481"></a> |
| Specify the full class name of the <code class="classname">DataSource</code> |
| implementation in the <a href="#openjpa.ConnectionDriverName" title="5.7. openjpa.ConnectionDriverName"> |
| <code class="literal">openjpa.ConnectionDriverName</code></a> property in place of a JDBC |
| driver. In this configuration OpenJPA will instantiate an instance of the named |
| class via reflection. It will then configure the <code class="classname">DataSource |
| </code> with the properties in the |
| <a href="#openjpa.ConnectionProperties" title="5.18. openjpa.ConnectionProperties"> |
| <code class="literal">openjpa.ConnectionProperties</code></a> setting. |
| </p></li></ul></div><p> |
| The features of OpenJPA's own <code class="classname">DataSource</code> can |
| also be used with third-party implementations. OpenJPA layers on top of the |
| third-party <code class="classname">DataSource</code> to provide the extra |
| functionality. To configure these features use the |
| <a href="#openjpa.ConnectionFactoryProperties" title="5.14. openjpa.ConnectionFactoryProperties"> |
| <code class="literal">openjpa.ConnectionFactoryProperties</code></a> property described |
| in the previous section. |
| </p><div class="example"><a name="ref_guide_dbsetup_thirdparty_ex"></a><p class="title"><b>Example 4.2. |
| Properties File for a Third-Party DataSource |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| <property name="openjpa.ConnectionDriverName" value="oracle.jdbc.pool.OracleDataSource"/> |
| <property name="openjpa.ConnectionProperties" |
| value="PortNumber=1521, ServerName=saturn, DatabaseName=solarsid, DriverType=thin"/> |
| <property name="openjpa.ConnectionFactoryProperties" value="QueryTimeout=5000"/> |
| </pre></div></div><br class="example-break"><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_dbsetup_thirdparty_enlist"></a>2.1. |
| Managed and XA DataSources |
| </h3></div></div></div><a class="indexterm" name="d0e17522"></a><a class="indexterm" name="d0e17527"></a><p> |
| <a class="indexterm" name="d0e17534"></a> |
| Certain application servers automatically enlist their <code class="classname"> DataSource |
| </code>s in global transactions. When this is the case, OpenJPA should not |
| attempt to commit the underlying connection, leaving JDBC transaction completion |
| to the application server. To notify OpenJPA that your third-party <code class="classname"> |
| DataSource</code> is managed by the application server, use the |
| <code class="literal">jta-data-source</code> element of your <code class="filename"> |
| persistence.xml</code> file or set the |
| <a href="#openjpa.ConnectionFactoryMode" title="5.13. openjpa.ConnectionFactoryMode"> |
| <code class="literal">openjpa.ConnectionFactoryMode</code></a> property to |
| <code class="literal">managed</code>. |
| </p><p> |
| Note that OpenJPA can only use managed <code class="classname">DataSource</code>s when |
| it is also integrating with the application server's managed transactions. Also |
| note that all XA <code class="classname">DataSource</code>s are enlisted, and you must |
| set this property when using any XA <code class="classname"> DataSource</code>. |
| </p><p> |
| When using a managed <code class="classname">DataSource</code>, you should also |
| configure a second unmanaged <code class="classname">DataSource</code> that OpenJPA can |
| use to perform tasks that are independent of the global transaction. The most |
| common of these tasks is updating the sequence table OpenJPA uses to generate |
| unique primary key values for your datastore identity objects. Configure the |
| second <code class="classname">DataSource</code> using the <code class="literal">non-jta-data-source |
| </code> <code class="filename">persistence.xml</code> element, or OpenJPA's various |
| "2" connection properties, such as <code class="literal">openjpa.ConnectionFactory2Name |
| </code> or <code class="literal">openjpa.Connection2DriverName</code>. These |
| properties are outlined in <a href="#ref_guide_conf" title="Chapter 2. Configuration">Chapter 2, <i xmlns:xlink="http://www.w3.org/1999/xlink"> |
| Configuration |
| </i></a>. |
| </p><div class="example"><a name="ref_guide_enterprise_xa_conf_ex"></a><p class="title"><b>Example 4.3. |
| Managed DataSource Configuration |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| <!-- managed DataSource --> |
| <jta-data-source>java:/OracleXASource</jta-data-source> |
| <properties> |
| <!-- use OpenJPA's built-in DataSource for unmanaged connections --> |
| <property name="openjpa.Connection2UserName" value="scott"/> |
| <property name="openjpa.Connection2Password" value="tiger"/> |
| <property name="openjpa.Connection2URL" value="jdbc:oracle:thin:@CROM:1521:OpenJPADB"/> |
| <property name="openjpa.Connection2DriverName" value="oracle.jdbc.driver.OracleDriver"/> |
| </properties> |
| </pre></div></div><br class="example-break"></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_dbsetup_sqlconn"></a>3. |
| Runtime Access to DataSource |
| </h2></div></div></div><a class="indexterm" name="d0e17602"></a><a class="indexterm" name="d0e17607"></a><p> |
| The JPA standard defines how to access JDBC connections from enterprise beans. |
| OpenJPA also provides APIs to access an <code class="classname">EntityManager</code>'s |
| connection, or to retrieve a connection directly from the <code class="classname"> |
| EntityManagerFactory</code>'s <code class="classname">DataSource</code>. |
| </p><p> |
| The |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/OpenJPAEntityManager.html" target="_top"> |
| <code class="methodname">OpenJPAEntityManager.getConnection</code></a> method |
| returns an <code class="classname">EntityManager</code>'s connection. If the <code class="classname"> |
| EntityManager</code> does not already have a connection, it will obtain |
| one. The returned connection is only guaranteed to be transactionally consistent |
| with other <code class="classname">EntityManager</code> operations if the <code class="classname"> |
| EntityManager</code> is in a managed or non-optimistic transaction, if the |
| <code class="classname">EntityManager</code> has flushed in the current transaction, or |
| if you have used the <code class="methodname">OpenJPAEntityManager.beginStore</code> |
| method to ensure that a datastore transaction is in progress. Always close the |
| returned connection before attempting any other <code class="classname">EntityManager |
| </code> operations. OpenJPA will ensure that the underlying native |
| connection is not released if a datastore transaction is in progress. |
| </p><div class="example"><a name="ref_guide_dbsetup_conn_jpa"></a><p class="title"><b>Example 4.4. |
| Using the EntityManager's Connection |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| import java.sql.*; |
| import org.apache.openjpa.persistence.*; |
| |
| ... |
| |
| OpenJPAEntityManager kem = OpenJPAPersistence.cast(em); |
| Connection conn = (Connection) kem.getConnection(); |
| |
| // do JDBC stuff |
| |
| conn.close(); |
| </pre></div></div><br class="example-break"><p> |
| The example below shows how to use a connection directly from the <code class="classname"> |
| DataSource</code>, rather than using an <code class="classname"> EntityManager |
| </code>'s connection. |
| </p><div class="example"><a name="ref_guide_dbsetup_conn_from_factory_jpa"></a><p class="title"><b>Example 4.5. |
| Using the EntityManagerFactory's DataSource |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| import java.sql.*; |
| import javax.sql.*; |
| import org.apache.openjpa.conf.*; |
| import org.apache.openjpa.persistence.*; |
| |
| ... |
| |
| OpenJPAEntityManagerFactory kemf = OpenJPAPersistence.cast(emf); |
| OpenJPAConfiguration conf = kemf.getConfiguration(); |
| DataSource dataSource = (DataSource) conf.getConnectionFactory(); |
| Connection conn = dataSource.getConnection(); |
| |
| // do JDBC stuff |
| |
| conn.close(); |
| </pre></div></div><br class="example-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_dbsetup_dbsupport"></a>4. |
| Database Support |
| </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#ref_guide_dbsetup_dbdictprops">4.1. |
| DBDictionary Properties |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_dbsetup_dbsupport_mysql">4.2. |
| MySQLDictionary Properties |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_dbsetup_dbsupport_oracle">4.3. |
| OracleDictionary Properties |
| </a></span></dt></dl></div><a class="indexterm" name="d0e17672"></a><a class="indexterm" name="d0e17675"></a><p> |
| OpenJPA can take advantage of any JDBC 2.x compliant |
| driver, making almost any major database a candidate for use. See our officially |
| supported database list in <a href="#supported_databases" title="Appendix 2. Supported Databases">Appendix 2, <i xmlns:xlink="http://www.w3.org/1999/xlink"> |
| Supported Databases |
| </i></a> for more |
| information. Typically, OpenJPA auto-configures its JDBC behavior and SQL |
| dialect for your database, based on the values of your connection-related |
| configuration properties. |
| </p><p> |
| If OpenJPA cannot detect what type of database you are using, or if you are |
| using an unsupported database, you will have to tell OpenJPA what |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/sql/DBDictionary.html" target="_top"> |
| <code class="classname">org.apache.openjpa.jdbc.sql.DBDictionary</code></a> to use. |
| The <code class="classname">DBDictionary</code> abstracts away the differences between |
| databases. You can plug a dictionary into OpenJPA using the |
| <a href="#openjpa.jdbc.DBDictionary" title="6.2. openjpa.jdbc.DBDictionary"><code class="literal">openjpa.jdbc.DBDictionary |
| </code></a> configuration property. The built-in dictionaries are listed |
| below. If you are using an unsupported database, you may have to write your own |
| <code class="classname">DBDictionary</code> subclass, a simple process. |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <a class="indexterm" name="d0e17707"></a> |
| <code class="literal">access</code>: Dictionary for Microsoft Access. This is an alias |
| for the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/sql/AccessDictionary.html" target="_top"> |
| <code class="classname">org.apache.openjpa.jdbc.sql.AccessDictionary</code></a> |
| class. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e17722"></a> |
| <code class="literal">db2</code>: Dictionary for IBM's DB2 database. This is an alias for |
| the <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/sql/DB2Dictionary.html" target="_top"> |
| <code class="classname">org.apache.openjpa.jdbc.sql.DB2Dictionary</code></a> class. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e17737"></a> |
| <code class="literal">derby</code>: Dictionary for the Apache Derby database. This is an |
| alias for the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/sql/DerbyDictionary.html" target="_top"> |
| <code class="classname">org.apache.openjpa.jdbc.sql.DerbyDictionary</code> class. |
| </a> |
| </p></li><li><p> |
| <a class="indexterm" name="d0e17753"></a> |
| <code class="literal">empress</code>: Dictionary for Empress database This is an alias |
| for the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/sql/EmpressDictionary.html" target="_top"> |
| <code class="classname">org.apache.openjpa.jdbc.sql.EmpressDictionary</code></a> |
| class. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e17768"></a> |
| <code class="literal">foxpro</code>: Dictionary for Microsoft Visual FoxPro. This is an |
| alias for the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/sql/FoxProDictionary.html" target="_top"> |
| <code class="classname">org.apache.openjpa.jdbc.sql.FoxProDictionary</code></a> |
| class. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e17783"></a> |
| <code class="literal">hsql</code>: Dictionary for the Hypersonic SQL database. This is an |
| alias for the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/sql/HSQLDictionary.html" target="_top"> |
| <code class="classname">org.apache.openjpa.jdbc.sql.HSQLDictionary</code></a> class. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e17798"></a> |
| <code class="literal">informix</code>: Dictionary for the Informix database. This is an |
| alias for the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/sql/InformixDictionary.html" target="_top"> |
| <code class="classname">org.apache.openjpa.jdbc.sql.InformixDictionary</code></a> |
| class. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e17813"></a> |
| <code class="literal">jdatastore</code>: Dictionary for Borland JDataStore. This is an |
| alias for the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/sql/JDataStoreDictionary.html" target="_top"> |
| <code class="classname">org.apache.openjpa.jdbc.sql.JDataStoreDictionary</code></a> |
| class. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e17828"></a> |
| <code class="literal">mysql</code>: Dictionary for the MySQL database. This is an alias |
| for the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/sql/MySQLDictionary.html" target="_top"> |
| <code class="classname">org.apache.openjpa.jdbc.sql.MySQLDictionary</code></a> |
| class. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e17843"></a> |
| <code class="literal">oracle</code>: Dictionary for Oracle. This is an alias for the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/sql/OracleDictionary.html" target="_top"> |
| <code class="classname">org.apache.openjpa.jdbc.sql.OracleDictionary</code></a> |
| class. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e17858"></a> |
| <code class="literal">pointbase</code>: Dictionary for Pointbase Embedded database. This |
| is an alias for the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/sql/PointbaseDictionary.html" target="_top"> |
| <code class="classname">org.apache.openjpa.jdbc.sql.PointbaseDictionary</code></a> |
| class. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e17873"></a> |
| <code class="literal">postgres</code>: Dictionary for PostgreSQL. This is an alias for |
| the <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/sql/PostgresDictionary.html" target="_top"> |
| <code class="classname">org.apache.openjpa.jdbc.sql.PostgresDictionary</code></a> |
| class. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e17888"></a> |
| <code class="literal">sqlserver</code>: Dictionary for Microsoft's SQLServer database. |
| This is an alias for the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/sql/SQLServerDictionary.html" target="_top"> |
| <code class="classname">org.apache.openjpa.jdbc.sql.SQLServerDictionary</code></a> |
| class. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e17903"></a> |
| <code class="literal">sybase</code>: Dictionary for Sybase. This is an alias for the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/sql/SybaseDictionary.html" target="_top"> |
| <code class="classname">org.apache.openjpa.jdbc.sql.SybaseDictionary</code></a> |
| class. |
| </p></li></ul></div><p> |
| The example below demonstrates how to set a dictionary and configure its |
| properties in your configuration file. The <code class="literal">DBDictionary</code> |
| property uses OpenJPA's <a href="#ref_guide_conf_plugins" title="4. Plugin Configuration">plugin syntax |
| </a>. |
| </p><div class="example"><a name="ref_guide_dbsetup_dbdict"></a><p class="title"><b>Example 4.6. |
| Specifying a DBDictionary |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| <property name="openjpa.jdbc.DBDictionary" value="hsql(SimulateLocking=true)"/> |
| </pre></div></div><br class="example-break"><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_dbsetup_dbdictprops"></a>4.1. |
| DBDictionary Properties |
| </h3></div></div></div><p> |
| The standard dictionaries all recognize the following properties. These |
| properties will usually not need to be overridden, since the dictionary |
| implementation should use the appropriate default values for your database. You |
| typically won't use these properties unless you are designing your own |
| <code class="classname">DBDictionary</code> for an unsupported database. |
| </p><div class="itemizedlist"><ul type="disc"><li><p><a name="DBDictionary.AllowsAliasInBulkClause"></a> |
| <a class="indexterm" name="d0e17941"></a> |
| <code class="literal">AllowsAliasInBulkClause</code>: |
| When true, SQL delete and update statements may use table aliases. |
| </p></li><li><p><a name="DBDictionary.ArrayTypeName"></a> |
| <a class="indexterm" name="d0e17953"></a> |
| <code class="literal">ArrayTypeName</code>: The overridden default column type for |
| <code class="literal">java.sql.Types.ARRAY</code>. This is used only when the schema is |
| generated by the <code class="literal">mappingtool</code>. |
| </p></li><li><p><a name="DBDictionary.AutoAssignClause"></a> |
| <a class="indexterm" name="d0e17971"></a> |
| <code class="literal">AutoAssignClause</code>: The column definition clause to append to |
| a creation statement. For example, <code class="literal">"AUTO_INCREMENT"</code> for |
| MySQL. This property is set automatically in the dictionary, and should not need |
| to be overridden, and is only used when the schema is generated using the |
| <code class="literal">mappingtool</code>. |
| </p></li><li><p><a name="DBDictionary.AutoAssignTypeName"></a> |
| <a class="indexterm" name="d0e17991"></a> |
| <a class="indexterm" name="d0e17997"></a> |
| <code class="literal">AutoAssignTypeName</code>: |
| The column type name for auto-increment |
| columns. For example, <code class="literal">"BIGSERIAL"</code> for PostgreSQL. This |
| property is set automatically in the dictionary and should not need to be |
| overridden. It is used only when the schema is generated using the |
| <code class="literal">mappingtool</code>. |
| </p></li><li><p><a name="DBDictionary.BatchLimit"></a> |
| <a class="indexterm" name="d0e18017"></a> |
| <code class="literal">BatchLimit</code>: |
| The default batch limit for sending multiple SQL statements at once to the |
| database. A value of -1 indicates unlimited batching, and any positive integer |
| indicates the maximum number of SQL statements to batch together. |
| Defaults to 0 which disables batching. |
| </p></li><li><p><a name="DBDictionary.BigintTypeName"></a> |
| <a class="indexterm" name="d0e18029"></a> |
| <code class="literal">BigintTypeName</code>: The overridden default column type for |
| <code class="literal">java.sql.Types.BIGINT</code>. This is used only when the schema is |
| generated by the <code class="literal">mappingtool</code>. |
| </p></li><li><p><a name="DBDictionary.BinaryTypeName"></a> |
| <a class="indexterm" name="d0e18047"></a> |
| <code class="literal">BinaryTypeName</code>: The overridden default column type for |
| <code class="literal">java.sql.Types.BINARY</code>. This is used only when the schema is |
| generated by the <code class="literal">mappingtool</code>. |
| </p></li><li><p><a name="DBDictionary.BitTypeName"></a> |
| <a class="indexterm" name="d0e18065"></a> |
| <code class="literal">BitTypeName</code>: The overridden default column type for |
| <code class="literal">java.sql.Types.BIT</code>. This is used only when the schema is generated by |
| the <code class="literal">mappingtool</code>. |
| </p></li><li><p><a name="DBDictionary.BlobBufferSize"></a> |
| <a class="indexterm" name="d0e18083"></a> |
| <code class="literal">BlobBufferSize</code>: This property establishes the buffer size in |
| the <code class="literal">INSERT/UPDATE</code> operations with an |
| <code class="literal">java.io.InputStream</code>This is only used with OpenJPA's |
| <a href="#ref_guide_streamsupport" title="7.11. Stream LOB Support">Section 7.11, “ |
| Stream LOB Support |
| ”</a>. Defaults to 50000. |
| </p></li><li><p><a name="DBDictionary.BlobTypeName"></a> |
| <a class="indexterm" name="d0e18103"></a> |
| <a class="indexterm" name="d0e18109"></a> |
| <code class="literal">BlobTypeName</code>: The overridden default column type for |
| <code class="literal">java.sql.Types.BLOB</code>. This is used only when the schema is |
| generated by the <code class="literal">mappingtool</code>. |
| </p></li><li><p><a name="DBDictionary.BooleanTypeName"></a> |
| <a class="indexterm" name="d0e18127"></a> |
| <code class="literal">BooleanTypeName</code>: |
| The overridden default column type for |
| <code class="literal">java.sql.Types.BOOLEAN</code>. This is used only when the schema |
| is generated by the <code class="literal">mappingtool</code>. |
| </p></li><li><p><a name="DBDictionary.CastFunction"></a> |
| <a class="indexterm" name="d0e18145"></a> |
| <code class="literal">CastFunction</code>: |
| The SQL function call to cast a value to another SQL type. |
| Use the tokens <code class="literal">{0}</code> and <code class="literal">{1}</code> to represent |
| the two arguments. The result of the function is convert the |
| <code class="literal">{0}</code> value to a <code class="literal">{1}</code> type. |
| The default is <code class="literal">"CAST({0} AS {1})"</code>. |
| </p></li><li><p><a name="DBDictionary.CatalogSeparator"></a> |
| <a class="indexterm" name="d0e18172"></a> |
| <code class="literal">CatalogSeparator</code>: The string the database uses to delimit |
| between the schema name and the table name. This is typically <code class="literal">"." |
| </code>, which is the default. |
| </p></li><li><p><a name="DBDictionary.CharTypeName"></a> |
| <a class="indexterm" name="d0e18187"></a> |
| <code class="literal">CharTypeName</code>: The overridden default column type for |
| <code class="literal">java.sql.Types.CHAR</code>. This is used only when the schema is |
| generated by the <code class="literal">mappingtool</code>. |
| </p></li><li><p><a name="DBDictionary.CharacterColumnSize"></a> |
| <a class="indexterm" name="d0e18205"></a> |
| <code class="literal">CharacterColumnSize</code>: The default size of <code class="literal">varchar |
| </code> and <code class="literal">char</code> columns. Typically 255. |
| </p></li><li><p><a name="DBDictionary.ClobBufferSize"></a> |
| <a class="indexterm" name="d0e18223"></a> |
| <code class="literal">ClobBufferSize</code>: This property establish the buffer size in |
| the <code class="literal">INSERT/UPDATE</code> operations with a |
| <code class="literal">java.io.Reader</code>This is only used with OpenJPA's |
| <a href="#ref_guide_streamsupport" title="7.11. Stream LOB Support">Section 7.11, “ |
| Stream LOB Support |
| ”</a>. Defaults to 50000. |
| </p></li><li><p><a name="DBDictionary.ClobTypeName"></a> |
| <a class="indexterm" name="d0e18243"></a> |
| <a class="indexterm" name="d0e18249"></a> |
| <code class="literal">ClobTypeName</code>: The overridden default column type for |
| <code class="literal">java.sql.Types.CLOB</code>. This is used only when the schema is |
| generated by the <code class="literal">mappingtool</code>. |
| </p></li><li><p><a name="DBDictionary.ClosePoolSQL"></a> |
| <a class="indexterm" name="d0e18267"></a> |
| <code class="literal">ClosePoolSQL</code>: |
| A special command to issue to the database when shutting down the pool. |
| Usually the pool of connections to the database is closed when the |
| application is ending. For embedded databases, whose lifecycle is |
| coterminous with the application, there may be a special |
| command, usually <code class="literal">"SHUTDOWN"</code>, |
| that will cause the embedded database to close cleanly. |
| Defaults to <code class="literal">null</code>. |
| </p></li><li><p><a name="DBDictionary.ConcatenateFunction"></a> |
| <a class="indexterm" name="d0e18285"></a> |
| <code class="literal">ConcatenateFunction</code>: |
| The SQL function call or operation to concatenate two strings. |
| Use the tokens <code class="literal">{0}</code> and <code class="literal">{1}</code> to represent |
| the two arguments. The result of the function or operation is to concatenate |
| the <code class="literal">{1}</code> string to the end of the <code class="literal">{0}</code> |
| string. Defaults to <code class="literal">"({0}||{1})"</code>. |
| </p></li><li><p><a name="DBDictionary.ConstraintNameMode"></a> |
| <a class="indexterm" name="d0e18312"></a> |
| <code class="literal">ConstraintNameMode</code>: When creating constraints, whether to |
| put the constraint name before the definition (<code class="literal">"before"</code>), |
| just after the constraint type name (<code class="literal">"mid"</code>), or after the |
| constraint definition (<code class="literal">"after"</code>). |
| Defaults to <code class="literal">"before"</code>. |
| </p></li><li><p><a name="DBDictionary.CreatePrimaryKeys"></a> |
| <a class="indexterm" name="d0e18336"></a> |
| <code class="literal">CreatePrimaryKeys</code>: When false, do not |
| create database primary keys for identifiers. Defaults to <code class="literal">true |
| </code>. |
| </p></li><li><p><a name="DBDictionary.CrossJoinClause"></a> |
| <a class="indexterm" name="d0e18351"></a> |
| <code class="literal">CrossJoinClause</code>: The clause to use for a cross join |
| (cartesian product). Defaults to <code class="literal">"CROSS JOIN"</code>. |
| </p></li><li><p><a name="DBDictionary.CurrentDateFunction"></a> |
| <a class="indexterm" name="d0e18366"></a> |
| <code class="literal">CurrentDateFunction</code>: |
| The SQL function call to obtain the current date from the database. |
| Defaults to <code class="literal">"CURRENT_DATE"</code>. |
| </p></li><li><p><a name="DBDictionary.CurrentTimeFunction"></a> |
| <a class="indexterm" name="d0e18381"></a> |
| <code class="literal">CurrentTimeFunction</code>: |
| The SQL function call to obtain the current time from the database. |
| Defaults to <code class="literal">"CURRENT_TIME"</code>. |
| </p></li><li><p><a name="DBDictionary.CurrentTimestampFunction"></a> |
| <a class="indexterm" name="d0e18396"></a> |
| <code class="literal">CurrentTimestampFunction</code>: |
| The SQL function call to obtain the current timestamp from the database. |
| Defaults to <code class="literal">"CURRENT_TIMESTAMP"</code>. |
| </p></li><li><p><a name="DBDictionary.DatePrecision"></a> |
| <a class="indexterm" name="d0e18411"></a> |
| <code class="literal">DatePrecision</code>: |
| The database is able to store time values to this degree of precision, |
| which is expressed in nanoseconds. |
| This value is usually one million, meaning that the database is able |
| to store time values with a precision of one millisecond. Particular |
| databases may have more or less precision. |
| OpenJPA will round all time values to this degree of precision |
| before storing them in the database. |
| Defaults to 1000000. |
| </p></li><li><p><a name="DBDictionary.DateTypeName"></a> |
| <a class="indexterm" name="d0e18423"></a> |
| <code class="literal">DateTypeName</code>: The overridden default column type for |
| <code class="literal">java.sql.Types.DATE</code>. This is used only when the schema is |
| generated by the <code class="literal">mappingtool</code>. |
| </p></li><li><p><a name="DBDictionary.DecimalTypeName"></a> |
| <a class="indexterm" name="d0e18441"></a> |
| <code class="literal">DecimalTypeName</code>: The overridden default column type for |
| <code class="literal">java.sql.Types.DECIMAL</code>. This is used only when the schema is |
| generated by the <code class="literal">mappingtool</code>. |
| </p></li><li><p><a name="DBDictionary.DistinctCountColumnSeparator"></a> |
| <a class="indexterm" name="d0e18459"></a> |
| <code class="literal">DistinctCountColumnSeparator</code>: The string the database uses |
| to delimit between column expressions in a <code class="literal">SELECT COUNT(DISTINCT |
| column-list)</code> clause. Defaults to <code class="literal">null</code> |
| for most databases, meaning that |
| multiple columns in a distinct COUNT clause are not supported. |
| </p></li><li><p><a name="DBDictionary.DistinctTypeName"></a> |
| <a class="indexterm" name="d0e18477"></a> |
| <code class="literal">DistinctTypeName</code>: The overridden default column type for |
| <code class="literal">java.sql.Types.DISTINCT</code>. This is used only when the schema |
| is generated by the <code class="literal">mappingtool</code>. |
| </p></li><li><p><a name="DBDictionary.DoubleTypeName"></a> |
| <a class="indexterm" name="d0e18495"></a> |
| <code class="literal">DoubleTypeName</code>: The overridden default column type for |
| <code class="literal">java.sql.Types.DOUBLE</code>. This is used only when the schema is |
| generated by the <code class="literal">mappingtool</code>. |
| </p></li><li><p><a name="DBDictionary.DriverVendor"></a> |
| <a class="indexterm" name="d0e18513"></a> |
| <code class="literal">DriverVendor</code>: The vendor of the particular JDBC driver you |
| are using. Some dictionaries must alter their behavior depending on the driver |
| vendor. Dictionaries usually detect the driver vendor and set this property |
| themselves. See the <code class="literal">VENDOR_XXX</code> constants defined in the |
| <code class="classname">DBDictionary</code> Javadoc for available options. |
| </p></li><li><p><a name="DBDictionary.DropTableSQL"></a> |
| <a class="indexterm" name="d0e18531"></a> |
| <code class="literal">DropTableSQL</code>: |
| The SQL statement used to drop a table. Use the token <code class="literal">{0}</code> |
| as the argument for the table name. |
| Defaults to <code class="literal">"DROP TABLE {0}"</code>. |
| </p></li><li><p><a name="DBDictionary.FixedSizeTypeNames"></a> |
| <a class="indexterm" name="d0e18549"></a> |
| <code class="literal">FixedSizeTypeNames</code>: |
| A comma separated list of additional database types that have a size |
| defined by the database. In other words, when a column of a fixed |
| size type is declared, its size cannot be defined by the user. Common |
| examples would be <code class="literal">DATE</code>, <code class="literal">FLOAT</code>, |
| and <code class="literal">INTEGER</code>. |
| Each database dictionary has its own internal set of fixed size type names |
| that include the names mentioned here and many others. |
| Names added to this property are added to the dictionary's internal set. |
| Defaults to <code class="literal">null</code>. |
| </p></li><li><p><a name="DBDictionary.FloatTypeName"></a> |
| <a class="indexterm" name="d0e18573"></a> |
| <code class="literal">FloatTypeName</code>: The overridden default column type for |
| <code class="literal">java.sql.Types.FLOAT</code>. This is used only when the schema is |
| generated by the <code class="literal">mappingtool</code>. |
| </p></li><li><p><a name="DBDictionary.ForUpdateClause"></a> |
| <a class="indexterm" name="d0e18591"></a> |
| <a class="indexterm" name="d0e18597"></a> |
| <code class="literal">ForUpdateClause</code>: The clause to append to <code class="literal">SELECT |
| </code> statements to issue queries that obtain pessimistic locks. Defaults |
| to <code class="literal">"FOR UPDATE"</code>. |
| </p></li><li><p><a name="DBDictionary.GetStringVal"></a> |
| <a class="indexterm" name="d0e18615"></a> |
| <a class="indexterm" name="d0e18621"></a> |
| <code class="literal">GetStringVal</code>: |
| A special function to return the value of an XML |
| column in a select statement. For example, Oracle uses |
| <code class="literal">".getStringVal()"</code>, as in, |
| <code class="literal">"select t0.xmlcol.getStringVal() from xmltab t0"</code>. |
| Defaults to the empty string. |
| </p></li><li><p><a name="DBDictionary.InClauseLimit"></a> |
| <a class="indexterm" name="d0e18639"></a> |
| <a class="indexterm" name="d0e18645"></a> |
| <code class="literal">InClauseLimit</code>: |
| The maximum number of elements in an <code class="literal">IN</code> clause. OpenJPA |
| works around cases where the limit is exceeded. Defaults to -1 meaning |
| no limit. |
| </p></li><li><p><a name="DBDictionary.InitializationSQL"></a> |
| <a class="indexterm" name="d0e18660"></a> |
| <a class="indexterm" name="d0e18666"></a> |
| <code class="literal">InitializationSQL</code>: A piece of SQL to issue against the |
| database whenever a connection is retrieved from the <code class="classname">DataSource |
| </code>. |
| </p></li><li><p><a name="DBDictionary.InnerJoinClause"></a> |
| <a class="indexterm" name="d0e18681"></a> |
| <code class="literal">InnerJoinClause</code>: The clause to use for an inner join. |
| Defaults to <code class="literal">"INNER JOIN"</code>. |
| </p></li><li><p><a name="DBDictionary.IntegerTypeName"></a> |
| <a class="indexterm" name="d0e18696"></a> |
| <code class="literal">IntegerTypeName</code>: The overridden default column type for |
| <code class="literal">java.sql.Types.INTEGER</code>. This is used only when the schema is |
| generated by the <code class="literal">mappingtool</code>. |
| </p></li><li><p><a name="DBDictionary.JavaObjectTypeName"></a> |
| <a class="indexterm" name="d0e18714"></a> |
| <code class="literal">JavaObjectTypeName</code>: The overridden default column type for |
| <code class="literal">java.sql.Types.JAVAOBJECT</code>. This is used only when the schema |
| is generated by the <code class="literal">mappingtool</code>. |
| </p></li><li><p><a name="DBDictionary.JoinSyntax"></a> |
| <a class="indexterm" name="d0e18732"></a> |
| <code class="literal">JoinSyntax</code>: The SQL join syntax to use in select statements. |
| See <a href="#ref_guide_dbsetup_sql92" title="6. Setting the SQL Join Syntax">Section 6, “ |
| Setting the SQL Join Syntax |
| ”</a>. |
| </p></li><li><p><a name="DBDictionary.LastGeneratedKeyQuery"></a> |
| <a class="indexterm" name="d0e18746"></a> |
| <code class="literal">LastGeneratedKeyQuery</code>: The query to issue to obtain the last |
| automatically generated key for an auto-increment column. For example, |
| <code class="literal">"SELECT LAST_INSERT_ID()"</code> for MySQL. This property is set |
| automatically in the dictionary, and should not need to be overridden. |
| </p></li><li><p><a name="DBDictionary.LongVarbinaryTypeName"></a> |
| <a class="indexterm" name="d0e18763"></a> |
| <code class="literal">LongVarbinaryTypeName</code>: The overridden default column type |
| for <code class="literal">java.sql.Types.LONGVARBINARY</code>. This is used only when the |
| schema is generated by the <code class="literal">mappingtool</code>. |
| </p></li><li><p><a name="DBDictionary.LongVarcharTypeName"></a> |
| <a class="indexterm" name="d0e18781"></a> |
| <code class="literal">LongVarcharTypeName</code>: The overridden default column type for |
| <code class="literal">java.sql.Types.LONGVARCHAR</code>. This is used only when the |
| schema is generated by the <code class="literal">mappingtool</code>. |
| </p></li><li><p><a name="DBDictionary.MaxAutoAssignNameLength"></a> |
| <a class="indexterm" name="d0e18799"></a> |
| <code class="literal">MaxAutoAssignNameLength</code>: Set this property to the maximum |
| length of the sequence name used for auto-increment columns. Names longer than |
| this value are truncated. Defaults to 31. |
| </p></li><li><p><a name="DBDictionary.MaxColumnNameLength"></a> |
| <a class="indexterm" name="d0e18811"></a> |
| <code class="literal">MaxColumnNameLength</code>: The maximum number of characters in a |
| column name. Defaults to 128. |
| </p></li><li><p><a name="DBDictionary.MaxConstraintNameLength"></a> |
| <a class="indexterm" name="d0e18823"></a> |
| <code class="literal">MaxConstraintNameLength</code>: The maximum number of characters in |
| a constraint name. Defaults to 128. |
| </p></li><li><p><a name="DBDictionary.MaxEmbeddedBlobSize"></a> |
| <a class="indexterm" name="d0e18835"></a> |
| <code class="literal">MaxEmbeddedBlobSize</code>: |
| When greater than -1, the maximum size of a <code class="literal">BLOB</code> value |
| that can be sent directly to the database within an insert or update statement. |
| Values whose size is greater than <code class="literal">MaxEmbeddedBlobSize</code> force |
| OpenJPA to work around this limitation. A value of -1 means that there is |
| no limitation. Defaults to -1. |
| </p></li><li><p><a name="DBDictionary.MaxEmbeddedClobSize"></a> |
| <a class="indexterm" name="d0e18853"></a> |
| <code class="literal">MaxEmbeddedClobSize</code>: |
| When greater than -1, the maximum size of a <code class="literal">CLOB</code> value |
| that can be sent directly to the database within an insert or update statement. |
| Values whose size is greater than <code class="literal">MaxEmbeddedClobSize</code> force |
| OpenJPA to work around this limitation. A value of -1 means that there is |
| no limitation. Defaults to -1. |
| </p></li><li><p><a name="DBDictionary.MaxIndexNameLength"></a> |
| <a class="indexterm" name="d0e18871"></a> |
| <a class="indexterm" name="d0e18877"></a> |
| <code class="literal">MaxIndexNameLength</code>: The maximum number of characters in an |
| index name. Defaults to 128. |
| </p></li><li><p><a name="DBDictionary.MaxIndexesPerTable"></a> |
| <a class="indexterm" name="d0e18889"></a> |
| <code class="literal">MaxIndexesPerTable</code>: The maximum number of indexes that can |
| be placed on a single table. Defaults to no limit. |
| </p></li><li><p><a name="DBDictionary.MaxTableNameLength"></a> |
| <a class="indexterm" name="d0e18901"></a> |
| <code class="literal">MaxTableNameLength</code>: The maximum number of characters in a |
| table name. Defaults to 128. |
| </p></li><li><p><a name="DBDictionary.NextSequenceQuery"></a> |
| <a class="indexterm" name="d0e18913"></a> |
| <code class="literal">NextSequenceQuery</code>: A SQL string for obtaining a native |
| sequence value. May use a placeholder of <code class="literal">{0}</code> for the variable |
| sequence name. Defaults to a database-appropriate value. For example, |
| <code class="literal">"SELECT {0}.NEXTVAL FROM DUAL"</code> for Oracle. |
| </p></li><li><p><a name="DBDictionary.NullTypeName"></a> |
| <a class="indexterm" name="d0e18931"></a> |
| <code class="literal">NullTypeName</code>: The overridden default column type for |
| <code class="literal">java.sql.Types.NULL</code>. This is used only when the schema is |
| generated by the <code class="literal">mappingtool</code>. |
| </p></li><li><p><a name="DBDictionary.NumericTypeName"></a> |
| <a class="indexterm" name="d0e18949"></a> |
| <code class="literal">NumericTypeName</code>: The overridden default column type for |
| <code class="literal">java.sql.Types.NUMERIC</code>. This is used only when the schema is |
| generated by the <code class="literal">mappingtool</code>. |
| </p></li><li><p><a name="DBDictionary.OtherTypeName"></a> |
| <a class="indexterm" name="d0e18967"></a> |
| <code class="literal">OtherTypeName</code>: The overridden default column type for |
| <code class="literal">java.sql.Types.OTHER</code>. This is used only when the schema is |
| generated by the <code class="literal">mappingtool</code>. |
| </p></li><li><p><a name="DBDictionary.OuterJoinClause"></a> |
| <a class="indexterm" name="d0e18985"></a> |
| <code class="literal">OuterJoinClause</code>: The clause to use for an left outer join. |
| Defaults to <code class="literal">"LEFT OUTER JOIN"</code>. |
| </p></li><li><p><a name="DBDictionary.Platform"></a> |
| <a class="indexterm" name="d0e19000"></a> |
| <code class="literal">Platform</code>: |
| The name of the database that this dictionary targets. |
| Defaults to <code class="literal">"Generic"</code>, but all dictionaries override this |
| value. |
| </p></li><li><p><a name="DBDictionary.RangePosition"></a> |
| <a class="indexterm" name="d0e19015"></a> |
| <code class="literal">RangePosition</code>: |
| Indicates where to specify in the SQL select statement the range, if any, |
| of the result rows to be returned. |
| When limiting the number of returned result rows to a subset of all those |
| that satisfy the query's conditions, the position of the range clause |
| varies by database. |
| Defaults to 0, meaning that the range |
| is expressed at the end of the select statement but before any locking clause. |
| See the RANGE_XXX constants defined in <code class="classname">DBDictionary</code>. |
| </p></li><li><p><a name="DBDictionary.RealTypeName"></a> |
| <a class="indexterm" name="d0e19030"></a> |
| <code class="literal">RealTypeName</code>: The overridden default column type for |
| <code class="literal">java.sql.Types.REAL</code>. This is used only when the schema is |
| generated by the <code class="literal">mappingtool</code>. |
| </p></li><li><p><a name="DBDictionary.RefTypeName"></a> |
| <a class="indexterm" name="d0e19048"></a> |
| <code class="literal">RefTypeName</code>: The overridden default column type for |
| <code class="literal">java.sql.Types.REF</code>. This is used only when the schema is generated by |
| the <code class="literal">mappingtool</code>. |
| </p></li><li><p><a name="DBDictionary.RequiresAliasForSubselect"></a> |
| <a class="indexterm" name="d0e19066"></a> |
| <a class="indexterm" name="d0e19072"></a> |
| <code class="literal">RequiresAliasForSubselect</code>: When true, the database |
| requires that subselects in a FROM clause be assigned an alias. |
| </p></li><li><p><a name="DBDictionary.RequiresAutoCommitForMetadata"></a> |
| <a class="indexterm" name="d0e19086"></a> |
| <code class="literal">RequiresAutoCommitForMetadata</code>: When true, the JDBC driver |
| requires that autocommit be enabled before any schema interrogation operations |
| can take place. |
| </p></li><li><p><a name="DBDictionary.RequiresCastForComparisons"></a> |
| <a class="indexterm" name="d0e19100"></a> |
| <code class="literal">RequiresCastForComparisons</code>: |
| When true, comparisons of two values of different types or |
| of two literals requires a cast in the generated SQL. |
| Defaults to <code class="literal">false</code>. |
| </p></li><li><p><a name="DBDictionary.RequiresCastForMathFunctions"></a> |
| <a class="indexterm" name="d0e19115"></a> |
| <code class="literal">RequiresCastForMathFunctions</code>: |
| When true, math operations on two values of different types or |
| on two literals requires a cast in the generated SQL. |
| Defaults to <code class="literal">false</code>. |
| </p></li><li><p><a name="DBDictionary.RequiresConditionForCrossJoin"></a> |
| <a class="indexterm" name="d0e19130"></a> |
| <code class="literal">RequiresConditionForCrossJoin</code>: Some databases require that |
| there always be a conditional statement for a cross join. If set, this parameter |
| ensures that there will always be some condition to the join clause. |
| </p></li><li><p><a name="DBDictionary.RequiresTargetForDelete"></a> |
| <a class="indexterm" name="d0e19142"></a> |
| <code class="literal">RequiresTargetForDelete</code>: |
| When true, the database requires a target for delete statements. Defaults |
| to <code class="literal">false</code>. |
| </p></li><li><p><a name="DBDictionary.ReservedWords"></a> |
| <a class="indexterm" name="d0e19157"></a> |
| <code class="literal">ReservedWords</code>: A comma-separated list of reserved words for |
| this database, beyond the standard SQL92 keywords. |
| </p></li><li><p><a name="DBDictionary.SchemaCase"></a> |
| <a class="indexterm" name="d0e19169"></a> |
| <code class="literal">SchemaCase</code>: The case to use when querying the database |
| metadata about schema components. Defaults to making all names upper case. |
| Available values are: <code class="literal">upper, lower, preserve</code>. |
| </p></li><li><p><a name="DBDictionary.SearchStringEscape"></a> |
| <a class="indexterm" name="d0e19186"></a> |
| <code class="literal">SearchStringEscape</code>: |
| The default escape character used when generating SQL <code class="literal">LIKE</code> |
| clauses. The escape character is used to escape the wildcard meaning of the |
| <code class="literal">_</code> and <code class="literal">%</code> characters. |
| Note: since JPQL provides the ability to define the escape character in |
| the query, this setting is primarily used when translating other query |
| languages, such as JDOQL. Defaults to <code class="literal">"\\"</code> |
| (a single backslash in Java speak). |
| </p></li><li><p><a name="DBDictionary.RequiresSearchStringEscapeForLike"></a> |
| <a class="indexterm" name="d0e19210"></a> |
| <code class="literal">RequiresSearchStringEscapeForLike</code>: |
| When true, the database requires an escape string for queries that use |
| <code class="literal">LIKE</code>. The escape string can be specified using |
| <code class="literal">searchStringEscape</code>. Defaults to <code class="literal">true</code>. |
| </p></li><li><p><a name="DBDictionary.SelectWords"></a> |
| <a class="indexterm" name="d0e19231"></a> |
| <code class="literal">SelectWords</code>: A comma-separated list of keywords which may be |
| used to start a SELECT statement for this database. If an application executes |
| a native SQL statement which begins with SelectWords OpenJPA will treat the |
| statement as a SELECT statement rather than an UPDATE statement. |
| </p></li><li><p><a name="DBDictionary.SequenceNameSQL"></a> |
| <a class="indexterm" name="d0e19243"></a> |
| <code class="literal">SequenceNameSQL</code>: |
| Additional phrasing to use with <code class="literal">SequenceSQL</code>. |
| Defaults to <code class="literal">null</code>. |
| </p></li><li><p><a name="DBDictionary.SequenceSQL"></a> |
| <a class="indexterm" name="d0e19263"></a> |
| <code class="literal">SequenceSQL</code>: |
| General structure of the SQL query to use when interrogating the database |
| for sequence names. |
| As there is no standard way to obtain sequence names, |
| it defaults to <code class="literal">null</code>. |
| </p></li><li><p><a name="DBDictionary.SequenceSchemaSQL"></a> |
| <a class="indexterm" name="d0e19280"></a> |
| <code class="literal">SequenceSchemaSQL</code>: |
| Additional phrasing to use with <code class="literal">SequenceSQL</code>. |
| Defaults to <code class="literal">null</code>. |
| </p></li><li><p><a name="DBDictionary.SimulateLocking"></a> |
| <a class="indexterm" name="d0e19300"></a> |
| <code class="literal">SimulateLocking</code>: Some databases do not support pessimistic |
| locking, which will result in an exception when you attempt a |
| transaction while using the pessimistic lock manager. |
| Setting this property to <code class="literal">true</code> suppresses the |
| locking of rows in the database, thereby allowing pessimistic transactions |
| even on databases that do not support locking. At the same time, setting this |
| property to <code class="literal">true</code> means that you do not obtain the semantics |
| of a pessimistic |
| transaction with the database. Defaults to <code class="literal">false</code>. |
| </p></li><li><p><a name="DBDictionary.SmallintTypeName"></a> |
| <a class="indexterm" name="d0e19321"></a> |
| <code class="literal">SmallintTypeName</code>: The overridden default column type for |
| <code class="literal">java.sql.Types.SMALLINT</code>. This is used only when the schema |
| is generated by the <code class="literal">mappingtool</code>. |
| </p></li><li><p><a name="DBDictionary.StorageLimitationsFatal"></a> |
| <a class="indexterm" name="d0e19339"></a> |
| <code class="literal">StorageLimitationsFatal</code>: When true, any data |
| truncation/rounding that is performed by the dictionary in order to store a |
| value in the database will be treated as a fatal error, rather than just issuing |
| a warning. |
| </p></li><li><p><a name="DBDictionary.StoreCharsAsNumbers"></a> |
| <a class="indexterm" name="d0e19351"></a> |
| <code class="literal">StoreCharsAsNumbers</code>: Set this property to <code class="literal">false |
| </code> to store Java <code class="literal">char</code> fields as <code class="literal">CHAR |
| </code> values rather than numbers. Defaults to <code class="literal">true</code>. |
| </p></li><li><p><a name="DBDictionary.StoreLargeNumbersAsStrings"></a> |
| <a class="indexterm" name="d0e19375"></a> |
| <code class="literal">StoreLargeNumbersAsStrings</code>: When true, the dictionary |
| prefers to store Java fields of |
| type <code class="classname">BigInteger</code> and <code class="classname">BigDecimal</code>) |
| as string values in the database. Likewise, the dictionary will instruct |
| the mapping tool to map these Java types to character columns. |
| Because some databases have limitations on the number of digits that can |
| be stored in a numeric column (for example, Oracle can only store 38 |
| digits), this option may be necessary for some applications. |
| Note that this option may prevent OpenJPA from executing meaningful numeric |
| queries against the columns. Defaults to <code class="literal">false</code>. |
| </p></li><li><p><a name="DBDictionary.StringLengthFunction"></a> |
| <a class="indexterm" name="d0e19396"></a> |
| <code class="literal">StringLengthFunction</code>: Name of the SQL function for getting |
| the length of a string. Use the token <code class="literal">{0}</code> to represent the |
| argument. |
| </p></li><li><p><a name="DBDictionary.StructTypeName"></a> |
| <a class="indexterm" name="d0e19411"></a> |
| <code class="literal">StructTypeName</code>: The overridden default column type for |
| <code class="literal">java.sql.Types.STRUCT</code>. This is used only when the schema is |
| generated by the <code class="literal">mappingtool</code>. |
| </p></li><li><p><a name="DBDictionary.SubstringFunctionName"></a> |
| <a class="indexterm" name="d0e19429"></a> |
| <code class="literal">SubstringFunctionName</code>: Name of the SQL function for getting |
| the substring of a string. |
| </p></li><li><p><a name="DBDictionary.SupportsAlterTableWithAddColumn"></a> |
| <a class="indexterm" name="d0e19441"></a> |
| <code class="literal">SupportsAlterTableWithAddColumn</code>: When true, the database |
| supports adding a new column in an ALTER TABLE statement. |
| Defaults to <code class="literal">true</code>. |
| </p></li><li><p><a name="DBDictionary.SupportsAlterTableWithDropColumn"></a> |
| <a class="indexterm" name="d0e19456"></a> |
| <code class="literal">SupportsAlterTableWithDropColumn</code>: When true, the database |
| supports dropping a column in an ALTER TABLE statement. |
| Defaults to <code class="literal">true</code>. |
| </p></li><li><p><a name="DBDictionary.SupportsAutoAssign"></a> |
| <a class="indexterm" name="d0e19471"></a> |
| <code class="literal">SupportsAutoAssign</code>: |
| When true, the database supports auto-assign columns, where the value of |
| column is assigned upon insertion of the row into the database. |
| Defaults to <code class="literal">false</code>. |
| </p></li><li><p><a name="DBDictionary.SupportsCascadeDeleteAction"></a> |
| <a class="indexterm" name="d0e19486"></a> |
| <code class="literal">SupportsCascadeDeleteAction</code>: When true, the database supports |
| the <code class="literal">CASCADE</code> delete action on foreign keys. |
| Defaults to <code class="literal">true</code>. |
| </p></li><li><p><a name="DBDictionary.SupportsCascadeUpdateAction"></a> |
| <a class="indexterm" name="d0e19504"></a> |
| <code class="literal">SupportsCascadeUpdateAction</code>: |
| When true, the database supports the <code class="literal">CASCADE</code> |
| update action on foreign keys. Defaults to <code class="literal">true</code>. |
| </p></li><li><p><a name="DBDictionary.SupportsComments"></a> |
| <a class="indexterm" name="d0e19522"></a> |
| <code class="literal">SupportsComments</code>: |
| When true, comments can be associated with the table in the table creation |
| statement. Defaults to <code class="literal">false</code>. |
| </p></li><li><p><a name="DBDictionary.SupportsCorrelatedSubselect"></a> |
| <a class="indexterm" name="d0e19537"></a> |
| <code class="literal">SupportsCorrelatedSubselect</code>: |
| When true, the database supports correlated subselects. Correlated |
| subselects are select statements nested within select statements that |
| refers to a column in the outer select statement. For performance |
| reasons, correlated subselects are generally a last resort. |
| Defaults to <code class="literal">true</code>. |
| </p></li><li><p><a name="DBDictionary.SupportsDefaultDeleteAction"></a> |
| <a class="indexterm" name="d0e19552"></a> |
| <code class="literal">SupportsDefaultDeleteAction</code>: When true, the database supports |
| the <code class="literal">SET DEFAULT</code> delete action on foreign keys. |
| Defaults to <code class="literal">true</code>. |
| </p></li><li><p><a name="DBDictionary.SupportsDefaultUpdateAction"></a> |
| <a class="indexterm" name="d0e19570"></a> |
| <code class="literal">SupportsDefaultUpdateAction</code>: |
| When true, the database supports the <code class="literal">SET DEFAULT</code> update |
| action on foreign keys. Defaults to <code class="literal">true</code>. |
| </p></li><li><p><a name="DBDictionary.SupportsDeferredConstraints"></a> |
| <a class="indexterm" name="d0e19588"></a> |
| <code class="literal">SupportsDeferredConstraints</code>: When true, the database |
| supports deferred constraints. The |
| database supports deferred constraints by checking for constraint |
| violations when the transaction commits, rather than checking for |
| violations immediately after receiving each SQL statement within the |
| transaction. Defaults to <code class="literal">true</code>. |
| </p></li><li><p><a name="DBDictionary.SupportsForeignKeys"></a> |
| <a class="indexterm" name="d0e19603"></a> |
| <code class="literal">SupportsForeignKeys</code>: When true, the database supports foreign |
| keys. Defaults to <code class="literal">true</code>. |
| </p></li><li><p><a name="DBDictionary.SupportsHaving"></a> |
| <a class="indexterm" name="d0e19618"></a> |
| <code class="literal">SupportsHaving</code>: When true, the database supports HAVING |
| clauses in selects. |
| </p></li><li><p><a name="DBDictionary.SupportsLockingWithDistinctClause"></a> |
| <a class="indexterm" name="d0e19632"></a> |
| <code class="literal">SupportsLockingWithDistinctClause</code>: When true, the |
| database supports <code class="literal">FOR UPDATE</code> select clauses with |
| <code class="literal">DISTINCT</code> clauses. |
| </p></li><li><p><a name="DBDictionary.SupportsLockingWithInnerJoin"></a> |
| <a class="indexterm" name="d0e19650"></a> |
| <code class="literal">SupportsLockingWithInnerJoin</code>: When true, the database |
| supports <code class="literal">FOR UPDATE</code> select clauses with inner join queries. |
| </p></li><li><p><a name="DBDictionary.SupportsLockingWithMultipleTables"></a> |
| <a class="indexterm" name="d0e19665"></a> |
| <code class="literal">SupportsLockingWithMultipleTables</code>: When true, the |
| database supports <code class="literal">FOR UPDATE</code> select clauses that select from |
| multiple tables. |
| </p></li><li><p><a name="DBDictionary.SupportsLockingWithOrderClause"></a> |
| <a class="indexterm" name="d0e19680"></a> |
| <code class="literal">SupportsLockingWithOrderClause</code>: When true, the database |
| supports <code class="literal">FOR UPDATE</code> select clauses with <code class="literal">ORDER BY |
| </code> clauses. |
| </p></li><li><p><a name="DBDictionary.SupportsLockingWithOuterJoin"></a> |
| <a class="indexterm" name="d0e19698"></a> |
| <code class="literal">SupportsLockingWithOuterJoin</code>: When true, the database |
| supports <code class="literal">FOR UPDATE</code> select clauses with outer join queries. |
| </p></li><li><p><a name="DBDictionary.SupportsLockingWithSelectRange"></a> |
| <a class="indexterm" name="d0e19713"></a> |
| <code class="literal">SupportsLockingWithSelectRange</code>: When true, the database |
| supports <code class="literal">FOR UPDATE</code> select clauses with queries that select a |
| range of data using <code class="literal">LIMIT</code>, <code class="literal">TOP</code> or the |
| database equivalent. Defaults to <code class="literal">true</code>. |
| </p></li><li><p><a name="DBDictionary.SupportsModOperator"></a> |
| <a class="indexterm" name="d0e19737"></a> |
| <code class="literal">SupportsModOperator</code>: |
| When true, the database supports the modulus operator (<code class="literal">%</code>) |
| instead of the <code class="literal">MOD</code> function. |
| Defaults to <code class="literal">false</code>. |
| </p></li><li><p><a name="DBDictionary.SupportsMultipleNontransactionalResultSets"></a> |
| <code class="literal">SupportsMultipleNontransactionalResultSets</code>: When true, a |
| nontransactional connection is capable of having multiple open |
| <code class="classname">ResultSet</code> instances. |
| </p></li><li><p><a name="DBDictionary.SupportsNullDeleteAction"></a> |
| <a class="indexterm" name="d0e19767"></a> |
| <code class="literal">SupportsNullDeleteAction</code>: When true, the database supports |
| the <code class="literal">SET NULL</code> delete action on foreign keys. |
| Defaults to <code class="literal">true</code>. |
| </p></li><li><p><a name="DBDictionary.SupportsNullTableForGetColumns"></a> |
| <a class="indexterm" name="d0e19785"></a> |
| <code class="literal">SupportsNullTableForGetColumns</code>: When true, the database |
| supports passing a <code class="literal">null</code> parameter to <code class="methodname"> |
| DatabaseMetaData.getColumns</code> as an optimization to get information |
| about all the tables. Defaults to <code class="literal">true</code>. |
| </p></li><li><p><a name="DBDictionary.SupportsNullTableForGetImportedKeys"></a> |
| <a class="indexterm" name="d0e19808"></a> |
| <code class="literal">SupportsNullTableForGetImportedKeys</code>: When true, the |
| database supports passing a <code class="literal">null</code> parameter to <code class="methodname"> |
| DatabaseMetaData.getImportedKeys</code> as an optimization to get |
| information about all the tables. Defaults to <code class="literal">false</code>. |
| </p></li><li><p><a name="DBDictionary.SupportsNullTableForGetIndexInfo"></a> |
| <a class="indexterm" name="d0e19831"></a> |
| <code class="literal">SupportsNullTableForGetIndexInfo</code>: When true, the database |
| supports passing a <code class="literal">null</code> parameter to <code class="methodname"> |
| DatabaseMetaData.getIndexInfo</code> as an optimization to get information |
| about all the tables. Defaults to <code class="literal">false</code>. |
| </p></li><li><p><a name="DBDictionary.SupportsNullTableForGetPrimaryKeys"></a> |
| <a class="indexterm" name="d0e19854"></a> |
| <code class="literal">SupportsNullTableForGetPrimaryKeys</code>: When true, the |
| database supports passing a <code class="literal">null</code> parameter to <code class="methodname"> |
| DatabaseMetaData.getPrimaryKeys</code> as an optimization to get |
| information about all the tables. Defaults to <code class="literal">false</code>. |
| </p></li><li><p><a name="DBDictionary.SupportsNullUpdateAction"></a> |
| <a class="indexterm" name="d0e19877"></a> |
| <code class="literal">SupportsNullUpdateAction</code>: |
| When true, the database supports the <code class="literal">SET NULL</code> update |
| action on foreign keys. Defaults to <code class="literal">true</code>. |
| </p></li><li><p><a name="DBDictionary.SupportsQueryTimeout"></a> |
| <a class="indexterm" name="d0e19895"></a> |
| <code class="literal">SupportsQueryTimeout</code>: When true, the JDBC driver supports |
| calls to <code class="methodname"> java.sql.Statement.setQueryTimeout</code>. |
| </p></li><li><p><a name="DBDictionary.SupportsRestrictDeleteAction"></a> |
| <a class="indexterm" name="d0e19912"></a> |
| <code class="literal">SupportsRestrictDeleteAction</code>: When true, the database |
| supports the <code class="literal">RESTRICT</code> delete action on foreign keys. |
| Defaults to <code class="literal">true</code>. |
| </p></li><li><p><a name="DBDictionary.SupportsRestrictUpdateAction"></a> |
| <a class="indexterm" name="d0e19930"></a> |
| <code class="literal">SupportsRestrictUpdateAction</code>: |
| When true, the database supports the <code class="literal">RESTRICT</code> update |
| action on foreign keys. Defaults to <code class="literal">true</code>. |
| </p></li><li><p><a name="DBDictionary.SupportsSchemaForGetColumns"></a> |
| <a class="indexterm" name="d0e19948"></a> |
| <code class="literal">SupportsSchemaForGetColumns</code>: When false, the database |
| driver does not support using the schema name for schema reflection on column |
| names. |
| </p></li><li><p><a name="DBDictionary.SupportsSchemaForGetTables"></a> |
| <a class="indexterm" name="d0e19962"></a> |
| <code class="literal">SupportsSchemaForGetTables</code>: If false, then the database |
| driver does not support using the schema name for schema reflection on table |
| names. |
| </p></li><li><p><a name="DBDictionary.SupportsSelectEndIndex"></a> |
| <a class="indexterm" name="d0e19976"></a> |
| <code class="literal">SupportsSelectEndIndex</code>: When true, the database can create a |
| select that is limited to the first N results. |
| </p></li><li><p><a name="DBDictionary.SupportsSelectForUpdate"></a> |
| <a class="indexterm" name="d0e19990"></a> |
| <code class="literal">SupportsSelectForUpdate</code>: When true, the database supports |
| <code class="literal">SELECT</code> statements with a pessimistic locking |
| (<code class="literal">FOR UPDATE</code>) clause. Defaults to <code class="literal">true</code>. |
| </p></li><li><p><a name="DBDictionary.SupportsSelectStartIndex"></a> |
| <a class="indexterm" name="d0e20011"></a> |
| <code class="literal">SupportsSelectStartIndex</code>: When true, the database can create a |
| select that skips the first N results. |
| </p></li><li><p><a name="DBDictionary.SupportsSubselect"></a> |
| <a class="indexterm" name="d0e20025"></a> |
| <a class="indexterm" name="d0e20031"></a> |
| <code class="literal">SupportsSubselect</code>: When true, the database supports subselects |
| in queries. |
| </p></li><li><p><a name="DBDictionary.SupportsTimestampNanos"></a> |
| <a class="indexterm" name="d0e20045"></a> |
| <code class="literal">SupportsTimestampNanos</code>: When true, the database supports |
| nanoseconds with TIMESTAMP columns. |
| Defaults to <code class="literal">true</code>. |
| </p></li><li><p><a name="DBDictionary.SupportsUniqueConstraints"></a> |
| <a class="indexterm" name="d0e20058"></a> |
| <code class="literal">SupportsUniqueConstraints</code>: When true, the database supports |
| unique constraints. Defaults to <code class="literal">true</code>. |
| </p></li><li><p><a name="DBDictionary.SupportsXMLColumn"></a> |
| <a class="indexterm" name="d0e20073"></a> |
| <code class="literal">SupportsXMLColumn</code>: |
| When true, the database supports an XML column type. See |
| <a href="#ref_guide_xmlmapping" title="7.10. XML Column Mapping">Section 7.10, “ |
| XML Column Mapping |
| ”</a> |
| for information on using this capability. Defaults to <code class="literal">false</code>. |
| </p></li><li><p><a name="DBDictionary.SystemSchemas"></a> |
| <a class="indexterm" name="d0e20090"></a> |
| <code class="literal">SystemSchemas</code>: A comma-separated list of schema names that |
| should be ignored. |
| </p></li><li><p><a name="DBDictionary.SystemTables"></a> |
| <a class="indexterm" name="d0e20104"></a> |
| <code class="literal">SystemTables</code>: A comma-separated list of table names that |
| should be ignored. |
| </p></li><li><p><a name="DBDictionary.TableForUpdateClause"></a> |
| <a class="indexterm" name="d0e20118"></a> |
| <a class="indexterm" name="d0e20124"></a> |
| <code class="literal">TableForUpdateClause</code>: The clause to append to the end of |
| each table alias in queries that obtain pessimistic locks. |
| Defaults to <code class="literal">null</code>. |
| </p></li><li><p><a name="DBDictionary.TableTypes"></a> |
| <a class="indexterm" name="d0e20139"></a> |
| <code class="literal">TableTypes</code>: Comma-separated list of table types to use when |
| looking for tables during schema reflection, as defined in the <code class="methodname"> |
| java.sql.DatabaseMetaData.getTableInfo</code> JDBC method. An example is: |
| <code class="literal">"TABLE,VIEW,ALIAS"</code>. Defaults to <code class="literal">"TABLE"</code>. |
| </p></li><li><p><a name="DBDictionary.TimeTypeName"></a> |
| <a class="indexterm" name="d0e20162"></a> |
| <code class="literal">TimeTypeName</code>: The overridden default column type for |
| <code class="literal">java.sql.Types.TIME</code>. This is used only when the schema is |
| generated by the <code class="literal">mappingtool</code>. |
| </p></li><li><p><a name="DBDictionary.TimestampTypeName"></a> |
| <a class="indexterm" name="d0e20180"></a> |
| <code class="literal">TimestampTypeName</code>: The overridden default column type for |
| <code class="literal">java.sql.Types.TIMESTAMP</code>. This is used only when the schema |
| is generated by the <code class="literal">mappingtool</code>. |
| </p></li><li><p><a name="DBDictionary.TinyintTypeName"></a> |
| <a class="indexterm" name="d0e20198"></a> |
| <code class="literal">TinyintTypeName</code>: The overridden default column type for |
| <code class="literal">java.sql.Types.TINYINT</code>. This is used only when the schema is |
| generated by the <code class="literal">mappingtool</code>. |
| </p></li><li><p><a name="DBDictionary.ToLowerCaseFunction"></a> |
| <a class="indexterm" name="d0e20216"></a> |
| <code class="literal">ToLowerCaseFunction</code>: Name of the SQL function for converting |
| a string to lower case. Use the token <code class="literal">{0}</code> to represent the |
| argument. |
| </p></li><li><p><a name="DBDictionary.ToUpperCaseFunction"></a> |
| <a class="indexterm" name="d0e20231"></a> |
| <code class="literal">ToUpperCaseFunction</code>: SQL function call for for converting a |
| string to upper case. Use the token <code class="literal">{0}</code> to represent the |
| argument. |
| </p></li><li><p><a name="DBDictionary.TrimBothFunction"></a> |
| <a class="indexterm" name="d0e20246"></a> |
| <code class="literal">TrimBothFunction</code>: |
| The SQL function call to trim any number of a particular character |
| from both the start and end of a string. |
| Note: some databases do not support specifying the character in which |
| case only spaces or whitespace can be trimmed. |
| Use the token <code class="literal">{1}</code> when possible to represent the character, |
| and the token <code class="literal">{0}</code> to represent the string. |
| Defaults to <code class="literal">"TRIM(BOTH {1} FROM {0})"</code>. |
| </p></li><li><p><a name="DBDictionary.TrimLeadingFunction"></a> |
| <a class="indexterm" name="d0e20267"></a> |
| <code class="literal">TrimLeadingFunction</code>: |
| The SQL function call to trim any number of a particular character |
| from the start of a string. |
| Note: some databases do not support specifying the character in which |
| case only spaces or whitespace can be trimmed. |
| Use the token <code class="literal">{1}</code> when possible to represent the character, |
| and the token <code class="literal">{0}</code> to represent the string. |
| Defaults to <code class="literal">"TRIM(LEADING {1} FROM {0})"</code>. |
| </p></li><li><p><a name="DBDictionary.TrimTrailingFunction"></a> |
| <a class="indexterm" name="d0e20288"></a> |
| <code class="literal">TrimTrailingFunction</code>: |
| The SQL function call to trim any number of a particular character |
| from the end of a string. |
| Note: some databases do not support specifying the character in which |
| case only spaces or whitespace can be trimmed. |
| Use the token <code class="literal">{1}</code> when possible to represent the character, |
| and the token <code class="literal">{0}</code> to represent the string. |
| Defaults to <code class="literal">"TRIM(TRAILING {1} FROM {0})"</code>. |
| </p></li><li><p><a name="DBDictionary.UseGetBestRowIdentifierForPrimaryKeys"></a> |
| <a class="indexterm" name="d0e20309"></a> |
| <code class="literal">UseGetBestRowIdentifierForPrimaryKeys</code>: When true, |
| metadata queries will use <code class="methodname">DatabaseMetaData.getBestRowIdentifier |
| </code> to obtain information about primary keys, rather than <code class="methodname"> |
| DatabaseMetaData.getPrimaryKeys</code>. |
| </p></li><li><p><a name="DBDictionary.UseGetBytesForBlobs"></a> |
| <a class="indexterm" name="d0e20329"></a> |
| <code class="literal">UseGetBytesForBlobs</code>: When true, <code class="methodname"> |
| ResultSet.getBytes</code> will be used to obtain blob data rather than |
| <code class="methodname">ResultSet.getBinaryStream</code>. |
| </p></li><li><p><a name="DBDictionary.UseGetObjectForBlobs"></a> |
| <a class="indexterm" name="d0e20347"></a> |
| <code class="literal">UseGetObjectForBlobs</code>: When true, <code class="methodname"> |
| ResultSet.getObject</code> will be used to obtain blob data rather than |
| <code class="methodname">ResultSet.getBinaryStream</code>. |
| </p></li><li><p><a name="DBDictionary.UseGetStringForClobs"></a> |
| <a class="indexterm" name="d0e20365"></a> |
| <code class="literal">UseGetStringForClobs</code>: When true, <code class="methodname"> |
| ResultSet.getString</code> will be used to obtain clob data rather than |
| <code class="methodname">ResultSet.getCharacterStream</code>. |
| </p></li><li><p><a name="DBDictionary.UseSchemaName"></a> |
| <a class="indexterm" name="d0e20383"></a> |
| <code class="literal">UseSchemaName</code>: If <code class="literal">false</code>, then avoid |
| including the schema name in table name references. Defaults to <code class="literal">true |
| </code>. |
| </p></li><li><p><a name="DBDictionary.UseSetBytesForBlobs"></a> |
| <a class="indexterm" name="d0e20401"></a> |
| <code class="literal">UseSetBytesForBlobs</code>: When true, <code class="methodname"> |
| PreparedStatement.setBytes</code> will be used to set blob data, rather |
| than <code class="methodname">PreparedStatement.setBinaryStream</code>. |
| </p></li><li><p><a name="DBDictionary.UseSetStringForClobs"></a> |
| <a class="indexterm" name="d0e20419"></a> |
| <code class="literal">UseSetStringForClobs</code>: When true, <code class="methodname"> |
| PreparedStatement.setString</code> will be used to set clob data, rather |
| than <code class="methodname">PreparedStatement.setCharacterStream</code>. |
| </p></li><li><p><a name="DBDictionary.ValidationSQL"></a> |
| <a class="indexterm" name="d0e20437"></a> |
| <a class="indexterm" name="d0e20443"></a> |
| <code class="literal">ValidationSQL</code>: The SQL used to validate that a connection is |
| still in a valid state. For example, <code class="literal">"SELECT SYSDATE FROM DUAL" |
| </code> for Oracle. |
| </p></li><li><p><a name="DBDictionary.VarbinaryTypeName"></a> |
| <a class="indexterm" name="d0e20458"></a> |
| <code class="literal">VarbinaryTypeName</code>: The overridden default column type for |
| <code class="literal">java.sql.Types.VARBINARY</code>. This is used only when the schema |
| is generated by the <code class="literal">mappingtool</code>. |
| </p></li><li><p><a name="DBDictionary.VarcharTypeName"></a> |
| <a class="indexterm" name="d0e20476"></a> |
| <code class="literal">VarcharTypeName</code>: The overridden default column type for |
| <code class="literal">java.sql.Types.VARCHAR</code>. This is used only when the schema is |
| generated by the <code class="literal">mappingtool</code>. |
| </p></li><li><p><a name="DBDictionary.XmlTypeName"></a> |
| <a class="indexterm" name="d0e20494"></a> |
| <code class="literal">XmlTypeName</code>: |
| The column type name for XML columns. This |
| property is set automatically in the dictionary and should not need to be |
| overridden. It is used only when the schema is generated using the |
| <code class="literal">mappingtool</code>. Defaults to <code class="literal">"XML"</code>. |
| </p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_dbsetup_dbsupport_mysql"></a>4.2. |
| MySQLDictionary Properties |
| </h3></div></div></div><a class="indexterm" name="d0e20513"></a><p> |
| The <code class="literal">mysql</code> dictionary also understands the following |
| properties: |
| </p><div class="itemizedlist"><ul type="disc"><li><p><a name="MySQLDictionary.DriverDeserializesBlobs"></a> |
| <a class="indexterm" name="d0e20527"></a> |
| <code class="literal">DriverDeserializesBlobs</code>: Many MySQL drivers automatically |
| deserialize BLOBs on calls to <code class="methodname">ResultSet.getObject</code>. The |
| <code class="classname">MySQLDictionary</code> overrides the standard <code class="methodname"> |
| DBDictionary.getBlobObject</code> method to take this into account. If |
| your driver does not deserialize automatically, set this property to |
| <code class="literal">false</code>. |
| </p></li><li><p><a name="MySQLDictionary.TableType"></a> |
| <a class="indexterm" name="d0e20551"></a> |
| <code class="literal">TableType</code>: The MySQL table type to use when creating tables. |
| Defaults to <code class="literal">"innodb"</code>. |
| </p></li><li><p><a name="MySQLDictionary.UseClobs"></a> |
| <a class="indexterm" name="d0e20566"></a> |
| <code class="literal">UseClobs</code>: Some older versions of MySQL do not handle clobs |
| correctly. To enable clob functionality, set this to <code class="literal">true</code>. |
| Defaults to <code class="literal">false</code>. |
| </p></li><li><p><a name="MySQLDictionary.OptimizeMultiTableDeletes"></a> |
| <a class="indexterm" name="d0e20584"></a> |
| <code class="literal">OptimizeMultiTableDeletes</code>: MySQL as of version 4.0.0 |
| supports multiple tables in <code class="literal">DELETE</code> statements. When |
| this option is set, OpenJPA will use that syntax when doing bulk deletes |
| from multiple tables. This can happen when the |
| <code class="literal">deleteTableContents</code> <code class="literal">SchemaTool</code> |
| action is used. (See <a href="#ref_guide_schema_schematool" title="13. Schema Tool">Section 13, “ |
| Schema Tool |
| ”</a> for |
| more info about <code class="literal">deleteTableContents</code>.) Defaults to |
| <code class="literal">false</code>, since the statement may fail if using InnoDB |
| tables and delete constraints. |
| </p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_dbsetup_dbsupport_oracle"></a>4.3. |
| OracleDictionary Properties |
| </h3></div></div></div><a class="indexterm" name="d0e20613"></a><p> |
| The <code class="literal">oracle</code> dictionary understands the following additional |
| properties: |
| </p><div class="itemizedlist"><ul type="disc"><li><p><a name="OracleDictionary.UseTriggersForAutoAssign"></a> |
| <a class="indexterm" name="d0e20627"></a> |
| <a class="indexterm" name="d0e20633"></a> |
| <code class="literal">UseTriggersForAutoAssign</code>: When true, OpenJPA will allow |
| simulation of auto-increment columns by the use of Oracle triggers. OpenJPA will |
| assume that the current sequence value from the sequence specified in the |
| <code class="literal">AutoAssignSequenceName</code> parameter will hold the value of the |
| new primary key for rows that have been inserted. For more details on |
| auto-increment support, see <a href="#ref_guide_pc_oid_pkgen_autoinc" title="4.4. Autoassign / Identity Strategy Caveats">Section 4.4, “ |
| Autoassign / Identity Strategy Caveats |
| ”</a> |
| . |
| </p></li><li><p><a name="OracleDictionary.AutoAssignSequenceName"></a> |
| <a class="indexterm" name="d0e20652"></a> |
| <a class="indexterm" name="d0e20658"></a> |
| <code class="literal">AutoAssignSequenceName</code>: The global name of the sequence that |
| OpenJPA will assume to hold the value of primary key value for rows that use |
| auto-increment. If left unset, OpenJPA will use a the sequence named <code class="literal"> |
| "SEQ_<table name>"</code>. |
| </p></li><li><p><a name="OracleDictionary.MaxEmbeddedBlobSize"></a> |
| <a class="indexterm" name="d0e20675"></a> |
| <a class="indexterm" name="d0e20681"></a> |
| <code class="literal">MaxEmbeddedBlobSize</code>: Oracle is unable to persist BLOBs using |
| the embedded update method when BLOBs get over a certain size. The size depends |
| on database configuration, e.g. encoding. This property defines the maximum size |
| BLOB to persist with the embedded method. Defaults to 4000 bytes. |
| </p></li><li><p><a name="OracleDictionary.MaxEmbeddedClobSize"></a> |
| <a class="indexterm" name="d0e20693"></a> |
| <a class="indexterm" name="d0e20699"></a> |
| <code class="literal">MaxEmbeddedClobSize</code>: Oracle is unable to persist CLOBs using |
| the embedded update method when Clobs get over a certain size. The size depends |
| on database configuration, e.g. encoding. This property defines the maximum size |
| CLOB to persist with the embedded method. Defaults to 4000 characters. |
| </p></li><li><p><a name="OracleDictionary.UseSetFormOfUseForUnicode"></a> |
| <code class="literal">UseSetFormOfUseForUnicode</code>: Prior to Oracle 10i, statements |
| executed against unicode capable columns (the <code class="literal">NCHAR</code>, |
| <code class="literal">NVARCHAR</code>, <code class="literal">NCLOB</code> Oracle types) required |
| special handling to be able to store unicode values. Setting this property to |
| <code class="literal">true</code> (the default) will cause OpenJPA to attempt to detect when the column of |
| one of these types, and if so, will attempt to correctly configure the statement |
| using the <code class="methodname"> OraclePreparedStatement.setFormOfUse</code>. For |
| more details, see the Oracle |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="http://www.oracle.com/technology/sample_code/tech/java/codesnippet/jdbc/nchar/readme.html" target="_top"> |
| Readme For NChar</a>. Note that this can only work if OpenJPA is able to |
| access the underlying <code class="classname">OraclePreparedStatement</code> instance, |
| which may not be possible when using some third-party datasources. If OpenJPA |
| detects that this is the case, a warning will be logged. |
| </p></li></ul></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_dbsetup_isolation"></a>5. |
| Setting the Transaction Isolation |
| </h2></div></div></div><a class="indexterm" name="d0e20738"></a><a class="indexterm" name="d0e20743"></a><a class="indexterm" name="d0e20748"></a><p> |
| OpenJPA typically retains the default transaction isolation level of the JDBC |
| driver. However, you can specify a transaction isolation level to use through |
| the <a href="#openjpa.jdbc.TransactionIsolation" title="6.18. openjpa.jdbc.TransactionIsolation"><code class="literal"> |
| openjpa.jdbc.TransactionIsolation</code></a> configuration property. The |
| following is a list of standard isolation levels. Note that not all databases |
| support all isolation levels. |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">default</code>: Use the JDBC driver's default isolation level. |
| OpenJPA uses this option if you do not explicitly specify any other. |
| </p></li><li><p> |
| <code class="literal">none</code>: No transaction isolation. |
| </p></li><li><p> |
| <code class="literal">read-committed</code>: Dirty reads are prevented; non-repeatable |
| reads and phantom reads can occur. |
| </p></li><li><p> |
| <code class="literal">read-uncommitted</code>: Dirty reads, non-repeatable reads and |
| phantom reads can occur. |
| </p></li><li><p> |
| <code class="literal">repeatable-read</code>: Dirty reads and non-repeatable reads are |
| prevented; phantom reads can occur. |
| </p></li><li><p> |
| <code class="literal">serializable</code>: Dirty reads, non-repeatable reads, and phantom |
| reads are prevented. |
| </p></li></ul></div><div class="example"><a name="ref_guide_dbsetup_isoex"></a><p class="title"><b>Example 4.7. |
| Specifying a Transaction Isolation |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| <property name="openjpa.jdbc.TransactionIsolation" value="repeatable-read"/> |
| </pre></div></div><br class="example-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_dbsetup_sql92"></a>6. |
| Setting the SQL Join Syntax |
| </h2></div></div></div><a class="indexterm" name="d0e20803"></a><a class="indexterm" name="d0e20808"></a><p> |
| Object queries often involve using SQL joins behind the scenes. You can |
| configure OpenJPA to use either SQL 92-style join syntax, in which joins are |
| placed in the SQL FROM clause, the traditional join syntax, in which join |
| criteria are part of the WHERE clause, or a database-specific join syntax |
| mandated by the <a href="#ref_guide_dbsetup_dbdict" title="Example 4.6. Specifying a DBDictionary"><code class="classname"> |
| DBDictionary</code></a>. OpenJPA only supports outer joins when using |
| SQL 92 syntax or a database-specific syntax with outer join support. |
| </p><p> |
| The <a href="#openjpa.jdbc.DBDictionary" title="6.2. openjpa.jdbc.DBDictionary"><code class="literal"> |
| openjpa.jdbc.DBDictionary</code></a> plugin accepts the <code class="literal"> |
| JoinSyntax</code> property to set the system's default syntax. The available |
| values are: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">traditional</code>: Traditional SQL join syntax; outer joins are |
| not supported. |
| </p></li><li><p> |
| <code class="literal">database</code>: The database's native join syntax. Databases that |
| do not have a native syntax will default to one of the other options. |
| </p></li><li><p> |
| <code class="literal">sql92</code>: ANSI SQL92 join syntax. Outer joins are supported. |
| Not all databases support this syntax. |
| </p></li></ul></div><p> |
| You can change the join syntax at runtime through the OpenJPA fetch |
| configuration API, which is described in <a href="#ref_guide_runtime" title="Chapter 9. Runtime Extensions">Chapter 9, <i xmlns:xlink="http://www.w3.org/1999/xlink"> |
| Runtime Extensions |
| </i></a>. |
| </p><div class="example"><a name="ref_guide_dbsetup_sql92_conf"></a><p class="title"><b>Example 4.8. |
| Specifying the Join Syntax Default |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| <property name="openjpa.jdbc.DBDictionary" value="JoinSyntax=sql92"/> |
| </pre></div></div><br class="example-break"><div class="example"><a name="ref_guide_dbsetup_sql92_fetch"></a><p class="title"><b>Example 4.9. |
| Specifying the Join Syntax at Runtime |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| import org.apache.openjpa.persistence.jdbc.*; |
| |
| ... |
| |
| Query q = em.createQuery("select m from Magazine m where m.title = 'JDJ'"); |
| OpenJPAQuery kq = OpenJPAPersistence.cast(q); |
| JDBCFetchPlan fetch = (JDBCFetchPlan) kq.getFetchPlan (); |
| fetch.setJoinSyntax(JoinSyntax.SQL92); |
| List results = q.getResultList(); |
| </pre></div></div><br class="example-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_dbsetup_multidb"></a>7. |
| Accessing Multiple Databases |
| </h2></div></div></div><a class="indexterm" name="d0e20864"></a><p> |
| Through the properties we've covered thus far, you can configure each |
| <code class="classname">EntityManagerFactory</code> to access a different |
| database. If your application accesses multiple databases, we recommend that you |
| maintain a separate persistence unit for each one. This will allow you to easily |
| load the appropriate resource for each database at runtime, and to give the |
| correct configuration file to OpenJPA's command-line tools during development. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_dbsetup_retain"></a>8. |
| Configuring the Use of JDBC Connections |
| </h2></div></div></div><a class="indexterm" name="d0e20877"></a><p> |
| In its default configuration, OpenJPA obtains JDBC connections on an as-needed |
| basis. OpenJPA <code class="classname">EntityManager</code>s do not retain a connection |
| to the database unless they are in a datastore transaction or there are open |
| <code class="classname">Query</code> results that are using a live JDBC result set. At |
| all other times, including during optimistic transactions, <code class="classname"> |
| EntityManager</code>s request a connection for each query, then |
| immediately release the connection back to the pool. |
| </p><p> |
| <a class="indexterm" name="d0e20895"></a> |
| In some cases, it may be more efficient to retain connections for longer periods |
| of time. You can configure OpenJPA's use of JDBC connections through the |
| <a href="#openjpa.ConnectionRetainMode" title="5.24. openjpa.ConnectionRetainMode"><code class="literal"> |
| openjpa.ConnectionRetainMode</code></a> configuration property. The |
| property accepts the following values: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">always</code>: Each <code class="classname">EntityManager</code> obtains a |
| single connection and uses it until the <code class="classname">EntityManager</code> |
| closes. Great care should be taken when using this property if the application |
| cannot close the EntityManager (ie container-managed EntityManagers in a JEE |
| Application Server). In this case the connection will remain open for an |
| undefined time and the application may not be able to recover from a terminated |
| connection(ie if a TCP/IP timeout severs the connection to the database). |
| For this reason the <code class="literal">always</code> option should not be used with |
| container managed EntityManagers. |
| </p></li><li><p> |
| <code class="literal">transaction</code>: A connection is obtained when each transaction |
| begins (optimistic or datastore), and is released when the transaction |
| completes. Non-transactional connections are obtained on-demand. |
| </p></li><li><p> |
| <code class="literal">on-demand</code>: Connections are obtained only when needed. This |
| option is equivalent to the <code class="literal">transaction</code> option when datastore |
| transactions are used. For optimistic transactions, though, it means that a |
| connection will be retained only for the duration of the datastore flush and |
| commit process. |
| </p></li></ul></div><p> |
| You can also specify the connection retain mode of individual <code class="classname"> |
| EntityManager</code>s when you retrieve them from the <code class="classname"> |
| EntityManagerFactory</code>. See |
| <a href="#ref_guide_runtime_emfactory" title="2.1. OpenJPAEntityManagerFactory">Section 2.1, “ |
| OpenJPAEntityManagerFactory |
| ”</a> for details. |
| </p><p> |
| <a class="indexterm" name="d0e20946"></a> |
| The <a href="#openjpa.FlushBeforeQueries" title="5.32. openjpa.FlushBeforeQueries"><code class="literal"> |
| openjpa.FlushBeforeQueries</code></a> configuration property controls |
| another aspect of connection usage: whether to flush transactional changes |
| before executing object queries. This setting only applies to queries that would |
| otherwise have to be executed in-memory because the |
| <a href="#openjpa.IgnoreChanges" title="5.33. openjpa.IgnoreChanges"><code class="literal">IgnoreChanges</code></a> |
| property is set to false and the query may involve objects that have been |
| changed in the current transaction. Legal values are: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">true</code>: Always flush rather than executing the query |
| in-memory. If the current transaction is optimistic, OpenJPA will begin a |
| non-locking datastore transaction. This is the default. |
| </p></li><li><p> |
| <code class="literal">false</code>: Never flush before a query. |
| </p></li><li><p> |
| <code class="literal">with-connection</code>: Flush only if the <code class="classname">EntityManager |
| </code> has already established a dedicated connection to the datastore, |
| otherwise execute the query in-memory. |
| This option is useful if you use long-running optimistic transactions and want |
| to ensure that these transactions do not consume database resources until |
| commit. OpenJPA's behavior with this option is dependent on the transaction |
| status and mode, as well as the configured connection retain mode described |
| earlier in this section. |
| </p></li></ul></div><p> |
| The flush mode can also be varied at runtime using the OpenJPA fetch |
| configuration API, discussed in <a href="#ref_guide_runtime" title="Chapter 9. Runtime Extensions">Chapter 9, <i xmlns:xlink="http://www.w3.org/1999/xlink"> |
| Runtime Extensions |
| </i></a>. |
| </p><p> |
| <a class="indexterm" name="d0e20986"></a> |
| The table below describes the behavior of automatic flushing in various |
| situations. In all cases, flushing will only occur if OpenJPA detects that you |
| have made modifications in the current transaction that may affect the query's |
| results. |
| </p><div class="table"><a name="d0e20992"></a><p class="title"><b>Table 4.1. |
| OpenJPA Automatic Flush Behavior |
| </b></p><div class="table-contents"><table summary="
 OpenJPA Automatic Flush Behavior
 " border="1"><colgroup><col align="left"><col align="left"><col align="left"><col align="left"><col align="left"></colgroup><thead><tr><th align="left"> |
| </th><th align="left"> |
| FlushBeforeQueries = false |
| </th><th align="left"> |
| FlushBeforeQueries = true |
| </th><th align="left"> |
| FlushBeforeQueries = with-connection; |
| ConnectionRetainMode = on-demand |
| </th><th align="left"> |
| FlushBeforeQueries = with-connection; |
| ConnectionRetainMode = transaction or always |
| </th></tr></thead><tbody><tr><td align="left"> |
| <span class="bold"><strong> |
| IgnoreChanges = true |
| </strong></span> |
| </td><td align="left"> |
| no flush |
| </td><td align="left"> |
| no flush |
| </td><td align="left"> |
| no flush |
| </td><td align="left"> |
| no flush |
| </td></tr><tr><td align="left"> |
| <span class="bold"><strong> |
| IgnoreChanges = false; no tx active |
| </strong></span> |
| </td><td align="left"> |
| no flush |
| </td><td align="left"> |
| no flush |
| </td><td align="left"> |
| no flush |
| </td><td align="left"> |
| no flush |
| </td></tr><tr><td align="left"> |
| <span class="bold"><strong> |
| IgnoreChanges = false; datastore tx active |
| </strong></span> |
| </td><td align="left"> |
| no flush |
| </td><td align="left"> |
| flush |
| </td><td align="left"> |
| flush |
| </td><td align="left"> |
| flush |
| </td></tr><tr><td align="left"> |
| <span class="bold"><strong> |
| IgnoreChanges = false; optimistic tx active |
| </strong></span> |
| </td><td align="left"> |
| no flush |
| </td><td align="left"> |
| flush |
| </td><td align="left"> |
| no flush unless <code class="methodname">flush</code> has already been invoked |
| </td><td align="left"> |
| flush |
| </td></tr></tbody></table></div></div><br class="table-break"><div class="example"><a name="ref_guide_dbsetup_sql92_retain_conf"></a><p class="title"><b>Example 4.10. |
| Specifying Connection Usage Defaults |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| <property name="openjpa.ConnectionRetainMode" value="on-demand"/> |
| <property name="openjpa.FlushBeforeQueries" value="true"/> |
| </pre></div></div><br class="example-break"><div class="example"><a name="ref_guide_dbsetup_sql92_retain_runtime"></a><p class="title"><b>Example 4.11. |
| Specifying Connection Usage at Runtime |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| import org.apache.openjpa.persistence.*; |
| |
| // obtaining an em with a certain connection retain mode |
| Map props = new HashMap(); |
| props.put("openjpa.ConnectionRetainMode", "always"); |
| EntityManager em = emf.createEntityManager(props); |
| </pre></div></div><br class="example-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_dbsetup_stmtbatch"></a>9. |
| Statement Batching |
| </h2></div></div></div><a class="indexterm" name="d0e21086"></a><a class="indexterm" name="d0e21089"></a><p> |
| In addition to connection pooling and prepared statement caching, OpenJPA |
| employs statement batching to speed up JDBC updates. Statement batching is |
| enabled by default for any JDBC driver that supports it. When batching is on, |
| OpenJPA automatically orders its SQL statements to maximize the size of each |
| batch. This can result in large performance gains for transactions that modify |
| a lot of data. |
| </p><p> |
| You configure statement batching through the system DBDictionary, which is |
| controlled by the openjpa.jdbc.DBDictionary configuration property. You can |
| enable the statement batching by setting the batchLimit in the value. The batch |
| limit is the maximum number of statements OpenJPA will ever batch |
| together. A value has the following meaning: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">-1</code>: Unlimited number of statements for a batch. |
| </p></li><li><p> |
| <code class="literal">0</code>: Disable batch support. This is the default for most |
| dictionaries. |
| </p></li><li><p> |
| <code class="literal">any positive number</code>: Maximum number of statements for a batch. |
| </p></li></ul></div><p> |
| </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| By default, the batch support is based on each Dictionary to define the default |
| batch limit. Currently only DB2 and Oracle dictionaries are set the default |
| batch limit to 100. The default batch limit for the rest of the dictionaries is set |
| to zero (disabled). |
| </p></div><p> |
| </p><p> |
| The example below shows how to enable and disable statement batching via |
| your configuration properties. |
| </p><div class="example"><a name="ref_guide_dbsetup_stmtbatch_exmple1"></a><p class="title"><b>Example 4.12. |
| Enable SQL statement batching |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| <property name="openjpa.jdbc.DBDictionary" value="db2(batchLimit=25)"/> |
| <property name="openjpa.jdbc.DBDictionary" value="oracle(batchLimit=-1)"/> |
| Or |
| <property name="openjpa.jdbc.DBDictionary" value="batchLimit=25"/> |
| <property name="openjpa.jdbc.DBDictionary" value="batchLimit=-1"/> |
| </pre></div></div><br class="example-break"><div class="example"><a name="ref_guide_dbsetup_stmtbatch_exmple2"></a><p class="title"><b>Example 4.13. |
| Disable SQL statement batching |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| <property name="openjpa.jdbc.DBDictionary" value="db2(batchLimit=0)"/> |
| Or |
| <property name="openjpa.jdbc.DBDictionary" value="batchLimit=0"/> |
| </pre></div></div><br class="example-break"><font color="red"><par> |
| By default, org.apache.openjpa.jdbc.kernel.BatchingConstraintUpdateManager |
| is the default statement batching implementation. OPENJPA also |
| provides another update manager |
| org.apache.openjpa.jdbc.kernel.BatchingOperationOrderUpdateManager for the |
| statements that required ordering. You can plug-in this update manager through |
| the "openjpa.jdbc.UpdateManager" property. Or you can plug-in your own |
| statement batching implementation by providing the implementation that extends |
| from AbstractUpdateManager, ConstraitUpdateManager or OperationOrderUpdateManager. |
| Add this implementation |
| class as a property in the persistence.xml file. For example, a custom |
| statement batching implementation mycomp.MyUpdateManager extends |
| ConstraitUpdateManager. You specify this implementation in the persistence.xml |
| file as the following example: |
| </par></font><div class="example"><a name="ref_guide_dbsetup_stmtbatch_exmple3"></a><p class="title"><b>Example 4.14. |
| Plug-in custom statement batching implementation |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| <property name="openjpa.jdbc.UpdateManager" value="mycomp.MyUpdateManager"/> |
| </pre></div></div><br class="example-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_dbsetup_lrs"></a>10. |
| Large Result Sets |
| </h2></div></div></div><a class="indexterm" name="d0e21146"></a><a class="indexterm" name="d0e21149"></a><p> |
| By default, OpenJPA uses standard forward-only JDBC result sets, and completely |
| instantiates the results of database queries on execution. When using a JDBC |
| driver that supports version 2.0 or higher of the JDBC specification, however, |
| you can configure OpenJPA to use scrolling result sets that may not bring all |
| results into memory at once. You can also configure the number of result objects |
| OpenJPA keeps references to, allowing you to traverse potentially enormous |
| amounts of data without exhausting JVM memory. |
| </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| You can also configure on-demand loading for individual collection and map |
| fields via large result set proxies. See |
| <a href="#ref_guide_pc_scos_proxy_lrs" title="6.4.2. Large Result Set Proxies">Section 6.4.2, “ |
| Large Result Set Proxies |
| ”</a>. |
| </p></div><p> |
| Use the following properties to configure OpenJPA's handling of result sets: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <a class="indexterm" name="d0e21169"></a> |
| <a href="#openjpa.FetchBatchSize" title="5.30. openjpa.FetchBatchSize"><code class="literal">openjpa.FetchBatchSize</code> |
| </a>: The number of objects to instantiate at once when traversing a result |
| set. This number will be set as the fetch size on JDBC <code class="classname">Statement |
| </code> objects used to obtain result sets. It also factors in to the |
| number of objects OpenJPA will maintain a hard reference to when traversing a |
| query result. |
| </p><p> |
| The fetch size defaults to -1, meaning all results will be instantiated |
| immediately on query execution. A value of 0 means to use the JDBC driver's |
| default batch size. Thus to enable large result set handling, you must set this |
| property to 0 or to a positive number. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e21186"></a> |
| <a href="#openjpa.jdbc.ResultSetType" title="6.11. openjpa.jdbc.ResultSetType"><code class="literal"> openjpa.jdbc.ResultSetType |
| </code></a>: The type of result set to use when executing database |
| queries. This property accepts the following values, each of which corresponds |
| exactly to the same-named <code class="classname">java.sql.ResultSet</code> constant: |
| </p><div class="itemizedlist"><ul type="circle"><li><p> |
| <code class="literal">forward-only</code>: This is the default. |
| </p></li><li><p> |
| <code class="literal">scroll-sensitive</code> |
| </p></li><li><p> |
| <code class="literal">scroll-insensitive</code> |
| </p></li></ul></div><p> |
| Different JDBC drivers treat the different result set types differently. Not all |
| drivers support all types. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e21221"></a> |
| <a href="#openjpa.jdbc.FetchDirection" title="6.5. openjpa.jdbc.FetchDirection"><code class="literal"> |
| openjpa.jdbc.FetchDirection</code></a>: The expected order in which you |
| will access the query results. This property affects the type of datastructure |
| OpenJPA will use to hold the results, and is also given to the JDBC driver in |
| case it can optimize for certain access patterns. This property accepts the |
| following values, each of which corresponds exactly to the same-named |
| <code class="classname">java.sql.ResultSet</code> FETCH constant: |
| </p><div class="itemizedlist"><ul type="circle"><li><p> |
| <code class="literal">forward</code>: This is the default. |
| </p></li><li><p> |
| <code class="literal">reverse</code> |
| </p></li><li><p> |
| <code class="literal">unknown</code> |
| </p></li></ul></div><p> |
| Not all drivers support all fetch directions. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e21256"></a> |
| <a href="#openjpa.jdbc.LRSSize" title="6.7. openjpa.jdbc.LRSSize"><code class="literal"> openjpa.jdbc.LRSSize</code> |
| </a>: The strategy OpenJPA will use to determine the size of result sets. |
| This property is <span class="bold"><strong>only</strong></span> used if you change the |
| fetch batch size from its default of -1, so that OpenJPA begins to use on-demand |
| result loading. Available values are: |
| </p><div class="itemizedlist"><ul type="circle"><li><p> |
| <code class="literal">query</code>: This is the default. The first time you ask for the |
| size of a query result, OpenJPA will perform a <code class="literal">SELECT COUNT(*) |
| </code> query to determine the number of expected results. Note that |
| depending on transaction status and settings, this can mean that the reported |
| size is slightly different than the actual number of results available. |
| </p></li><li><p> |
| <code class="literal">last</code>: If you have chosen a scrollable result set type, this |
| setting will use the <code class="methodname">ResultSet.last</code> method to move to |
| the last element in the result set and get its index. Unfortunately, some JDBC |
| drivers will bring all results into memory in order to access the last one. Note |
| that if you do not choose a scrollable result set type, then this will behave |
| exactly like <code class="literal">unknown</code>. The default result set type is |
| <code class="literal">forward-only</code>, so you must change the result set type in |
| order for this property to have an effect. |
| </p></li><li><p> |
| <code class="literal">unknown</code>: Under this setting OpenJPA will return <code class="literal"> |
| Integer.MAX_VALUE</code> as the size for any query result that uses on-demand |
| loading. |
| </p></li></ul></div></li></ul></div><div class="example"><a name="ref_guide_dbsetup_lrs_def"></a><p class="title"><b>Example 4.15. |
| Specifying Result Set Defaults |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| <property name="openjpa.FetchBatchSize" value="20"/> |
| <property name="openjpa.jdbc.ResultSetType" value="scroll-insensitive"/> |
| <property name="openjpa.jdbc.FetchDirection" value="forward"/> |
| <property name="openjpa.jdbc.LRSSize" value="last"/> |
| </pre></div></div><br class="example-break"><p> |
| Many <a href="#ref_guide_runtime" title="Chapter 9. Runtime Extensions">OpenJPA runtime components</a> also |
| have methods to configure these properties on a case-by-case basis through their |
| fetch configuration. See <a href="#ref_guide_runtime" title="Chapter 9. Runtime Extensions">Chapter 9, <i xmlns:xlink="http://www.w3.org/1999/xlink"> |
| Runtime Extensions |
| </i></a>. |
| </p><div class="example"><a name="ref_guide_dbsetup_lrs_runtime"></a><p class="title"><b>Example 4.16. |
| Specifying Result Set Behavior at Runtime |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| import java.sql.*; |
| import org.apache.openjpa.persistence.jdbc.*; |
| |
| ... |
| |
| Query q = em.createQuery("select m from Magazine m where m.title = 'JDJ'"); |
| OpenJPAQuery kq = OpenJPAPersistence.cast(q); |
| JDBCFetchPlan fetch = (JDBCFetchPlan) kq.getFetchPlan(); |
| fetch.setFetchBatchSize(20); |
| fetch.setResultSetType(ResultSetType.SCROLL_INSENSITIVE); |
| fetch.setFetchDirection(FetchDirection.FORWARD); |
| fetch.setLRSSizeAlgorithm(LRSSizeAlgorithm.LAST); |
| List results = q.getResultList(); |
| </pre></div></div><br class="example-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_schema_def"></a>11. |
| Default Schema |
| </h2></div></div></div><a class="indexterm" name="d0e21322"></a><p> |
| It is common to duplicate a database model in multiple schemas. You may have one |
| schema for development and another for production, or different database users |
| may access different schemas. OpenJPA facilitates these patterns with the |
| <a href="#openjpa.jdbc.Schema" title="6.12. openjpa.jdbc.Schema"><code class="literal">openjpa.jdbc.Schema</code> |
| </a> configuration property. This property establishes a default schema for |
| any unqualified table names, allowing you to leave schema names out of your |
| mapping definitions. |
| </p><p> |
| The <code class="literal">Schema</code> property also establishes the default schema for |
| new tables created through OpenJPA tools, such as the mapping tool covered in |
| <a href="#ref_guide_mapping_mappingtool" title="1. Forward Mapping">Section 1, “ |
| Forward Mapping |
| ”</a>. |
| </p><p> |
| If the entities are mapped to the same table name but with different schema |
| name within one <code class="literal">PersistenceUnit</code> intentionally, and the |
| strategy of <code class="literal">GeneratedType.AUTO</code> is used to generate the ID |
| for each entity, a schema name for each entity must be explicitly declared |
| either through the annotation or the mapping.xml file. Otherwise, the mapping |
| tool only creates the tables for those entities with the schema names under |
| each schema. In addition, there will be only one |
| <code class="literal">OPENJPA_SEQUENCE_TABLE</code> created for all the entities within |
| the <code class="literal">PersistenceUnit</code> if the entities are not identified |
| with the schema name. |
| Read <a href="#ref_guide_sequence" title="6. Generators">Section 6, “ |
| Generators |
| ”</a> in the Reference Guide. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_schema_info"></a>12. |
| Schema Reflection |
| </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#ref_guide_schema_info_list">12.1. |
| Schemas List |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_schema_info_factory">12.2. |
| Schema Factory |
| </a></span></dt></dl></div><a class="indexterm" name="d0e21360"></a><p> |
| OpenJPA needs information about your database schema for two reasons. First, it |
| can use schema information at runtime to validate that your schema is compatible |
| with your persistent class definitions. Second, OpenJPA requires schema |
| information during development so that it can manipulate the schema to match |
| your object model. OpenJPA uses the <code class="literal">SchemaFactory</code> interface |
| to provide runtime mapping information, and the <code class="classname">SchemaTool |
| </code> for development-time data. Each is presented below. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_schema_info_list"></a>12.1. |
| Schemas List |
| </h3></div></div></div><a class="indexterm" name="d0e21376"></a><a class="indexterm" name="d0e21379"></a><p> |
| By default, schema reflection acts on all the schemas your JDBC driver can |
| "see". You can limit the schemas and tables OpenJPA acts on with the <code class="literal"> |
| openjpa.jdbc.Schemas</code> configuration property. This property accepts a |
| comma-separated list of schemas and tables. To list a schema, list its name. To |
| list a table, list its full name in the form <code class="literal"> |
| <schema-name>.<table-name></code>. If a table does not have a |
| schema or you do not know its schema, list its name as <code class="literal"> |
| .<table-name></code> (notice the preceding '.'). For example, to list |
| the <code class="literal">BUSOBJS</code> schema, the <code class="literal">ADDRESS</code> table in |
| the <code class="literal">GENERAL</code> schema, and the <code class="literal">SYSTEM_INFO</code> |
| table, regardless of what schema it is in, use the string: |
| </p><pre class="programlisting"> |
| BUSOBJS,GENERAL.ADDRESS,.SYSTEM_INFO |
| </pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| Some databases are case-sensitive with respect to schema and table names. |
| Oracle, for example, requires names in all upper case. |
| </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_schema_info_factory"></a>12.2. |
| Schema Factory |
| </h3></div></div></div><a class="indexterm" name="d0e21415"></a><p> |
| OpenJPA relies on the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/schema/SchemaFactory.html" target="_top"> |
| <code class="classname">openjpa.jdbc.SchemaFactory</code></a> interface for runtime |
| schema information. You can control the schema factory OpenJPA uses through the |
| <code class="literal">openjpa.jdbc.SchemaFactory</code> property. There are several |
| built-in options to choose from: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">dynamic</code>: This is the default setting. It is an alias for the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/schema/DynamicSchemaFactory.html" target="_top"> |
| <code class="classname"> |
| org.apache.openjpa.jdbc.schema.DynamicSchemaFactory</code></a>. The |
| <code class="classname">DynamicSchemaFactory</code> is the most performant |
| schema factory, because it does not validate mapping information against the |
| database. Instead, it assumes all object-relational mapping information is |
| correct, and dynamically builds an in-memory representation of the schema from |
| your mapping metadata. When using this factory, it is important that your |
| mapping metadata correctly represent your database's foreign key constraints so |
| that OpenJPA can order its SQL statements to meet them. |
| </p></li><li><p> |
| <code class="literal">native</code>: This is an alias for the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/schema/LazySchemaFactory.html" target="_top"> |
| <code class="classname">org.apache.openjpa.jdbc.schema.LazySchemaFactory</code></a> |
| . As persistent classes are loaded by the application, OpenJPA reads their |
| metadata and object-relational mapping information. This factory uses the |
| <code class="classname">java.sql.DatabaseMetaData</code> interface to reflect on the |
| schema and ensure that it is consistent with the mapping data being read. |
| Use this factory if you want up-front validation that your mapping metadata is |
| consistent with the database during development. This factory accepts the |
| following important properties: |
| </p><div class="itemizedlist"><ul type="circle"><li><p> |
| <code class="literal">ForeignKeys</code>: Set to <code class="literal">true</code> to automatically |
| read foreign key information during schema validation. |
| </p></li></ul></div></li><li><p> |
| <code class="literal">table</code>: This is an alias for the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/schema/TableSchemaFactory.html" target="_top"> |
| <code class="classname">org.apache.openjpa.jdbc.schema.TableSchemaFactory</code></a> |
| . This schema factory stores schema information as an XML document in a database |
| table it creates for this purpose. If your JDBC driver doesn't support the |
| <code class="classname">java.sql.DatabaseMetaData</code> standard interface, but you |
| still want some schema validation to occur at runtime, you might use this |
| factory. It is not recommended for most users, though, because it is easy for |
| the stored XML schema definition to get out-of-synch with the actual database. |
| This factory accepts the following properties: |
| </p><div class="itemizedlist"><ul type="circle"><li><p> |
| <code class="literal">Table</code>: The name of the table to create to store schema |
| information. Defaults to <code class="literal">OPENJPA_SCHEMA</code>. |
| </p></li><li><p> |
| <code class="literal">PrimaryKeyColumn</code>: The name of the table's numeric primary |
| key column. Defaults to <code class="literal">ID</code>. |
| </p></li><li><p> |
| <code class="literal">SchemaColumn</code>: The name of the table's string column for |
| holding the schema definition as an XML string. Defaults to <code class="literal">SCHEMA_DEF |
| </code>. |
| </p></li></ul></div></li><li><p> |
| <code class="literal">file</code>: This is an alias for the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/schema/FileSchemaFactory.html" target="_top"> |
| <code class="classname">org.apache.openjpa.jdbc.schema.FileSchemaFactory</code></a> |
| . This factory is a lot like the <code class="classname">TableSchemaFactory</code>, and |
| has the same advantages and disadvantages. Instead of storing its XML schema |
| definition in a database table, though, it stores it in a file. This factory |
| accepts the following properties: |
| </p><div class="itemizedlist"><ul type="circle"><li><p> |
| <code class="literal">File</code>: The resource name of the XML schema file. By default, |
| the factory looks for a resource called <code class="filename"> package.schema</code>, |
| located in any top-level directory of the <code class="literal">CLASSPATH</code> or in the |
| top level of any jar in your <code class="literal">CLASSPATH</code>. |
| </p></li></ul></div></li></ul></div><p> |
| You can switch freely between schema factories at any time. The XML file format |
| used by some factories is detailed in <a href="#ref_guide_schema_xml" title="14. XML Schema Format">Section 14, “ |
| XML Schema Format |
| ”</a> |
| . As with any OpenJPA plugin, you can can also implement your own schema |
| factory if you have needs not met by the existing options. |
| </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_schema_schematool"></a>13. |
| Schema Tool |
| </h2></div></div></div><a class="indexterm" name="d0e21548"></a><a class="indexterm" name="d0e21553"></a><a class="indexterm" name="d0e21560"></a><a class="indexterm" name="d0e21567"></a><p> |
| Most users will only access the schema tool indirectly, through the interfaces |
| provided by other tools. You may find, however, that the schema tool is a |
| powerful utility in its own right. The schema tool has two functions: |
| </p><div class="orderedlist"><ol type="1"><li><p> |
| To reflect on the current database schema, optionally translating it to an XML |
| representation for further manipulation. |
| </p></li><li><p> |
| To take in an XML schema definition, calculate the differences between the XML |
| and the existing database schema, and apply the necessary changes to make the |
| database match the XML. |
| </p></li></ol></div><p> |
| The <a href="#ref_guide_schema_xml" title="14. XML Schema Format">XML format</a> used by the schema |
| tool abstracts away the differences between SQL dialects used by different |
| database vendors. The tool also automatically adapts its SQL to meet foreign key |
| dependencies. Thus the schema tool is useful as a general way to manipulate |
| schemas. |
| </p><p> |
| You can invoke the schema tool through its Java class, |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/schema/SchemaTool.html" target="_top"> |
| <code class="classname">org.apache.openjpa.jdbc.schema.SchemaTool</code></a>. In |
| addition to the universal flags of the <a href="#ref_guide_conf" title="Chapter 2. Configuration"> |
| configuration framework</a>, the schema tool accepts the following command |
| line arguments: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">-ignoreErrors/-i <true/t | false/f></code>: If <code class="literal">false |
| </code>, an exception will be thrown if the tool encounters any database |
| errors. Defaults to <code class="literal">false</code>. |
| </p></li><li><p> |
| <code class="literal">-file/-f <stdout | output file></code>: Use this option to |
| write a SQL script for the planned schema modifications, rather them committing |
| them to the database. When used in conjunction with the <code class="literal">export |
| </code> or <code class="literal">reflect</code> actions, the named file will be used to |
| write the exported schema XML. If the file names a resource in the <code class="literal"> |
| CLASSPATH</code>, data will be written to that resource. Use <code class="literal">stdout |
| </code> to write to standard output. Defaults to <code class="literal">stdout</code>. |
| </p></li><li><p> |
| <code class="literal">-openjpaTables/-ot <true/t | false/f></code>: When reflecting |
| on the schema, whether to reflect on tables and sequences whose names start with |
| <code class="literal">OPENJPA_</code>. Certain OpenJPA components may use such tables - |
| for example, the <code class="literal">table</code> schema factory option covered in |
| <a href="#ref_guide_schema_info_factory" title="12.2. Schema Factory">Section 12.2, “ |
| Schema Factory |
| ”</a>. When using other |
| actions, <code class="literal">openjpaTables</code> controls whether these tables can be |
| dropped. Defaults to <code class="literal">false</code>. |
| </p></li><li><p> |
| <code class="literal">-dropTables/-dt <true/t | false/f></code>: Set this option to |
| <code class="literal">true</code> to drop tables that appear to be unused during <code class="literal"> |
| retain</code> and <code class="literal">refresh</code> actions. Defaults to <code class="literal"> |
| true</code>. |
| </p></li><li><p> |
| <code class="literal">-dropSequences/-dsq <true/t | false/f></code>: Set this |
| option to <code class="literal">true</code> to drop sequences that appear to be unused |
| during <code class="literal">retain</code> and <code class="literal">refresh</code> actions. |
| Defaults to <code class="literal">true</code>. |
| </p></li><li><p> |
| <code class="literal">-sequences/-sq <true/t | false/f></code>: Whether to |
| manipulate sequences. Defaults to <code class="literal">true</code>. |
| </p></li><li><p> |
| <code class="literal">-indexes/-ix <true/t | false/f></code>: Whether to manipulate |
| indexes on existing tables. Defaults to <code class="literal">true</code>. |
| </p></li><li><p> |
| <code class="literal">-primaryKeys/-pk <true/t | false/f></code>: Whether to |
| manipulate primary keys on existing tables. Defaults to <code class="literal">true</code>. |
| </p></li><li><p> |
| <code class="literal">-foreignKeys/-fk <true/t | false/f></code>: Whether to |
| manipulate foreign keys on existing tables. Defaults to <code class="literal">true</code>. |
| </p></li><li><p> |
| <code class="literal">-record/-r <true/t | false/f></code>: Use <code class="literal">false |
| </code> to prevent writing the schema changes made by the tool to the current |
| <a href="#ref_guide_schema_info_factory" title="12.2. Schema Factory"><code class="literal">schema |
| factory</code></a>. Defaults to <code class="literal">true</code>. |
| </p></li><li><p> |
| <code class="literal">-schemas/-s <schema list></code>: A list of schema and table |
| names that OpenJPA should access during this run of the schema tool. This is |
| equivalent to setting the <a href="#openjpa.jdbc.Schemas" title="6.14. openjpa.jdbc.Schemas"> |
| openjpa.jdbc.Schemas</a> property for a single run. |
| </p></li></ul></div><p> |
| The schema tool also accepts an <code class="literal">-action</code> or <code class="literal">-a |
| </code> flag. Multiple actions can be composed in a comma-separated list. |
| The available actions are: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">add</code>: This is the default action if you do not specify one. |
| It brings the schema up-to-date with the given XML document by adding tables, |
| columns, indexes, etc. This action never drops any schema components. |
| </p></li><li><p> |
| <code class="literal">retain</code>: Keep all schema components in the given XML |
| definition, but drop the rest from the database. This action never adds any |
| schema components. |
| </p></li><li><p> |
| <code class="literal">drop</code>: Drop all schema components in the schema XML. Tables |
| will only be dropped if they would have 0 columns after dropping all columns |
| listed in the XML. |
| </p></li><li><p> |
| <code class="literal">refresh</code>: Equivalent to <code class="literal">retain</code>, then |
| <code class="literal">add</code>. |
| </p></li><li><p> |
| <code class="literal">build</code>: Generate SQL to build a schema matching the one in |
| the given XML file. Unlike <code class="literal">add</code>, this option does not take |
| into account the fact that part of the schema defined in the XML file might |
| already exist in the database. Therefore, this action is typically used in |
| conjunction with the <code class="literal">-file</code> flag to write a SQL script. This |
| script can later be used to recreate the schema in the XML. |
| </p></li><li><p> |
| <code class="literal">reflect</code>: Generate an XML representation of the current |
| database schema. |
| </p></li><li><p> |
| <code class="literal">createDB</code>: Generate SQL to re-create the current database. |
| This action is typically used in conjunction with the <code class="literal">-file</code> |
| flag to write a SQL script that can be used to recreate the current schema on a |
| fresh database. |
| </p></li><li><p> |
| <code class="literal">dropDB</code>: Generate SQL to drop the current database. Like |
| <code class="literal">createDB</code>, this action can be used with the <code class="literal">-file |
| </code> flag to script a database drop rather than perform it. |
| </p></li><li><p> |
| <code class="literal">import</code>: Import the given XML schema definition into the |
| current schema factory. Does nothing if the factory does not store a record of |
| the schema. |
| </p></li><li><p> |
| <code class="literal">export</code>: Export the current schema factory's stored schema |
| definition to XML. May produce an empty file if the factory does not store a |
| record of the schema. |
| </p></li><li><p> |
| <code class="literal">deleteTableContents</code>: Execute SQL to delete all rows from |
| all tables that OpenJPA knows about. |
| </p></li></ul></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| The schema tool manipulates tables, columns, indexes, constraints, and |
| sequences. It cannot create or drop the database schema objects in which the |
| tables reside, however. If your XML documents refer to named database schemas, |
| those schemas must exist. |
| </p></div><p> |
| We present some examples of schema tool usage below. |
| </p><div class="example"><a name="ref_guide_schema_schematool_create"></a><p class="title"><b>Example 4.17. |
| Schema Creation |
| </b></p><div class="example-contents"><a class="indexterm" name="d0e21851"></a><p> |
| Add the necessary schema components to the database to match the given XML |
| document, but don't drop any data: |
| </p><pre class="programlisting"> |
| java org.apache.openjpa.jdbc.schema.SchemaTool targetSchema.xml |
| </pre></div></div><br class="example-break"><div class="example"><a name="ref_guide_schema_schematool_script"></a><p class="title"><b>Example 4.18. |
| SQL Scripting |
| </b></p><div class="example-contents"><p> |
| Repeat the same action as the first example, but this time don't change the |
| database. Instead, write any planned changes to a SQL script: |
| </p><pre class="programlisting"> |
| java org.apache.openjpa.jdbc.schema.SchemaTool -f script.sql targetSchema.xml |
| </pre><p> |
| Write a SQL script that will re-create the current database: |
| </p><pre class="programlisting"> |
| java org.apache.openjpa.jdbc.schema.SchemaTool -a createDB -f script.sql |
| </pre></div></div><br class="example-break"><div class="example"><a name="ref_guide_schema_schematool_table_cleanup"></a><p class="title"><b>Example 4.19. |
| Table Cleanup |
| </b></p><div class="example-contents"><a class="indexterm" name="d0e21874"></a><a class="indexterm" name="d0e21879"></a><p> |
| Refresh the schema and delete all contents of all tables that OpenJPA |
| knows about: |
| </p><pre class="programlisting"> |
| java org.apache.openjpa.jdbc.schema.SchemaTool -a refresh,deleteTableContents |
| </pre></div></div><br class="example-break"><div class="example"><a name="ref_guide_schema_schematool_drop"></a><p class="title"><b>Example 4.20. |
| Schema Drop |
| </b></p><div class="example-contents"><p> |
| Drop the current database: |
| </p><pre class="programlisting"> |
| java org.apache.openjpa.jdbc.schema.SchemaTool -a dropDB |
| </pre></div></div><br class="example-break"><div class="example"><a name="ref_guide_schema_schematool_reflect"></a><p class="title"><b>Example 4.21. |
| Schema Reflection |
| </b></p><div class="example-contents"><a class="indexterm" name="d0e21898"></a><p> |
| Write an XML representation of the current schema to file <code class="filename">schema.xml |
| </code>. |
| </p><pre class="programlisting"> |
| java org.apache.openjpa.jdbc.schema.SchemaTool -a reflect -f schema.xml |
| </pre></div></div><br class="example-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_schema_xml"></a>14. |
| XML Schema Format |
| </h2></div></div></div><a class="indexterm" name="d0e21915"></a><p> |
| The <a href="#ref_guide_schema_schematool" title="13. Schema Tool">schema tool</a> and |
| <a href="#ref_guide_schema_info_factory" title="12.2. Schema Factory"> schema factories</a> all use |
| the same XML format to represent database schema. The Document Type Definition |
| (DTD) for schema information is presented below, followed by examples of schema |
| definitions in XML. |
| </p><pre class="programlisting"> |
| <!ELEMENT schemas (schema)+> |
| <!ELEMENT schema (table|sequence)+> |
| <!ATTLIST schema name CDATA #IMPLIED> |
| |
| <!ELEMENT sequence EMPTY> |
| <!ATTLIST sequence name CDATA #REQUIRED> |
| <!ATTLIST sequence initial-value CDATA #IMPLIED> |
| <!ATTLIST sequence increment CDATA #IMPLIED> |
| <!ATTLIST sequence allocate CDATA #IMPLIED> |
| |
| <!ELEMENT table (column|index|pk|fk|unique)+> |
| <!ATTLIST table name CDATA #REQUIRED> |
| |
| <!ELEMENT column EMPTY> |
| <!ATTLIST column name CDATA #REQUIRED> |
| <!ATTLIST column type (array | bigint | binary | bit | blob | char | clob |
| | date | decimal | distinct | double | float | integer | java_object |
| | longvarbinary | longvarchar | null | numeric | other | real | ref |
| | smallint | struct | time | timestamp | tinyint | varbinary | varchar) |
| #REQUIRED> |
| <!ATTLIST column not-null (true|false) "false"> |
| <!ATTLIST column auto-assign (true|false) "false"> |
| <!ATTLIST column default CDATA #IMPLIED> |
| <!ATTLIST column size CDATA #IMPLIED> |
| <!ATTLIST column decimal-digits CDATA #IMPLIED> |
| |
| <!-- the type-name attribute can be used when you want OpenJPA to --> |
| <!-- use a particular SQL type declaration when creating the --> |
| <!-- column. It is up to you to ensure that this type is --> |
| <!-- compatible with the JDBC type used in the type attribute. --> |
| <!ATTLIST column type-name CDATA #IMPLIED> |
| |
| <!-- the 'column' attribute of indexes, pks, and fks can be used --> |
| <!-- when the element has only one column (or for foreign keys, --> |
| <!-- only one local column); in these cases the on/join child --> |
| <!-- elements can be omitted --> |
| <!ELEMENT index (on)*> |
| <!ATTLIST index name CDATA #REQUIRED> |
| <!ATTLIST index column CDATA #IMPLIED> |
| <!ATTLIST index unique (true|false) "false"> |
| |
| <!-- the 'logical' attribute of pks should be set to 'true' if --> |
| <!-- the primary key does not actually exist in the database, --> |
| <!-- but the given column should be used as a primary key for --> |
| <!-- O-R purposes --> |
| <!ELEMENT pk (on)*> |
| <!ATTLIST pk name CDATA #IMPLIED> |
| <!ATTLIST pk column CDATA #IMPLIED> |
| <!ATTLIST pk logical (true|false) "false"> |
| |
| <!ELEMENT on EMPTY> |
| <!ATTLIST on column CDATA #REQUIRED> |
| |
| <!-- fks with a delete-action of 'none' are similar to logical --> |
| <!-- pks; they do not actually exist in the database, but --> |
| <!-- represent a logical relation between tables (or their --> |
| <!-- corresponding Java classes) --> |
| <!ELEMENT fk (join)*> |
| <!ATTLIST fk name CDATA #IMPLIED> |
| <!ATTLIST fk deferred (true|false) "false"> |
| <!ATTLIST fk to-table CDATA #REQUIRED> |
| <!ATTLIST fk column CDATA #IMPLIED> |
| <!ATTLIST fk delete-action (cascade|default|exception|none|null) "none"> |
| |
| <!ELEMENT join EMPTY> |
| <!ATTLIST join column CDATA #REQUIRED> |
| <!ATTLIST join to-column CDATA #REQUIRED> |
| <!ATTLIST join value CDATA #IMPLIED> |
| |
| <!-- unique constraint --> |
| <!ELEMENT unique (on)*> |
| <!ATTLIST unique name CDATA #IMPLIED> |
| <!ATTLIST unique column CDATA #IMPLIED> |
| <!ATTLIST unique deferred (true|false) "false"> |
| </pre><div class="example"><a name="ref_guide_schema_xml_basic"></a><p class="title"><b>Example 4.22. |
| Basic Schema |
| </b></p><div class="example-contents"><p> |
| A very basic schema definition. |
| </p><pre class="programlisting"> |
| <schemas> |
| <schema> |
| <sequence name="S_ARTS"/> |
| <table name="ARTICLE"> |
| <column name="TITLE" type="varchar" size="255" not-null="true"/> |
| <column name="AUTHOR_FNAME" type="varchar" size="28"> |
| <column name="AUTHOR_LNAME" type="varchar" size="28"> |
| <column name="CONTENT" type="clob"> |
| </table> |
| <table name="AUTHOR"> |
| <column name="FIRST_NAME" type="varchar" size="28" not-null="true"> |
| <column name="LAST_NAME" type="varchar" size="28" not-null="true"> |
| </table> |
| </schema> |
| </schemas> |
| </pre></div></div><br class="example-break"><div class="example"><a name="ref_guide_schema_xml_full"></a><p class="title"><b>Example 4.23. |
| Full Schema |
| </b></p><div class="example-contents"><p> |
| Expansion of the above schema with primary keys, constraints, and indexes, some |
| of which span multiple columns. |
| </p><pre class="programlisting"> |
| <schemas> |
| <schema> |
| <sequence name="S_ARTS"/> |
| <table name="ARTICLE"> |
| <column name="TITLE" type="varchar" size="255" not-null="true"/> |
| <column name="AUTHOR_FNAME" type="varchar" size="28"> |
| <column name="AUTHOR_LNAME" type="varchar" size="28"> |
| <column name="CONTENT" type="clob"> |
| <pk column="TITLE"/> |
| <fk to-table="AUTHOR" delete-action="exception"> |
| <join column="AUTHOR_FNAME" to-column="FIRST_NAME"/> |
| <join column="AUTHOR_LNAME" to-column="LAST_NAME"/> |
| </fk> |
| <index name="ARTICLE_AUTHOR"> |
| <on column="AUTHOR_FNAME"/> |
| <on column="AUTHOR_LNAME"/> |
| </index> |
| </table> |
| <table name="AUTHOR"> |
| <column name="FIRST_NAME" type="varchar" size="28" not-null="true"> |
| <column name="LAST_NAME" type="varchar" size="28" not-null="true"> |
| <pk> |
| <on column="FIRST_NAME"/> |
| <on column="LAST_NAME"/> |
| </pk> |
| </table> |
| </schema> |
| </schemas> |
| </pre></div></div><br class="example-break"></div></div><div class="chapter" lang="en" id="ref_guide_pc"><div class="titlepage"><div><div><h2 class="title"><a name="ref_guide_pc"></a>Chapter 5. |
| Persistent Classes |
| </h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#ref_guide_pc_pcclasses">1. |
| Persistent Class List |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_pc_enhance">2. |
| Enhancement |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_pc_enhance_build">2.1. |
| Enhancing at Build Time |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_pc_enhance_runtime_container">2.2. |
| Enhancing JPA Entities on Deployment |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_pc_enhance_runtime">2.3. |
| Enhancing at Runtime |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_pc_enhance_unenhanced_types">2.4. |
| Omitting the OpenJPA enhancer |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_pc_interfaces">3. Managed Interfaces</a></span></dt><dt><span class="section"><a href="#ref_guide_pc_oid">4. |
| Object Identity |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_pc_oid_datastore">4.1. |
| Datastore Identity |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_pc_oid_entitypk">4.2. |
| Entities as Identity Fields |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_pc_oid_application">4.3. |
| Application Identity Tool |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_pc_oid_pkgen_autoinc">4.4. |
| Autoassign / Identity Strategy Caveats |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_inverses">5. |
| Managed Inverses |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_pc_scos">6. |
| Persistent Fields |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_pc_scos_restore">6.1. |
| Restoring State |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_pc_scos_order">6.2. |
| Typing and Ordering |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_pc_calendar_timezone">6.3. |
| Calendar Fields and TimeZones |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_pc_scos_proxy">6.4. |
| Proxies |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_pc_scos_proxy_smart">6.4.1. |
| Smart Proxies |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_pc_scos_proxy_lrs">6.4.2. |
| Large Result Set Proxies |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_pc_scos_proxy_custom">6.4.3. |
| Custom Proxies |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_pc_extern">6.5. |
| Externalization |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_pc_extern_values">6.5.1. |
| External Values |
| </a></span></dt></dl></dd></dl></dd><dt><span class="section"><a href="#ref_guide_fetch">7. |
| Fetch Groups |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_fetch_custom">7.1. |
| Custom Fetch Groups |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_fetch_conf">7.2. |
| Custom Fetch Group Configuration |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_fetch_single_field">7.3. |
| Per-field Fetch Configuration |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_fetch_impl">7.4. |
| Implementation Notes |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_perfpack_eager">8. |
| Eager Fetching |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_perfpack_eager_conf">8.1. |
| Configuring Eager Fetching |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_perfpack_eager_consider">8.2. |
| Eager Fetching Considerations and Limitations |
| </a></span></dt></dl></dd></dl></div><a class="indexterm" name="d0e21948"></a><p> |
| Persistent class basics are covered in <a href="#jpa_overview_pc" title="Chapter 4. Entity">Chapter 4, <i xmlns:xlink="http://www.w3.org/1999/xlink"> |
| Entity |
| </i></a> |
| of the JPA Overview. This chapter details the persistent class features OpenJPA |
| offers beyond the core JPA specification. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_pc_pcclasses"></a>1. |
| Persistent Class List |
| </h2></div></div></div><a class="indexterm" name="d0e21958"></a><a class="indexterm" name="d0e21963"></a><p> |
| Unlike many ORM products, OpenJPA does not need to know about all of your |
| persistent classes at startup. OpenJPA discovers new persistent classes |
| automatically as they are loaded into the JVM; in fact you can introduce new |
| persistent classes into running applications under OpenJPA. However, there are |
| certain situations in which providing OpenJPA with a persistent class list is |
| helpful: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| OpenJPA must be able to match entity names in JPQL queries to persistent |
| classes. OpenJPA automatically knows the entity names of any persistent classes |
| already loaded into the JVM. To match entity names to classes that have not been |
| loaded, however, you must supply a persistent class list. |
| </p></li><li><p> |
| When OpenJPA manipulates classes in a persistent inheritance hierarchy, OpenJPA |
| must be aware of all the classes in the hierarchy. If some of the classes have |
| not been loaded into the JVM yet, OpenJPA may not know about them, and queries |
| may return incorrect results. |
| </p></li><li><p> |
| If you configure OpenJPA to create the needed database schema on startup (see |
| <a href="#ref_guide_mapping_synch" title="1.3. Runtime Forward Mapping">Section 1.3, “ |
| Runtime Forward Mapping |
| ”</a>), OpenJPA must know all of your |
| persistent classes up-front. |
| </p></li></ul></div><p> |
| When any of these conditions are a factor in your JPA application, use the |
| <code class="literal">class</code>, <code class="literal">mapping-file</code>, and <code class="literal"> |
| jar-file</code> elements of JPA's standard XML format to list your persistent |
| classes. See <a href="#jpa_overview_persistence_xml" title="1. persistence.xml">Section 1, “ |
| persistence.xml |
| ”</a> for details. |
| </p><p> |
| Alternately, you can tell OpenJPA to search through your classpath for |
| persistent types. This is described in more detail in |
| <a href="#ref_guide_meta_factory" title="1. Metadata Factory">Section 1, “ |
| Metadata Factory |
| ”</a>. |
| </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| Listing persistent classes (or their metadata or jar files) is an all-or-nothing |
| endeavor. If your persistent class list is non-empty, OpenJPA will assume that |
| any unlisted class is not persistent. |
| </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_pc_enhance"></a>2. |
| Enhancement |
| </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#ref_guide_pc_enhance_build">2.1. |
| Enhancing at Build Time |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_pc_enhance_runtime_container">2.2. |
| Enhancing JPA Entities on Deployment |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_pc_enhance_runtime">2.3. |
| Enhancing at Runtime |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_pc_enhance_unenhanced_types">2.4. |
| Omitting the OpenJPA enhancer |
| </a></span></dt></dl></div><a class="indexterm" name="d0e22003"></a><a class="indexterm" name="d0e22006"></a><p> |
| In order to provide optimal runtime performance, flexible lazy loading, and |
| efficient, immediate dirty tracking, OpenJPA can use an <span class="emphasis"><em>enhancer |
| </em></span>. An enhancer is a tool that automatically adds code to your |
| persistent classes after you have written them. The enhancer post-processes the |
| bytecode generated by your Java compiler, adding the necessary fields and |
| methods to implement the required persistence features. This bytecode |
| modification perfectly preserves the line numbers in stack traces and is |
| compatible with Java debuggers. In fact, the only change to debugging |
| is that the persistent setter and getter methods of entity classes using |
| property access will be prefixed with <code class="literal">pc</code> in stack traces and |
| step-throughs. For example, if your entity has a <code class="methodname">getId</code> |
| method for persistent property <code class="literal">id</code>, and that method throws an |
| exception, the stack trace will report the exception from method <code class="methodname"> |
| pcgetId</code>. The line numbers, however, will correctly correspond to |
| the <code class="methodname">getId</code> method in your source file. |
| </p><div class="mediaobject"><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="339"><tr><td><img src="img/enhancement.png"></td></tr></table></div><p> |
| The diagram above illustrates the compilation of a persistent class. |
| </p><p> |
| You can add the OpenJPA enhancer to your build process, or use Java 1.5's |
| instrumentation features to transparently enhance persistent classes when they |
| are loaded into the JVM. The following sections describe each option. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_pc_enhance_build"></a>2.1. |
| Enhancing at Build Time |
| </h3></div></div></div><a class="indexterm" name="d0e22042"></a><p> |
| The enhancer can be invoked at build time |
| via its Java class, <code class="classname"> |
| org.apache.openjpa.enhance.PCEnhancer</code>. |
| </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| You can also enhance via Ant; see |
| <a href="#ref_guide_integration_enhance" title="1.2. Enhancer Ant Task">Section 1.2, “ |
| Enhancer Ant Task |
| ”</a>. |
| </p></div><div class="example"><a name="ref_guide_pc_enhance_enhancer"></a><p class="title"><b>Example 5.1. |
| Using the OpenJPA Enhancer |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| java org.apache.openjpa.enhance.PCEnhancer Magazine.java |
| </pre></div></div><br class="example-break"><p> |
| The enhancer accepts the standard set of command-line arguments defined by the |
| configuration framework (see <a href="#ref_guide_conf_devtools" title="3. Command Line Configuration">Section 3, “ |
| Command Line Configuration |
| ”</a> ), |
| along with the following flags: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">-directory/-d <output directory></code>: Path to the output |
| directory. If the directory does not match the enhanced class' package, the |
| package structure will be created beneath the directory. By default, the |
| enhancer overwrites the original <code class="filename">.class</code> file. |
| </p></li><li><p> |
| <code class="literal">-enforcePropertyRestrictions/-epr <true/t | false/f></code>: |
| Whether to throw an exception when it appears that a property access entity is |
| not obeying the restrictions placed on property access. Defaults to false. |
| </p></li><li><p> |
| <code class="literal">-addDefaultConstructor/-adc <true/t | false/f></code>: The |
| spec requires that all persistent classes define a no-arg constructor. This flag |
| tells the enhancer whether to add a protected no-arg constructor to any |
| persistent classes that don't already have one. Defaults to <code class="literal"> |
| true</code>. |
| </p></li><li><p> |
| <code class="literal">-tmpClassLoader/-tcl <true/t | false/f></code>: Whether to |
| load persistent classes with a temporary class loader. This allows other code to |
| then load the enhanced version of the class within the same JVM. Defaults to |
| <code class="literal">true</code>. Try setting this flag to <code class="literal">false</code> as a |
| debugging step if you run into class loading problems when running the enhancer. |
| </p></li></ul></div><p> |
| Each additional argument to the enhancer must be one of the following: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| The full name of a class. |
| </p></li><li><p> |
| The .java file for a class. |
| </p></li><li><p> |
| The <code class="filename">.class</code> file of a class. |
| </p></li></ul></div><p> |
| If you do not supply any arguments to the enhancer, it will run on the classes |
| in your persistent class list (see <a href="#ref_guide_pc_pcclasses" title="1. Persistent Class List">Section 1, “ |
| Persistent Class List |
| ”</a>). |
| </p><p> |
| You can run the enhancer over classes that have already been enhanced, in which |
| case it will not further modify the class. You can also run it over classes that |
| are not persistence-capable, in which case it will treat the class as |
| persistence-aware. Persistence-aware classes can directly manipulate the |
| persistent fields of persistence-capable classes. |
| </p><p> |
| Note that the enhancement process for subclasses introduces dependencies on the |
| persistent parent class being enhanced. This is normally not problematic; |
| however, when running the enhancer multiple times over a subclass whose parent |
| class is not yet enhanced, class loading errors can occur. In the event of a |
| class load error, simply re-compile and re-enhance the offending classes. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_pc_enhance_runtime_container"></a>2.2. |
| Enhancing JPA Entities on Deployment |
| </h3></div></div></div><a class="indexterm" name="d0e22129"></a><p> |
| The Java EE 5 specification includes hooks to automatically enhance JPA entities |
| when they are deployed into a container. Thus, if you are using a Java EE |
| 5-compliant application server, OpenJPA will enhance your entities automatically |
| at runtime. Note that if you prefer build-time enhancement, OpenJPA's runtime |
| enhancer will correctly recognize and skip pre-enhanced classes. |
| </p><p> |
| If your application server does not support the Java EE 5 enhancement hooks, |
| consider using the build-time enhancement described above, or the more general |
| runtime enhancement described in the next section. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_pc_enhance_runtime"></a>2.3. |
| Enhancing at Runtime |
| </h3></div></div></div><a class="indexterm" name="d0e22143"></a><p> |
| OpenJPA includes a <span class="emphasis"><em>Java agent</em></span> for automatically enhancing |
| persistent classes as they are loaded into the JVM. Java agents are classes that |
| are invoked prior to your application's <code class="methodname">main</code> method. |
| OpenJPA's agent uses JVM hooks to intercept all class loading to enhance classes |
| that have persistence metadata before the JVM loads them. |
| </p><p> |
| Searching for metadata for every class loaded by the JVM can slow application |
| initialization. One way to speed things up is to take advantage of the optional |
| persistent class list described in <a href="#ref_guide_pc_pcclasses" title="1. Persistent Class List">Section 1, “ |
| Persistent Class List |
| ”</a>. If |
| you declare a persistent class list, OpenJPA will only search for |
| metadata for classes in that list. |
| </p><p> |
| To employ the OpenJPA agent, invoke <code class="literal">java</code> with the <code class="literal"> |
| -javaagent</code> set to the path to your OpenJPA jar file. |
| </p><div class="example"><a name="ref_guide_pc_enhance_runtime_ex"></a><p class="title"><b>Example 5.2. |
| Using the OpenJPA Agent for Runtime Enhancement |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| java -javaagent:/home/dev/openjpa/lib/openjpa.jar com.xyz.Main |
| </pre></div></div><br class="example-break"><p> |
| You can pass settings to the agent using OpenJPA's plugin syntax (see |
| <a href="#ref_guide_conf_plugins" title="4. Plugin Configuration">Section 4, “ |
| Plugin Configuration |
| ”</a>). The agent accepts the long |
| form of any of the standard configuration options |
| (<a href="#ref_guide_conf_devtools" title="3. Command Line Configuration">Section 3, “ |
| Command Line Configuration |
| ”</a> ). It also accepts the following |
| options, the first three of which correspond exactly to to the same-named |
| options of the enhancer tool described in |
| <a href="#ref_guide_pc_enhance_build" title="2.1. Enhancing at Build Time">Section 2.1, “ |
| Enhancing at Build Time |
| ”</a>: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">addDefaultConstructor</code> |
| </p></li><li><p> |
| <code class="literal">enforcePropertyRestrictions</code> |
| </p></li><li><p> |
| <code class="literal">scanDevPath</code>: Boolean indicating whether to scan the |
| classpath for persistent types if none have been configured. If you do not |
| specify a persistent types list and do not set this option to true, OpenJPA will |
| check whether each class loaded into the JVM is persistent, and enhance it |
| accordingly. This may slow down class load times significantly. |
| </p></li><li><p> |
| <code class="literal">classLoadEnhancement</code>: Boolean controlling whether OpenJPA |
| load-time class enhancement should be available in this JVM execution. Default: |
| <code class="literal">true</code> |
| </p></li><li><p> |
| <code class="literal">runtimeRedefinition</code>: Boolean controlling whether OpenJPA |
| class redefinition should be available in this JVM execution. Default: |
| <code class="literal">true</code> |
| </p></li></ul></div><div class="example"><a name="ref_guide_pc_enhance_runtime_opt_ex"></a><p class="title"><b>Example 5.3. |
| Passing Options to the OpenJPA Agent |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| java -javaagent:/home/dev/openjpa/lib/openjpa.jar=addDefaultConstructor=false com.xyz.Main |
| </pre></div></div><br class="example-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_pc_enhance_unenhanced_types"></a>2.4. |
| Omitting the OpenJPA enhancer |
| </h3></div></div></div><a class="indexterm" name="d0e22228"></a><p> |
| OpenJPA does not require that the enhancer be run. If you do not run the |
| enhancer, OpenJPA will fall back to one of several possible alternatives for |
| state tracking, depending on the execution environment. |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <span class="emphasis"><em>Deploy-time enhancement</em></span>: if you are running your |
| application inside a Java EE 5 container, or another environment that supports |
| the JPA container contract, then OpenJPA will automatically perform class |
| transformation at deploy time. |
| </p></li><li><p> |
| <span class="emphasis"><em>Java 6 class retransformation</em></span>: if you are running your |
| application in a Java 6 environment, OpenJPA will attempt to dynamically |
| register a <code class="literal">ClassTransformer</code> that will redefine your |
| persistent classes on the fly to track access to persistent data. Additionally, |
| OpenJPA will create a subclass for each of your persistent classes. When |
| you execute a query or traverse a relation, OpenJPA will return an instance |
| of the subclass. This means that the <code class="literal">instanceof</code> operator |
| will work as expected, but <code class="literal">o.getClass()</code> will return the |
| subclass instead of the class that you wrote. |
| </p><p> |
| You do not need to do anything at all to get this behavior. OpenJPA will |
| automatically detect whether or not the execution environment is capable of |
| Java 6 class retransformation. |
| </p></li><li><p> |
| <span class="emphasis"><em>Java 5 class redefinition</em></span>: if you are running your |
| application in a Java 5 environment, and you specify the OpenJPA javaagent, |
| OpenJPA will use Java 5 class redefinition to redefine any persistent classes |
| that are not enhanced by the OpenJPA javaagent. Aside from the requirement |
| that you specify a javaagent on the command line, this behavior is exactly the |
| same as the Java 6 class retransformation behavior. Of course, since the |
| OpenJPA javaagent performs enhancement by default, this will only be available |
| if you set the <code class="literal">classLoadEnhancement</code> javaagent flag to |
| <code class="literal">false</code>, or on any classes that are skipped by the OpenJPA |
| runtime enhancement process for some reason. |
| </p></li><li><p> |
| <span class="emphasis"><em>Runtime Unenhanced Classes</em></span>: AKA statte comparison and |
| subclassing. If you are running |
| in a Java 5 environment without a javaagent, or in a Java 6 environment that |
| does not support class retransformation, OpenJPA will still create subclasses |
| as outlined above. However, in some cases, OpenJPA may not be able to receive |
| notifications when you read or write persistent data. |
| </p><p> |
| </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> |
| Runtime Unenhanced Classes has some known limitations which are discussed below |
| and documented in JIRA issues on the OpenJPA website. Support for this method |
| of automatic enhancement may be enabled or disabled via the |
| <a href="#openjpa.RuntimeUnenhancedClasses" title="5.57. openjpa.RuntimeUnenhancedClasses">Section 5.57, “openjpa.RuntimeUnenhancedClasses”</a>option. |
| </div><p> |
| </p><p> |
| If you are using <span class="emphasis"><em>property access</em></span> for your persistent data, |
| then OpenJPA will be able to track all accesses for instances that you load |
| from the database, but not for instances that you create. This is because |
| OpenJPA will create new instances of its dynamically-generated subclass when |
| it loads data from the database. The dynamically-generated subclass has |
| code in the setters and getters that notify OpenJPA about persistent data |
| access. This means that new instances that you create will be subject to |
| state-comparison checks (see discussion below) to compute which fields to |
| write to the database, and that OpenJPA will ignore requests to evict |
| persistent data from such instances. In practice, this is not a particularly |
| bad limitation, since OpenJPA already knows that it must insert all field |
| values for new instances. So, this is only really an issue if you flush |
| changes to the database while inserting new records; after such a flush, |
| OpenJPA will need to hold potentially-unneeded hard references to the |
| new-flushed instances. |
| </p><p> |
| If you are using <span class="emphasis"><em>field access</em></span> for your persistent data, |
| then OpenJPA will not be able to track accesses for any instances, including |
| ones that you load from the database. So, OpenJPA will perform state-comparison |
| checks to determine which fields are dirty. These state comparison checks are |
| costly in two ways. First, there is a performance penalty at flush / commit |
| time, since OpenJPA must walk through every field of every instance to determine |
| which fields of which records are dirty. Second, there is a memory penalty, |
| since OpenJPA must hold hard references to all instances that were loaded at |
| any time in a given transaction, and since OpenJPA must keep a copy of all |
| the initial values of the loaded data for later comparison. Additionally, |
| OpenJPA will ignore requests to evict persistent state for these types of |
| instances. Finally, the default lazy loading configuration will be ignored for |
| single-valued fields (one-to-one, many-to-one, and any other non-collection |
| or non-map field that has a lazy loading configuration). If you use fetch |
| groups or programmatically configure your fetch plan, OpenJPA will obey these |
| directives, but will be unable to lazily load any data that you exclude from |
| loading. As a result of these limitations, it is not recommended that you use |
| field access if you are not either running the enhancer or using OpenJPA with |
| a javaagent or in a Java 6 environment. |
| </p></li></ul></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_pc_interfaces"></a>3. Managed Interfaces</h2></div></div></div><a class="indexterm" name="d0e22300"></a><p> |
| OpenJPA's managed interface feature allows you to define your object model |
| entirely in terms of interfaces, instead of concrete classes. To use this |
| feature, you must annotate your managed interfaces with the |
| <code class="classname">ManagedInterface</code> annotation, and use the |
| <code class="literal">OpenJPAEntityManager.createInstance(Class)</code> method to |
| create new records. Note that <code class="literal">createInstance()</code> returns |
| unmanaged instances; you must pass them to |
| <code class="literal">EntityManager.persist()</code> to store them in the database. |
| </p><pre class="programlisting"> |
| @ManagedInterface |
| public interface PersonIface { |
| @Id @GeneratedValue |
| int getId(); |
| void setId(int id); |
| |
| // implicitly persistent per JPA property rules |
| String getName(); |
| void setName(String name); |
| } |
| </pre><pre class="programlisting"> |
| OpenJPAEntityManager em = ...; |
| PersonIface person = em.createInstance(PersonIface.class); |
| person.setName("Homer Simpson"); |
| em.getTransaction().begin(); |
| em.persist(person); |
| em.getTransaction().commit(); |
| </pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_pc_oid"></a>4. |
| Object Identity |
| </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#ref_guide_pc_oid_datastore">4.1. |
| Datastore Identity |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_pc_oid_entitypk">4.2. |
| Entities as Identity Fields |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_pc_oid_application">4.3. |
| Application Identity Tool |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_pc_oid_pkgen_autoinc">4.4. |
| Autoassign / Identity Strategy Caveats |
| </a></span></dt></dl></div><a class="indexterm" name="d0e22326"></a><p> |
| OpenJPA makes several enhancements to JPA's standard entity identity. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_pc_oid_datastore"></a>4.1. |
| Datastore Identity |
| </h3></div></div></div><a class="indexterm" name="d0e22334"></a><p> |
| The JPA specification requires you to declare one or more identity fields in |
| your persistent classes. OpenJPA fully supports this form of object identity, |
| called <span class="emphasis"><em>application</em></span> identity. OpenJPA, however, also |
| supports <span class="emphasis"><em>datastore</em></span> identity. In datastore identity, you do |
| not declare any primary key fields. OpenJPA manages the identity of your |
| persistent objects for you through a surrogate key in the database. |
| </p><p> |
| You can control how your JPA datastore identity value is generated through |
| OpenJPA's |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/DataStoreId.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.DataStoreId</code></a> class |
| annotation. This annotation has <code class="literal">strategy</code> and <code class="literal"> |
| generator</code> properties that mirror the same-named properties on the |
| standard <code class="classname">javax.persistence.GeneratedValue</code> annotation |
| described in <a href="#jpa_overview_meta_id" title="2.2. Id">Section 2.2, “ |
| Id |
| ”</a> of the JPA Overview. |
| </p><p> |
| To retrieve the identity value of a datastore identity entity, use the |
| <code class="methodname">OpenJPAEntityManager.getObjectId(Object entity)</code> |
| method. See <a href="#ref_guide_runtime_em" title="2.2. OpenJPAEntityManager">Section 2.2, “ |
| OpenJPAEntityManager |
| ”</a> for more information on |
| the <code class="classname">OpenJPAEntityManager</code>. |
| </p><div class="example"><a name="ref_guide_pc_oid_datastoreentityex"></a><p class="title"><b>Example 5.4. |
| JPA Datastore Identity Metadata |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| import org.apache.openjpa.persistence.*; |
| |
| @Entity |
| @DataStoreId |
| public class LineItem { |
| |
| ... no @Id fields declared ... |
| } |
| </pre></div></div><br class="example-break"><p> |
| Internally, OpenJPA uses the public |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/util/Id.html" target="_top"><code class="classname"> |
| org.apache.openjpa.util.Id</code></a> class for datastore identity |
| objects. When writing OpenJPA plugins, you can manipulate datastore identity |
| objects by casting them to this class. You can also create your own <code class="classname"> |
| Id</code> instances and pass them to any internal OpenJPA method that |
| expects an identity object. |
| </p><p> |
| In JPA, you will never see <code class="classname">Id</code> instances directly. |
| Instead, calling <code class="classname">OpenJPAEntityManager.getObjectId</code> on a |
| datastore identity object will return the <code class="classname">Long</code> surrogate |
| primary key value for that object. You can then use this value in calls to |
| <code class="classname">EntityManager.find</code> for subsequent lookups of the same |
| record. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_pc_oid_entitypk"></a>4.2. |
| Entities as Identity Fields |
| </h3></div></div></div><a class="indexterm" name="d0e22406"></a><p> |
| The JPA specification limits identity fields to simple types. OpenJPA, however, |
| also allows <code class="literal">ManyToOne</code> and <code class="literal">OneToOne</code> |
| relations to be identity fields. To identify a relation field as an identity |
| field, simply annotate it with both the <code class="literal">@ManyToOne</code> or |
| <code class="literal">@OneToOne</code> relation annotation and the <code class="literal">@Id</code> |
| identity annotation. |
| </p><p> |
| When finding an entity identified by a relation, pass the id of the |
| <span class="emphasis"><em>relation</em></span> to the <code class="methodname">EntityManager.find</code> |
| method: |
| </p><div class="example"><a name="ref_guide_pc_oid_entitypk_simplefind"></a><p class="title"><b>Example 5.5. |
| Finding an Entity with an Entity Identity Field |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| public Delivery createDelivery(Order order) { |
| Delivery delivery = new Delivery(); |
| delivery.setId(order); |
| delivery.setDelivered(new Date()); |
| return delivery; |
| } |
| |
| public Delivery findDelivery(EntityManager em, Order order) { |
| // use the identity of the related instance |
| return em.find(Delivery.class, order.getId()); |
| } |
| </pre></div></div><br class="example-break"><p> |
| When your entity has multiple identity fields, at least one of which is a |
| relation to another entity, you must use an identity class (see |
| <a href="#jpa_overview_pc_identitycls" title="2.1. Identity Class">Section 2.1, “ |
| Identity Class |
| ”</a> in the JPA Overview). You cannot |
| use an embedded identity object. Identity class fields corresponding to |
| entity identity fields should be of the same type as the related entity's |
| identity. |
| </p><div class="example"><a name="ref_guide_pc_oid_entitypk_idcls"></a><p class="title"><b>Example 5.6. |
| Id Class for Entity Identity Fields |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| @Entity |
| public class Order { |
| |
| @Id |
| private long id; |
| |
| ... |
| } |
| |
| @Entity |
| @IdClass(LineItemId.class) |
| public class LineItem { |
| |
| @Id |
| private int index; |
| |
| @Id |
| @ManyToOne |
| private Order order; |
| |
| ... |
| } |
| |
| public class LineItemId { |
| |
| public int index; |
| public long order; // same type as order's identity |
| |
| ... |
| } |
| </pre></div></div><br class="example-break"><p> |
| In the example above, if <code class="classname">Order</code> had used an identity |
| class <code class="classname">OrderId</code> in place of a simple <code class="classname">long |
| </code> value, then the <code class="literal">LineItemId.order</code> field would |
| have been of type <code class="classname">OrderId</code>. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_pc_oid_application"></a>4.3. |
| Application Identity Tool |
| </h3></div></div></div><a class="indexterm" name="d0e22472"></a><a class="indexterm" name="d0e22479"></a><p> |
| If you choose to use application identity, you may want to take advantage of |
| OpenJPA's application identity tool. The application |
| identity tool generates Java code implementing the identity class for any |
| persistent type using application identity. The code satisfies all the |
| requirements the specification places on identity classes. You can use it as-is, |
| or simply use it as a starting point, editing it to meet your needs. |
| </p><p> |
| Before you can run the application identity tool on a persistent class, the |
| class must be compiled and must have complete metadata. All primary key fields |
| must be marked as such in the metadata. |
| </p><p> |
| In JPA metadata, do not attempt to specify the <code class="literal">@IdClass</code> |
| annotation unless you are using the application identity tool to overwrite an |
| existing identity class. Attempting to set the value of the <code class="literal">@IdClass |
| </code> to a non-existent class will prevent your persistent class from |
| compiling. Instead, use the <code class="literal">-name</code> or <code class="literal">-suffix |
| </code> options described below to tell OpenJPA what name to give your |
| generated identity class. Once the application identity tool has generated the |
| class code, you can set the <code class="literal">@IdClass</code> annotation. |
| </p><p> |
| The application identity tool can be invoked via its Java class, |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/enhance/ApplicationIdTool" target="_top"> |
| <code class="classname">org.apache.openjpa.enhance.ApplicationIdTool</code></a>. |
| </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| <a href="#ref_guide_integration_appidtool" title="1.3. Application Identity Tool Ant Task">Section 1.3, “ |
| Application Identity Tool Ant Task |
| ”</a> describes the |
| application identity tool's Ant task. |
| </p></div><div class="example"><a name="ref_guide_pc_appid_appidtool"></a><p class="title"><b>Example 5.7. |
| Using the Application Identity Tool |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| java org.apache.openjpa.enhance.ApplicationIdTool -s Id Magazine.java |
| </pre></div></div><br class="example-break"><p> |
| The application identity tool accepts the standard set of command-line arguments |
| defined by the configuration framework (see |
| <a href="#ref_guide_conf_devtools" title="3. Command Line Configuration">Section 3, “ |
| Command Line Configuration |
| ”</a>), including code formatting |
| flags described in <a href="#ref_guide_conf_devtools_format" title="3.1. Code Formatting">Section 3.1, “ |
| Code Formatting |
| ”</a>. It |
| also accepts the following arguments: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">-directory/-d <output directory></code>: Path to the output |
| directory. If the directory does not match the generated oid class' package, the |
| package structure will be created beneath the directory. If not specified, the |
| tool will first try to find the directory of the <code class="filename">.java</code> file |
| for the persistence-capable class, and failing that will use the current |
| directory. |
| </p></li><li><p> |
| <code class="literal">-ignoreErrors/-i <true/t | false/f></code>: If <code class="literal">false |
| </code>, an exception will be thrown if the tool is run on any class that |
| does not use application identity, or is not the base class in the inheritance |
| hierarchy (recall that subclasses never define the application identity class; |
| they inherit it from their persistent superclass). |
| </p></li><li><p> |
| <code class="literal">-token/-t <token></code>: The token to use to separate |
| stringified primary key values in the string form of the object id. This option |
| is only used if you have multiple primary key fields. It defaults to "::". |
| </p></li><li><p> |
| <code class="literal">-name/-n <id class name></code>: The name of the identity |
| class to generate. If this option is specified, you must run the tool on exactly |
| one class. If the class metadata already names an object id class, this option |
| is ignored. If the name is not fully qualified, the persistent class' package is |
| prepended to form the qualified name. |
| </p></li><li><p> |
| <code class="literal">-suffix/-s <id class suffix></code>: A string to suffix each |
| persistent class name with to form the identity class name. This option is |
| overridden by <code class="literal">-name</code> or by any object id class specified in |
| metadata. |
| </p></li></ul></div><p> |
| Each additional argument to the tool must be one of the following: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| The full name of a persistent class. |
| </p></li><li><p> |
| The .java file for a persistent class. |
| </p></li><li><p> |
| The <code class="filename">.class</code> file of a persistent class. |
| </p></li></ul></div><p> |
| If you do not supply any arguments to the tool, it will act on the classes in |
| your persistent classes list (see <a href="#ref_guide_pc_pcclasses" title="1. Persistent Class List">Section 1, “ |
| Persistent Class List |
| ”</a>). |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_pc_oid_pkgen_autoinc"></a>4.4. |
| Autoassign / Identity Strategy Caveats |
| </h3></div></div></div><a class="indexterm" name="d0e22588"></a><a class="indexterm" name="d0e22593"></a><a class="indexterm" name="d0e22598"></a><p> |
| <a href="#jpa_overview_meta_gen" title="2.3. Generated Value">Section 2.3, “ |
| Generated Value |
| ”</a> explains how to use JPA's |
| <code class="literal">IDENTITY</code> generation type to automatically assign field |
| values. However, here are some additional caveats you should be aware of when |
| using <code class="literal">IDENTITY</code> generation: |
| </p><div class="orderedlist"><ol type="1"><li><p> |
| Your database must support auto-increment / identity columns, or some equivalent |
| (see <a href="#ref_guide_dbsetup_dbsupport_oracle" title="4.3. OracleDictionary Properties">Section 4.3, “ |
| OracleDictionary Properties |
| ”</a> for how to |
| configure a combination of triggers and sequences to fake auto-increment support |
| in Oracle). |
| </p></li><li><p> |
| Auto-increment / identity columns must be an integer or long integer type. |
| </p></li><li><p> |
| Databases support auto-increment / identity columns to varying degrees. Some do |
| not support them at all. Others only allow a single such column per table, and |
| require that it be the primary key column. More lenient databases may allow |
| non-primary key auto-increment columns, and may allow more than one per table. |
| See your database documentation for details. |
| </p></li></ol></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_inverses"></a>5. |
| Managed Inverses |
| </h2></div></div></div><a class="indexterm" name="d0e22628"></a><p> |
| Bidirectional relations are an essential part of data modeling. |
| <a href="#jpa_overview_mapping" title="Chapter 12. Mapping Metadata">Chapter 12, <i xmlns:xlink="http://www.w3.org/1999/xlink"> |
| Mapping Metadata |
| </i></a> in the JPA Overview explains how to |
| use the <code class="literal">mappedBy</code> annotation attribute to form bidirectional |
| relations that also share datastore storage in JPA. |
| </p><p> |
| OpenJPA also allows you to define purely logical bidirectional relations. The |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/InverseLogical.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.InverseLogical</code></a> |
| annotation names a logical inverse in JPA metadata. |
| </p><div class="example"><a name="ref_guide_inverses_logicalex"></a><p class="title"><b>Example 5.8. |
| Specifying Logical Inverses |
| </b></p><div class="example-contents"><p> |
| <code class="literal">Magazine.coverPhoto</code> and <code class="literal">Photograph.mag</code> are |
| each mapped to different foreign keys in their respective tables, but form a |
| logical bidirectional relation. Only one of the fields needs to declare the |
| other as its logical inverse, though it is not an error to set the logical |
| inverse of both fields. |
| </p><pre class="programlisting"> |
| import org.apache.openjpa.persistence.*; |
| |
| @Entity |
| public class Magazine { |
| |
| @OneToOne |
| private Photograph coverPhoto; |
| |
| ... |
| } |
| |
| @Entity |
| public class Photograph { |
| |
| @OneToOne |
| @InverseLogical("coverPhoto") |
| private Magazine mag; |
| |
| ... |
| } |
| </pre></div></div><br class="example-break"><p> |
| Java does not provide any native facilities to ensure that both sides of a |
| bidirectional relation remain consistent. Whenever you set one side of the |
| relation, you must manually set the other side as well. |
| </p><p> |
| By default, OpenJPA behaves the same way. OpenJPA does not automatically |
| propagate changes from one field in bidirectional relation to the other field. |
| This is in keeping with the philosophy of transparency, and also provides higher |
| performance, as OpenJPA does not need to analyze your object graph to correct |
| inconsistent relations. |
| </p><p> |
| <a class="indexterm" name="d0e22666"></a> |
| If convenience is more important to you than strict transparency, however, you |
| can enable inverse relation management in OpenJPA. Set the |
| <a href="#openjpa.InverseManager" title="5.35. openjpa.InverseManager"><code class="classname">openjpa.InverseManager |
| </code></a> plugin property to <code class="literal">true</code> for standard |
| management. Under this setting, OpenJPA detects changes to either side of a |
| bidirectional relation (logical or physical), and automatically sets the other |
| side appropriately on flush. |
| </p><div class="example"><a name="ref_guide_inversesex"></a><p class="title"><b>Example 5.9. |
| Enabling Managed Inverses |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| <property name="openjpa.InverseManager" value="true"/> |
| </pre></div></div><br class="example-break"><p> |
| The inverse manager has options to log a warning or throw an exception when it |
| detects an inconsistent bidirectional relation, rather than correcting it. To |
| use these modes, set the manager's <code class="literal">Action</code> property to |
| <code class="literal">warn</code> or <code class="literal">exception</code>, respectively. |
| </p><p> |
| By default, OpenJPA excludes <a href="#ref_guide_pc_scos_proxy_lrs" title="6.4.2. Large Result Set Proxies"> large |
| result set fields</a> from management. You can force large result set fields |
| to be included by setting the <code class="literal">ManageLRS</code> plugin property to |
| <code class="literal">true</code>. |
| </p><div class="example"><a name="ref_guide_inverses_logex"></a><p class="title"><b>Example 5.10. |
| Log Inconsistencies |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| <property name="openjpa.InverseManager" value="true(Action=warn)"/> |
| </pre></div></div><br class="example-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_pc_scos"></a>6. |
| Persistent Fields |
| </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#ref_guide_pc_scos_restore">6.1. |
| Restoring State |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_pc_scos_order">6.2. |
| Typing and Ordering |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_pc_calendar_timezone">6.3. |
| Calendar Fields and TimeZones |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_pc_scos_proxy">6.4. |
| Proxies |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_pc_scos_proxy_smart">6.4.1. |
| Smart Proxies |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_pc_scos_proxy_lrs">6.4.2. |
| Large Result Set Proxies |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_pc_scos_proxy_custom">6.4.3. |
| Custom Proxies |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_pc_extern">6.5. |
| Externalization |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_pc_extern_values">6.5.1. |
| External Values |
| </a></span></dt></dl></dd></dl></div><a class="indexterm" name="d0e22712"></a><p> |
| OpenJPA enhances the specification's support for persistent fields in many ways. |
| This section documents aspects of OpenJPA's persistent field handling that may |
| affect the way you design your persistent classes. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_pc_scos_restore"></a>6.1. |
| Restoring State |
| </h3></div></div></div><a class="indexterm" name="d0e22720"></a><a class="indexterm" name="d0e22725"></a><p> |
| While the JPA specification says that you should not use rolled back objects, |
| such objects are perfectly valid in OpenJPA. You can control whether the |
| objects' managed state is rolled back to its pre-transaction values with the |
| <a href="#openjpa.RestoreState" title="5.54. openjpa.RestoreState"><code class="literal">openjpa.RestoreState</code> |
| </a> configuration property. <code class="literal">none</code> does not roll back state |
| (the object becomes hollow, and will re-load its state the next time it is |
| accessed), <code class="literal">immutable</code> restores immutable values (primitives, |
| primitive wrappers, strings) and clears mutable values so that they are reloaded |
| on next access, and <code class="literal">all</code> restores all managed values to their |
| pre-transaction state. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_pc_scos_order"></a>6.2. |
| Typing and Ordering |
| </h3></div></div></div><a class="indexterm" name="d0e22747"></a><p> |
| When loading data into a field, OpenJPA examines the value you assign the field |
| in your declaration code or in your no-args constructor. If the field value's |
| type is more specific than the field's declared type, OpenJPA uses the value |
| type to hold the loaded data. OpenJPA also uses the comparator you've |
| initialized the field with, if any. Therefore, you can use custom comparators on |
| your persistent field simply by setting up the comparator and using it in your |
| field's initial value. |
| </p><div class="example"><a name="ref_guide_pc_scos_order_initialvals"></a><p class="title"><b>Example 5.11. |
| Using Initial Field Values |
| </b></p><div class="example-contents"><p> |
| Though the annotations are left out for simplicity, assume <code class="literal"> |
| employeesBySal</code> and <code class="literal">departments</code> are persistent |
| fields in the class below. |
| </p><pre class="programlisting"> |
| public class Company { |
| |
| // OpenJPA will detect the custom comparator in the initial field value |
| // and use it whenever loading data from the database into this field |
| private Collection employeesBySal = new TreeSet(new SalaryComparator()); |
| private Map departments; |
| |
| public Company { |
| // or we can initialize fields in our no-args constructor; even though |
| // this field is declared type Map, OpenJPA will detect that it's |
| // actually a TreeMap and use natural ordering for loaded data |
| departments = new TreeMap(); |
| } |
| |
| // rest of class definition... |
| } |
| </pre></div></div><br class="example-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_pc_calendar_timezone"></a>6.3. |
| Calendar Fields and TimeZones |
| </h3></div></div></div><a class="indexterm" name="d0e22770"></a><p> |
| OpenJPA's support for the <code class="classname">java.util.Calendar</code> type will |
| store only the <code class="classname">Date</code> part of the field, not the |
| <code class="classname">TimeZone</code> associated with the field. When loading the date |
| into the <code class="classname">Calendar</code> field, OpenJPA will use the <code class="classname"> |
| TimeZone</code> that was used to initialize the field. |
| </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| OpenJPA will automatically track changes made via modification methods in fields |
| of type <code class="classname">Calendar</code>, with one exception: when using Java |
| version 1.3, the <code class="methodname">set()</code> method cannot be overridden, so |
| when altering the calendar using that method, the field must be explicitly |
| marked as dirty. This limitation does not apply when running with Java version |
| 1.4 and higer. |
| </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_pc_scos_proxy"></a>6.4. |
| Proxies |
| </h3></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#ref_guide_pc_scos_proxy_smart">6.4.1. |
| Smart Proxies |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_pc_scos_proxy_lrs">6.4.2. |
| Large Result Set Proxies |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_pc_scos_proxy_custom">6.4.3. |
| Custom Proxies |
| </a></span></dt></dl></div><a class="indexterm" name="d0e22804"></a><a class="indexterm" name="d0e22807"></a><p> |
| At runtime, the values of all mutable second class object fields in persistent |
| and transactional objects are replaced with implementation-specific proxies. On |
| modification, these proxies notify their owning instance that they have been |
| changed, so that the appropriate updates can be made on the datastore. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="ref_guide_pc_scos_proxy_smart"></a>6.4.1. |
| Smart Proxies |
| </h4></div></div></div><a class="indexterm" name="d0e22819"></a><p> |
| Most proxies only track whether or not they have been modified. Smart proxies |
| for collection and map fields, however, keep a record of which elements have |
| been added, removed, and changed. This record enables the OpenJPA runtime to |
| make more efficient database updates on these fields. |
| </p><p> |
| When designing your persistent classes, keep in mind that you can optimize for |
| OpenJPA smart proxies by using fields of type <code class="classname">java.util.Set |
| </code>, <code class="classname">java.util.TreeSet</code>, and <code class="classname"> |
| java.util.HashSet</code> for your collections whenever possible. Smart |
| proxies for these types are more efficient than proxies for <code class="classname"> |
| List</code>s. You can also design your own smart proxies to further |
| optimize OpenJPA for your usage patterns. See the section on |
| <a href="#ref_guide_pc_scos_proxy_custom" title="6.4.3. Custom Proxies">custom proxies</a> for |
| details. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="ref_guide_pc_scos_proxy_lrs"></a>6.4.2. |
| Large Result Set Proxies |
| </h4></div></div></div><a class="indexterm" name="d0e22846"></a><a class="indexterm" name="d0e22851"></a><p> |
| Under standard ORM behavior, traversing a persistent collection or map field |
| brings the entire contents of that field into memory. Some persistent fields, |
| however, might represent huge amounts of data, to the point that attempting to |
| fully instantiate them can overwhelm the JVM or seriously degrade performance. |
| </p><p> |
| OpenJPA uses special proxy types to represent these "large result set" fields. |
| OpenJPA's large result set proxies do not cache any data in memory. Instead, |
| each operation on the proxy offloads the work to the database and returns the |
| proper result. For example, the <code class="methodname">contains</code> method of a |
| large result set collection will perform a <code class="literal"> SELECT COUNT(*)</code> |
| query with the proper <code class="literal">WHERE</code> conditions to find out if the |
| given element exists in the database's record of the collection. Similarly, each |
| time you obtain an iterator OpenJPA performs the proper query using the current |
| <a href="#ref_guide_dbsetup_lrs" title="10. Large Result Sets">large result set settings</a>, as |
| discussed in the <a href="#ref_guide_dbsetup" title="Chapter 4. JDBC">JDBC</a> chapter. As you |
| invoke <code class="methodname">Iterator.next</code>, OpenJPA instantiates the result |
| objects on-demand. |
| </p><p> |
| You can free the resources used by a large result set iterator by passing it to |
| the static <a href="#ref_guide_runtime_openjpapersistence" title="2.9. OpenJPAPersistence"><code class="methodname"> |
| OpenJPAPersistence.close</code></a> method. |
| </p><div class="example"><a name="ref_guide_pc_scos_proxy_lrs_itr"></a><p class="title"><b>Example 5.12. |
| Using a Large Result Set Iterator |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| import org.apache.openjpa.persistence.*; |
| |
| ... |
| |
| Collection employees = company.getEmployees(); // employees is a lrs collection |
| Iterator itr = employees.iterator(); |
| while (itr.hasNext()) |
| process((Employee) itr.next()); |
| OpenJPAPersistence.close(itr); |
| </pre></div></div><br class="example-break"><p> |
| You can also add and remove from large result set proxies, just as with standard |
| fields. OpenJPA keeps a record of all changes to the elements of the proxy, |
| which it uses to make sure the proper results are always returned from |
| collection and map methods, and to update the field's database record on commit. |
| </p><p> |
| In order to use large result set proxies in JPA, add the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/LRS.html" target="_top"><code class="classname"> |
| org.apache.openjpa.persistence.LRS</code></a> annotation to the |
| persistent field. |
| </p><p> |
| The following restrictions apply to large result set fields: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| The field must be declared as either a <code class="classname">java.util.Collection |
| </code> or <code class="classname">java.util.Map</code>. It cannot be declared as |
| any other type, including any sub-interface of collection or map, or any |
| concrete collection or map class. |
| </p></li><li><p> |
| The field cannot have an externalizer (see |
| <a href="#ref_guide_pc_extern" title="6.5. Externalization">Section 6.5, “ |
| Externalization |
| ”</a>). |
| </p></li><li><p> |
| Because they rely on their owning object for context, large result set proxies |
| cannot be transferred from one persistent field to another. The following code |
| would result in an error on commit: |
| </p><pre class="programlisting"> |
| Collection employees = company.getEmployees() // employees is a lrs collection |
| company.setEmployees(null); |
| anotherCompany.setEmployees(employees); |
| </pre></li></ul></div><div class="example"><a name="ref_guide_pc_scos_proxy_lrs_extension"></a><p class="title"><b>Example 5.13. |
| Marking a Large Result Set Field |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| import org.apache.openjpa.persistence.*; |
| |
| @Entity |
| public class Company { |
| |
| @ManyToMany |
| @LRS private Collection<Employee> employees; |
| |
| ... |
| } |
| </pre></div></div><br class="example-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="ref_guide_pc_scos_proxy_custom"></a>6.4.3. |
| Custom Proxies |
| </h4></div></div></div><a class="indexterm" name="d0e22927"></a><a class="indexterm" name="d0e22932"></a><p> |
| OpenJPA manages proxies through the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/util/ProxyManager.html" target="_top"><code class="classname"> |
| org.apache.openjpa.util.ProxyManager</code></a> interface. OpenJPA |
| includes a default proxy manager, the <code class="classname"> |
| org.apache.openjpa.util.ProxyManagerImpl</code> (with a plugin alias name |
| of <code class="literal">default</code>), that will meet the needs of most users. The |
| default proxy manager understands the following configuration properties: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">TrackChanges</code>: Whether to use |
| <a href="#ref_guide_pc_scos_proxy_smart" title="6.4.1. Smart Proxies">smart proxies</a>. Defaults to |
| <code class="literal">true</code>. |
| </p></li><li><p> |
| <code class="literal">AssertAllowedType</code>: Whether to immediately throw an exception |
| if you attempt to add an element to a collection or map that is not assignable |
| to the element type declared in metadata. Defaults to <code class="literal">false</code>. |
| </p></li></ul></div><p> |
| The default proxy manager can proxy the standard methods of any |
| <code class="classname">Collection</code>, <code class="classname">List</code>, |
| <code class="classname">Map</code>, <code class="classname">Queue</code>, |
| <code class="classname">Date</code>, or <code class="classname">Calendar</code> class, |
| including custom implementations. It can also proxy custom classes whose |
| accessor and mutator methods follow JavaBean naming conventions. Your custom |
| types must, however, meet the following criteria: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| Custom container types must have a public no-arg constructor or a public |
| constructor that takes a single <code class="classname">Comparator</code> parameter. |
| </p></li><li><p> |
| Custom date types must have a public no-arg constructor or a public |
| constructor that takes a single <code class="classname">long</code> parameter |
| representing the current time. |
| </p></li><li><p> |
| Other custom types must have a public no-arg constructor or a public copy |
| constructor. If a custom types does not have a copy constructor, it must be |
| possible to fully copy an instance A by creating a new instance B and calling |
| each of B's setters with the value from the corresponding getter on A. |
| </p></li></ul></div><p> |
| If you have custom classes that must be proxied and do not meet these |
| requirements, OpenJPA allows you to define your own proxy classes and |
| your own proxy manager. See the <code class="literal">openjpa.util</code> package |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/" target="_top">Javadoc</a> for details on the interfaces involved, |
| and the utility classes OpenJPA provides to assist you. |
| </p><p> |
| You can plug your custom proxy manager into the OpenJPA runtime through the |
| <a href="#openjpa.ProxyManager" title="5.49. openjpa.ProxyManager"><code class="literal"> openjpa.ProxyManager</code> |
| </a> configuration property. |
| </p><div class="example"><a name="ref_guide_pc_scos_proxy_custom_ex"></a><p class="title"><b>Example 5.14. |
| Configuring the Proxy Manager |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| <property name="openjpa.ProxyManager" value="TrackChanges=false"/> |
| </pre></div></div><br class="example-break"></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_pc_extern"></a>6.5. |
| Externalization |
| </h3></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#ref_guide_pc_extern_values">6.5.1. |
| External Values |
| </a></span></dt></dl></div><a class="indexterm" name="d0e23030"></a><a class="indexterm" name="d0e23033"></a><p> |
| OpenJPA offers the ability to write |
| <a href="#ref_guide_mapping_custom_field" title="14.3. Custom Field Mapping">custom field mappings</a> in |
| order to have complete control over the mechanism with which fields are stored, |
| queried, and loaded from the datastore. Often, however, a custom mapping is |
| overkill. There is often a simple transformation from a Java field value to its |
| database representation. Thus, OpenJPA provides the externalization service. |
| Externalization allows you to specify methods that will externalize a field |
| value to its database equivalent on store and then rebuild the value from its |
| externalized form on load. |
| </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| Fields of embeddable classes used for <code class="literal">@EmbeddedId</code> values in |
| JPA cannot have externalizers. |
| </p></div><p> |
| The OpenJPA |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/Externalizer.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.Externalizer</code></a> |
| annotation sets the name of a method that will be invoked to convert |
| the field into its external form for database storage. You can specify either |
| the name of a non-static method, which will be invoked on the field value, or a |
| static method, which will be invoked with the field value as a parameter. Each |
| method can also take an optional |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/kernel/StoreContext.html" target="_top"><code class="classname"> |
| StoreContext</code></a> parameter for access to a persistence context. |
| The return value of the method is the field's external form. By default, OpenJPA |
| assumes that all named methods belong to the field value's class (or its |
| superclasses). You can, however, specify static methods of other classes using |
| the format <code class="literal"><class-name>.<method-name></code>. |
| </p><p> |
| Given a field of type <code class="classname">CustomType</code> that externalizes to a |
| string, the table below demonstrates several possible externalizer methods and |
| their corresponding metadata extensions. |
| </p><div class="table"><a name="d0e23070"></a><p class="title"><b>Table 5.1. |
| Externalizer Options |
| </b></p><div class="table-contents"><table summary="
 Externalizer Options
 " border="1"><colgroup><col align="left"><col align="left"></colgroup><thead><tr><th align="left"> |
| Method |
| </th><th align="left"> |
| Extension |
| </th></tr></thead><tbody><tr><td align="left"> |
| <code class="literal"> |
| public String CustomType.toString() |
| </code> |
| </td><td align="left"> |
| <code class="literal"> |
| @Externalizer("toString") |
| </code> |
| </td></tr><tr><td align="left"> |
| <code class="literal"> |
| public String CustomType.toString(StoreContext ctx) |
| </code> |
| </td><td align="left"> |
| <code class="literal"> |
| @Externalizer("toString") |
| </code> |
| </td></tr><tr><td align="left"> |
| <code class="literal"> |
| public static String AnyClass.toString(CustomType ct) |
| </code> |
| </td><td align="left"> |
| <code class="literal"> |
| @Externalizer("AnyClass.toString") |
| </code> |
| </td></tr><tr><td align="left"> |
| <code class="literal"> |
| public static String AnyClass.toString(CustomType ct, StoreContext ctx) |
| </code> |
| </td><td align="left"> |
| <code class="literal"> |
| @Externalizer("AnyClass.toString") |
| </code> |
| </td></tr></tbody></table></div></div><br class="table-break"><p> |
| The OpenJPA |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/Factory.html" target="_top"><code class="classname"> |
| org.apache.openjpa.persistence.Factory</code></a> annotation |
| contains the name of a method that will be invoked to instantiate the field from |
| the external form stored in the database. Specify a static method name. The |
| method will be invoked with the externalized value and must return an |
| instance of the field type. The method can also take an optional |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/kernel/StoreContext.html" target="_top"><code class="classname"> |
| StoreContext</code></a> parameter for access to a persistence context. |
| If a factory is not specified, OpenJPA will use the constructor of the field |
| type that takes a single argument of the external type, or will throw an |
| exception if no constructor with that signature exists. |
| </p><p> |
| Given a field of type <code class="classname">CustomType</code> that externalizes to a |
| string, the table below demonstrates several possible factory methods and their |
| corresponding metadata extensions. |
| </p><div class="table"><a name="d0e23142"></a><p class="title"><b>Table 5.2. |
| Factory Options |
| </b></p><div class="table-contents"><table summary="
 Factory Options
 " border="1"><colgroup><col align="left"><col align="left"></colgroup><thead><tr><th align="left"> |
| Method |
| </th><th align="left"> |
| Extension |
| </th></tr></thead><tbody><tr><td align="left"> |
| <code class="literal"> |
| public CustomType(String str) |
| </code> |
| </td><td align="left"> |
| none |
| </td></tr><tr><td align="left"> |
| <code class="literal"> |
| public static CustomType CustomType.fromString(String str) |
| </code> |
| </td><td align="left"> |
| <code class="literal"> |
| @Factory("fromString") |
| </code> |
| </td></tr><tr><td align="left"> |
| <code class="literal"> |
| public static CustomType CustomType.fromString(String str, StoreContext ctx) |
| </code> |
| </td><td align="left"> |
| <code class="literal"> |
| @Factory("fromString") |
| </code> |
| </td></tr><tr><td align="left"> |
| <code class="literal"> |
| public static CustomType AnyClass.fromString(String str) |
| </code> |
| </td><td align="left"> |
| <code class="literal"> |
| @Factory("AnyClass.fromString") |
| </code> |
| </td></tr><tr><td align="left"> |
| <code class="literal"> |
| public static CustomType AnyClass.fromString(String str, StoreContext ctx) |
| </code> |
| </td><td align="left"> |
| <code class="literal"> |
| @Factory("AnyClass.fromString") |
| </code> |
| </td></tr></tbody></table></div></div><br class="table-break"><p> |
| If your externalized field is not a standard persistent type, you must |
| explicitly mark it persistent. In OpenJPA, you can force a persistent field |
| by annotating it with <a href="#ref_guide_meta_jpa_persistent" title="3.3. Persistent Field Values"><code class="classname"> |
| org.apache.openjpa.persistence.Persistent</code></a> annotation. |
| </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| If your custom field type is mutable and is not a standard collection, map, or |
| date class, OpenJPA will not be able to detect changes to the field. You must |
| mark the field dirty manually, or create a custom field proxy. |
| See |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/OpenJPAEntityManager.html" target="_top"> |
| <code class="methodname">OpenJPAEntityManager.dirty</code></a> for how to mark a |
| field dirty manually in JPA. |
| See <a href="#ref_guide_pc_scos_proxy" title="6.4. Proxies">Section 6.4, “ |
| Proxies |
| ”</a> for a discussion of proxies. |
| </p></div><p> |
| You can externalize a field to virtually any value that is supported by |
| OpenJPA's field mappings (embedded relations are the exception; you must declare |
| your field to be a persistence-capable type in order to embed it). This means |
| that a field can externalize to something as simple as a primitive, something as |
| complex as a collection or map of entities, or anything in |
| between. If you do choose to externalize to a collection or map, OpenJPA |
| recognizes a family of metadata extensions for specying type information for the |
| externalized form of your fields - see <a href="#type" title="4.2.6. Type">Section 4.2.6, “ |
| Type |
| ”</a>. If the |
| external form of your field is an entity object or contains entities, OpenJPA |
| will correctly include the objects in its persistence-by-reachability |
| algorithms and its delete-dependent algorithms. |
| </p><p> |
| The example below demonstrates a few forms of externalization. |
| </p><div class="example"><a name="ref_guide_pc_externex"></a><p class="title"><b>Example 5.15. |
| Using Externalization |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| import org.apache.openjpa.persistence.*; |
| |
| @Entity |
| public class Magazine { |
| |
| // use Class.getName and Class.forName to go to/from strings |
| @Persistent |
| @Externalizer("getName") |
| @Factory("forName") |
| private Class cls; |
| |
| // use URL.getExternalForm for externalization. no factory; |
| // we can rely on the URL string constructor |
| @Persistent |
| @Externalizer("toExternalForm") |
| private URL url; |
| |
| // use our custom methods |
| @Persistent |
| @Externalizer("Magazine.authorsFromCustomType") |
| @Factory("Magazine.authorsToCustomType") |
| @ElementType(Author.class) |
| private CustomType customType; |
| |
| public static Collection authorsFromCustomType(CustomType customType) { |
| ... logic to pack custom type into a list of authors ... |
| } |
| |
| public static CustomType authorsToCustomType (Collection authors) { |
| ... logic to create custom type from a collection of authors ... |
| } |
| |
| ... |
| } |
| </pre></div></div><br class="example-break"><p> |
| <a class="indexterm" name="d0e23236"></a> |
| You can query externalized fields using parameters. Pass in a value of the field |
| type when executing the query. OpenJPA will externalize the parameter using the |
| externalizer method named in your metadata, and compare the externalized |
| parameter with the value stored in the database. As a shortcut, OpenJPA also |
| allows you to use parameters or literals of the field's externalized type in |
| queries, as demonstrated in the example below. |
| </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| Currently, queries are limited to fields that externalize to a primitive, |
| primitive wrapper, string, or date types, due to constraints on query syntax. |
| </p></div><div class="example"><a name="ref_guide_pc_extern_queryex"></a><p class="title"><b>Example 5.16. |
| Querying Externalization Fields |
| </b></p><div class="example-contents"><p> |
| Assume the <code class="classname">Magazine</code> class has the same fields as in the |
| previous example. |
| </p><pre class="programlisting"> |
| // you can query using parameters |
| Query q = em.createQuery("select m from Magazine m where m.url = :u"); |
| q.setParameter("u", new URL("http://www.solarmetric.com")); |
| List results = q.getResultList(); |
| |
| // or as a shortcut, you can use the externalized form directly |
| q = em.createQuery("select m from Magazine m where m.url = 'http://www.solarmetric.com'"); |
| results = q.getResultList(); |
| </pre></div></div><br class="example-break"><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="ref_guide_pc_extern_values"></a>6.5.1. |
| External Values |
| </h4></div></div></div><a class="indexterm" name="d0e23258"></a><p> |
| Externalization often takes simple constant values and transforms them to |
| constant values of a different type. An example would be storing a <code class="classname"> |
| boolean</code> field as a <code class="classname">char</code>, where <code class="literal">true |
| </code> and <code class="literal">false</code> would be stored in the database as |
| <code class="literal">'T'</code> and <code class="literal">'F'</code> respectively. |
| </p><p> |
| OpenJPA allows you to define these simple translations in metadata, so that the |
| field behaves as in <a href="#ref_guide_pc_extern" title="6.5. Externalization">full-fledged |
| externalization</a> without requiring externalizer and factory methods. |
| External values supports translation of pre-defined simple types (primitives, |
| primitive wrappers, and Strings), to other pre-defined simple values. |
| </p><p> |
| Use the OpenJPA |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/ExternalValues.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.ExternalValues</code></a> |
| annotation to define external value translations. The values are |
| defined in a format similar to that of <a href="#ref_guide_conf_plugins" title="4. Plugin Configuration"> |
| configuration plugins</a>, except that the value pairs represent Java and |
| datastore values. To convert the Java boolean values of <code class="literal">true</code> |
| and <code class="literal">false</code> to the character values <code class="literal">T</code> and |
| <code class="literal">F</code>, for example, you would use the extension value: <code class="literal"> |
| true=T,false=F</code>. |
| </p><p> |
| If the type of the datastore value is different from the field's type, use the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/Type.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.Type</code></a> annotation |
| to define the datastore type. |
| </p><div class="example"><a name="externvalues_ex"></a><p class="title"><b>Example 5.17. |
| Using External Values |
| </b></p><div class="example-contents"><p> |
| This example uses external value translation to transform a string field to an |
| integer in the database. |
| </p><pre class="programlisting"> |
| public class Magazine { |
| |
| @ExternalValues({"SMALL=5", "MEDIUM=8", "LARGE=10"}) |
| @Type(int.class) |
| private String sizeWidth; |
| |
| ... |
| } |
| </pre></div></div><br class="example-break"></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_fetch"></a>7. |
| Fetch Groups |
| </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#ref_guide_fetch_custom">7.1. |
| Custom Fetch Groups |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_fetch_conf">7.2. |
| Custom Fetch Group Configuration |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_fetch_single_field">7.3. |
| Per-field Fetch Configuration |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_fetch_impl">7.4. |
| Implementation Notes |
| </a></span></dt></dl></div><a class="indexterm" name="d0e23330"></a><p> |
| Fetch groups are sets of fields that load together. They can be used to to pool |
| together associated fields in order to provide performance improvements over |
| standard data fetching. Specifying fetch groups allows for tuning of lazy |
| loading and eager fetching behavior. |
| </p><p> |
| The JPA Overview's <a href="#jpa_overview_meta_fetch" title="2.6.1. Fetch Type">Section 2.6.1, “ |
| Fetch Type |
| ”</a> describes how |
| to use JPA metadata annotations to control whether a field is fetched eagerly or |
| lazily. Fetch groups add a dynamic aspect to this standard ability. As you will |
| see, OpenJPA's JPA extensions allow you can add and remove fetch groups at |
| runtime to vary the sets of fields that are eagerly loaded. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_fetch_custom"></a>7.1. |
| Custom Fetch Groups |
| </h3></div></div></div><p> |
| OpenJPA places any field that is eagerly loaded according to the JPA metadata |
| rules into the built-in <span class="emphasis"><em>default</em></span> fetch group. As its name |
| implies, the default fetch group is active by default. You may also |
| define your own named fetch groups and activate or deactivate them at runtime, |
| as described later in this chapter. OpenJPA will eagerly-load the fields in all |
| active fetch groups when loading objects from the datastore. |
| </p><p> |
| You create fetch groups with the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/FetchGroup.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.FetchGroup</code></a> |
| annotation. If your class only has one custom fetch group, you can place this |
| annotation directly on the class declaration. Otherwise, use the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/FetchGroups.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.FetchGroups</code></a> |
| annotation to declare an array of individual <code class="classname">FetchGroup</code> |
| values. The <code class="classname">FetchGroup</code> annotation has the following |
| properties: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">String name</code>: The name of the fetch group. Fetch group names |
| are global, and are expected to be shared among classes. For example, a shopping |
| website may use a <span class="emphasis"><em>detail</em></span> fetch group in each product class |
| to efficiently load all the data needed to display a product's "detail" page. |
| The website might also define a sparse <span class="emphasis"><em>list</em></span> fetch group |
| containing only the fields needed to display a table of products, as in a search |
| result. |
| </p><p> |
| The following names are reserved for use by OpenJPA: <code class="literal">default</code> |
| , <code class="literal">values</code>, <code class="literal">all</code>, <code class="literal">none</code>, |
| and any name beginning with <code class="literal">jdo</code>, <code class="literal">jpa</code>, or |
| <code class="literal">openjpa</code>. |
| </p></li><li><p> |
| <code class="literal">FetchAttribute[] attributes</code>: The set of persistent fields or |
| properties in the fetch group. |
| </p></li><li><p> |
| <code class="literal">String[] fetchGroups</code>: Other fetch groups whose fields to |
| include in this group. |
| </p></li></ul></div><p> |
| As you might expect, listing a |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/FetchAttribute.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.FetchAttribute</code></a> |
| within a <code class="classname">FetchGroup</code> includes the corresponding persistent |
| field or property in the fetch group. Each <code class="classname">FetchAttribute</code> |
| has the following properties: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">String name</code>: The name of the persistent field or property to |
| include in the fetch group. |
| </p></li><li><p> |
| <code class="literal">recursionDepth</code>: If the attribute represents a relation, the |
| maximum number of same-typed relations to eager-fetch from this field. Defaults |
| to 1. For example, consider an <code class="classname">Employee</code> class with a |
| <code class="literal">manager</code> field, also of type <code class="classname">Employee</code>. |
| When we load an <code class="classname">Employee</code> and the <code class="literal"> |
| manager</code> field is in an active fetch group, the recursion depth (along |
| with the max fetch depth setting, described below) determines whether we only |
| retrieve the target <code class="classname">Employee</code> and his manager (depth 1), |
| or whether we also retrieve the manager's manager (depth 2), or the manager's |
| manager's manager (depth 3), etc. Use -1 for unlimited depth. |
| </p></li></ul></div><div class="example"><a name="ref_guide_fetch_customgroups"></a><p class="title"><b>Example 5.18. |
| Custom Fetch Group Metadata |
| </b></p><div class="example-contents"><p> |
| Creates a <span class="emphasis"><em>detail</em></span> fetch group consisting of the |
| <code class="literal">publisher</code> and <code class="literal">articles</code> relations. |
| </p><pre class="programlisting"> |
| import org.apache.openjpa.persistence.*; |
| |
| @Entity |
| @FetchGroups({ |
| @FetchGroup(name="detail", attributes={ |
| @FetchAttribute(name="publisher"), |
| @FetchAttribute(name="articles") |
| }), |
| ... |
| }) |
| public class Magazine { |
| ... |
| } |
| </pre></div></div><br class="example-break"><p> |
| A field can be a member of any number of fetch groups. A field can also |
| declare a <span class="emphasis"><em>load fetch group</em></span>. |
| When you access a lazy-loaded field for the first time, OpenJPA makes a |
| datastore trip to fetch that field's data. Sometimes, however, you know |
| that whenever you access a lazy field A, you're likely to access lazy fields B |
| and C as well. Therefore, it would be more efficient to fetch the data for A, |
| B, and C in the same datastore trip. By setting A's load fetch group to the |
| name of a <a href="#ref_guide_fetch" title="7. Fetch Groups">fetch group</a> containing B and |
| C, you can tell OpenJPA to load all of these fields together when A is first |
| accessed. |
| </p><p> |
| Use OpenJPA's |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/LoadFetchGroup.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.LoadFetchGroup</code></a> |
| annotation to specify the load fetch group of any persistent field. The value of |
| the annotation is the name of a declared fetch group whose members should be |
| loaded along with the annotated field. |
| </p><div class="example"><a name="ref_guide_fetch_loadgroup"></a><p class="title"><b>Example 5.19. |
| Load Fetch Group Metadata |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| import org.apache.openjpa.persistence.*; |
| |
| @Entity |
| @FetchGroups({ |
| @FetchGroup(name="detail", attributes={ |
| @FetchAttribute(name="publisher"), |
| @FetchAttribute(name="articles") |
| }), |
| ... |
| }) |
| public class Magazine { |
| |
| @ManyToOne(fetch=FetchType.LAZY) |
| @LoadFetchGroup("detail") |
| private Publisher publisher; |
| |
| ... |
| } |
| </pre></div></div><br class="example-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_fetch_conf"></a>7.2. |
| Custom Fetch Group Configuration |
| </h3></div></div></div><a class="indexterm" name="d0e23496"></a><p> |
| <a class="indexterm" name="d0e23503"></a> |
| You can control the default set of fetch groups with the |
| <a href="#openjpa.FetchGroups" title="5.31. openjpa.FetchGroups"><code class="literal">openjpa.FetchGroups</code> |
| </a> configuration property. Set this property to a comma-separated list of |
| fetch group names. |
| </p><p> |
| You can also set the system's default maximum fetch depth with the |
| <a href="#openjpa.MaxFetchDepth" title="5.41. openjpa.MaxFetchDepth"><code class="literal">openjpa.MaxFetchDepth</code> |
| </a> configuration property. The maximum fetch depth determines how "deep" |
| into the object graph to traverse when loading an instance. For example, with |
| a <code class="literal">MaxFetchDepth</code> of 1, OpenJPA will load at most the target |
| instance and its immediate relations. With a <code class="literal">MaxFetchDepth</code> |
| of 2, OpenJPA may load the target instance, its immediate relations, and |
| the relations of those relations. This works to arbitrary depth. In fact, |
| the default <code class="literal">MaxFetchDepth</code> value is -1, which symbolizes |
| infinite depth. Under this setting, OpenJPA will fetch configured relations |
| until it reaches the edges of the object graph. Of course, which relation |
| fields are loaded depends on whether the fields are eager or lazy, and on the |
| active fetch groups. A fetch group member's recursion depth may also limit |
| the fetch depth to something less than the configured maximum. |
| </p><p> |
| OpenJPA's <code class="classname">OpenJPAEntityManager</code> and <code class="classname"> |
| OpenJPAQuery</code> extensions to the standard <code class="classname">EntityManager |
| </code> and <code class="classname">Query</code> interfaces provide access to a |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/FetchPlan.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.FetchPlan</code></a> object. |
| The <code class="classname">FetchPlan</code> maintains the set of active fetch groups |
| and the maximum fetch depth. It begins with the groups and depth defined in the |
| <code class="literal">openjpa.FetchGroups</code> and <code class="literal">openjpa.MaxFetchDepth |
| </code> properties, but allows you to add or remove groups and change the |
| maximum fetch depth for an individual <code class="classname">EntityManager</code> or |
| <code class="classname">Query</code> through the methods below. |
| </p><pre class="programlisting"> |
| public FetchPlan addFetchGroup(String group); |
| public FetchPlan addFetchGroups(String... groups); |
| public FetchPlan addFetchGroups(Collection groups); |
| public FetchPlan removeFetchGrop(String group); |
| public FetchPlan removeFetchGroups(String... groups); |
| public FetchPlan removeFetchGroups(Collection groups); |
| public FetchPlan resetFetchGroups(); |
| public Collection<String> getFetchGroups(); |
| public void clearFetchGroups(); |
| public FetchPlan setMaxFetchDepth(int depth); |
| public int getMaxFetchDepth(); |
| </pre><p> |
| <a href="#ref_guide_runtime" title="Chapter 9. Runtime Extensions">Chapter 9, <i xmlns:xlink="http://www.w3.org/1999/xlink"> |
| Runtime Extensions |
| </i></a> details the <code class="classname"> |
| OpenJPAEntityManager</code>, <code class="classname">OpenJPAQuery</code>, and |
| <code class="classname">FetchPlan</code> interfaces. |
| </p><div class="example"><a name="ref_guide_fetch_conf_query"></a><p class="title"><b>Example 5.20. |
| Using the FetchPlan |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| import org.apache.openjpa.persistence.*; |
| |
| ... |
| |
| OpenJPAQuery kq = OpenJPAPersistence.cast(em.createQuery(...)); |
| kq.getFetchPlan().setMaxFetchDepth(3).addFetchGroup("detail"); |
| List results = kq.getResultList(); |
| </pre></div></div><br class="example-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_fetch_single_field"></a>7.3. |
| Per-field Fetch Configuration |
| </h3></div></div></div><a class="indexterm" name="d0e23587"></a><p> |
| In addition to controlling fetch configuration on a per-fetch-group basis, you |
| can configure OpenJPA to include particular fields in the current fetch |
| plan. This allows you to add individual fields that are not in the |
| default fetch group or in any other active fetch groups to the set of |
| fields that will be eagerly loaded from the database. |
| </p><p> |
| JPA <code class="classname">FetchPlan</code> methods: |
| </p><pre class="programlisting"> |
| public FetchPlan addField(String field); |
| public FetchPlan addFields(String... fields); |
| public FetchPlan addFields(Class cls, String... fields); |
| public FetchPlan addFields(Collection fields); |
| public FetchPlan addFields(Class cls, Collection fields); |
| public FetchPlan removeField(String field); |
| public FetchPlan removeFields(String... fields); |
| public FetchPlan removeFields(Class cls, String... fields); |
| public FetchPlan removeFields(Collection fields); |
| public FetchPlan removeFields(Class cls, Collection fields); |
| public Collection<String> getFields(); |
| public void clearFields(); |
| </pre><p> |
| The methods that take only string arguments use the fully-qualified field name, |
| such as <code class="literal">org.mag.Magazine.publisher</code>. Similarly, <code class="methodname"> |
| getFields</code> returns the set of fully-qualified field names. In all |
| methods, the named field must be defined in the class specified in the |
| invocation, not a superclass. So, if the field <code class="literal">publisher</code> is |
| defined in base class <code class="classname">Publication</code> rather than subclass |
| <code class="classname">Magazine</code>, you must invoke <code class="literal">addField |
| (Publication.class, "publisher")</code> and not <code class="literal">addField |
| (Magazine.class, "publisher")</code>. This is stricter than Java's default |
| field-masking algorithms, which would allow the latter method behavior if |
| <code class="literal">Magazine</code> did not also define a field called <code class="literal"> |
| publisher</code>. |
| </p><p> |
| In order to avoid the cost of reflection, OpenJPA does not perform any |
| validation of the field name / class name pairs that you put into the fetch |
| configuration. If you specify non-existent class / field pairs, nothing adverse |
| will happen, but you will receive no notification of the fact that the specified |
| configuration is not being used. |
| </p><div class="example"><a name="ref_guide_fetch-conf_per_field"></a><p class="title"><b>Example 5.21. |
| Adding an Eager Field |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| import org.apache.openjpa.persistence.*; |
| |
| ... |
| |
| OpenJPAEntityManager kem = OpenJPAPersistence.cast(em); |
| kem.getFetchPlan().addField(Magazine.class, "publisher"); |
| Magazine mag = em.find(Magazine.class, magId); |
| </pre></div></div><br class="example-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_fetch_impl"></a>7.4. |
| Implementation Notes |
| </h3></div></div></div><div class="itemizedlist"><ul type="disc"><li><p> |
| Even when a direct relation is not eagerly fetched, OpenJPA selects the foreign |
| key columns and caches the values. This way when you do traverse the relation, |
| OpenJPA can often find the related object in its cache, or at least avoid joins |
| when loading the related object from the database. |
| </p></li><li><p> |
| The above implicit foreign key-selecting behavior does not always apply when the |
| relation is in a subclass table. If the subclass table would not otherwise be |
| joined into the select, OpenJPA avoids the extra join just to select the foreign |
| key values. |
| </p></li></ul></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_perfpack_eager"></a>8. |
| Eager Fetching |
| </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#ref_guide_perfpack_eager_conf">8.1. |
| Configuring Eager Fetching |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_perfpack_eager_consider">8.2. |
| Eager Fetching Considerations and Limitations |
| </a></span></dt></dl></div><a class="indexterm" name="d0e23650"></a><a class="indexterm" name="d0e23653"></a><a class="indexterm" name="d0e23658"></a><a class="indexterm" name="d0e23665"></a><p> |
| Eager fetching is the ability to efficiently load subclass data and related |
| objects along with the base instances being queried. Typically, OpenJPA has to |
| make a trip to the database whenever a relation is loaded, or when you first |
| access data that is mapped to a table other than the least-derived superclass |
| table. If you perform a query that returns 100 <code class="classname">Person</code> |
| objects, and then you have to retrieve the <code class="classname">Address</code> for |
| each person, OpenJPA may make as many as 101 queries (the initial query, plus |
| one for the address of each person returned). Or if some of the <code class="classname"> |
| Person</code> instances turn out to be <code class="classname">Employee</code>s, |
| where <code class="classname">Employee</code> has additional data in its own joined |
| table, OpenJPA once again might need to make extra database trips to access the |
| additional employee data. With eager fetching, OpenJPA can reduce these cases to |
| a single query. |
| </p><p> |
| Eager fetching only affects relations in the active fetch groups, and is limited |
| by the declared maximum fetch depth and field recursion depth (see |
| <a href="#ref_guide_fetch" title="7. Fetch Groups">Section 7, “ |
| Fetch Groups |
| ”</a>). In other words, relations that would |
| not normally be loaded immediately when retrieving an object or accessing a |
| field are not affected by eager fetching. In our example above, the address of |
| each person would only be eagerly fetched if the query were configured to |
| include the address field or its fetch group, or if the address were in the |
| default fetch group. This allows you to control exactly which fields are eagerly |
| fetched in different situations. Similarly, queries that exclude subclasses |
| aren't affected by eager subclass fetching, described below. |
| </p><p> |
| Eager fetching has three modes: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">none</code>: No eager fetching is performed. Related objects are |
| always loaded in an independent select statement. No joined subclass data is |
| loaded unless it is in the table(s) for the base type being queried. Unjoined |
| subclass data is loaded using separate select statements rather than a SQL UNION |
| operation. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e23705"></a> |
| <code class="literal">join</code>: In this mode, OpenJPA joins to to-one relations in the |
| configured fetch groups. If OpenJPA is loading data for a single instance, then |
| OpenJPA will also join to any collection field in the configured fetch groups. |
| When loading data for multiple instances, though, (such as when executing a |
| <code class="classname">Query</code>) OpenJPA will not join to collections by default. |
| Instead, OpenJPA defaults to <code class="literal">parallel</code> mode for collections, |
| as described below. You can force OpenJPA use a join rather than parallel mode |
| for a collection field using the metadata extension described in |
| <a href="#eager-fetch-mode" title="13.2.1. Eager Fetch Mode">Section 13.2.1, “ |
| Eager Fetch Mode |
| ”</a>. |
| </p><p> |
| <a class="indexterm" name="d0e23724"></a> |
| Under <code class="literal">join</code> mode, OpenJPA uses a left outer join (or inner |
| join, if the relations' field metadata declares the relation non-nullable) to |
| select the related data along with the data for the target objects. This process |
| works recursively for to-one joins, so that if <code class="classname">Person</code> has |
| an <code class="classname">Address</code>, and <code class="classname">Address</code> has a |
| <code class="classname">TelephoneNumber</code>, and the fetch groups are configured |
| correctly, OpenJPA might issue a single select that joins across the tables for |
| all three classes. To-many joins can not recursively spawn other to-many joins, |
| but they can spawn recursive to-one joins. |
| </p><p> |
| Under the <code class="literal">join</code> subclass fetch mode, subclass data in joined |
| tables is selected by outer joining to all possible subclass tables of the type |
| being queried. As you'll see below, subclass data fetching is configured |
| separately from relation fetching, and can be disabled for specific classes. |
| </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| Some databases may not support outer joins. Also, OpenJPA can not use |
| outer joins if you have set the <a href="#openjpa.jdbc.DBDictionary" title="6.2. openjpa.jdbc.DBDictionary"> |
| <code class="literal"> DBDictionary</code></a>'s <code class="literal">JoinSyntax</code> to |
| <code class="literal">traditional</code>. See <a href="#ref_guide_dbsetup_sql92" title="6. Setting the SQL Join Syntax">Section 6, “ |
| Setting the SQL Join Syntax |
| ”</a>. |
| </p></div></li><li><p> |
| <a class="indexterm" name="d0e23767"></a> |
| <code class="literal">parallel</code>: Under this mode, OpenJPA selects to-one relations |
| and joined collections as outlined in the <code class="literal">join</code> mode |
| description above. Unjoined collection fields, however, are eagerly fetched |
| using a separate select statement for each collection, executed in parallel with |
| the select statement for the target objects. The parallel selects use the |
| <code class="literal">WHERE</code> conditions from the primary select, but add their own |
| joins to reach the related data. Thus, if you perform a query that returns 100 |
| <code class="classname">Company</code> objects, where each company has a list of |
| <code class="classname">Employee</code> objects and <code class="classname">Department</code> |
| objects, OpenJPA will make 3 queries. The first will select the company objects, |
| the second will select the employees for those companies, and the third will |
| select the departments for the same companies. Just as for joins, this process |
| can be recursively applied to the objects in the relations being eagerly |
| fetched. Continuing our example, if the <code class="classname">Employee</code> class |
| had a list of <code class="classname">Projects</code> in one of the fetch groups being |
| loaded, OpenJPA would execute a single additional select in parallel to load the |
| projects of all employees of the matching companies. |
| </p><p> |
| Using an additional select to load each collection avoids transferring more data |
| than necessary from the database to the application. If eager joins were used |
| instead of parallel select statements, each collection added to the configured |
| fetch groups would cause the amount of data being transferred to rise |
| dangerously, to the point that you could easily overwhelm the network. |
| </p><p> |
| Polymorphic to-one relations to table-per-class mappings use parallel eager |
| fetching because proper joins are impossible. You can force other to-one |
| relations to use parallel rather than join mode eager fetching using the |
| metadata extension described in <a href="#eager-fetch-mode" title="13.2.1. Eager Fetch Mode">Section 13.2.1, “ |
| Eager Fetch Mode |
| ”</a>. |
| </p><p> |
| Parallel subclass fetch mode only applies to queries on joined inheritance |
| hierarchies. Rather than outer-joining to |
| subclass tables, OpenJPA will issue the query separately for each subclass. In |
| all other situations, parallel subclass fetch mode acts just like join mode in |
| regards to vertically-mapped subclasses. |
| </p><p> |
| When OpenJPA knows that it is selecting for a single object only, it never uses |
| <code class="literal">parallel</code> mode, because the additional selects can be made |
| lazily just as efficiently. This mode only increases efficiency over <code class="literal"> |
| join</code> mode when multiple objects with eager relations are being loaded, |
| or when multiple selects might be faster than joining to all possible |
| subclasses. |
| </p></li></ul></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_perfpack_eager_conf"></a>8.1. |
| Configuring Eager Fetching |
| </h3></div></div></div><a class="indexterm" name="d0e23816"></a><p> |
| <a class="indexterm" name="d0e23823"></a> |
| <a class="indexterm" name="d0e23827"></a> |
| <a class="indexterm" name="d0e23831"></a> |
| <a class="indexterm" name="d0e23837"></a> |
| You can control OpenJPA's default eager fetch mode through the |
| <a href="#openjpa.jdbc.EagerFetchMode" title="6.4. openjpa.jdbc.EagerFetchMode"><code class="literal"> |
| openjpa.jdbc.EagerFetchMode</code></a> and |
| <a href="#openjpa.jdbc.SubclassFetchMode" title="6.16. openjpa.jdbc.SubclassFetchMode"><code class="literal"> |
| openjpa.jdbc.SubclassFetchMode</code></a> configuration properties. Set |
| each of these properties to one of the mode names described in the previous |
| section: <code class="literal">none, join, parallel</code>. If left unset, the eager |
| fetch mode defaults to <code class="literal">parallel</code> and the subclass fetch mode |
| defaults to <code class="literal">join</code> These are generally the most robust and |
| performant strategies. |
| </p><p> |
| You can easily override the default fetch modes at runtime for any lookup or |
| query through OpenJPA's fetch configuration APIs. See |
| <a href="#ref_guide_runtime" title="Chapter 9. Runtime Extensions">Chapter 9, <i xmlns:xlink="http://www.w3.org/1999/xlink"> |
| Runtime Extensions |
| </i></a> for details. |
| </p><div class="example"><a name="ref_guide_perfpack_eager_def"></a><p class="title"><b>Example 5.22. |
| Setting the Default Eager Fetch Mode |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| <property name="openjpa.jdbc.EagerFetchMode" value="parallel"/> |
| <property name="openjpa.jdbc.SubclassFetchMode" value="join"/> |
| </pre></div></div><br class="example-break"><div class="example"><a name="ref_guide_perfpack_eager_runtime"></a><p class="title"><b>Example 5.23. |
| Setting the Eager Fetch Mode at Runtime |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| import org.apache.openjpa.persistence.*; |
| import org.apache.openjpa.persistence.jdbc.*; |
| |
| ... |
| |
| Query q = em.createQuery("select p from Person p where p.address.state = 'TX'"); |
| OpenJPAQuery kq = OpenJPAPersistence.cast(q); |
| JDBCFetchPlan fetch = (JDBCFetchPlan) kq.getFetchPlan(); |
| fetch.setEagerFetchMode(FetchMode.PARALLEL); |
| fetch.setSubclassFetchMode(FetchMode.JOIN); |
| List results = q.getResultList(); |
| </pre></div></div><br class="example-break"><p> |
| You can specify a default subclass fetch mode for an individual class with the |
| metadata extension described in <a href="#subclass-fetch-mode" title="13.1.1. Subclass Fetch Mode">Section 13.1.1, “ |
| Subclass Fetch Mode |
| ”</a>. |
| Note, however, that you cannot "upgrade" the runtime fetch mode with your class |
| setting. If the runtime fetch mode is <code class="literal">none</code>, no eager |
| subclass data fetching will take place, regardless of your metadata setting. |
| </p><p> |
| This applies to the eager fetch mode metadata extension as well (see |
| <a href="#eager-fetch-mode" title="13.2.1. Eager Fetch Mode">Section 13.2.1, “ |
| Eager Fetch Mode |
| ”</a>). You can use this extension to |
| disable eager fetching on a field or to declare that a collection would rather |
| use joins than parallel selects or vice versa. But an extension value of |
| <code class="literal">join</code> won't cause any eager joining if the fetch |
| configuration's setting is <code class="literal">none</code>. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_perfpack_eager_consider"></a>8.2. |
| Eager Fetching Considerations and Limitations |
| </h3></div></div></div><p> |
| There are several important points that you should consider when using eager |
| fetching: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <a class="indexterm" name="d0e23900"></a> |
| <a class="indexterm" name="d0e23906"></a> |
| When you are using <code class="literal">parallel</code> eager fetch mode and you have |
| large result sets enabled (see <a href="#ref_guide_dbsetup_lrs" title="10. Large Result Sets">Section 10, “ |
| Large Result Sets |
| ”</a>) |
| or you place a range on a query, OpenJPA performs the needed parallel selects on |
| one page of results at a time. For example, suppose your <code class="literal"> |
| FetchBatchSize</code> is set to 20, and you perform a large result set query |
| on a class that has collection fields in the configured fetch groups. OpenJPA |
| will immediately cache the first <code class="literal">20</code> results of the query |
| using <code class="literal">join</code> mode eager fetching only. Then, it will issue the |
| extra selects needed to eager fetch your collection fields according to |
| <code class="literal">parallel</code> mode. Each select will use a SQL <code class="literal">IN |
| </code> clause (or multiple <code class="literal">OR</code> clauses if your class has a |
| compound primary key) to limit the selected collection elements to those owned |
| by the 20 cached results. |
| </p><p> |
| Once you iterate past the first 20 results, OpenJPA will cache the next 20 and |
| again issue any needed extra selects for collection fields, and so on. This |
| pattern ensures that you get the benefits of eager fetching without bringing |
| more data into memory than anticipated. |
| </p></li><li><p> |
| Once OpenJPA eager-joins into a class, it cannot issue any further eager to-many |
| joins or parallel selects from that class in the same query. To-one joins, |
| however, can recurse to any level. |
| </p></li><li><p> |
| Using a to-many join makes it impossible to determine the number of instances |
| the result set contains without traversing the entire set. This is because each |
| result object might be represented by multiple rows. Thus, queries with a range |
| specification or queries configured for lazy result set traversal automatically |
| turn off eager to-many joining. |
| </p></li><li><p> |
| OpenJPA cannot eagerly join to polymorphic relations to non-leaf classes in a |
| table-per-class inheritance hierarchy. You can work around this restriction |
| using the mapping extensions described in <a href="#nonpolymorphic" title="13.2.2. Nonpolymorphic">Section 13.2.2, “ |
| Nonpolymorphic |
| ”</a>. |
| </p></li></ul></div></div></div></div><div class="chapter" lang="en" id="ref_guide_meta"><div class="titlepage"><div><div><h2 class="title"><a name="ref_guide_meta"></a>Chapter 6. |
| Metadata |
| </h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#ref_guide_meta_factory">1. |
| Metadata Factory |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_meta_repository">2. Metadata Repository</a></span></dt><dt><span class="section"><a href="#ref_guide_meta_jpa">3. |
| Additional JPA Metadata |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_meta_jpa_datastoreid">3.1. |
| Datastore Identity |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_meta_jpa_version">3.2. |
| Surrogate Version |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_meta_jpa_persistent">3.3. |
| Persistent Field Values |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_meta_jpa_persistent_coll">3.4. Persistent Collection Fields</a></span></dt><dt><span class="section"><a href="#ref_guide_meta_jpa_persistent_map">3.5. Persistent Map Fields</a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_meta_ext">4. |
| Metadata Extensions |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_meta_class">4.1. |
| Class Extensions |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#fetch-groups">4.1.1. |
| Fetch Groups |
| </a></span></dt><dt><span class="section"><a href="#data-cache">4.1.2. |
| Data Cache |
| </a></span></dt><dt><span class="section"><a href="#detached-state-field">4.1.3. |
| Detached State |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_meta_field">4.2. |
| Field Extensions |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#dependent">4.2.1. |
| Dependent |
| </a></span></dt><dt><span class="section"><a href="#load-fetch-group">4.2.2. |
| Load Fetch Group |
| </a></span></dt><dt><span class="section"><a href="#lrs">4.2.3. |
| LRS |
| </a></span></dt><dt><span class="section"><a href="#inverse-logical">4.2.4. |
| Inverse-Logical |
| </a></span></dt><dt><span class="section"><a href="#read-only">4.2.5. |
| Read-Only |
| </a></span></dt><dt><span class="section"><a href="#type">4.2.6. |
| Type |
| </a></span></dt><dt><span class="section"><a href="#externalizer">4.2.7. |
| Externalizer |
| </a></span></dt><dt><span class="section"><a href="#factory">4.2.8. |
| Factory |
| </a></span></dt><dt><span class="section"><a href="#external-values">4.2.9. |
| External Values |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_meta_example">4.3. |
| Example |
| </a></span></dt></dl></dd></dl></div><p> |
| The JPA Overview covers JPA metadata in <a href="#jpa_overview_meta" title="Chapter 5. Metadata">Chapter 5, <i xmlns:xlink="http://www.w3.org/1999/xlink"> |
| Metadata |
| </i></a>. |
| This chapter discusses OpenJPA's extensions to standard JPA metadata. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_meta_factory"></a>1. |
| Metadata Factory |
| </h2></div></div></div><a class="indexterm" name="d0e23959"></a><p> |
| The <a href="#openjpa.MetaDataFactory" title="5.42. openjpa.MetaDataFactory"><code class="literal">openjpa.MetaDataFactory |
| </code></a> configuration property controls metadata loading and storing. |
| This property takes a plugin string (see |
| <a href="#ref_guide_conf_plugins" title="4. Plugin Configuration">Section 4, “ |
| Plugin Configuration |
| ”</a>) describing a concrete |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/meta/MetaDataFactory.html" target="_top"> |
| <code class="classname">org.apache.openjpa.meta.MetaDataFactory</code></a> |
| implementation. A metadata factory can load mapping information as well as |
| persistence metadata, or it can leave mapping information to a separate |
| <span class="emphasis"><em>mapping factory</em></span> (see |
| <a href="#ref_guide_mapping_factory" title="5. Mapping Factory">Section 5, “ |
| Mapping Factory |
| ”</a>). OpenJPA recognizes the |
| following built-in metadata factories: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">jpa</code>: Standard JPA metadata. This is an alias for the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/PersistenceMetaDataFactory.html" target="_top"> |
| <code class="classname"> |
| org.apache.openjpa.persistence.PersistenceMetaDataFactory</code></a>. |
| </p></li></ul></div><p> |
| JPA has built-in settings for listing your persistent classes, which |
| the <a href="#jpa_overview_persistence_xml" title="1. persistence.xml">JPA Overview</a> describes. |
| OpenJPA supports these JPA standard settings by translating them into its own |
| internal metadata factory properties. Each internal property represents a |
| different mechanism for locating persistent types; you can choose the mechanism |
| or combination of mechanisms that are most convenient. See |
| <a href="#ref_guide_pc_pcclasses" title="1. Persistent Class List">Section 1, “ |
| Persistent Class List |
| ”</a> for a discussion of when it is |
| necessary to list your persistent classes. |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">Types</code>: A semicolon-separated list of fully-qualified |
| persistent class names. |
| </p></li><li><p> |
| <code class="literal">Resources</code>: A semicolon-separated list of resource paths to |
| metadata files or jar archives. Each jar archive will be scanned for |
| annotated JPA entities. |
| </p></li><li><p> |
| <code class="literal">URLs</code>: A semicolon-separated list of URLs of metadata files |
| or jar archives. Each jar archive will be scanned for annotated JPA |
| entities. |
| </p></li><li><p> |
| <code class="literal">ClasspathScan</code>: A semicolon-separated list of directories or |
| jar archives listed in your classpath. Each directory and jar archive will be |
| scanned for annotated JPA entities. |
| </p></li></ul></div><div class="example"><a name="ref_guide_meta_stdfactoryex"></a><p class="title"><b>Example 6.1. |
| Setting a Standard Metadata Factory |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| <property name="openjpa.MetaDataFactory" value="jpa(ClasspathScan=build;lib.jar)"/> |
| </pre></div></div><br class="example-break"><div class="example"><a name="ref_guide_meta_customfactoryex"></a><p class="title"><b>Example 6.2. |
| Setting a Custom Metadata Factory |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| <property name="openjpa.MetaDataFactory" value="com.xyz.CustomMetaDataFactory"/> |
| </pre></div></div><br class="example-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_meta_repository"></a>2. Metadata Repository</h2></div></div></div><p>The openjpa.MetaDataRepository configuration property controls the configuration of |
| the MetaDataRepository. The following are valid properties:</p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">Preload</code>: A boolean property. If true, OpenJPA will eagerly load the repository on |
| EntityManagerFactory creation. As a result, all Entity classes will be eagerly loaded by the JVM. |
| Once MetaData preloading completes, all locking is removed from the MetaDataRepository and this will |
| result in a much more scalable repository. If false, the repository will be lazily loaded as Entity |
| classes are loaded by the JVM. The default value is false. |
| </p></li></ul></div><div class="example"><a name="ref_guide_meta_repo"></a><p class="title"><b>Example 6.3. </b></p><div class="example-contents"><pre class="programlisting"> |
| <property name="openjpa.MetaDataRepository" value="Preload=true"/> |
| </pre></div></div><br class="example-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_meta_jpa"></a>3. |
| Additional JPA Metadata |
| </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#ref_guide_meta_jpa_datastoreid">3.1. |
| Datastore Identity |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_meta_jpa_version">3.2. |
| Surrogate Version |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_meta_jpa_persistent">3.3. |
| Persistent Field Values |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_meta_jpa_persistent_coll">3.4. Persistent Collection Fields</a></span></dt><dt><span class="section"><a href="#ref_guide_meta_jpa_persistent_map">3.5. Persistent Map Fields</a></span></dt></dl></div><a class="indexterm" name="d0e24058"></a><p> |
| This section describes OpenJPA's core additions to standard entity metadata. We |
| present the object-relational mapping syntax to support these additions in |
| <a href="#ref_guide_mapping_jpa" title="7. Additional JPA Mappings">Section 7, “ |
| Additional JPA Mappings |
| ”</a>. Finally, |
| <a href="#ref_guide_meta_ext" title="4. Metadata Extensions">Section 4, “ |
| Metadata Extensions |
| ”</a> covers additional extensions to JPA |
| metadata that allow you to access auxiliary OpenJPA features. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_meta_jpa_datastoreid"></a>3.1. |
| Datastore Identity |
| </h3></div></div></div><a class="indexterm" name="d0e24072"></a><p> |
| JPA typically requires you to declare one or more <code class="literal">Id</code> fields |
| to act as primary keys. OpenJPA, however, can create and maintain a surrogate |
| primary key value when you do not declare any <code class="literal">Id</code> fields. This |
| form of persistent identity is called <span class="emphasis"><em>datastore identity</em></span>. |
| <a href="#ref_guide_pc_oid" title="4. Object Identity">Section 4, “ |
| Object Identity |
| ”</a> discusses OpenJPA's support for |
| datastore identity in JPA. We cover how to map your datastore identity primary |
| key column in <a href="#ref_guide_mapping_jpa_datastoreid" title="7.1. Datastore Identity Mapping">Section 7.1, “ |
| Datastore Identity Mapping |
| ”</a> |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_meta_jpa_version"></a>3.2. |
| Surrogate Version |
| </h3></div></div></div><a class="indexterm" name="d0e24095"></a><p> |
| Just as OpenJPA can maintain your entity's identity without any <code class="literal">Id |
| </code> fields, OpenJPA can maintain your entity's optimistic version without |
| any <code class="literal">Version</code> fields. |
| <a href="#ref_guide_mapping_jpa_version" title="7.2. Surrogate Version Mapping">Section 7.2, “ |
| Surrogate Version Mapping |
| ”</a> shows you how to map |
| surrogate version columns. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_meta_jpa_persistent"></a>3.3. |
| Persistent Field Values |
| </h3></div></div></div><a class="indexterm" name="d0e24113"></a><p> |
| JPA defines <code class="literal">Basic</code>, <code class="literal">Lob</code>, <code class="literal">Embedded |
| </code>, <code class="literal">ManyToOne</code>, and <code class="literal">OneToOne</code> |
| persistence strategies for direct field values. OpenJPA supports all of these |
| standard strategies, but adds one of its own: <code class="literal">Persistent</code>. |
| The <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/Persistent.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.Persistent</code></a> |
| metadata annotation can represent any direct field value, including custom |
| types. It has the following properties: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">FetchType fetch</code>: Whether to load the field eagerly or |
| lazily. Corresponds exactly to the same-named property of standard JPA |
| annotations such as <a href="#jpa_overview_meta_basic" title="2.6. Basic"><code class="classname"> Basic |
| </code></a>. Defaults to <code class="literal">FetchType.EAGER</code>. |
| </p></li><li><p> |
| <code class="literal">CascadeType[] cascade</code>: Array of enum values defining cascade |
| behavior for this field. Corresponds exactly to the same-named property of |
| standard JPA annotations such as <a href="#jpa_overview_meta_manytoone" title="2.8. Many To One"> |
| <code class="classname"> ManyToOne</code></a>. Defaults to empty array. |
| </p></li><li><p> |
| <code class="literal">String mappedBy</code>: Names the field in the related entity that |
| maps this bidirectional relation. Corresponds to the same-named property of |
| standard JPA annotations such as <a href="#jpa_overview_meta_onetoone" title="2.10. One To One"> |
| <code class="classname"> OneToOne</code></a>. |
| </p></li><li><p> |
| <code class="literal">boolean optional</code>: Whether the value can be null. Corresponds |
| to the same-named property of standard JPA annotations such as |
| <a href="#jpa_overview_meta_manytoone" title="2.8. Many To One"><code class="classname"> ManyToOne</code> |
| </a>, but can apply to non-entity object values as well. Defaults to |
| <code class="literal">true</code>. |
| </p></li><li><p> |
| <code class="literal">boolean embedded</code>: Set this property to <code class="literal">true |
| </code> if the field value is stored as an embedded object. |
| </p></li></ul></div><p> |
| Though you can use the <code class="classname">Persistent</code> annotation in place of |
| most of the standard direct field annotations mentioned above, we recommend |
| primarily using it for non-standard and custom types for which no standard JPA |
| annotation exists. For example, <a href="#ref_guide_mapping_jpa_columns" title="7.3. Multi-Column Mappings">Section 7.3, “ |
| Multi-Column Mappings |
| ”</a> |
| demonstrates the use of the <code class="classname">Persistent</code> annotation |
| to denote a persistent <code class="classname">java.awt.Point</code> field. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_meta_jpa_persistent_coll"></a>3.4. Persistent Collection Fields</h3></div></div></div><a class="indexterm" name="d0e24216"></a><p> |
| JPA standardizes support for collections of entities with the <code class="literal"> |
| OneToMany</code> and <code class="literal">ManyToMany</code> persistence strategies. |
| OpenJPA supports these strategies, and may be extended for other strategies as |
| well. For extended strategies, use the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/PersistentCollection.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.PersistentCollection</code></a> metadata |
| annotation to represents any persistent collection field. It has the following |
| properties: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">Class elementType</code>: The class of the collection elements. |
| This information is usually taken from the parameterized collection element |
| type. You must supply it explicitly, however, if your field isn't a |
| parameterized type. |
| </p></li><li><p> |
| <code class="literal">FetchType fetch</code>: Whether to load the collection eagerly or |
| lazily. Corresponds exactly to the same-named property of standard JPA |
| annotations such as <a href="#jpa_overview_meta_basic" title="2.6. Basic"><code class="classname"> |
| Basic</code></a>. Defaults to <code class="literal">FetchType.LAZY</code>. |
| </p></li><li><p> |
| <code class="literal">String mappedBy</code>: Names the field in the related entity that |
| maps this bidirectional relation. Corresponds to the same-named property of |
| standard JPA annotations such as <a href="#jpa_overview_meta_manytomany" title="2.11. Many To Many"> |
| <code class="classname">ManyToMany</code></a>. |
| </p></li><li><p> |
| <code class="literal">CascadeType[] elementCascade</code>: Array of enum values defining |
| cascade behavior for the collection elements. Corresponds exactly to the |
| <code class="literal">cascade</code> property of standard JPA annotations such as |
| <a href="#jpa_overview_meta_manytomany" title="2.11. Many To Many"><code class="classname"> |
| ManyToMany</code></a>. Defaults to empty array. |
| </p></li><li><p> |
| <code class="literal">boolean elementEmbedded</code>: Set this property to <code class="literal">true |
| </code> if the elements are stored as embedded objects. |
| </p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_meta_jpa_persistent_map"></a>3.5. Persistent Map Fields</h3></div></div></div><a class="indexterm" name="d0e24290"></a><p> |
| JPA has limited support for maps. If you extend JPA's standard map support to |
| encompass new mappings, use the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/PersistentMap.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.PersistentMap</code></a> metadata |
| annotation to represent your custom persistent map fields. It has the |
| following properties: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">Class keyType</code>: The class of the map keys. This information |
| is usually taken from the parameterized map key type. You must supply it |
| explicitly, however, if your field isn't a parameterized type. |
| </p></li><li><p> |
| <code class="literal">Class elementType</code>: The class of the map values. This |
| information is usually taken from the parameterized map value type. You must |
| supply it explicitly, however, if your field isn't a parameterized type. |
| </p></li><li><p> |
| <code class="literal">FetchType fetch</code>: Whether to load the collection eagerly or |
| lazily. Corresponds exactly to the same-named property of standard JPA |
| annotations such as <a href="#jpa_overview_meta_basic" title="2.6. Basic"><code class="classname"> |
| Basic</code></a>. Defaults to <code class="literal">FetchType.LAZY</code>. |
| </p></li><li><p> |
| <code class="literal">CascadeType[] keyCascade</code>: Array of enum values defining |
| cascade behavior for the map keys. Corresponds exactly to the <code class="literal">cascade |
| </code> property of standard JPA annotations such as |
| <a href="#jpa_overview_meta_manytoone" title="2.8. Many To One"><code class="classname"> |
| ManyToOne</code></a>. Defaults to empty array. |
| </p></li><li><p> |
| <code class="literal">CascadeType[] elementCascade</code>: Array of enum values defining |
| cascade behavior for the map values. Corresponds exactly to the |
| <code class="literal">cascade</code> property of standard JPA annotations such as |
| <a href="#jpa_overview_meta_manytoone" title="2.8. Many To One"><code class="classname"> |
| ManyToOne</code></a>. Defaults to empty array. |
| </p></li><li><p> |
| <code class="literal">boolean keyEmbedded</code>: Set this property to <code class="literal">true |
| </code> if the map keys are stored as embedded objects. |
| </p></li><li><p> |
| <code class="literal">boolean elementEmbedded</code>: Set this property to <code class="literal"> |
| true</code> if the map values are stored as embedded objects. |
| </p></li></ul></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_meta_ext"></a>4. |
| Metadata Extensions |
| </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#ref_guide_meta_class">4.1. |
| Class Extensions |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#fetch-groups">4.1.1. |
| Fetch Groups |
| </a></span></dt><dt><span class="section"><a href="#data-cache">4.1.2. |
| Data Cache |
| </a></span></dt><dt><span class="section"><a href="#detached-state-field">4.1.3. |
| Detached State |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_meta_field">4.2. |
| Field Extensions |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#dependent">4.2.1. |
| Dependent |
| </a></span></dt><dt><span class="section"><a href="#load-fetch-group">4.2.2. |
| Load Fetch Group |
| </a></span></dt><dt><span class="section"><a href="#lrs">4.2.3. |
| LRS |
| </a></span></dt><dt><span class="section"><a href="#inverse-logical">4.2.4. |
| Inverse-Logical |
| </a></span></dt><dt><span class="section"><a href="#read-only">4.2.5. |
| Read-Only |
| </a></span></dt><dt><span class="section"><a href="#type">4.2.6. |
| Type |
| </a></span></dt><dt><span class="section"><a href="#externalizer">4.2.7. |
| Externalizer |
| </a></span></dt><dt><span class="section"><a href="#factory">4.2.8. |
| Factory |
| </a></span></dt><dt><span class="section"><a href="#external-values">4.2.9. |
| External Values |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_meta_example">4.3. |
| Example |
| </a></span></dt></dl></div><a class="indexterm" name="d0e24375"></a><p> |
| OpenJPA extends standard metadata to allow you to access advanced OpenJPA |
| functionality. This section covers persistence metadata extensions; we discuss |
| mapping metadata extensions in <a href="#ref_guide_mapping_ext" title="13. Mapping Extensions">Section 13, “ |
| Mapping Extensions |
| ”</a>. |
| All metadata extensions are optional; OpenJPA will rely on its defaults when no |
| explicit data is provided. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_meta_class"></a>4.1. |
| Class Extensions |
| </h3></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#fetch-groups">4.1.1. |
| Fetch Groups |
| </a></span></dt><dt><span class="section"><a href="#data-cache">4.1.2. |
| Data Cache |
| </a></span></dt><dt><span class="section"><a href="#detached-state-field">4.1.3. |
| Detached State |
| </a></span></dt></dl></div><p> |
| OpenJPA recognizes the following class extensions: |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="fetch-groups"></a>4.1.1. |
| Fetch Groups |
| </h4></div></div></div><a class="indexterm" name="d0e24392"></a><p> |
| The <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/FetchGroups.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.FetchGroups</code></a> and |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/FetchGroup.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.FetchGroup</code></a> |
| annotations allow you to define fetch groups in your JPA entities. |
| <a href="#ref_guide_fetch" title="7. Fetch Groups">Section 7, “ |
| Fetch Groups |
| ”</a> discusses OpenJPA's support for fetch |
| groups in general; see <a href="#ref_guide_fetch_custom" title="7.1. Custom Fetch Groups">Section 7.1, “ |
| Custom Fetch Groups |
| ”</a> for how to |
| use these annotations in particular. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="data-cache"></a>4.1.2. |
| Data Cache |
| </h4></div></div></div><a class="indexterm" name="d0e24420"></a><p> |
| <a href="#ref_guide_cache" title="1. Data Cache">Section 1, “ |
| Data Cache |
| ”</a> examines caching in OpenJPA. Metadata |
| extensions allow individual classes to override system caching defaults. |
| </p><p> |
| OpenJPA defines the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/DataCache.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.DataCache</code></a> |
| annotation for caching information. This annotation has the following |
| properties: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">boolean enabled</code>: Whether to cache data for instances of the |
| class. Defaults to <code class="literal">true</code> for base classes, or the superclass |
| value for subclasses. If you set this property to <code class="literal">false</code>, all |
| other properties are ignored. |
| </p></li><li><p> |
| <code class="literal">int timeout</code>: The number of milliseconds data for the class |
| remains valid. Use -1 for no timeout. Defaults to the |
| <a href="#openjpa.DataCacheTimeout" title="5.27. openjpa.DataCacheTimeout"><code class="literal"> openjpa.DataCacheTimeout |
| </code></a> property value. |
| </p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="detached-state-field"></a>4.1.3. |
| Detached State |
| </h4></div></div></div><a class="indexterm" name="d0e24466"></a><p> |
| The OpenJPA <a href="#ref_guide_pc_enhance" title="2. Enhancement">enhancer</a> may add a |
| synthetic field to detachable classes to hold detached state (see |
| <a href="#ref_guide_detach_graph" title="1.3. Defining the Detached Object Graph">Section 1.3, “ |
| Defining the Detached Object Graph |
| ”</a> for details). You can instead |
| declare your own detached state field or supress the creation of a detached |
| state field altogether. In the latter case, your class must not use |
| <a href="#ref_guide_pc_oid" title="4. Object Identity">datastore identity</a>, and should declare |
| a version field to detect optimistic concurrency errors during detached |
| modifications. |
| </p><p> |
| OpenJPA defines the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/DetachedState.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.DetachedState</code></a> |
| annotation for controlling detached state. When used to annotate a class, |
| <code class="classname">DetachedState</code> recognizes the following properties: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">boolean enabled</code>: Set to false to suppress the use of |
| detached state. |
| </p></li><li><p> |
| <code class="literal">String fieldName</code>: Use this property to declare your own |
| detached state field. The field must be of type <code class="classname">Object</code>. |
| Typically this property is only used if the field is inherited from a |
| non-persisted superclass. If the field is declared in your entity class, you |
| will typically annotate the field directly, as described below. |
| </p></li></ul></div><p> |
| If you declare your own detached state field, you can annotate that field with |
| <code class="classname">DetachedState</code> directly, rather than placing the |
| annotation at the class level and using the <code class="literal">fieldName</code> |
| property. When placed on a field, <code class="classname">DetachedState</code> acts as a |
| marker annotation; it does not recognize any properties. Your annotated field |
| must be of type <code class="classname">Object</code>. |
| </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_meta_field"></a>4.2. |
| Field Extensions |
| </h3></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#dependent">4.2.1. |
| Dependent |
| </a></span></dt><dt><span class="section"><a href="#load-fetch-group">4.2.2. |
| Load Fetch Group |
| </a></span></dt><dt><span class="section"><a href="#lrs">4.2.3. |
| LRS |
| </a></span></dt><dt><span class="section"><a href="#inverse-logical">4.2.4. |
| Inverse-Logical |
| </a></span></dt><dt><span class="section"><a href="#read-only">4.2.5. |
| Read-Only |
| </a></span></dt><dt><span class="section"><a href="#type">4.2.6. |
| Type |
| </a></span></dt><dt><span class="section"><a href="#externalizer">4.2.7. |
| Externalizer |
| </a></span></dt><dt><span class="section"><a href="#factory">4.2.8. |
| Factory |
| </a></span></dt><dt><span class="section"><a href="#external-values">4.2.9. |
| External Values |
| </a></span></dt></dl></div><p> |
| OpenJPA recognizes the following field extensions: |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="dependent"></a>4.2.1. |
| Dependent |
| </h4></div></div></div><a class="indexterm" name="d0e24533"></a><p> |
| In a <span class="emphasis"><em>dependent</em></span> relation, the referenced object is deleted |
| whenever the owning object is deleted, or whenever the relation is severed by |
| nulling or resetting the owning field. For example, if the <code class="literal"> |
| Magazine.coverArticle</code> field is marked dependent, then setting |
| <code class="literal">Magazine.coverArticle</code> to a new <code class="classname">Article</code> |
| instance will automatically delete the old <code class="classname">Article</code> stored |
| in the field. Similarly, deleting a <code class="classname">Magazine</code> object will |
| automatically delete its current cover <code class="classname">Article</code>. (This |
| latter processing is analogous to using JPA's CascadeType.REMOVE functionality |
| as described in <a href="#jpa_overview_meta_cascade" title="2.8.1. Cascade Type">Section 2.8.1, “ |
| Cascade Type |
| ”</a>.) You can |
| prevent an orphaned dependent object from being automatically deleted by |
| assigning it to another relation in the same transaction. |
| </p><p> |
| OpenJPA offers a family of marker annotations to denote dependent relations in |
| JPA entities: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/Dependent.html" target="_top"> |
| <code class="classname"> org.apache.openjpa.persistence.Dependent</code></a>: Marks |
| a direct relation as dependent. |
| </p></li><li><p> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/ElementDependent.html" target="_top"> |
| <code class="classname"> org.apache.openjpa.persistence.ElementDependent</code></a> |
| : Marks the entity elements of a collection, array, or map field as dependent. |
| </p></li><li><p> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/KeyDependent.html" target="_top"> |
| <code class="classname"> org.apache.openjpa.persistence.KeyDependent</code></a>: |
| Marks the key entities in a map field as dependent. |
| </p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="load-fetch-group"></a>4.2.2. |
| Load Fetch Group |
| </h4></div></div></div><a class="indexterm" name="d0e24595"></a><a class="indexterm" name="d0e24602"></a><p> |
| The <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/LoadFetchGroup.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.LoadFetchGroup</code></a> |
| annotation specifies a field's load fetch group. |
| <a href="#ref_guide_fetch" title="7. Fetch Groups">Section 7, “ |
| Fetch Groups |
| ”</a> discusses OpenJPA's support for fetch groups |
| in general; see <a href="#ref_guide_fetch_custom" title="7.1. Custom Fetch Groups">Section 7.1, “ |
| Custom Fetch Groups |
| ”</a> for how to use this |
| annotation in particular. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="lrs"></a>4.2.3. |
| LRS |
| </h4></div></div></div><a class="indexterm" name="d0e24621"></a><p> |
| This boolean extension, denoted by the OpenJPA |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/LRS.html" target="_top"><code class="classname"> |
| org.apache.openjpa.persistence.LRS</code></a> annotation, |
| indicates that a field should use OpenJPA's special large result set collection |
| or map proxies. A complete description of large result set proxies is available |
| in <a href="#ref_guide_pc_scos_proxy_lrs" title="6.4.2. Large Result Set Proxies">Section 6.4.2, “ |
| Large Result Set Proxies |
| ”</a>. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="inverse-logical"></a>4.2.4. |
| Inverse-Logical |
| </h4></div></div></div><a class="indexterm" name="d0e24641"></a><p> |
| This extension names the inverse field in a logical bidirectional relation. |
| To create a logical bidrectional relation in OpenJPA, use the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/InverseLogical.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.InverseLogical</code></a> |
| annotation. We discuss logical bidirectional relations and this |
| extension in detail in <a href="#ref_guide_inverses" title="5. Managed Inverses">Section 5, “ |
| Managed Inverses |
| ”</a>. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="read-only"></a>4.2.5. |
| Read-Only |
| </h4></div></div></div><a class="indexterm" name="d0e24662"></a><a class="indexterm" name="d0e24671"></a><p> |
| The read-only extension makes a field unwritable. The extension only applies to |
| existing persistent objects; new object fields are always writeable. |
| </p><p> |
| To mark a field read-only in JPA metadata, set the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/ReadOnly.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.ReadOnly</code></a> |
| annotation to an |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/UpdateAction.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.UpdateAction</code></a> enum |
| value. The <code class="classname">UpdateAction</code> enum includes: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">UpdateAction.IGNORE</code>: Updates to the field are completely |
| ignored. The field is not considered dirty. The new value will not even get |
| stored in the OpenJPA <a href="#ref_guide_cache" title="1. Data Cache">data cache</a>. |
| </p></li><li><p> |
| <code class="literal">UpdateAction.RESTRICT</code>: Any attempt to change the field will |
| result in an immediate exception. |
| </p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="type"></a>4.2.6. |
| Type |
| </h4></div></div></div><a class="indexterm" name="d0e24712"></a><p> |
| OpenJPA has three levels of support for relations: |
| </p><div class="orderedlist"><ol type="1"><li><p> |
| Relations that hold a reference to an object of a concrete persistent class are |
| supported by storing the primary key values of the related instance in the |
| database. |
| </p></li><li><p> |
| Relations that hold a reference to an object of an unknown persistent class are |
| supported by storing the stringified identity value of the related instance. |
| This level of support does not allow queries across the relation. |
| </p></li><li><p> |
| Relations that hold an unknown object or interface. The only way to support |
| these relations is to serialize their value to the database. This does not allow |
| you to query the field, and is not very efficient. |
| </p></li></ol></div><p> |
| Clearly, when you declare a field's type to be another persistence-capable |
| class, OpenJPA uses level 1 support. By default, OpenJPA assumes that any |
| interface-typed fields you declare will be implemented only by other persistent |
| classes, and assigns interfaces level 2 support. The exception to this rule is |
| the <code class="classname">java.io.Serializable</code> interface. If you declare a |
| field to be of type <code class="classname">Serializable</code>, OpenJPA lumps it |
| together with <code class="classname">java.lang.Object</code> fields and other |
| non-interface, unrecognized field types, which are all assigned level 3 support. |
| </p><p> |
| With OpenJPA's type family of metadata extensions, you can control the level of |
| support given to your unknown/interface-typed fields. Setting the value of this |
| extension to <code class="classname">Entity</code> indicates that the |
| field value will always be some persistent object, and gives level 2 support. |
| Setting the value of this extension to the class of a concrete persistent type |
| is even better; it gives you level 1 support (just as if you had declared your |
| field to be of that type in the first place). Setting this extension to |
| <code class="classname">Object</code> uses level 3 support. This is useful when you have |
| an interface relation that may <span class="bold"><strong>not</strong></span> hold other |
| persistent objects (recall that OpenJPA assumes interface fields will always |
| hold persistent instances by default). |
| </p><p> |
| This extension is also used with OpenJPA's externalization feature, described in |
| <a href="#ref_guide_pc_extern" title="6.5. Externalization">Section 6.5, “ |
| Externalization |
| ”</a>. |
| </p><p> |
| OpenJPA defines the following type annotations for field values, collection, |
| array, and map elements, and map keys, respectively: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/Type.html" target="_top"><code class="classname"> |
| org.apache.openjpa.persistence.Type</code></a> |
| </p></li><li><p> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/ElementType.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.ElementType</code></a> |
| </p></li><li><p> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/KeyType.html" target="_top"><code class="classname"> |
| org.apache.openjpa.persistence.KeyType</code></a> |
| </p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="externalizer"></a>4.2.7. |
| Externalizer |
| </h4></div></div></div><a class="indexterm" name="d0e24787"></a><p> |
| The OpenJPA |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/Externalizer.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.Externalizer</code></a> |
| annotation names a method to transform a field value into a value of |
| another type. See <a href="#ref_guide_pc_extern" title="6.5. Externalization">Section 6.5, “ |
| Externalization |
| ”</a> for details. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="factory"></a>4.2.8. |
| Factory |
| </h4></div></div></div><a class="indexterm" name="d0e24808"></a><p> |
| The OpenJPA |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/Factory.html" target="_top"><code class="classname"> |
| org.apache.openjpa.persistence.Factory</code></a> annotation |
| names a method to re-create a field value from its externalized form. See |
| <a href="#ref_guide_pc_extern" title="6.5. Externalization">Section 6.5, “ |
| Externalization |
| ”</a> for details. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="external-values"></a>4.2.9. |
| External Values |
| </h4></div></div></div><a class="indexterm" name="d0e24828"></a><p> |
| The OpenJPA |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/ExternalValues.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.ExternalValues</code></a> |
| annotation declares values for transformation of simple fields to |
| different constant values in the datastore. See |
| <a href="#ref_guide_pc_extern_values" title="6.5.1. External Values">Section 6.5.1, “ |
| External Values |
| ”</a> for details. |
| </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_meta_example"></a>4.3. |
| Example |
| </h3></div></div></div><p> |
| The following example shows you how to specify extensions in metadata. |
| </p><div class="example"><a name="ref_guide_metaex"></a><p class="title"><b>Example 6.4. |
| OpenJPA Metadata Extensions |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| import org.apache.openjpa.persistence.*; |
| |
| @Entity |
| @DataCache(enabled=false) |
| public class Magazine |
| { |
| @ManyToMany |
| @LRS |
| private Collection<Subscriber> subscribers; |
| |
| @ExternalValues({"true=1", "false=2"}) |
| @Type(int.class) |
| private boolean weekly; |
| |
| ... |
| } |
| </pre></div></div><br class="example-break"></div></div></div><div class="chapter" lang="en" id="ref_guide_mapping"><div class="titlepage"><div><div><h2 class="title"><a name="ref_guide_mapping"></a>Chapter 7. |
| Mapping |
| </h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#ref_guide_mapping_mappingtool">1. |
| Forward Mapping |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_mapping_mappingtool_examples">1.1. |
| Using the Mapping Tool |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_ddl_examples">1.2. |
| Generating DDL SQL |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_synch">1.3. |
| Runtime Forward Mapping |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_pc_reverse">2. |
| Reverse Mapping |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_pc_reverse_custom">2.1. |
| Customizing Reverse Mapping |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_mapping_middle">3. |
| Meet-in-the-Middle Mapping |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_defaults">4. |
| Mapping Defaults |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_factory">5. |
| Mapping Factory |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_notes_nonstdjoins">6. |
| Non-Standard Joins |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_jpa">7. |
| Additional JPA Mappings |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_mapping_jpa_datastoreid">7.1. |
| Datastore Identity Mapping |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_jpa_version">7.2. |
| Surrogate Version Mapping |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_jpa_columns">7.3. |
| Multi-Column Mappings |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_jpa_fieldjoin">7.4. |
| Join Column Attribute Targets |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_jpa_embed">7.5. |
| Embedded Mapping |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_jpa_coll">7.6. |
| Collections |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_mapping_jpa_coll_table">7.6.1. |
| Container Table |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_jpa_coll_joincols">7.6.2. |
| Element Join Columns |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_jpa_coll_order">7.6.3. |
| Order Column |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_mapping_jpa_onemany">7.7. |
| One-Sided One-Many Mapping |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_jpa_map">7.8. |
| Maps |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_jpa_constraints">7.9. |
| Indexes and Constraints |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_mapping_jpa_index">7.9.1. |
| Indexes |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_jpa_fk">7.9.2. |
| Foreign Keys |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_jpa_unique">7.9.3. |
| Unique Constraints |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_xmlmapping">7.10. |
| XML Column Mapping |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_streamsupport">7.11. |
| Stream LOB Support |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_mapping_jpa_map_keycols">8. Key Columns</a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_jpa_map_keyjoincols">9. Key Join Columns</a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_jpa_map_embedkey">10. Key Embedded Mapping</a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_jpa_map_ex">11. Examples</a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_limits">12. |
| Mapping Limitations |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_mapping_limits_tpc">12.1. |
| Table Per Class |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_mapping_ext">13. |
| Mapping Extensions |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_mapping_ext_cls">13.1. |
| Class Extensions |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#subclass-fetch-mode">13.1.1. |
| Subclass Fetch Mode |
| </a></span></dt><dt><span class="section"><a href="#class-strategy">13.1.2. |
| Strategy |
| </a></span></dt><dt><span class="section"><a href="#discriminator-strategy">13.1.3. |
| Discriminator Strategy |
| </a></span></dt><dt><span class="section"><a href="#version-strategy">13.1.4. |
| Version Strategy |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_mapping_ext_field">13.2. |
| Field Extensions |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#eager-fetch-mode">13.2.1. |
| Eager Fetch Mode |
| </a></span></dt><dt><span class="section"><a href="#nonpolymorphic">13.2.2. |
| Nonpolymorphic |
| </a></span></dt><dt><span class="section"><a href="#class-criteria">13.2.3. |
| Class Criteria |
| </a></span></dt><dt><span class="section"><a href="#strategy">13.2.4. |
| Strategy |
| </a></span></dt></dl></dd></dl></dd><dt><span class="section"><a href="#ref_guide_mapping_custom">14. |
| Custom Mappings |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_mapping_custom_class">14.1. |
| Custom Class Mapping |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_custom_versdiscrim">14.2. |
| Custom Discriminator and Version Strategies |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_custom_field">14.3. |
| Custom Field Mapping |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_mapping_custom_vhandler">14.3.1. |
| Value Handlers |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_custom_fieldstrat">14.3.2. |
| Field Strategies |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_custom_field_conf">14.3.3. |
| Configuration |
| </a></span></dt></dl></dd></dl></dd><dt><span class="section"><a href="#ref_guide_orphan">15. |
| Orphaned Keys |
| </a></span></dt></dl></div><a class="indexterm" name="d0e24860"></a><p> |
| The JPA Overview's <a href="#jpa_overview_mapping" title="Chapter 12. Mapping Metadata">Chapter 12, <i xmlns:xlink="http://www.w3.org/1999/xlink"> |
| Mapping Metadata |
| </i></a> explains |
| object-relational mapping under JPA. This chapter reviews the mapping utilities |
| OpenJPA provides and examines OpenJPA features that go beyond the JPA |
| specification. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_mapping_mappingtool"></a>1. |
| Forward Mapping |
| </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#ref_guide_mapping_mappingtool_examples">1.1. |
| Using the Mapping Tool |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_ddl_examples">1.2. |
| Generating DDL SQL |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_synch">1.3. |
| Runtime Forward Mapping |
| </a></span></dt></dl></div><a class="indexterm" name="d0e24870"></a><a class="indexterm" name="d0e24873"></a><a class="indexterm" name="d0e24878"></a><p> |
| <span class="emphasis"><em>Forward mapping</em></span> is the process of creating mappings and |
| their corresponding database schema from your object model. OpenJPA supports |
| forward mapping through the <span class="emphasis"><em>mapping tool</em></span>. The next section |
| presents several common mapping tool use cases. You can invoke the tool through |
| its Java class, |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/meta/MappingTool" target="_top"><code class="classname"> |
| org.apache.openjpa.jdbc.meta.MappingTool</code></a>. |
| </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| <a href="#ref_guide_integration_mappingtool" title="1.4. Mapping Tool Ant Task">Section 1.4, “ |
| Mapping Tool Ant Task |
| ”</a> describes the mapping |
| tool Ant task. |
| </p></div><div class="example"><a name="ref_guide_mapping_mappingtool_typical"></a><p class="title"><b>Example 7.1. |
| Using the Mapping Tool |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| java org.apache.openjpa.jdbc.meta.MappingTool Magazine.java |
| </pre></div></div><br class="example-break"><p> |
| In addition to the universal flags of the |
| <a href="#ref_guide_conf_devtools" title="3. Command Line Configuration">configuration framework</a>, the |
| mapping tool accepts the following command line arguments: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">-schemaAction/-sa <add | refresh | drop | build | retain | reflect | createDB | dropDB | import | export | none> |
| </code>: The action to take on the schema. These options correspond to the |
| same-named actions on the schema tool described in |
| <a href="#ref_guide_schema_schematool" title="13. Schema Tool">Section 13, “ |
| Schema Tool |
| ”</a>. Actions can be composed in a |
| comma-separated list. Unless you are running the mapping tool on all of |
| your persistent types at once or dropping a mapping, we strongly |
| recommend you use the default <code class="literal">add</code> action or the |
| <code class="literal">build</code> action. Otherwise you may end up inadvertently |
| dropping schema components that are used by classes you are not |
| currently running the tool over. |
| </p></li><li><p> |
| <code class="literal">-schemaFile/-sf <stdout | output file></code>: Use this |
| option to write the planned schema to an XML document rather than modify the |
| database. The document can then be manipulated and committed to the database |
| with the <a href="#ref_guide_schema_schematool" title="13. Schema Tool"> schema tool</a>. |
| </p></li><li><p> |
| <code class="literal">-sqlFile/-sql <stdout | output file></code>: Use this option |
| to write the planned schema modifications to a SQL script rather than modify the |
| database. Combine this with a <code class="literal">schemaAction</code> of <code class="literal">build |
| </code> to generate a script that recreates the schema for the current |
| mappings, even if the schema already exists. |
| </p></li><li><p> |
| <code class="literal">-dropTables/-dt <true/t | false/f></code>: Corresponds to the |
| same-named option on the schema tool. |
| </p></li><li><p> |
| <code class="literal">-dropSequences/-dsq <true/t | false/f></code>: Corresponds to |
| the same-named option on the schema tool. |
| </p></li><li><p> |
| <code class="literal">-openjpaTables/-ot <true/t | false/f></code>: Corresponds to |
| the same-named option on the schema tool. |
| </p></li><li><p> |
| <code class="literal">-ignoreErrors/-i <true/t | false/f></code>: Corresponds to |
| the same-named option on the schema tool. |
| </p></li><li><p> |
| <code class="literal">-schemas/-s <schema and table names></code>: Corresponds to |
| the same-named option on the schema tool. This option is ignored if <code class="literal"> |
| readSchema</code> is not set to <code class="literal">true</code>. |
| </p></li><li><p> |
| <code class="literal">-readSchema/-rs <true/t | false/f></code>: Set this option to |
| <code class="literal">true</code> to read the entire existing schema when the tool runs. |
| Reading the existing schema ensures that OpenJPA does not generate any mappings |
| that use table, index, primary key, or foreign key names that conflict with |
| existing names. Depending on the JDBC driver, though, it can be a slow process |
| for large schemas. |
| </p></li><li><p> |
| <code class="literal">-primaryKeys/-pk <true/t | false/f></code>: Whether to read |
| and manipulate primary key information of existing tables. Defaults to false. |
| </p></li><li><p> |
| <code class="literal">-foreignKeys/-fk <true/t | false/f></code>: Whether to read |
| and manipulate foreign key information of existing tables. Defaults to false. |
| This means that to add any new foreign keys to a class that has already been |
| mapped, you must explicitly set this flag to true. |
| </p></li><li><p> |
| <code class="literal">-indexes/-ix <true/t | false/f></code>: Whether to read and |
| manipulate index information of existing tables. Defaults to false. This means |
| that to add any new indexes to a class that has already been mapped once, you |
| must explicitly set this flag to true. |
| </p></li><li><p> |
| <code class="literal">-sequences/-sq <true/t | false/f></code>: Whether to |
| manipulate sequences. Defaults to true. |
| </p></li><li><p> |
| <code class="literal">-meta/-m <true/t | false/f></code>: Whether the given action |
| applies to metadata rather than or in addition to mappings. |
| </p></li></ul></div><p> |
| The mapping tool also uses an <code class="literal">-action/-a</code> argument to specify |
| the action to take on each class. The available actions are: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">buildSchema</code>: This is the default action. It |
| makes the database schema match your existing mappings. If your provided |
| mappings conflict with your class definitions, OpenJPA will fail with an |
| informative exception. |
| </p></li><li><p> |
| <code class="literal">validate</code>: Ensure that the mappings for the given classes are |
| valid and that they match the schema. No mappings or tables will be changed. An |
| exception is thrown if any mappings are invalid. |
| </p></li></ul></div><p> |
| Each additional argument to the tool should be one of: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| The full name of a persistent class. |
| </p></li><li><p> |
| The .java file for a persistent class. |
| </p></li><li><p> |
| The <code class="filename">.class</code> file of a persistent class. |
| </p></li></ul></div><p> |
| If you do not supply any arguments to the mapping tool, it will run on the |
| classes in your persistent classes list (see |
| <a href="#ref_guide_pc_pcclasses" title="1. Persistent Class List">Section 1, “ |
| Persistent Class List |
| ”</a>). |
| </p><p> |
| The mappings generated by the mapping tool are stored by the system <span class="emphasis"><em> |
| mapping factory</em></span>. <a href="#ref_guide_mapping_factory" title="5. Mapping Factory">Section 5, “ |
| Mapping Factory |
| ”</a> |
| discusses your mapping factory options. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_mapping_mappingtool_examples"></a>1.1. |
| Using the Mapping Tool |
| </h3></div></div></div><a class="indexterm" name="d0e25070"></a><p> |
| The JPA specification defines a comprehensive set of defaults for missing |
| mapping information. Thus, forward mapping in JPA is virtually automatic. After |
| using the mapping annotations covered in <a href="#jpa_overview_mapping" title="Chapter 12. Mapping Metadata">Chapter 12, <i xmlns:xlink="http://www.w3.org/1999/xlink"> |
| Mapping Metadata |
| </i></a> |
| of the JPA Overview to override any unsatisfactory defaults, run the |
| mapping tool on your persistent classes. The default <code class="literal">buildSchema |
| </code> mapping tool action manipulates the database schema to |
| match your mappings. It fails if any of your mappings don't match your object |
| model. |
| </p><div class="example"><a name="ref_guide_mapping_mappingtool_buildschema"></a><p class="title"><b>Example 7.2. |
| Creating the Relational Schema from Mappings |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| java org.apache.openjpa.jdbc.meta.MappingTool Magazine.java |
| </pre></div></div><br class="example-break"><p> |
| To drop the schema for a persistent class, set the mapping tool's <code class="literal"> |
| schemaAction</code> to <code class="literal">drop</code>. |
| </p><div class="example"><a name="ref_guide_mapping_mappingtool_cleanup_tables"></a><p class="title"><b>Example 7.3. |
| Refreshing entire schema and cleaning out tables |
| </b></p><div class="example-contents"><a class="indexterm" name="d0e25098"></a><pre class="programlisting"> |
| java org.apache.openjpa.jdbc.meta.MappingTool -schemaAction add,deleteTableContents |
| </pre></div></div><br class="example-break"><div class="example"><a name="ref_guide_mapping_mappingtool_dropschema"></a><p class="title"><b>Example 7.4. |
| Dropping Mappings and Association Schema |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| java org.apache.openjpa.jdbc.meta.MappingTool -schemaAction drop Magazine.java |
| </pre></div></div><br class="example-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_ddl_examples"></a>1.2. |
| Generating DDL SQL |
| </h3></div></div></div><a class="indexterm" name="d0e25113"></a><a class="indexterm" name="d0e25118"></a><p> |
| The examples below show how to use the mapping tool to generate DDL SQL scripts, |
| rather than modifying the database directly. |
| </p><div class="example"><a name="ref_guid_mapping_ddl_full_ddl"></a><p class="title"><b>Example 7.5. |
| Create DDL for Current Mappings |
| </b></p><div class="example-contents"><p> |
| This example uses your existing mappings to determine the needed schema, then |
| writes the SQL to create that schema to <code class="filename">create.sql</code>. |
| </p><pre class="programlisting"> |
| java org.apache.openjpa.jdbc.meta.MappingTool -schemaAction build -sql create.sql Magazine.java |
| </pre></div></div><br class="example-break"><div class="example"><a name="ref_guid_mapping_ddl_part_ddl"></a><p class="title"><b>Example 7.6. |
| Create DDL to Update Database for Current Mappings |
| </b></p><div class="example-contents"><p> |
| This example uses your existing mappings to determine the needed schema. It then |
| writes the SQL to add any missing tables and columns to the current schema to |
| <code class="filename">update.sql</code>. |
| </p><pre class="programlisting"> |
| java org.apache.openjpa.jdbc.meta.MappingTool -sql update.sql Magazine.java |
| </pre></div></div><br class="example-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_mapping_synch"></a>1.3. |
| Runtime Forward Mapping |
| </h3></div></div></div><a class="indexterm" name="d0e25148"></a><a class="indexterm" name="d0e25153"></a><p> |
| You can configure OpenJPA to automatically run the mapping tool at runtime |
| through the <a href="#openjpa.jdbc.SynchronizeMappings" title="6.17. openjpa.jdbc.SynchronizeMappings"><code class="literal"> |
| openjpa.jdbc.SynchronizeMappings</code></a> configuration property. Using |
| this property saves you the trouble of running the mapping tool manually, and is |
| meant for use during rapid test/debug cycles. |
| </p><p> |
| In order to enable automatic runtime mapping, you must first list all your |
| persistent classes as described in <a href="#ref_guide_pc_pcclasses" title="1. Persistent Class List">Section 1, “ |
| Persistent Class List |
| ”</a>. |
| </p><p> |
| OpenJPA will run the mapping tool on these classes when your application obtains |
| its first <code class="classname">EntityManager</code>. |
| </p><p> |
| The <code class="literal">openjpa.jdbc.SynchronizeMappings</code> property is a plugin |
| string (see <a href="#ref_guide_conf_plugins" title="4. Plugin Configuration">Section 4, “ |
| Plugin Configuration |
| ”</a>) where the class |
| name is the mapping tool action to invoke, and the properties are the |
| <code class="classname">MappingTool</code> class' JavaBean properties. These properties |
| correspond go the long versions of the tool's command line flags. |
| </p><div class="example"><a name="ref_guide_mapping_synchex"></a><p class="title"><b>Example 7.7. |
| Configuring Runtime Forward Mapping |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| <property name="openjpa.jdbc.SynchronizeMappings" value="buildSchema(ForeignKeys=true)"/> |
| </pre><p> |
| The setting above corresponds to running the following command: |
| </p><pre class="programlisting"> |
| java org.apache.openjpa.jdbc.meta.MappingTool -action buildSchema -foreignKeys true |
| </pre></div></div><br class="example-break"></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_pc_reverse"></a>2. |
| Reverse Mapping |
| </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#ref_guide_pc_reverse_custom">2.1. |
| Customizing Reverse Mapping |
| </a></span></dt></dl></div><a class="indexterm" name="d0e25195"></a><a class="indexterm" name="d0e25198"></a><a class="indexterm" name="d0e25203"></a><p> |
| OpenJPA includes a <span class="emphasis"><em>reverse mapping</em></span> tool for generating |
| persistent class definitions, complete with metadata, from an existing database |
| schema. You do not have to use the reverse mapping tool to access an existing |
| schema; you are free to write your classes and mappings yourself, as described |
| in <a href="#ref_guide_mapping_middle" title="3. Meet-in-the-Middle Mapping">Section 3, “ |
| Meet-in-the-Middle Mapping |
| ”</a>. The reverse mapping tool, |
| however, can give you an excellent starting point from which to grow your |
| persistent classes. |
| </p><p> |
| To use the reverse mapping tool, follow the steps below: |
| </p><div class="orderedlist"><ol type="1"><li><p> |
| Use the <a href="#ref_guide_schema_schematool" title="13. Schema Tool"> schema tool</a> to |
| export your current schema to an XML schema file. You can skip this step and the |
| next step if you want to run the reverse mapping tool directly against the |
| database. |
| </p><div class="example"><a name="ref_guide_pc_reverse_schemagen"></a><p class="title"><b>Example 7.8. |
| Reflection with the Schema Tool |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| java org.apache.openjpa.jdbc.schema.SchemaTool -a reflect -f schema.xml |
| </pre></div></div><br class="example-break"></li><li><p> |
| Examine the generated schema file. JDBC drivers often provide incomplete or |
| faulty metadata, in which case the file will not exactly match the actual |
| schema. Alter the XML file to match the true schema. The XML format for the |
| schema file is described in <a href="#ref_guide_schema_xml" title="14. XML Schema Format">Section 14, “ |
| XML Schema Format |
| ”</a>. |
| </p><p> |
| After fixing any errors in the schema file, modify the XML to include foreign |
| keys between all relations. The schema tool will have automatically detected |
| existing foreign key constraints; many schemas, however, do not employ database |
| foreign keys for every relation. By manually adding any missing foreign keys, |
| you will give the reverse mapping tool the information it needs to generate the |
| proper relations between the persistent classes it creates. |
| </p></li><li><p> |
| Run the reverse mapping tool on the finished schema file. If you do not supply |
| the schema file to reverse map, the tool will run directly against the schema in |
| the database. The tool can be run via its Java class, |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/meta/ReverseMappingTool" target="_top"> |
| <code class="classname">org.apache.openjpa.jdbc.meta.ReverseMappingTool</code></a>. |
| </p><div class="example"><a name="ref_guide_pc_reverse_reversemappingtool"></a><p class="title"><b>Example 7.9. |
| Using the Reverse Mapping Tool |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| java org.apache.openjpa.jdbc.meta.ReverseMappingTool -pkg com.xyz -d ~/src -cp customizer.properties schema.xml |
| </pre></div></div><br class="example-break"><p> |
| In addition to OpenJPA's <a href="#ref_guide_conf_devtools" title="3. Command Line Configuration">standard |
| configuration flags</a>, including |
| <a href="#ref_guide_conf_devtools_format" title="3.1. Code Formatting">code formatting options</a>, |
| the reverse mapping tool recognizes the following command line arguments: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">-schemas/-s <schema and table names></code>: A |
| comma-separated list of schema and table names to reverse map, if no XML schema |
| file is supplied. Each element of the list must follow the naming conventions |
| for the <code class="literal">openjpa.jdbc.Schemas</code> property described in |
| <a href="#ref_guide_schema_info_list" title="12.1. Schemas List">Section 12.1, “ |
| Schemas List |
| ”</a>. In fact, if this flag is |
| omitted, it defaults to the value of the <code class="literal">Schemas</code> property. If |
| the <code class="literal">Schemas</code> property is not defined, all schemas will be |
| reverse-mapped. |
| </p></li><li><p> |
| <code class="literal">-package/-pkg <package name></code>: The package name of the |
| generated classes. If no package name is given, the generated code will not |
| contain package declarations. |
| </p></li><li><p> |
| <code class="literal">-directory/-d <output directory></code>: All generated code |
| and metadata will be written to the directory at this path. If the path does not |
| match the package of a class, the package structure will be created beneath this |
| directory. Defaults to the current directory. |
| </p></li><li><p> |
| <code class="literal">-metadata/-md <class | package | none></code>: Specify the |
| level the metadata should be generated at. Defaults to generating a single |
| package-level metadata file. Set to <code class="literal">none</code> to disable orm.xml |
| generation. |
| </p></li><li><p> |
| <code class="literal">-annotations/-ann <true/t | false/f></code>: Set to true to |
| generate JPA annotations in generated java classes. |
| </p></li><li><p> |
| <code class="literal">-accessType/-access <field | property></code>: Change access |
| type for generated annotations. Defaults to field access. |
| </p></li><li><p> |
| <code class="literal">-useSchemaName/-sn <true/t | false/f></code>: Set this flag |
| to <code class="literal">true</code> to include the schema as well as table name in the |
| name of each generated class. This can be useful when dealing with multiple |
| schemas with same-named tables. |
| </p></li><li><p> |
| <code class="literal">-useForeignKeyName/-fkn <true/t | false/f></code>: Set this |
| flag to <code class="literal">true</code> if you would like field names for relations to |
| be based on the database foreign key name. By default, relation field names are |
| derived from the name of the related class. |
| </p></li><li><p> |
| <code class="literal">-nullableAsObject/-no <true/t | false/f></code>: By default, |
| all non-foreign key columns are mapped to primitives. Set this flag to <code class="literal"> |
| true</code> to generate primitive wrapper fields instead for columns that |
| allow null values. |
| </p></li><li><p> |
| <code class="literal">-blobAsObject/-bo <true/t | false/f></code>: By default, all |
| binary columns are mapped to <code class="classname">byte[]</code> fields. Set this flag |
| to <code class="literal">true</code> to map them to <code class="classname">Object</code> fields |
| instead. Note that when mapped this way, the column is presumed to contain a |
| serialized Java object. |
| </p></li><li><p> |
| <code class="literal">-primaryKeyOnJoin/-pkj <true/t | false/f></code>: The |
| standard reverse mapping tool behavior is to map all tables with primary keys to |
| persistent classes. If your schema has primary keys on many-many join tables as |
| well, set this flag to <code class="literal">true</code> to avoid creating classes for |
| those tables. |
| </p></li><li><p> |
| <code class="literal">-inverseRelations/-ir <true/t | false/f></code>: Set to |
| <code class="literal">false</code> to prevent the creation of inverse 1-many/1-1 relations |
| for every many-1/1-1 relation detected. |
| </p></li><li><p> |
| <code class="literal">-useGenericCollections/-gc <true/t | false/f></code>: Set to |
| true to use generic collections on OneToMany and ManyToMany relations (requires |
| JDK 1.5 or higher). |
| </p></li><li><p> |
| <code class="literal">-useDatastoreIdentity/-ds <true/t | false/f></code>: Set to |
| <code class="literal">true</code> to use datastore identity for tables that have single |
| numeric primary key columns. The tool typically uses application identity for |
| all generated classes. |
| </p></li><li><p> |
| <code class="literal">-useBuiltinIdentityClass/-bic <true/t | false/f></code>: Set |
| to <code class="literal">false</code> to prevent the tool from using built-in application |
| identity classes when possible. This will force the tool to to create custom |
| application identity classes even when there is only one primary key column. |
| </p></li><li><p> |
| <code class="literal">-innerIdentityClasses/-inn <true/t | false/f></code>: Set to |
| <code class="literal">true</code> to have any generated application identity classes be |
| created as static inner classes within the persistent classes. Defaults to |
| <code class="literal">false</code>. |
| </p></li><li><p> |
| <code class="literal">-identityClassSuffix/-is <suffix></code>: Suffix to append to |
| class names to form application identity class names, or for inner identity |
| classes, the inner class name. Defaults to <code class="literal">Id</code>. |
| </p></li><li><p> |
| <code class="literal">-typeMap/-typ <type mapping></code>: A string that specifies |
| the default Java classes to generate for each SQL type that is seen in the |
| schema. The format is <code class="literal"> SQLTYPE1=JavaClass1,SQLTYPE2=JavaClass2 |
| </code>. The SQL type name first looks for a customization based on <code class="literal"> |
| SQLTYPE(SIZE,PRECISION)</code>, then <code class="literal">SQLTYPE(SIZE)</code>, then |
| <code class="literal">SQLTYPE(SIZE,PRECISION)</code>. So if a column whose type name is |
| <code class="literal">CHAR</code> is found, it will first look for the <code class="literal"> |
| CHAR(50,0)</code> type name specification, then it will look for <code class="literal"> |
| CHAR(50)</code>, and finally it will just look for <code class="literal">CHAR</code>. |
| For example, to generate a char array for every <code class="literal">CHAR</code> column |
| whose size is exactly 50, and to generate a <code class="literal">short</code> for every |
| type name of <code class="literal">INTEGER</code>, you might specify: <code class="literal"> |
| CHAR(50)=char[],INTEGER=short</code>. Note that since various databases |
| report different type names differently, one database's type name specification |
| might not work for another database. Enable <code class="literal">TRACE</code> level |
| logging on the <code class="literal">MetaData</code> channel to track which type names |
| OpenJPA is examining. |
| </p></li><li><p> |
| <code class="literal">-customizerClass/-cc <class name></code>: The full class name |
| of a |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/meta/ReverseCustomizer.html" target="_top"> |
| <code class="classname">org.apache.openjpa.jdbc.meta.ReverseCustomizer</code></a> |
| customization plugin. If you do not specify a reverse customizer of your own, |
| the system defaults to a |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/meta/PropertiesReverseCustomizer.html" target="_top"> |
| <code class="classname">PropertiesReverseCustomizer</code></a>. This customizer |
| allows you to specify simple customization options in the properties file given |
| with the <code class="literal">-customizerProperties</code> flag below. We present the |
| available property keys <a href="#ref_guide_pc_reverse_custom" title="2.1. Customizing Reverse Mapping"> |
| below</a>. |
| </p></li><li><p> |
| <code class="literal">-customizerProperties/-cp <properties file or resource></code> |
| : The path or resource name of a properties file to pass to the reverse |
| customizer on initialization. |
| </p></li><li><p> |
| <code class="literal">-customizer./-c.<property name> <property value></code> |
| : The given property name will be matched with the corresponding Java bean |
| property in the specified reverse customizer, and set to the given value. |
| </p></li></ul></div><p> |
| Running the tool will generate <code class="filename">.java</code> files for each |
| generated class (and its application identity class, if applicable), along with |
| JPA annotations (if enabled by setting <code class="literal">-annotations true</code>), |
| or an <code class="filename">orm.xml</code> file (if not disabled with <code class="literal"> |
| -metadata none</code>) containing the corresponding persistence metadata. |
| </p></li><li><p> |
| Examine the generated class, metadata, and mapping information, and modify it as |
| necessary. Remember that the reverse mapping tool only provides a starting |
| point, and you are free to make whatever modifications you like to the code it |
| generates. |
| </p><p> |
| After you are satisfied with the generated classes and their mappings, you |
| should first compile the classes with <code class="literal">javac</code>, <code class="literal"> |
| jikes</code>, or your favorite Java compiler. Make sure the classes are |
| located in the directory corresponding to the <code class="literal">-package</code> flag |
| you gave the reverse mapping tool. Next, if you have generated an <code class="filename"> |
| orm.xml</code>, move that file to a <code class="filename">META-INF</code> directory |
| within a directory in your classpath. Finally, enhance the classes |
| if necessary (see <a href="#ref_guide_pc_enhance" title="2. Enhancement">Section 2, “ |
| Enhancement |
| ”</a>). |
| </p></li></ol></div><p> |
| Your persistent classes are now ready to access your existing schema. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_pc_reverse_custom"></a>2.1. |
| Customizing Reverse Mapping |
| </h3></div></div></div><p> |
| The <code class="classname">org.apache.openjpa.jdbc.meta.ReverseCustomizer</code> plugin |
| interface allows you to customze the reverse mapping process. See the class |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/meta/ReverseCustomizer.html" target="_top"> |
| Javadoc</a> for details on the hooks that this interface provides. Specify |
| the concrete plugin implementation to use with the <code class="literal"> |
| -customizerClass/-cc</code> command-line flag, described in the preceding |
| section. |
| </p><p> |
| By default, the reverse mapping tool uses a |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/meta/PropertiesReverseCustomizer.html" target="_top"> |
| <code class="classname">org.apache.openjpa.jdbc.meta.PropertiesReverseCustomizer</code> |
| </a>. This customizer allows you to perform relatively simple |
| customizations through the properties file named with the <code class="literal"> |
| -customizerProperties</code> tool flag. The customizer recognizes the |
| following properties: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal"><table name>.table-type <type></code>: Override the |
| default type of the table with name <code class="literal"><table name></code>. |
| Legal values are: |
| </p><div class="itemizedlist"><ul type="circle"><li><p> |
| <code class="literal">base</code>: Primary table for a base class. |
| </p></li><li><p> |
| <code class="literal">secondary</code>: Secondary table for a class. The table must have |
| a foreign key joining to a class table. |
| </p></li><li><p> |
| <code class="literal">secondary-outer</code>: Outer-joined secondary table for a class. |
| The table must have a foreign key joining to a class table. |
| </p></li><li><p> |
| <code class="literal">association</code>: Association table. The table must have two |
| foreign keys to class tables. |
| </p></li><li><p> |
| <code class="literal">collection</code>: Collection table. The table must have one |
| foreign key to a class table and one data column. |
| </p></li><li><p> |
| <code class="literal">subclass</code>: A joined subclass table. The table must have a |
| foreign key to the superclass' table. |
| </p></li><li><p> |
| <code class="literal">none</code>: The table should not be reverse-mapped. |
| </p></li></ul></div></li><li><p> |
| <code class="literal"><class name>.rename <new class name></code>: Override |
| the given tool-generated name <code class="literal"><class name></code> with a new |
| value. Use full class names, including package. You are free to rename a class |
| to a new package. Specify a value of <code class="literal">none</code> to reject the class |
| and leave the corresponding table unmapped. |
| </p></li><li><p> |
| <code class="literal"><table name>.class-name <new class name></code>: Assign |
| the given fully-qualified class name to the type created from the table with |
| name <code class="literal"><table name></code>. Use a value of <code class="literal">none |
| </code> to prevent reverse mapping this table. This property can be used in |
| place of the <code class="literal">rename</code> property. |
| </p></li><li><p> |
| <code class="literal"><class name>.identity <datastore | builtin | identity class |
| name></code>: Set this property to <code class="literal">datastore</code> to use |
| datastore identity for the class <code class="literal"><class name></code>, |
| <code class="literal">builtin</code> to use a built-in identity class, or the desired |
| application identity class name. Give full class names, including package. You |
| are free to change the package of the identity class this way. If the persistent |
| class has been renamed, use the new class name for this property key. Remember |
| that datastore identity requires a table with a single numeric primary key |
| column, and built-in identity requires a single primary key column of any type. |
| </p></li><li><p> |
| <code class="literal"><class name>.<field name>.rename <new field name> |
| </code>: Override the tool-generated <code class="literal"><field name></code> in |
| class <code class="literal"><class name></code> with the given name. Use the field |
| owner's full class name in the property key. If the field owner's class was |
| renamed, use the new class name. The property value should be the new field |
| name, without the preceding class name. Use a value of <code class="literal">none</code> |
| to reject the generated mapping and remove the field from the class. |
| </p></li><li><p> |
| <code class="literal"><table name>.<column name>.field-name <new field |
| name></code>: Set the generated field name for the <code class="literal"><table |
| name></code> table's <code class="literal"><column name></code> column. If |
| this is a multi-column mapping, any of the columns can be used. Use a value of |
| <code class="literal">none</code> to prevent the column and its associated columns from |
| being reverse-mapped. |
| </p></li><li><p> |
| <code class="literal"><class name>.<field name>.type <field type></code> |
| : The type to give the named field. Use full class names. If the field or the |
| field's owner class has been renamed, use the new name. |
| </p></li><li><p> |
| <code class="literal"><class name>.<field name>.value</code>: The initial |
| value for the named field. The given string will be placed as-is in the |
| generated Java code, so be sure it is valid Java. If the field or the field's |
| owner class has been renamed, use the new name. |
| </p></li></ul></div><p> |
| All property keys are optional; if not specified, the customizer keeps the |
| default value generated by the reverse mapping tool. |
| </p><div class="example"><a name="ref_guide_pc_reverse_custom_ex"></a><p class="title"><b>Example 7.10. |
| Customizing Reverse Mapping with Properties |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| java org.apache.openjpa.jdbc.meta.ReverseMappingTool -pkg com.xyz -cp custom.properties schema.xml |
| </pre><p> |
| Example <code class="filename">custom.properties</code>: |
| </p><pre class="programlisting"> |
| com.xyz.TblMagazine.rename: com.xyz.Magazine |
| com.xyz.TblArticle.rename: com.xyz.Article |
| com.xyz.TblPubCompany.rename: com.xyz.pub.Company |
| com.xyz.TblSysInfo.rename: none |
| |
| com.xyz.Magazine.allArticles.rename: articles |
| com.xyz.Magazine.articles.type: java.util.Collection |
| com.xyz.Magazine.articles.value: new TreeSet() |
| com.xyz.Magazine.identity: datastore |
| |
| com.xyz.pub.Company.identity: com.xyz.pub.CompanyId |
| </pre></div></div><br class="example-break"></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_mapping_middle"></a>3. |
| Meet-in-the-Middle Mapping |
| </h2></div></div></div><a class="indexterm" name="d0e25714"></a><a class="indexterm" name="d0e25717"></a><a class="indexterm" name="d0e25722"></a><p> |
| In the <span class="emphasis"><em>meet-in-the-middle</em></span> |
| mapping approach, you control both the relational model and the object model. It |
| is up to you to define the mappings between these models. The mapping |
| tool's <code class="literal">validate</code> action is useful to meet-in-the-middle |
| mappers. This action verifies that the mapping information for a class matches |
| the class definition and the existing schema. It throws an informative exception |
| when your mappings are incorrect. |
| </p><div class="example"><a name="ref_guide_mapping_mappingtool_validate"></a><p class="title"><b>Example 7.11. |
| Validating Mappings |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| java org.apache.openjpa.jdbc.meta.MappingTool -action validate Magazine.java |
| </pre></div></div><br class="example-break"><p> |
| The <code class="literal">buildSchema</code> action we discussed in |
| <a href="#ref_guide_mapping_mappingtool" title="1. Forward Mapping">Section 1, “ |
| Forward Mapping |
| ”</a> is also somewhat useful |
| during meet-in-the-middle mapping. Unlike the <code class="literal">validate</code> |
| action, which throws an exception if your mapping data does not match the |
| existing schema, the <code class="literal">buildSchema</code> action assumes your mapping |
| data is correct, and modifies the schema to match your mappings. This lets you |
| modify your mapping data manually, but saves you the hassle of using your |
| database's tools to bring the schema up-to-date. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_mapping_defaults"></a>4. |
| Mapping Defaults |
| </h2></div></div></div><a class="indexterm" name="d0e25758"></a><a class="indexterm" name="d0e25761"></a><p> |
| The previous sections showed how to use the mapping tool to generate default |
| mappings. But how does the mapping tool know what mappings to generate? The |
| answer lies in the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/meta/MappingDefaults.html" target="_top"> |
| <code class="classname">org.apache.openjpa.jdbc.meta.MappingDefaults</code></a> |
| interface. OpenJPA uses an instance of this interface to decide how to name |
| tables and columns, where to put foreign keys, and generally how to create a |
| schema that matches your object model. |
| </p><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Important</h3><p> |
| OpenJPA relies on foreign key constraint information at runtime to order SQL |
| appropriately. Be sure to set your mapping defaults to reflect your existing |
| database constraints, set the schema factory to reflect on the database for |
| constraint information (see <a href="#ref_guide_schema_info_factory" title="12.2. Schema Factory">Section 12.2, “ |
| Schema Factory |
| ”</a>), |
| or use explicit foreign key mappings as described in |
| <a href="#ref_guide_mapping_jpa_fk" title="7.9.2. Foreign Keys">Section 7.9.2, “ |
| Foreign Keys |
| ”</a>. |
| </p></div><p> |
| The <a href="#openjpa.jdbc.MappingDefaults" title="6.8. openjpa.jdbc.MappingDefaults"><code class="literal"> |
| openjpa.jdbc.MappingDefaults</code></a> configuration property controls |
| the <code class="classname">MappingDefaults</code> interface implementation in use. This |
| is a plugin property (see <a href="#ref_guide_conf_plugins" title="4. Plugin Configuration">Section 4, “ |
| Plugin Configuration |
| ”</a>), so |
| you can substitute your own implementation or configure the existing ones. |
| OpenJPA includes the following standard implementations: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">jpa</code>: Provides defaults in compliance with the JPA standard. |
| This is an alias for the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/jdbc/PersistenceMappingDefaults.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.jdbc.PersistenceMappingDefaults |
| </code></a> class. This class extends the <code class="classname"> |
| MappingDefaultsImpl</code> class described below, so it has all the same |
| properties (though with different default values), as well as: |
| </p><div class="itemizedlist"><ul type="circle"><li><p> |
| <code class="literal">PrependFieldNameToJoinTableInverseJoinColumns</code>: Whether to |
| prepend the owning field name to the names of inverse join columns in join |
| tables. Defaults to true per the JPA specification. Set to false for |
| compatibility with older OpenJPA versions which did not prepend the field name. |
| </p></li></ul></div></li><li><p> |
| <code class="literal">default</code>: This is an alias for the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/meta/MappingDefaultsImpl.html" target="_top"> |
| <code class="classname">org.apache.openjpa.jdbc.meta.MappingDefaultsImpl</code></a> |
| class. This default implementation is highly configurable. It has the following |
| properties: |
| </p><div class="itemizedlist"><ul type="circle"><li><p> |
| <code class="literal">DefaultMissingInfo</code>: Whether to default missing column and |
| table names rather than throw an exception. If set to false, full explicit |
| mappings are required at runtime and when using mapping tool actions like |
| <code class="literal">buildSchema</code> and <code class="literal">validate</code>. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e25842"></a> |
| <code class="literal">RemoveHungarianNotation</code>: Switches on/off removal of |
| Hungarian notation when generating column names. |
| Fields such as <code class="literal">mFoobar</code> and <code class="literal">strBarFoo</code> |
| would become columns named <code class="literal">foobar</code> and |
| <code class="literal">barfoo</code> respectively. OpenJPA will search for the first |
| instance of a uppercase character in the field name and then truncate the |
| column name to remove anything before it. |
| </p></li><li><p> |
| <code class="literal">BaseClassStrategy</code>: The default mapping strategy for base |
| classes. You can specify a built-in strategy alias or the full class name of a |
| <a href="#ref_guide_mapping_custom_class" title="14.1. Custom Class Mapping">custom class strategy</a>. |
| You can also use OpenJPA's plugin format (see |
| <a href="#ref_guide_conf_plugins" title="4. Plugin Configuration">Section 4, “ |
| Plugin Configuration |
| ”</a>) to pass arguments to the |
| strategy instance. See the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/meta/strats/package-summary.html" target="_top"> |
| <code class="literal">org.apache.openjpa.jdbc.meta.strats</code></a> package for |
| available strategies. |
| </p></li><li><p> |
| <code class="literal">SubclassStrategy</code>: The default mapping strategy for |
| subclasses. You can specify a builtin strategy alias or the full class name of a |
| <a href="#ref_guide_mapping_custom_class" title="14.1. Custom Class Mapping"> custom class strategy</a>. |
| You can also use OpenJPA's plugin format (see |
| <a href="#ref_guide_conf_plugins" title="4. Plugin Configuration">Section 4, “ |
| Plugin Configuration |
| ”</a>) to pass arguments to the |
| strategy instance. Common strategies are <code class="literal">vertical</code> and |
| <code class="literal">flat</code>, the default. See the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/meta/strats/package-summary.html" target="_top"> |
| <code class="literal">org.apache.openjpa.jdbc.meta.strats</code></a> package for all |
| available strategies. |
| </p></li><li><p> |
| <code class="literal">VersionStrategy</code>: The default version strategy for classes |
| without a version field. You can specify a builtin strategy alias or the full |
| class name of a <a href="#ref_guide_mapping_custom_versdiscrim" title="14.2. Custom Discriminator and Version Strategies"> custom |
| version strategy</a>. You can also use OpenJPA's plugin format (see |
| <a href="#ref_guide_conf_plugins" title="4. Plugin Configuration">Section 4, “ |
| Plugin Configuration |
| ”</a>) to pass arguments to the |
| strategy instance. Common strategies are <code class="literal">none</code>, <code class="literal"> |
| state-comparison</code>, <code class="literal"> timestamp</code>, and <code class="literal"> |
| version-number</code>, the default. See the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/meta/strats/package-summary.html" target="_top"> |
| <code class="literal">org.apache.openjpa.jdbc.meta.strats</code></a> package for all |
| available strategies. |
| </p></li><li><p> |
| <code class="literal">DiscriminatorStrategy</code>: The default discriminator strategy |
| when no discriminator value is given. You can specify a builtin strategy alias |
| or the full class name of a |
| <a href="#ref_guide_mapping_custom_versdiscrim" title="14.2. Custom Discriminator and Version Strategies"> custom discriminator |
| strategy</a>. You can also use OpenJPA's plugin format (see |
| <a href="#ref_guide_conf_plugins" title="4. Plugin Configuration">Section 4, “ |
| Plugin Configuration |
| ”</a>) to pass arguments to the |
| strategy instance. Common strategies are <code class="literal">final</code> for a base |
| class without subclasses, <code class="literal">none</code> to use joins to subclass |
| tables rather than a discriminator column, and <code class="literal"> class-name</code>, |
| the default. See the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/meta/strats/package-summary.html" target="_top"> |
| <code class="literal">org.apache.openjpa.jdbc.meta.strats</code></a> package for all |
| available strategies. |
| </p></li><li><p> |
| <code class="literal">FieldStrategies</code>: This property associates field types with |
| custom strategies. The format of this property is similar to that of plugin |
| strings (see <a href="#ref_guide_conf_plugins" title="4. Plugin Configuration">Section 4, “ |
| Plugin Configuration |
| ”</a> ), without the class |
| name. It is a comma-separated list of key/value pairs, where each key is a |
| possible field type, and each value is itself a plugin string describing the |
| strategy for that type. We present an example below. See |
| <a href="#ref_guide_mapping_custom_field" title="14.3. Custom Field Mapping">Section 14.3, “ |
| Custom Field Mapping |
| ”</a> for information on custum |
| field strategies. |
| </p></li><li><p> |
| <code class="literal">ForeignKeyDeleteAction</code>: The default delete action of foreign |
| keys representing relations to other objects. Recognized values include |
| <code class="literal">restrict</code>, <code class="literal">cascade</code>, <code class="literal">null</code> |
| , <code class="literal">default</code>. These values correspond exactly to the standard |
| database foreign key actions of the same names. |
| </p><p> |
| The value <code class="literal">none</code> tells OpenJPA not to create database foreign |
| keys on relation columns. This is the default. |
| </p></li><li><p> |
| <code class="literal">JoinForeignKeyDeleteAction</code>: The defualt delete action of |
| foreign keys that join join secondary, collection, map, or subclass tables to |
| the primary table. Accepts the same values as the <code class="literal"> |
| ForeignKeyDeleteAction</code> property above. |
| </p></li><li><p> |
| <code class="literal">DeferConstraints</code>: Whether to use deferred database |
| constraints if possible. Defaults to false. |
| </p></li><li><p> |
| <code class="literal">IndexLogicalForeignKeys</code>: Boolean property controlling |
| whether to create indexes on logical foreign keys. Logical foreign keys are |
| columns that represent a link between tables, but have been configured through |
| the <code class="literal">ForeignKey</code> properties above not to use a physical |
| database foreign key. Defaults to true. |
| </p></li><li><p> |
| <code class="literal">DataStoreIdColumnName</code>: The default name of datastore |
| identity columns. |
| </p></li><li><p> |
| <code class="literal">DiscriminatorColumnName</code>: The default name of discriminator |
| columns. |
| </p></li><li><p> |
| <code class="literal">IndexDiscriminator</code>: Whether to index the discriminator |
| column. Defaults to true. |
| </p></li><li><p> |
| <code class="literal">VersionColumnName</code>: The default name of version columns. |
| </p></li><li><p> |
| <code class="literal">IndexVersion</code>: Whether to index the version column. Defaults |
| to false. |
| </p></li><li><p> |
| <code class="literal">AddNullIndicator</code>: Whether to create a synthetic null |
| indicator column for embedded mappings. The null indicator column allows OpenJPA |
| to distinguish between a null embedded object and one with default values for |
| all persistent fields. |
| </p></li><li><p> |
| <code class="literal">NullIndicatorColumnName</code>: The default name of synthetic null |
| indicator columns for embedded objects. |
| </p></li><li><p> |
| <code class="literal">OrderLists</code>: Whether to create a database ordering column for |
| maintaining the order of persistent lists and arrays. |
| </p></li><li><p> |
| <code class="literal">OrderColumnName</code>: The default name of collection and array |
| ordering columns. |
| </p></li><li><p> |
| <code class="literal">StoreEnumOrdinal</code>: Set to true to store enum fields as |
| numeric ordinal values in the database. The default is to store the enum value |
| name as a string, which is more robust if the Java enum declaration might be |
| rearranged. |
| </p></li><li><p> |
| <code class="literal">StoreUnmappedObjectIdString</code>: Set to true to store the |
| stringified identity of related objects when the declared related type is |
| unmapped. By default, OpenJPA stores the related object's primary key value(s). |
| However, this breaks down if different subclasses of the related type use |
| incompatible primary key structures. In that case, stringifying the identity |
| value is the better choice. |
| </p></li></ul></div></li></ul></div><p> |
| The example below turns on foreign key generation during schema creation and |
| associates the <code class="classname">org.mag.data.InfoStruct</code> field type with |
| the custom <code class="classname">org.mag.mapping.InfoStructHandler</code> value |
| handler. |
| </p><div class="example"><a name="ref_guide_mapping_defaults_conf"></a><p class="title"><b>Example 7.12. |
| Configuring Mapping Defaults |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| <property name="openjpa.jdbc.MappingDefaults" |
| value="ForeignKeyDeleteAction=restrict, |
| FieldStrategies='org.mag.data.InfoStruct=org.mag.mapping.InfoStructHandler'"/> |
| </pre></div></div><br class="example-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_mapping_factory"></a>5. |
| Mapping Factory |
| </h2></div></div></div><a class="indexterm" name="d0e26091"></a><a class="indexterm" name="d0e26094"></a><p> |
| An important decision in the object-relational mapping process is how and where |
| to store the data necessary to map your persistent classes to the database |
| schema. |
| </p><p> |
| <a href="#ref_guide_meta_factory" title="1. Metadata Factory">Section 1, “ |
| Metadata Factory |
| ”</a> introduced OpenJPA's <code class="classname"> |
| MetaDataFactory</code> interface. OpenJPA uses this same interface to |
| abstract the storage and retrieval of mapping information. OpenJPA includes the |
| built-in mapping factories below, and you can create your own factory if you |
| have custom needs. You control which mapping factory OpenJPA uses with the |
| <a href="#openjpa.jdbc.MappingFactory" title="6.9. openjpa.jdbc.MappingFactory"><code class="literal"> |
| openjpa.jdbc.MappingFactory</code></a> configuration property. |
| </p><p> |
| The bundled mapping factories are: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">-</code>: Leaving the <code class="literal"> openjpa.jdbc.MappingFactory |
| </code> property unset allows your metadata factory to take over mappings as |
| well. If you are using the default <code class="literal">jpa</code> metadata factory, |
| OpenJPA will read mapping information from your annotations and |
| <code class="filename">orm.xml</code> when you leave the mapping factory unspecified. |
| </p></li></ul></div><div class="example"><a name="ref_guide_mapping_factory_jpa"></a><p class="title"><b>Example 7.13. |
| Standard JPA Configuration |
| </b></p><div class="example-contents"><p> |
| In the standard JPA configuration, the mapping factory is left unset. |
| </p><pre class="programlisting"> |
| <property name="openjpa.MetaDataFactory" value="jpa"/> |
| </pre></div></div><br class="example-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_mapping_notes_nonstdjoins"></a>6. |
| Non-Standard Joins |
| </h2></div></div></div><a class="indexterm" name="d0e26142"></a><p> |
| The JPA Overview's <a href="#jpa_overview_mapping" title="Chapter 12. Mapping Metadata">Chapter 12, <i xmlns:xlink="http://www.w3.org/1999/xlink"> |
| Mapping Metadata |
| </i></a> explains join |
| mapping. All of the examples in that document, however, use "standard" joins, in |
| that there is one foreign key column for each primary key column in the target |
| table. OpenJPA supports additional join patterns, including partial primary key |
| joins, non-primary key joins, and joins using constant values. |
| </p><p> |
| <a class="indexterm" name="d0e26153"></a> |
| In a partial primary key join, the source table only has foreign key columns for |
| a subset of the primary key columns in the target table. So long as this subset |
| of columns correctly identifies the proper row(s) in the referenced table, |
| OpenJPA will function properly. There is no special syntax for expressing a |
| partial primary key join - just do not include column definitions for missing |
| foreign key columns. |
| </p><p> |
| <a class="indexterm" name="d0e26161"></a> |
| In a non-primary key join, at least one of the target columns is not a primary |
| key. Once again, OpenJPA supports this join type with the same syntax as a |
| primary key join. There is one restriction, however: each non-primary key column |
| you are joining to must be controlled by a field mapping that implements the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/meta/Joinable.html" target="_top"><code class="classname"> |
| org.apache.openjpa.jdbc.meta.Joinable</code></a> interface. All built |
| in basic mappings implement this interface, including basic fields of embedded |
| objects. OpenJPA will also respect any custom mappings that implement this |
| interface. See <a href="#ref_guide_mapping_custom" title="14. Custom Mappings">Section 14, “ |
| Custom Mappings |
| ”</a> for an |
| examination of custom mappings. |
| </p><p> |
| <a class="indexterm" name="d0e26175"></a> |
| Not all joins consist of only links between columns. In some cases you might |
| have a schema in which one of the join criteria is that a column in the source |
| or target table must have some constant value. OpenJPA calls joins involving |
| constant values <span class="emphasis"><em>constant joins</em></span>. |
| </p><p> |
| To form a constant join in JPA mapping, first set the <code class="literal">JoinColumn |
| </code>'s <code class="literal">name</code> attribute to the name of the column. If the |
| column with the constant value is the target of the join, give its fully |
| qualified name in the form <code class="literal"><table name>.<column name> |
| </code>. Next, set the <code class="literal">referencedColumnName</code> attribute to |
| the constant value. If the constant value is a string, place it in single quotes |
| to differentiate it from a column name. |
| </p><div class="mediaobject"><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="285"><tr><td><img src="img/joins-constant.png"></td></tr></table></div><p> |
| Consider the tables above. First, we want to join row <code class="literal">T1.R1</code> |
| to row <code class="literal">T2.R1</code>. If we just join column <code class="literal">T1.FK</code> |
| to <code class="literal">T2.PK1</code>, we will wind up matching both <code class="literal">T2.R1 |
| </code> and <code class="literal"> T2.R2</code>. So in addition to joining <code class="literal"> |
| T1.FK</code> to <code class="literal">T2.PK1</code>, we also have to specify that |
| <code class="literal">T2.PK2</code> has the value <code class="literal">a</code>. Here is how we'd |
| accomplish this in mapping metadata. |
| </p><pre class="programlisting"> |
| @Entity |
| @Table(name="T1") |
| public class ... { |
| |
| @ManyToOne |
| @JoinColumns({ |
| @JoinColumn(name="FK" referencedColumnName="PK1"), |
| @JoinColumn(name="T2.PK2" referencedColumnName="'a'") |
| }); |
| private ...; |
| } |
| </pre><p> |
| Notice that we had to fully qualify the name of column <code class="literal">PK2</code> |
| because it is in the target table. Also notice that we put single quotes around |
| the constant value so that it won't be confused with a column name. You do not |
| need single quotes for numeric constants. For example, the syntax to join |
| <code class="literal">T1.R2</code> to <code class="literal">T2.R4</code> is: |
| </p><pre class="programlisting"> |
| @Entity |
| @Table(name="T1") |
| public class ... { |
| |
| @ManyToOne |
| @JoinColumns({ |
| @JoinColumn(name="FK" referencedColumnName="PK2"), |
| @JoinColumn(name="T2.PK1" referencedColumnName="2") |
| }); |
| private ...; |
| } |
| </pre><p> |
| Finally, from the inverse direction, these joins would look like this: |
| </p><pre class="programlisting"> |
| @Entity |
| @Table(name="T2") |
| public class ... { |
| |
| @ManyToOne |
| @JoinColumns({ |
| @JoinColumn(name="T1.FK" referencedColumnName="PK1"), |
| @JoinColumn(name="PK2" referencedColumnName="'a'") |
| }); |
| private ...; |
| |
| @ManyToOne |
| @JoinColumns({ |
| @JoinColumn(name="T1.FK" referencedColumnName="PK2"), |
| @JoinColumn(name="PK1" referencedColumnName="2") |
| }); |
| private ...; |
| } |
| </pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_mapping_jpa"></a>7. |
| Additional JPA Mappings |
| </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#ref_guide_mapping_jpa_datastoreid">7.1. |
| Datastore Identity Mapping |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_jpa_version">7.2. |
| Surrogate Version Mapping |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_jpa_columns">7.3. |
| Multi-Column Mappings |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_jpa_fieldjoin">7.4. |
| Join Column Attribute Targets |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_jpa_embed">7.5. |
| Embedded Mapping |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_jpa_coll">7.6. |
| Collections |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_mapping_jpa_coll_table">7.6.1. |
| Container Table |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_jpa_coll_joincols">7.6.2. |
| Element Join Columns |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_jpa_coll_order">7.6.3. |
| Order Column |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_mapping_jpa_onemany">7.7. |
| One-Sided One-Many Mapping |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_jpa_map">7.8. |
| Maps |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_jpa_constraints">7.9. |
| Indexes and Constraints |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_mapping_jpa_index">7.9.1. |
| Indexes |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_jpa_fk">7.9.2. |
| Foreign Keys |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_jpa_unique">7.9.3. |
| Unique Constraints |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_xmlmapping">7.10. |
| XML Column Mapping |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_streamsupport">7.11. |
| Stream LOB Support |
| </a></span></dt></dl></div><a class="indexterm" name="d0e26256"></a><p> |
| OpenJPA supports many persistence strategies beyond those of the JPA |
| specification. <a href="#ref_guide_meta_jpa" title="3. Additional JPA Metadata">Section 3, “ |
| Additional JPA Metadata |
| ”</a> covered the logical |
| metadata for OpenJPA's additional persistence strategies. We now demonstrate how |
| to map entities using these strategies to the database. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_mapping_jpa_datastoreid"></a>7.1. |
| Datastore Identity Mapping |
| </h3></div></div></div><a class="indexterm" name="d0e26268"></a><a class="indexterm" name="d0e26273"></a><a class="indexterm" name="d0e26280"></a><a class="indexterm" name="d0e26285"></a><p> |
| <a href="#ref_guide_pc_oid" title="4. Object Identity">Section 4, “ |
| Object Identity |
| ”</a> describes how to use datastore identity |
| in JPA. OpenJPA requires a single numeric primary key column to hold datastore |
| identity values. The |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/jdbc/DataStoreIdColumn.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.jdbc.DataStoreIdColumn</code> |
| </a> annotation customizes the datastore identity column. This annotation |
| has the following properties: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">String name</code>: Defaults to <code class="literal">ID</code>. |
| </p></li><li><p> |
| <code class="literal">int precision</code> |
| </p></li><li><p> |
| <code class="literal">String columnDefinition</code> |
| </p></li><li><p> |
| <code class="literal">boolean insertable</code> |
| </p></li><li><p> |
| <code class="literal">boolean updatable</code> |
| </p></li></ul></div><p> |
| All properties correspond exactly to the same-named properties on the standard |
| <code class="classname">Column</code> annotation, described in |
| <a href="#jpa_overview_mapping_column" title="3. Column">Section 3, “ |
| Column |
| ”</a>. |
| </p><div class="example"><a name="ref_guide_mapping_jpa_datastoreidex"></a><p class="title"><b>Example 7.14. |
| Datastore Identity Mapping |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| import org.apache.openjpa.persistence.*; |
| import org.apache.openjpa.persistence.jdbc.*; |
| |
| @Entity |
| @Table(name="LOGS") |
| @DataStoreIdColumn(name="ENTRY") |
| public class LogEntry { |
| |
| @Lob |
| private String content; |
| |
| ... |
| } |
| </pre></div></div><br class="example-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_mapping_jpa_version"></a>7.2. |
| Surrogate Version Mapping |
| </h3></div></div></div><a class="indexterm" name="d0e26347"></a><a class="indexterm" name="d0e26352"></a><a class="indexterm" name="d0e26359"></a><p> |
| OpenJPA supports version fields as defined by the JPA specification, but allows |
| you to use a surrogate version column in place of a version field if you like. |
| You map the surrogate version column with the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/jdbc/VersionColumn.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.jdbc.VersionColumn</code></a> |
| annotation. You can also use the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/jdbc/VersionColumns.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.jdbc.VersionColumns</code> |
| </a> annotation to declare an array of <code class="classname">VersionColumn</code> |
| values. Each <code class="classname">VersionColumn</code> has the following properties: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">String name</code>: Defaults to <code class="literal">VERSN</code>. |
| </p></li><li><p> |
| <code class="literal">int length</code> |
| </p></li><li><p> |
| <code class="literal">int precision</code> |
| </p></li><li><p> |
| <code class="literal">int scale</code> |
| </p></li><li><p> |
| <code class="literal">String columnDefinition</code> |
| </p></li><li><p> |
| <code class="literal">boolean nullable</code> |
| </p></li><li><p> |
| <code class="literal">boolean insertable</code> |
| </p></li><li><p> |
| <code class="literal">boolean updatable</code> |
| </p></li></ul></div><p> |
| All properties correspond exactly to the same-named properties on the standard |
| <code class="classname">Column</code> annotation, described in |
| <a href="#jpa_overview_mapping_column" title="3. Column">Section 3, “ |
| Column |
| ”</a>. |
| </p><p> |
| By default, OpenJPA assumes that surrogate versioning uses a version number |
| strategy. You can choose a different strategy with the <code class="classname"> |
| VersionStrategy</code> annotation described in |
| <a href="#version-strategy" title="13.1.4. Version Strategy">Section 13.1.4, “ |
| Version Strategy |
| ”</a>. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_mapping_jpa_columns"></a>7.3. |
| Multi-Column Mappings |
| </h3></div></div></div><a class="indexterm" name="d0e26452"></a><a class="indexterm" name="d0e26457"></a><a class="indexterm" name="d0e26462"></a><p> |
| OpenJPA makes it easy to create multi-column |
| <a href="#ref_guide_mapping_custom_field" title="14.3. Custom Field Mapping">custom mappings</a>. The JPA |
| specification includes a <code class="classname">Column</code> annotation, but is |
| missing a way to declare multiple columns for a single field. OpenJPA remedies |
| this with the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/jdbc/Columns.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.jdbc.Columns</code></a> |
| annotation, which contains an array of <code class="classname">Column</code> values. |
| </p><p> |
| Remember to annotate custom field types with <code class="classname">Persistent</code>, |
| as described in <a href="#ref_guide_meta_jpa_persistent" title="3.3. Persistent Field Values">Section 3.3, “ |
| Persistent Field Values |
| ”</a>. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_mapping_jpa_fieldjoin"></a>7.4. |
| Join Column Attribute Targets |
| </h3></div></div></div><p> |
| <a href="#jpa_overview_mapping_rel" title="8.4. Direct Relations">Section 8.4, “ |
| Direct Relations |
| ”</a> in the JPA Overview introduced |
| you to the <code class="classname">JoinColumn</code> annotation. A <code class="classname"> |
| JoinColumn</code>'s <code class="literal"> referencedColumnName</code> property |
| declares which column in the table of the related type this join column links |
| to. Suppose, however, that the related type is unmapped, or that it is part of a |
| table-per-class inheritance hierarchy. Each subclass that might be assigned to |
| the field could reside in a different table, and could use entirely different |
| names for its primary key columns. It becomes impossible to supply a single |
| <code class="literal">referencedColumnName</code> that works for all subclasses. |
| </p><p> |
| OpenJPA rectifies this by allowing you to declare which <span class="emphasis"><em>attribute |
| </em></span> in the related type each join column links to, rather than which |
| column. If the attribute is mapped differently in various subclass tables, |
| OpenJPA automatically forms the proper join for the subclass record at hand. The |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/jdbc/XJoinColumn.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.jdbc.XJoinColumn</code></a> |
| annotation has all the same properties as the standard <code class="classname">JoinColumn |
| </code> annotation, but adds an additional <code class="literal"> |
| referencedAttributeName</code> property for this purpose. Simply use a |
| <code class="classname">XJoinColumn</code> in place of a <code class="classname">JoinColumn |
| </code> whenever you need to access this added functionality. |
| </p><p> |
| For compound keys, use the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/jdbc/XJoinColumns.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.jdbc.XJoinColumns</code></a> |
| annotation. The value of this annotation is an array of individual <code class="classname"> |
| XJoinColumn</code>s. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_mapping_jpa_embed"></a>7.5. |
| Embedded Mapping |
| </h3></div></div></div><p> |
| JPA uses the <code class="classname">AttributeOverride</code> annotation to override the |
| default mappings of an embeddable class. The JPA Overview details this process |
| in <a href="#jpa_overview_mapping_embed" title="8.3. Embedded Mapping">Section 8.3, “ |
| Embedded Mapping |
| ”</a>. <code class="classname"> |
| AttributeOverride</code>s suffice for simple mappings, but do not allow |
| you to override complex mappings. Also, JPA has no way to differentitate between |
| a null embedded object and one with default values for all of its fields. |
| </p><p> |
| OpenJPA overcomes these shortcomings with the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/jdbc/EmbeddedMapping.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.jdbc.EmbeddedMapping</code> |
| </a> annotation. This annotation has the following properties: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">String nullIndicatorColumnName</code>: If the named column's value |
| is <code class="literal">NULL</code>, then the embedded object is assumed to be null. If |
| the named column has a non- <code class="literal">NULL</code> value, then the embedded |
| object will get loaded and populated with data from the other embedded fields. |
| This property is entirely optional. By default, OpenJPA always assumes the |
| embedded object is non-null, just as in standard JPA mapping. |
| </p><p> |
| If the column you name does not belong to any fields of the embedded object, |
| OpenJPA will create a synthetic null-indicator column with this name. In fact, |
| you can specify a value of <code class="literal">true</code> to simply indicate that you |
| want a synthetic null-indicator column, without having to come up with a name |
| for it. A value of <code class="literal">false</code> signals that you explicitly do not |
| want a null-indicator column created for this mapping (in case you have |
| configured your <a href="#ref_guide_mapping_defaults" title="4. Mapping Defaults">mapping defaults |
| </a> to create one by default). |
| </p></li><li><p> |
| <code class="literal">String nullIndicatorFieldName</code>: Rather than name a null |
| indicator column, you can name a field of the embedded type. OpenJPA will use |
| the column of this field as the null-indicator column. |
| </p></li><li><p> |
| <code class="literal">MappingOverride[] overrides</code>: This array allows you to |
| override any mapping of the embedded object. |
| </p></li></ul></div><p> |
| The <code class="classname">EmbeddedMapping</code>'s <code class="literal">overrides</code> array |
| serves the same purpose as standard JPA's <code class="classname">AttributeOverride |
| </code>s and <code class="classname">AssociationOverride</code> s. In fact, you can |
| also use the <code class="classname">MappingOverride</code> annotation on an entity |
| class to override a complex mapping of its mapped superclass, just as you can |
| with <code class="classname"> AttributeOverride</code> and <code class="classname"> |
| AssociationOverride</code> s. The <code class="classname">MappingOverrides</code> |
| annotation, whose value is an array of <code class="classname">MappingOverride</code> s, |
| allows you to overide multiple mapped superclass mappings. |
| </p><p> |
| Each |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/jdbc/MappingOverride.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.jdbc.MappingOverride</code> |
| </a> annotation has the following properties: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">String name</code>: The name of the field that is being overridden. |
| </p></li><li><p> |
| <code class="literal">Column[] columns</code>: Columns for the new field mapping. |
| </p></li><li><p> |
| <code class="literal">XJoinColumn[] joinColumns</code>: Join columns for the new field |
| mapping, if it is a relation field. |
| </p></li><li><p> |
| <code class="literal">ContainerTable containerTable</code>: Table for the new collection |
| or map field mapping. We cover collection mappings in |
| <a href="#ref_guide_mapping_jpa_coll" title="7.6. Collections">Section 7.6, “ |
| Collections |
| ”</a>, and map mappings in |
| <a href="#ref_guide_mapping_jpa_map" title="7.8. Maps">Section 7.8, “ |
| Maps |
| ”</a>. |
| </p></li><li><p> |
| <code class="literal">ElementJoinColumn[] elementJoinColumns</code>: Element join columns |
| for the new collection or map field mapping. You will see how to use element |
| join columns in <a href="#ref_guide_mapping_jpa_coll_joincols" title="7.6.2. Element Join Columns">Section 7.6.2, “ |
| Element Join Columns |
| ”</a>. |
| </p></li></ul></div><p> |
| The following example defines an embeddable <code class="classname"> PathCoordinate |
| </code> class with a custom mapping of a <code class="classname">java.awt.Point |
| </code> field to two columns. It then defines an entity which embeds a |
| <code class="classname"> PointCoordinate</code> and overrides the default mapping for |
| the point field. The entity also declares that if the <code class="classname">PathCoordinate |
| </code>'s <code class="literal">siteName</code> field column is null, it means that |
| no <code class="classname">PathCoordinate</code> is stored in the embedded record; the |
| owning field will load as null. |
| </p><div class="example"><a name="ref_guide_mapping_jpa_embedex"></a><p class="title"><b>Example 7.15. |
| Overriding Complex Mappings |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| import org.apache.openjpa.persistence.jdbc.*; |
| |
| @Embeddable |
| public class PathCoordinate { |
| |
| private String siteName; |
| |
| @Persistent |
| @Strategy("com.xyz.openjpa.PointValueHandler") |
| private Point point; |
| |
| ... |
| } |
| |
| @Entity |
| public class Path { |
| |
| @Embedded |
| @EmbeddedMapping(nullIndicatorFieldName="siteName", overrides={ |
| @MappingOverride(name="siteName", columns=@Column(name="START_SITE")), |
| @MappingOverride(name="point", columns={ |
| @Column(name="START_X"), |
| @Column(name="START_Y") |
| }) |
| }) |
| private PathCoordinate start; |
| |
| ... |
| } |
| </pre></div></div><br class="example-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_mapping_jpa_coll"></a>7.6. |
| Collections |
| </h3></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#ref_guide_mapping_jpa_coll_table">7.6.1. |
| Container Table |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_jpa_coll_joincols">7.6.2. |
| Element Join Columns |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_jpa_coll_order">7.6.3. |
| Order Column |
| </a></span></dt></dl></div><a class="indexterm" name="d0e26700"></a><p> |
| In <a href="#ref_guide_meta_jpa_persistent_coll" title="3.4. Persistent Collection Fields">Section 3.4, “Persistent Collection Fields”</a>, we explored the |
| <code class="classname">PersistentCollection</code> annotation for persistent collection |
| fields that aren't a standard <code class="literal">OneToMany</code> or <code class="literal"> |
| ManyToMany</code> relation. To map these non-standard collections, combine |
| OpenJPA's <code class="classname">ContainerTable</code> annotation with |
| <code class="classname">ElementJoinColumn</code>s. |
| We explore the annotations below. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="ref_guide_mapping_jpa_coll_table"></a>7.6.1. |
| Container Table |
| </h4></div></div></div><a class="indexterm" name="d0e26727"></a><p> |
| The |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/jdbc/ContainerTable.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.jdbc.ContainerTable</code> |
| </a> annotation describes a database table that holds collection (or map) |
| elements. This annotation has the following properties: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">String name</code> |
| </p></li><li><p> |
| <code class="literal">String catalog</code> |
| </p></li><li><p> |
| <code class="literal">String schema</code> |
| </p></li><li><p> |
| <code class="literal">XJoinColumn[] joinColumns</code> |
| </p></li><li><p> |
| <code class="literal">ForeignKey joinForeignKey</code> |
| </p></li><li><p> |
| <code class="literal">Index joinIndex</code> |
| </p></li></ul></div><p> |
| The <code class="literal">name</code>, <code class="literal">catalog</code>, <code class="literal">schema |
| </code>, and <code class="literal">joinColumns</code> properties describe the container |
| table and how it joins to the owning entity's table. These properties correspond |
| to the same-named properties on the standard <code class="classname"> JoinTable</code> |
| annotation, described in <a href="#jpa_overview_mapping_assoccoll" title="8.5. Join Table">Section 8.5, “ |
| Join Table |
| ”</a> |
| . If left unspecified, the name of the table defaults to the first five |
| characters of the entity table name, plus an underscore, plus the field name. |
| The <code class="literal">joinForeignKey</code> and <code class="literal"> joinIndex</code> |
| properties override default foreign key and index generation for the join |
| columns. We explore foreign keys and indexes later in this chapter. |
| </p><p> |
| You may notice that the container table does not define how to store the |
| collection elements. That is left to separate annotations, which are the subject |
| of the next sections. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="ref_guide_mapping_jpa_coll_joincols"></a>7.6.2. |
| Element Join Columns |
| </h4></div></div></div><a class="indexterm" name="d0e26807"></a><p> |
| Element join columns are equivalent to standard JPA join columns, except that |
| they represent a join to a collection or map element entity rather than a direct |
| relation. You represent an element join column with OpenJPA's |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/jdbc/ElementJoinColumn.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.jdbc.ElementJoinColumn</code> |
| </a> annotation. To declare a compound join, enclose an array of <code class="classname"> |
| ElementJoinColumn</code>s in the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/jdbc/ElementJoinColumns.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.jdbc.ElementJoinColumns</code> |
| </a> annotation. |
| </p><p> |
| An <code class="classname">ElementJoinColumn</code> always resides in a container table, |
| so it does not have the <code class="literal"> table</code> property of a standard |
| <code class="classname"> JoinColumn</code>. Like <code class="classname"> XJoinColumn</code>s |
| above, <code class="classname"> ElementJoinColumn</code>s can reference a linked |
| attribute rather than a static linked column. Otherwise, the <code class="classname"> |
| ElementJoinColumn</code> and standard <code class="classname">JoinColumn</code> |
| annotations are equivalent. See <a href="#jpa_overview_mapping_rel" title="8.4. Direct Relations">Section 8.4, “ |
| Direct Relations |
| ”</a> |
| in the JPA Overview for a review of the <code class="classname">JoinColumn</code> |
| annotation. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="ref_guide_mapping_jpa_coll_order"></a>7.6.3. |
| Order Column |
| </h4></div></div></div><a class="indexterm" name="d0e26860"></a><p> |
| Relational databases do not guarantee that records are returned in insertion |
| order. If you want to make sure that your collection elements are loaded in the |
| same order they were in when last stored, you must declare an order column. |
| OpenJPA's |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/jdbc/OrderColumn" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.jdbc.OrderColumn</code></a> |
| annotation has the following properties: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">String name</code>: Defaults to <code class="literal">ORDR</code>. |
| </p></li><li><p> |
| <code class="literal">boolean enabled</code> |
| </p></li><li><p> |
| <code class="literal">int precision</code> |
| </p></li><li><p> |
| <code class="literal">String columnDefinition</code> |
| </p></li><li><p> |
| <code class="literal">boolean insertable</code> |
| </p></li><li><p> |
| <code class="literal">boolean updatable</code> |
| </p></li></ul></div><p> |
| Order columns are always in the container table. You can explicitly turn off |
| ordering (if you have enabled it by default via your |
| <a href="#ref_guide_mapping_defaults" title="4. Mapping Defaults"> mapping defaults</a>) by setting |
| the <code class="literal">enabled</code> property to <code class="literal">false</code>. All other |
| properties correspond exactly to the same-named properties on the standard |
| <code class="classname">Column</code> annotation, described in |
| <a href="#jpa_overview_mapping_column" title="3. Column">Section 3, “ |
| Column |
| ”</a>. |
| </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_mapping_jpa_onemany"></a>7.7. |
| One-Sided One-Many Mapping |
| </h3></div></div></div><a class="indexterm" name="d0e26931"></a><p> |
| The previous section covered the use of <code class="classname">ElementJoinColumn</code> |
| annotations in conjunction with a <code class="classname">ContainerTable</code> for |
| mapping collections to dedicate tables. <code class="classname">ElementJoinColumn</code> |
| s, however, have one additional use: to create a one-sided one-many mapping. |
| Standard JPA supports <code class="classname">OneToMany</code> fields without a |
| <code class="literal">mappedBy</code> inverse, but only by mapping these fields to a |
| <code class="classname">JoinTable</code> (see |
| <a href="#jpa_overview_mapping_assoccoll" title="8.5. Join Table">Section 8.5, “ |
| Join Table |
| ”</a> in the JPA Overview for |
| details). Often, you'd like to create a one-many association based on an inverse |
| foreign key (logical or actual) in the table of the related type. |
| </p><div class="mediaobject"><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="261"><tr><td><img src="img/inv-key-coll.png"></td></tr></table></div><p> |
| Consider the model above. <code class="classname">Subscription</code> has a collection |
| of <code class="classname">LineItem</code> s, but <code class="classname">LineItem</code> has |
| no inverse relation to <code class="classname">Subscription</code>. To retrieve all of |
| the <code class="classname">LineItem</code> records for a <code class="classname">Subscription |
| </code>, we join the <code class="literal">SUB_ID</code> inverse foreign key column |
| in the <code class="literal">LINE_ITEM</code> table to the primary key column of the |
| <code class="literal">SUB</code> table. The example below shows how to represent this |
| model in mapping annotations. Note that OpenJPA automatically assumes an inverse |
| foreign key mapping when element join columns are given, but no container or |
| join table is given. |
| </p><div class="example"><a name="ref_guide_mapping_jpa_onemanyex"></a><p class="title"><b>Example 7.16. |
| One-Sided One-Many Mapping |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| package org.mag.subscribe; |
| |
| import org.apache.openjpa.persistence.jdbc.*; |
| |
| @Entity |
| @Table(name="LINE_ITEM", schema="CNTRCT") |
| public class LineItem { |
| ... |
| } |
| |
| @Entity |
| @Table(name="SUB", schema="CNTRCT") |
| public class Subscription { |
| |
| @Id private long id; |
| |
| @OneToMany |
| @ElementJoinColumn(name="SUB_ID", referencedColumnName="ID") |
| private Collection<LineItem> items; |
| |
| ... |
| } |
| </pre></div></div><br class="example-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_mapping_jpa_map"></a>7.8. |
| Maps |
| </h3></div></div></div><a class="indexterm" name="d0e27001"></a><p> |
| We detailed the <code class="literal">ContainerTable</code> annotation in |
| <a href="#ref_guide_mapping_jpa_coll_table" title="7.6.1. Container Table">Section 7.6.1, “ |
| Container Table |
| ”</a>. Custom map mappings may |
| also use this annotation to represent a map table. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_mapping_jpa_constraints"></a>7.9. |
| Indexes and Constraints |
| </h3></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#ref_guide_mapping_jpa_index">7.9.1. |
| Indexes |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_jpa_fk">7.9.2. |
| Foreign Keys |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_jpa_unique">7.9.3. |
| Unique Constraints |
| </a></span></dt></dl></div><p> |
| OpenJPA uses index information during schema generation to index the proper |
| columns. OpenJPA uses foreign key and unique constraint information during |
| schema creation to generate the proper database constraints, and also at runtime |
| to order SQL statements to avoid constraint violations while maximizing SQL |
| batch size. |
| </p><p> |
| OpenJPA assumes certain columns have indexes or constraints based on your |
| mapping defaults, as detailed in <a href="#ref_guide_mapping_defaults" title="4. Mapping Defaults">Section 4, “ |
| Mapping Defaults |
| ”</a>. |
| You can override the configured defaults on individual joins, field |
| values, collection elements, map keys, or map values using the annotations |
| presented in the following sections. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="ref_guide_mapping_jpa_index"></a>7.9.1. |
| Indexes |
| </h4></div></div></div><a class="indexterm" name="d0e27025"></a><a class="indexterm" name="d0e27030"></a><p> |
| The <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/jdbc/Index.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.jdbc.Index</code></a> |
| annotation represents an index on the columns of a field. It is also used within |
| the <a href="#ref_guide_mapping_jpa_coll_table" title="7.6.1. Container Table"><code class="classname">ContainerTable |
| </code></a> annotation to index join columns. |
| To index the columns of a collection element, use the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/jdbc/ElementIndex.html" target="_top"> |
| <code class="classname"> org.apache.openjpa.persistence.jdbc.ElementIndex</code></a> |
| annotation. These annotations have the following properties: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">boolean enabled</code>: Set this property to <code class="literal">false |
| </code> to explicitly tell OpenJPA not to index these columns, when OpenJPA |
| would otherwise do so. |
| </p></li><li><p> |
| <code class="literal">String name</code>: The name of the index. OpenJPA will choose a |
| name if you do not provide one. |
| </p></li><li><p> |
| <code class="literal">boolean unique</code>: Whether to create a unique index. Defaults |
| to false. |
| </p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="ref_guide_mapping_jpa_fk"></a>7.9.2. |
| Foreign Keys |
| </h4></div></div></div><a class="indexterm" name="d0e27074"></a><a class="indexterm" name="d0e27079"></a><p> |
| The <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/jdbc/ForeignKey.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.jdbc.ForeignKey</code></a> |
| annotation represents a foreign key on the columns of a field. It is also used |
| within the <a href="#ref_guide_mapping_jpa_coll_table" title="7.6.1. Container Table"><code class="classname"> |
| ContainerTable</code></a> annotation to set a database foreign key on |
| join columns. To set a constraint to the columns of a collection element, use |
| the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/jdbc/ElementForeignKey.html" target="_top"> |
| <code class="classname"> org.apache.openjpa.persistence.jdbc.ElementForeignKey</code> |
| </a> annotation. These annotations have the following properties: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">boolean enabled</code>: Set this property to <code class="literal">false |
| </code> to explicitly tell OpenJPA not to set a foreign key on these columns, |
| when OpenJPA would otherwise do so. |
| </p></li><li><p> |
| <code class="literal">String name</code>: The name of the foreign key. OpenJPA will |
| choose a name if you do not provide one, or will create an anonymous key. |
| </p></li><li><p> |
| <code class="literal">boolean deferred</code>: Whether to create a deferred key if |
| supported by the database. |
| </p></li><li><p> |
| <code class="literal">ForeignKeyAction deleteAction</code>: Value from the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/jdbc/ForeignKeyAction.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.jdbc.ForeignKeyAction</code> |
| </a> enum identifying the desired delete action. Defaults to <code class="literal"> |
| RESTRICT</code>. |
| </p></li><li><p> |
| <code class="literal">ForeignKeyAction updateAction</code>: Value from the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/jdbc/ForeignKeyAction.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.jdbc.ForeignKeyAction</code> |
| </a> enum identifying the desired update action. Defaults to <code class="literal"> |
| RESTRICT</code>. |
| </p></li></ul></div><p> |
| Keep in mind that OpenJPA uses foreign key information at runtime to avoid |
| constraint violations; it is important, therefore, that your |
| <a href="#ref_guide_mapping_defaults" title="4. Mapping Defaults">mapping defaults</a> and foreign |
| key annotations combine to accurately reflect your existing database |
| constraints, or that you configure OpenJPA to reflect on your database schema |
| to discover existing foreign keys (see |
| <a href="#ref_guide_schema_info_factory" title="12.2. Schema Factory">Section 12.2, “ |
| Schema Factory |
| ”</a>). |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="ref_guide_mapping_jpa_unique"></a>7.9.3. |
| Unique Constraints |
| </h4></div></div></div><a class="indexterm" name="d0e27161"></a><a class="indexterm" name="d0e27166"></a><p> |
| The <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/jdbc/Unique.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.jdbc.Unique</code></a> |
| annotation represents a unqiue constraint on the columns of a field. It is more |
| convenient than using the <code class="literal">uniqueConstraints</code> property of |
| standard JPA <code class="classname">Table</code> and <code class="classname">SecondaryTable |
| </code> annotations, because you can apply it directly to the constrained |
| field. The <code class="classname">Unique</code> annotation has the following |
| properties: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">boolean enabled</code>: Set this property to <code class="literal">false |
| </code> to explicitly tell OpenJPA not to constrain these columns, when |
| OpenJPA would otherwise do so. |
| </p></li><li><p> |
| <code class="literal">String name</code>: The name of the constraint. OpenJPA will choose |
| a name if you do not provide one, or will create an anonymous constraint. |
| </p></li><li><p> |
| <code class="literal">boolean deferred</code>: Whether to create a deferred constraint if |
| supported by the database. |
| </p></li></ul></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_xmlmapping"></a>7.10. |
| XML Column Mapping |
| </h3></div></div></div><a class="indexterm" name="d0e27213"></a><a class="indexterm" name="d0e27218"></a><p> |
| DB2, Oracle and SQLServer support XML column types and |
| XPath queries and indexes over these columns.OpenJPA supports mapping of an |
| entity property mapped to an XML column. |
| </p><p> |
| Annotate the entity property using the XMLValueHandler strategy: |
| </p><pre class="programlisting"> |
| @Persistent |
| @Strategy("org.apache.openjpa.jdbc.meta.strats.XMLValueHandler") |
| </pre><p> |
| The default fetch type is EAGER but can be changed to LAZY by using: |
| </p><pre class="programlisting"> |
| @Persistence(fetch=FetchType.LAZY) |
| </pre><p> |
| The entity property class is required to have |
| jaxb binding annotations. This is produced when the classes are generated |
| from an xml schema using the jaxb generator XJC.Ensure that <code class="classname">@XmlRootElement</code> |
| appears in the root class. In some case this annotation needs to be added manually if it is missing. |
| </p><p> |
| The jaxb jar files must be on the application classpath (jaxb-api.jar, |
| jaxb-impl.jar, jsr173_1.0_api.jar or equivalent). |
| </p><p> |
| EJB Query path expressions can navigate into the mapped class and its |
| subfields to any level. |
| </p><p> |
| The path expression is rewritten into an equivalent XPATH expression using SQL |
| XML functions. |
| </p><p> |
| The path expression must be single valued.Path expressions over xml |
| mapped classes can only be used in WHERE as an operand to a simple predicate |
| (= <> < > >= <=). |
| </p><p> |
| Path expressions over XML mapped fields can not be: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| an input to a EJB query scalar function |
| </p></li><li><p> |
| an operand of BETWEEN, IS NULL, LIKE or IN predicate |
| </p></li><li><p> |
| used to project out subfields in the SELECT clause |
| </p></li><li><p> |
| used in the FROM , GROUP BY, HAVING, ORDER BY clauses |
| </p></li></ul></div><p> |
| XML schema must not contain namespace declarations. The EJB query path |
| expressions can not refer to java fields generated from XML ANY type or |
| XML mixed element types. |
| </p><p> |
| The datatype generated by JAXB must be a valid EJB query type |
| to use the property in an EJB query predicate. |
| </p><p> |
| Shown below is a sample XML schema <a href="#ref_guide_xmlmapping_myaddress" title="Example 7.17. myaddress.xsd">myaddress.xsd</a>, |
| in which the JPA entity Order has <code class="classname"><shipAddress></code> persistent field that maps to an XML column. |
| </p><div class="example"><a name="ref_guide_xmlmapping_myaddress"></a><p class="title"><b>Example 7.17. |
| myaddress.xsd |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| <?xml version="1.0" ?> |
| <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" > |
| |
| <xs:complexType name="Address"> |
| <xs:sequence> |
| <xs:element name="Name" type="xs:string" /> |
| <xs:element name="Street" type="xs:string" |
| minOccurs="1" maxOccurs="3" /> |
| <xs:element name="City" type="xs:string" /> |
| </xs:sequence> |
| </xs:complexType> |
| |
| <xs:complexType name="CAN_Address"> |
| <xs:complexContent> |
| <xs:extension base="Address"> |
| <xs:sequence> |
| <xs:element name="Province" type="xs:string" /> |
| <xs:element name="PostalCode" type="xs:string" /> |
| </xs:sequence> |
| </xs:extension> |
| </xs:complexContent> |
| </xs:complexType> |
| |
| <xs:simpleType name="USPS_ZIP"> |
| <xs:restriction base="xs:integer"> |
| <xs:minInclusive value="01000" /> |
| <xs:maxInclusive value="99999" /> |
| </xs:restriction> |
| </xs:simpleType> |
| |
| <xs:complexType name="USA_Address"> |
| <xs:complexContent> |
| <xs:extension base="Address"> |
| <xs:sequence> |
| <xs:element name="State" type="xs:string" /> |
| <xs:element name="ZIP" type="USPS_ZIP" /> |
| </xs:sequence> |
| </xs:extension> |
| </xs:complexContent> |
| </xs:complexType> |
| |
| <xs:element name="MailAddress" type="Address" /> |
| <xs:element name="AddrCAN" type="CAN_Address" |
| substitutionGroup="MailAddress" /> |
| <xs:element name="AddrUSA" type="USA_Address" |
| substitutionGroup="MailAddress" /> |
| </xs:schema> |
| </pre></div></div><br class="example-break"><p> |
| Java classes <a href="#ref_guide_xmlmapping_address" title="Example 7.18. Address.Java">Address</a>, |
| <a href="#ref_guide_xmlmapping_usaaddress" title="Example 7.19. USAAddress.java">USAAddress</a> and |
| <a href="#ref_guide_xmlmapping_canaddress" title="Example 7.20. CANAddress.java">CANAddress</a> |
| are produced using jaxb XJC generator from myaddress schema. |
| </p><div class="example"><a name="ref_guide_xmlmapping_address"></a><p class="title"><b>Example 7.18. |
| Address.Java |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| ... |
| @XmlRootElement |
| @XmlAccessorType(XmlAccessType.FIELD) |
| @XmlType(name = "Address", propOrder = { |
| "name", |
| "street", |
| "city" |
| }) |
| public class Address { |
| @XmlElement(name = "Name", required = true) |
| protected String name; |
| @XmlElement(name = "Street", required = true) |
| protected List<String> street; |
| @XmlElement(name = "City", required = true) |
| protected String city; |
| |
| /** |
| * Getter and Setter methods. |
| * |
| */ |
| ... |
| } |
| </pre></div></div><br class="example-break"><div class="example"><a name="ref_guide_xmlmapping_usaaddress"></a><p class="title"><b>Example 7.19. |
| USAAddress.java |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| ... |
| @XmlRootElement |
| @XmlAccessorType(XmlAccessType.FIELD) |
| @XmlType(name = "USA_Address", propOrder = { |
| "state", |
| "zip" |
| }) |
| public class USAAddress |
| extends Address |
| { |
| |
| @XmlElement(name = "State") |
| protected String state; |
| @XmlElement(name = "ZIP") |
| protected int zip; |
| |
| /** |
| * Getter and Setter methods. |
| * |
| */ |
| ... |
| } |
| </pre></div></div><br class="example-break"><div class="example"><a name="ref_guide_xmlmapping_canaddress"></a><p class="title"><b>Example 7.20. |
| CANAddress.java |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| ... |
| @XmlRootElement |
| @XmlAccessorType(XmlAccessType.FIELD) |
| @XmlType(name = "CAN_Address", propOrder = { |
| "province", |
| "postalCode" |
| }) |
| public class CANAddress |
| extends Address |
| { |
| |
| @XmlElement(name = "Province") |
| protected String province; |
| @XmlElement(name = "PostalCode") |
| protected String postalCode; |
| |
| /** |
| * Getter and Setter methods. |
| * |
| */ |
| ... |
| } |
| </pre></div></div><br class="example-break"><div class="example"><a name="ref_guide_xmlmapping_annorder"></a><p class="title"><b>Example 7.21. |
| Showing annotated Order entity with XML mapping strategy |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| @Entity |
| public class Order { |
| @Id private into id; |
| @Persistent |
| @Strategy ("org.apache.openjpa.jdbc.meta.strats.XMLValueHandler") |
| private Address shipAddress; |
| ... |
| } |
| </pre></div></div><br class="example-break"><div class="example"><a name="ref_guide_xmlmapping_createorder"></a><p class="title"><b>Example 7.22. |
| Showing creation of Order Entity having shipAddress mapped to XML column |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| ... |
| myaddress.ObjectFactory addressFactory = new myaddress.ObjectFactory(); |
| Customer c1 = new Customer(); |
| c1.setCid( new Customer.CustomerKey("USA", 1) ); |
| c1.setName("Harry's Auto"); |
| Order o1 = new Order( 850, false, c1); |
| USAAddress addr1 = addressFactory.createUSAAddress(); |
| addr1.setCity("San Jose"); |
| addr1.setState("CA"); |
| addr1.setZIP(new Integer("95141")); |
| addr1.getStreet().add("12500 Monterey"); |
| addr1.setName( c1.getName()); |
| o1.setShipAddress(addr1); |
| em.persist(o1); |
| ... |
| </pre></div></div><br class="example-break"><div class="example"><a name="ref_guide_xmlmapping_ejbquery"></a><p class="title"><b>Example 7.23. |
| Sample EJB Queries for XML Column mapping |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| . select o from Order o where o.shipAddress.city = "San Jose" or |
| o.shipAddress.city = "San Francisco" (OK) |
| |
| . select o.shipaAddress from Order o (OK) |
| |
| . select o.shipAddress.city from Order o (INVALID) |
| |
| . select o from Order o where o.shipAddress.street = "San Jose" (INVALID multi valued) |
| </pre></div></div><br class="example-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_streamsupport"></a>7.11. |
| Stream LOB Support |
| </h3></div></div></div><a class="indexterm" name="d0e27320"></a><a class="indexterm" name="d0e27323"></a><p> |
| Since the 1.1.0 release Apache OpenJPA added support for Streams. This feature |
| makes it possible to stream large amounts of data into and out of fields in |
| objects managed by OpenJPA without ever holding all the data in memory at the |
| same time. |
| </p><p> |
| To persist a stream, use the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/Persistent.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.Persistent</code></a> |
| annotation. |
| </p><div class="example"><a name="ref_guide_streamsupport_example"></a><p class="title"><b>Example 7.24. |
| Showing annotated InputStream |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| @Entity |
| public class Employee { |
| ... |
| @Persistent |
| private InputStream photoStream; |
| ... |
| } |
| </pre></div></div><br class="example-break"></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_mapping_jpa_map_keycols"></a>8. Key Columns</h2></div></div></div><a class="indexterm" name="d0e27343"></a><p> |
| Key columns serve the same role for map keys as the element |
| columns described in |
| <a href="#">???</a> serve for |
| collection elements. OpenJPA's |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/jdbc/KeyColumn.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.jdbc.KeyColumn</code> |
| </a> annotation represents a map key. To map custom |
| multi-column keys, use the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/jdbc/KeyColumns.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.jdbc.KeyColumns</code> |
| </a> annotation, whose value is an array of <code class="classname">KeyColumn</code>s. |
| </p><p> |
| A <code class="classname">KeyColumn</code> always resides in |
| a container table, so it does not have the <code class="literal">table</code> |
| property of a standard <code class="classname">Column</code>. Otherwise, the |
| <code class="classname">KeyColumn</code> and standard <code class="classname">Column</code> |
| annotations are equivalent. See |
| <a href="#jpa_overview_mapping_column" title="3. Column">Section 3, “ |
| Column |
| ”</a> in the JPA |
| Overview for a review of the <code class="classname">Column</code> annotation. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_mapping_jpa_map_keyjoincols"></a>9. Key Join Columns</h2></div></div></div><a class="indexterm" name="d0e27392"></a><p> |
| Key join columns are equivalent to standard JPA |
| join columns, except that they represent a join to a map key entity rather than a direct relation. You represent |
| a key join column with OpenJPA's |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/jdbc/KeyJoinColumn.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.jdbc.KeyJoinColumn</code></a> annotation. To declare a compound join, enclose an |
| array of <code class="classname">KeyJoinColumn</code>s in the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/jdbc/KeyJoinColumns.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.jdbc.KeyJoinColumns</code> |
| </a> annotation. |
| </p><p> |
| A <code class="classname">KeyJoinColumn</code> always resides in |
| a container table, so it does not have the <code class="literal">table</code> property |
| of a standard <code class="classname">JoinColumn</code>. Like <code class="classname">XJoinColumn</code>s above, |
| <code class="classname">KeyJoinColumn</code>s can reference a linked field |
| rather than a static linked column. Otherwise, the <code class="classname">KeyJoinColumn</code> |
| and standard <code class="classname">JoinColumn</code> annotations are equivalent. See |
| <a href="#jpa_overview_mapping_rel" title="8.4. Direct Relations">Section 8.4, “ |
| Direct Relations |
| ”</a> in the JPA |
| Overview for a review of the <code class="classname">JoinColumn</code> annotation. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_mapping_jpa_map_embedkey"></a>10. Key Embedded Mapping</h2></div></div></div><a class="indexterm" name="d0e27444"></a><p> |
| The |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/jdbc/KeyEmbeddedMapping.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.jdbc.KeyEmbeddedMapping</code> |
| </a> annotation allows you to map your map field's embedded |
| key type to your container table. This annotation has exactly |
| the same properties as the |
| <code class="classname">EmbeddedMapping</code> annotation described |
| <a href="#ref_guide_mapping_jpa_embed" title="7.5. Embedded Mapping">above</a>. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_mapping_jpa_map_ex"></a>11. Examples</h2></div></div></div><div class="mediaobject"><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="273"><tr><td><img src="img/string-rel-map.png"></td></tr></table></div><p> |
| Map mapping in OpenJPA uses the same principles you saw in |
| collection mapping. The example below maps the <code class="literal"> |
| Article.authors</code> map according to the diagram above. |
| </p><div class="example"><a name="ref_guide_mapping_jpa_map_stringrelmap"></a><p class="title"><b>Example 7.25. String Key, Entity Value Map Mapping</b></p><div class="example-contents"><pre class="programlisting"> |
| package org.mag.pub; |
| |
| import org.apache.openjpa.persistence.*; |
| import org.apache.openjpa.persistence.jdbc.*; |
| |
| @Entity |
| @Table(name="AUTH") |
| @DataStoreIdColumn(name="AID" columnDefinition="INTEGER64") |
| public class Author { |
| ... |
| } |
| |
| package org.mag; |
| |
| @Entity |
| @Table(name="ART") |
| public class Article { |
| @Id private long id; |
| |
| @PersistentMap |
| @ContainerTable(name="ART_AUTHS", joinColumns=@XJoinColumn(name="ART_ID")) |
| @KeyColumn(name="LNAME") |
| @ElementJoinColumn(name="AUTH_ID") |
| private Map<String,Author> authors; |
| |
| ... |
| } |
| </pre></div></div><br class="example-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_mapping_limits"></a>12. |
| Mapping Limitations |
| </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#ref_guide_mapping_limits_tpc">12.1. |
| Table Per Class |
| </a></span></dt></dl></div><a class="indexterm" name="d0e27483"></a><p> |
| The following sections outline the limitations OpenJPA places on specific |
| mapping strategies. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_mapping_limits_tpc"></a>12.1. |
| Table Per Class |
| </h3></div></div></div><a class="indexterm" name="d0e27493"></a><p> |
| Table-per-class inheritance mapping has the following limitations: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| You cannot traverse polymorphic relations to non-leaf classes in a |
| table-per-class inheritance hierarchy in queries. |
| </p></li><li><p> |
| You cannot map a one-sided polymorphic relation to a non-leaf class in a |
| table-per-class inheritance hierarchy using an inverse foreign key. |
| </p></li><li><p> |
| You cannot use an order column in a polymorphic relation to a non-leaf class in |
| a table-per-class inheritance hierarchy mapped with an inverse foreign key. |
| </p></li><li><p> |
| Table-per-class hierarchies impose limitations on eager fetching. See |
| <a href="#ref_guide_perfpack_eager_consider" title="8.2. Eager Fetching Considerations and Limitations">Section 8.2, “ |
| Eager Fetching Considerations and Limitations |
| ”</a>. |
| </p></li></ul></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| Non-polymorphic relations do not suffer from these limitations. You can declare |
| a non-polymorphic relation using the extensions described in |
| <a href="#nonpolymorphic" title="13.2.2. Nonpolymorphic">Section 13.2.2, “ |
| Nonpolymorphic |
| ”</a>. |
| </p></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_mapping_ext"></a>13. |
| Mapping Extensions |
| </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#ref_guide_mapping_ext_cls">13.1. |
| Class Extensions |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#subclass-fetch-mode">13.1.1. |
| Subclass Fetch Mode |
| </a></span></dt><dt><span class="section"><a href="#class-strategy">13.1.2. |
| Strategy |
| </a></span></dt><dt><span class="section"><a href="#discriminator-strategy">13.1.3. |
| Discriminator Strategy |
| </a></span></dt><dt><span class="section"><a href="#version-strategy">13.1.4. |
| Version Strategy |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_mapping_ext_field">13.2. |
| Field Extensions |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#eager-fetch-mode">13.2.1. |
| Eager Fetch Mode |
| </a></span></dt><dt><span class="section"><a href="#nonpolymorphic">13.2.2. |
| Nonpolymorphic |
| </a></span></dt><dt><span class="section"><a href="#class-criteria">13.2.3. |
| Class Criteria |
| </a></span></dt><dt><span class="section"><a href="#strategy">13.2.4. |
| Strategy |
| </a></span></dt></dl></dd></dl></div><p> |
| Mapping extensions allow you to access OpenJPA-specific functionality from your |
| mappings. Note that all extensions below are specific to mappings. If you store |
| your mappings separately from your persistence metadata, these extensions must |
| be specified along with the mapping information, not the persistence metadata |
| information. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_mapping_ext_cls"></a>13.1. |
| Class Extensions |
| </h3></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#subclass-fetch-mode">13.1.1. |
| Subclass Fetch Mode |
| </a></span></dt><dt><span class="section"><a href="#class-strategy">13.1.2. |
| Strategy |
| </a></span></dt><dt><span class="section"><a href="#discriminator-strategy">13.1.3. |
| Discriminator Strategy |
| </a></span></dt><dt><span class="section"><a href="#version-strategy">13.1.4. |
| Version Strategy |
| </a></span></dt></dl></div><p> |
| OpenJPA recognizes the following class extensions. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="subclass-fetch-mode"></a>13.1.1. |
| Subclass Fetch Mode |
| </h4></div></div></div><a class="indexterm" name="d0e27535"></a><p> |
| This extension specifies how to eagerly fetch subclass state. It overrides the |
| global <a href="#openjpa.jdbc.SubclassFetchMode" title="6.16. openjpa.jdbc.SubclassFetchMode"><code class="literal"> |
| openjpa.jdbc.SubclassFetchMode</code></a> property. Set the JPA |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/jdbc/SubclassFetchMode.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.jdbc.SubclassFetchMode</code> |
| </a> annotation to a value from the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/jdbc/EagerFetchType.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.jdbc.EagerFetchType</code> |
| </a> enum: <code class="literal">JOIN</code>, <code class="literal">PARALLEL</code>, or |
| <code class="literal">NONE</code>. See <a href="#ref_guide_perfpack_eager" title="8. Eager Fetching">Section 8, “ |
| Eager Fetching |
| ”</a> |
| for a discussion of eager fetching. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="class-strategy"></a>13.1.2. |
| Strategy |
| </h4></div></div></div><a class="indexterm" name="d0e27576"></a><p> |
| The <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/jdbc/Strategy.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.jdbc.Strategy</code></a> |
| class annotation allows you to specify a custom mapping strategy for your class. |
| See <a href="#ref_guide_mapping_custom" title="14. Custom Mappings">Section 14, “ |
| Custom Mappings |
| ”</a> for information on custom |
| mappings. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="discriminator-strategy"></a>13.1.3. |
| Discriminator Strategy |
| </h4></div></div></div><a class="indexterm" name="d0e27597"></a><p> |
| The |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/jdbc/DiscriminatorStrategy.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.jdbc.DiscriminatorStrategy</code> |
| </a> class annotation allows you to specify a custom discriminator strategy. |
| See <a href="#ref_guide_mapping_custom" title="14. Custom Mappings">Section 14, “ |
| Custom Mappings |
| ”</a> for information on custom |
| mappings. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="version-strategy"></a>13.1.4. |
| Version Strategy |
| </h4></div></div></div><a class="indexterm" name="d0e27619"></a><p> |
| The |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/jdbc/VersionStrategy.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.jdbc.VersionStrategy</code> |
| </a> class annotation allows you to specify a custom version strategy. See |
| <a href="#ref_guide_mapping_custom" title="14. Custom Mappings">Section 14, “ |
| Custom Mappings |
| ”</a> for information on custom |
| mappings. |
| </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_mapping_ext_field"></a>13.2. |
| Field Extensions |
| </h3></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#eager-fetch-mode">13.2.1. |
| Eager Fetch Mode |
| </a></span></dt><dt><span class="section"><a href="#nonpolymorphic">13.2.2. |
| Nonpolymorphic |
| </a></span></dt><dt><span class="section"><a href="#class-criteria">13.2.3. |
| Class Criteria |
| </a></span></dt><dt><span class="section"><a href="#strategy">13.2.4. |
| Strategy |
| </a></span></dt></dl></div><p> |
| OpenJPA recognizes the following field extensions. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="eager-fetch-mode"></a>13.2.1. |
| Eager Fetch Mode |
| </h4></div></div></div><a class="indexterm" name="d0e27646"></a><p> |
| This extension specifies how to eagerly fetch related objects. It overrides the |
| global <a href="#openjpa.jdbc.EagerFetchMode" title="6.4. openjpa.jdbc.EagerFetchMode"><code class="literal"> |
| openjpa.jdbc.EagerFetchMode</code></a> property. Set the JPA |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/jdbc/EagerFetchMode.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.jdbc.EagerFetchMode</code> |
| </a> annotation to a value from the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/jdbc/EagerFetchType.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.jdbc.EagerFetchType</code> |
| </a> enum: <code class="literal">JOIN</code>, <code class="literal">PARALLEL</code>, or |
| <code class="literal">NONE</code>. See <a href="#ref_guide_perfpack_eager" title="8. Eager Fetching">Section 8, “ |
| Eager Fetching |
| ”</a> |
| for a discussion of eager fetching. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="nonpolymorphic"></a>13.2.2. |
| Nonpolymorphic |
| </h4></div></div></div><a class="indexterm" name="d0e27687"></a><p> |
| All fields in Java are polymorphic. If you declare a field of type <code class="literal">T |
| </code>, you can assign any subclass of <code class="literal">T</code> to the field as |
| well. This is very convenient, but can make relation traversal very inefficient |
| under some inheritance strategies. It can even make querying across the field |
| impossible. Often, you know that certain fields do not need to be entirely |
| polymorphic. By telling OpenJPA about such fields, you can improve the |
| efficiency of your relations. |
| </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| OpenJPA also includes the <code class="literal">type</code> metadata extension for |
| narrowing the declared type of a field. See <a href="#type" title="4.2.6. Type">Section 4.2.6, “ |
| Type |
| ”</a>. |
| </p></div><p> |
| OpenJPA defines the following extensions for nonpolymorphic values: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/jdbc/Nonpolymorphic.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.jdbc.Nonpolymorphic</code> |
| </a> |
| </p></li><li><p> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/jdbc/ElementNonpolymorphic.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.jdbc.ElementNonpolymorphic</code> |
| </a> |
| </p></li></ul></div><p> |
| The value of these extensions is a constant from the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/jdbc/NonpolymorphicType.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.jdbc.NonpolymorphicType</code> |
| </a> enumeration. The default value, <code class="literal">EXACT</code>, indicates |
| that the relation will always be of the exact declared type. A value of |
| <code class="literal">JOINABLE</code>, on the other hand, means that the relation might |
| be to any joinable subclass of the declared type. This value only excludes |
| table-per-class subclasses. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="class-criteria"></a>13.2.3. |
| Class Criteria |
| </h4></div></div></div><a class="indexterm" name="d0e27748"></a><a class="indexterm" name="d0e27757"></a><p> |
| This family of boolean extensions determines whether OpenJPA will use the |
| expected class of related objects as criteria in the SQL it issues to load a |
| relation field. Typically, this is not needed. The foreign key values uniquely |
| identify the record for the related object. Under some rare mappings, however, |
| you may need to consider both foreign key values and the expected class of the |
| related object - for example, if you have an inverse relation that shares the |
| foreign key with another inverse relation to an object of a different subclass. |
| In these cases, set the proper class critera extension to <code class="literal">true |
| </code> to force OpenJPA to append class criteria to its select SQL. |
| </p><p> |
| OpenJPA defines the following class criteria annotations for field relations and |
| array or collection element relations, respectively: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/jdbc/ClassCriteria.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.jdbc.ClassCriteria</code></a> |
| </p></li><li><p> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/jdbc/ElementClassCriteria.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.jdbc.ElementClassCriteria</code> |
| </a> |
| </p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="strategy"></a>13.2.4. |
| Strategy |
| </h4></div></div></div><a class="indexterm" name="d0e27790"></a><p> |
| OpenJPA's |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/jdbc/Strategy.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.jdbc.Strategy</code></a> |
| extension allows you to specify a custom mapping |
| strategy or value handler for a field. See |
| <a href="#ref_guide_mapping_custom" title="14. Custom Mappings">Section 14, “ |
| Custom Mappings |
| ”</a> for information on custom |
| mappings. |
| </p></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_mapping_custom"></a>14. |
| Custom Mappings |
| </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#ref_guide_mapping_custom_class">14.1. |
| Custom Class Mapping |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_custom_versdiscrim">14.2. |
| Custom Discriminator and Version Strategies |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_custom_field">14.3. |
| Custom Field Mapping |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_mapping_custom_vhandler">14.3.1. |
| Value Handlers |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_custom_fieldstrat">14.3.2. |
| Field Strategies |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_custom_field_conf">14.3.3. |
| Configuration |
| </a></span></dt></dl></dd></dl></div><a class="indexterm" name="d0e27811"></a><a class="indexterm" name="d0e27814"></a><p> |
| In OpenJPA, you are not limited to the set of standard mappings defined by the |
| specification. OpenJPA allows you to define custom class, discriminator, |
| version, and field mapping strategies with all the power of OpenJPA's built-in |
| strategies. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_mapping_custom_class"></a>14.1. |
| Custom Class Mapping |
| </h3></div></div></div><p> |
| To create a custom class mapping, write an implementation of the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/meta/ClassStrategy.html" target="_top"> |
| <code class="classname">org.apache.openjpa.jdbc.meta.ClassStrategy</code></a> |
| interface. You will probably want to extend one of the existing abstract or |
| concrete strategies in the <code class="literal">org.apache.openjpa.jdbc.meta.strats |
| </code> package. |
| </p><p> |
| The <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/jdbc/Strategy.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.jdbc.Strategy</code></a> |
| annotation allows you to declare a custom class mapping strategy in JPA mapping |
| metadata. Set the value of the annotation to the full class name of your custom |
| strategy. You can configure your strategy class' bean properties using |
| OpenJPA's plugin syntax, detailed in <a href="#ref_guide_conf_plugins" title="4. Plugin Configuration">Section 4, “ |
| Plugin Configuration |
| ”</a>. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_mapping_custom_versdiscrim"></a>14.2. |
| Custom Discriminator and Version Strategies |
| </h3></div></div></div><p> |
| To define a custom discriminator or version strategy, implement the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/meta/DiscriminatorStrategy.html" target="_top"> |
| <code class="classname">org.apache.openjpa.jdbc.meta.DiscriminatorStrategy</code> |
| </a> or |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/meta/VersionStrategy.html" target="_top"> |
| <code class="classname">org.apache.openjpa.jdbc.meta.VersionStrategy</code></a> |
| interface, respectively. You might extend one of the existing abstract or |
| concrete strategies in the <code class="literal">org.apache.openjpa.jdbc.meta.strats |
| </code> package. |
| </p><p> |
| OpenJPA includes the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/jdbc/DiscriminatorStrategy.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.jdbc.DiscriminatorStrategy</code> |
| </a> and |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/jdbc/VersionStrategy.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.jdbc.VersionStrategy</code> |
| </a> class annotations for declaring a custom discriminator or version |
| strategy in JPA mapping metadata. Set the string value of these annotations to |
| the full class name of your implementation, or to the class name or alias of an |
| existing OpenJPA implementation. |
| </p><p> |
| As with custom class mappings, you can configure your strategy class' bean |
| properties using OpenJPA's plugin syntax, detailed in |
| <a href="#ref_guide_conf_plugins" title="4. Plugin Configuration">Section 4, “ |
| Plugin Configuration |
| ”</a>. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_mapping_custom_field"></a>14.3. |
| Custom Field Mapping |
| </h3></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#ref_guide_mapping_custom_vhandler">14.3.1. |
| Value Handlers |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_custom_fieldstrat">14.3.2. |
| Field Strategies |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_mapping_custom_field_conf">14.3.3. |
| Configuration |
| </a></span></dt></dl></div><a class="indexterm" name="d0e27885"></a><p> |
| While custom class, discriminator, and version mapping can be useful, custom |
| field mappings are far more common. OpenJPA offers two types of custom field |
| mappings: value handlers, and full custom field strategies. The following |
| sections examine each. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="ref_guide_mapping_custom_vhandler"></a>14.3.1. |
| Value Handlers |
| </h4></div></div></div><a class="indexterm" name="d0e27895"></a><p> |
| Value handlers make it trivial to map any type that you can break down into one |
| or more simple values. All value handlers implement the <code class="classname"> |
| org.apache.openjpa.jdbc.meta.ValueHandler</code> interface; see its |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/meta/ValueHandler.html" target="_top"> Javadoc |
| </a> for details. Also, examine the built-in handlers in the <code class="filename"> |
| src/openjpa/jdbc/meta/strats</code> directory of your OpenJPA source |
| distribution. Use these functional implementations as examples when you |
| create your own value handlers. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="ref_guide_mapping_custom_fieldstrat"></a>14.3.2. |
| Field Strategies |
| </h4></div></div></div><a class="indexterm" name="d0e27916"></a><p> |
| OpenJPA interacts with persistent fields through the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/meta/FieldStrategy" target="_top"><code class="classname"> |
| org.apache.openjpa.jdbc.meta.FieldStrategy</code></a> interface. You |
| can implement this interface yourself to create a custom field strategy, or |
| extend one of the existing abstract or concrete strategies in the <code class="literal"> |
| org.apache.openjpa.jdbc.meta.strats</code> package. Creating a custom field |
| strategy is more difficult than writing a custom value handler, but gives you |
| more freedom in how you interact with the database. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="ref_guide_mapping_custom_field_conf"></a>14.3.3. |
| Configuration |
| </h4></div></div></div><a class="indexterm" name="d0e27935"></a><p> |
| OpenJPA gives you two ways to configure your custom field mappings. The |
| <code class="literal">FieldStrategies</code> property of the built-in <code class="classname"> |
| MappingDefaults</code> implementations allows you to globally associate |
| field types with their corresponding custom value handler or strategy. OpenJPA |
| will automatically use your custom strategies when it encounters a field of the |
| associated type. OpenJPA will use your custom value handlers whenever it |
| encounters a field of the associated type. |
| <a href="#ref_guide_mapping_defaults" title="4. Mapping Defaults">Section 4, “ |
| Mapping Defaults |
| ”</a> described mapping |
| defaults in detail. |
| </p><p> |
| Your other option is to explicitly install a custom value handler or strategy on |
| a particular field. To do so, specify the full name of your implementation class |
| in the proper mapping metadata extension. OpenJPA includes the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/jdbc/Strategy.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.jdbc.Strategy</code></a> |
| annotation. You can configure the named strategy or handler's bean |
| properties in these extensions using OpenJPA's plugin format (see |
| <a href="#ref_guide_conf_plugins" title="4. Plugin Configuration">Section 4, “ |
| Plugin Configuration |
| ”</a>). |
| </p></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_orphan"></a>15. |
| Orphaned Keys |
| </h2></div></div></div><p> |
| Unless you apply database foreign key constraints extensively, it is possible to |
| end up with orphaned keys in your database. For example, suppose <code class="classname"> |
| Magazine</code><code class="literal">m</code> has a reference to <code class="classname">Article |
| </code><code class="literal">a</code>. If you delete <code class="literal">a</code> without |
| nulling <code class="literal">m</code>'s reference, <code class="literal">m</code>'s database |
| record will wind up with an orphaned key to the non-existent <code class="literal">a |
| </code> record. |
| </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| One way of avoiding orphaned keys is to use <span class="emphasis"><em>dependent</em></span> |
| fields. |
| </p></div><p> |
| OpenJPA's <a href="#openjpa.OrphanedKeyAction" title="5.46. openjpa.OrphanedKeyAction"><code class="literal"> |
| openjpa.OrphanedKeyAction</code></a> configuration property controls what |
| action to take when OpenJPA encounters an orphaned key. You can set this plugin |
| string (see <a href="#ref_guide_conf_plugins" title="4. Plugin Configuration">Section 4, “ |
| Plugin Configuration |
| ”</a>) to a custom |
| implementation of the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/event/OrphanedKeyAction.html" target="_top"> |
| <code class="classname"> org.apache.openjpa.event.OrphanedKeyAction</code></a> |
| interface, or use one of the built-in options: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">log</code>: This is the default setting. This option logs a message |
| for each orphaned key. It is an alias for the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/event/LogOrphanedKeyAction.html" target="_top"> |
| <code class="classname">org.apache.openjpa.event.LogOrphanedKeyAction</code></a> |
| class, which has the following additional properties: |
| </p><div class="itemizedlist"><ul type="circle"><li><p> |
| <code class="literal">Channel</code>: The channel to log to. Defaults to <code class="literal"> |
| openjpa.Runtime</code>. |
| </p></li><li><p> |
| <code class="literal">Level</code>: The level to log at. Defaults to <code class="literal">WARN |
| </code>. |
| </p></li></ul></div></li><li><p> |
| <code class="literal">exception</code>: Throw an <code class="classname"> |
| EntityNotFoundException</code> when OpenJPA discovers an |
| orphaned key. This is an alias for the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/event/ExceptionOrphanedKeyAction.html" target="_top"> |
| <code class="classname">org.apache.openjpa.event.ExceptionOrphanedKeyAction</code> |
| </a> class. |
| </p></li><li><p> |
| <code class="literal">none</code>: Ignore orphaned keys. This is an alias for the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/event/NoneOrphanedKeyAction.html" target="_top"> |
| <code class="classname">org.apache.openjpa.event.NoneOrphanedKeyAction</code></a> |
| class. |
| </p></li></ul></div><div class="example"><a name="ref_guide_orphan_logex"></a><p class="title"><b>Example 7.26. |
| Custom Logging Orphaned Keys |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| <property name="openjpa.OrphanedKeyAction" value="log(Channel=Orphans, Level=DEBUG)"/> |
| </pre></div></div><br class="example-break"></div></div><div class="chapter" lang="en" id="ref_guide_deploy"><div class="titlepage"><div><div><h2 class="title"><a name="ref_guide_deploy"></a>Chapter 8. |
| Deployment |
| </h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#ref_guide_deploy_factory">1. |
| Factory Deployment |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_deploy_factory_standalone">1.1. |
| Standalone Deployment |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_deploy_inject">1.2. |
| EntityManager Injection |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_enterprise_trans">2. |
| Integrating with the Transaction Manager |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_enterprise_xa">3. |
| XA Transactions |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_enterprise_xa_req">3.1. |
| Using OpenJPA with XA Transactions |
| </a></span></dt></dl></dd></dl></div><p> |
| OpenJPA deployment includes choosing a factory deployment strategy, and in a |
| managed environment, optionally integrating with your application server's |
| managed and XA transactions. This chapter examines each aspect of deployment in |
| turn. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_deploy_factory"></a>1. |
| Factory Deployment |
| </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#ref_guide_deploy_factory_standalone">1.1. |
| Standalone Deployment |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_deploy_inject">1.2. |
| EntityManager Injection |
| </a></span></dt></dl></div><p> |
| OpenJPA offers two <code class="classname">EntityManagerFactory</code> |
| deployment options. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_deploy_factory_standalone"></a>1.1. |
| Standalone Deployment |
| </h3></div></div></div><a class="indexterm" name="d0e28086"></a><p> |
| The JPA Overview describes the <code class="classname">javax.persistence.Persistence |
| </code> class. You can use <code class="classname">Persistence</code> to obtain |
| <code class="classname">EntityManagerFactory</code> instances, as demonstrated in |
| <a href="#jpa_overview_persistence" title="Chapter 6. Persistence">Chapter 6, <i xmlns:xlink="http://www.w3.org/1999/xlink"> |
| Persistence |
| </i></a>. OpenJPA also extends |
| <code class="classname">Persistence</code> to add additional <code class="classname"> |
| EntityManagerFactory</code> creation methods. The <code class="classname"> |
| org.apache.openjpa.persistence.OpenJPAPersistence</code> class |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/OpenJPAPersistence.html" target="_top"> |
| Javadoc</a> details these extensions. |
| </p><p> |
| After obtaining the factory, you can cache it for all <code class="classname"> |
| EntityManager</code> creation duties. OpenJPA factories support being |
| bound to JNDI as well. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_deploy_inject"></a>1.2. |
| EntityManager Injection |
| </h3></div></div></div><p> |
| Java EE 5 application servers allow you to <span class="emphasis"><em>inject</em></span> |
| entity managers into your session beans using the <code class="literal">PersistenceContext |
| </code> annotation. See your application server documentation for details. |
| </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_enterprise_trans"></a>2. |
| Integrating with the Transaction Manager |
| </h2></div></div></div><a class="indexterm" name="d0e28137"></a><a class="indexterm" name="d0e28142"></a><a class="indexterm" name="d0e28147"></a><a class="indexterm" name="d0e28152"></a><p> |
| OpenJPA <code class="classname">EntityManager</code>s have the ability to automatically |
| synchronize their transactions with an external transaction manager. Whether |
| or not <code class="classname">EntityManager</code>s from a given <code class="classname"> |
| EntityManagerFactory</code> exhibit this behavior by default depends on |
| the transaction type you set for the factory's persistence unit in |
| your <code class="filename">persistence.xml</code> file. OpenJPA uses the given |
| transaction type internally to set the |
| <a href="#openjpa.TransactionMode" title="5.60. openjpa.TransactionMode"><code class="literal">openjpa.TransactionMode |
| </code></a> configuration property. This property accepts the following |
| modes: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">local</code>: Perform transaction operations locally. |
| </p></li><li><p> |
| <code class="literal">managed</code>: Integrate with the application server's managed |
| global transactions. |
| </p></li></ul></div><p> |
| You can override the global transaction mode setting when you obtain an |
| <code class="classname">EntityManager</code> using the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="http://java.sun.com/javaee/5/docs/api/javax/persistence/EntityManagerFactory.html" target="_top"> |
| <code class="classname">EntityManagerFactory</code></a>'s |
| <code class="methodname">createEntityManager(Map props)</code> method. Simply set the |
| <code class="literal">openjpa.TransactionMode</code> key of the given <code class="classname">Map |
| </code> to the desired value. |
| </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| You can also override the <code class="literal">openjpa.ConnectionUserName</code>, |
| <code class="literal">openjpa.ConnectionPassword</code>, and <code class="literal"> |
| openjpa.ConnectionRetainMode</code> settings using the given <code class="classname"> |
| Map</code>. |
| </p></div><p> |
| <a class="indexterm" name="d0e28222"></a> |
| In order to use global transactions, OpenJPA must be able to access the |
| application server's <code class="classname"> |
| javax.transaction.TransactionManager</code>. OpenJPA can automatically |
| discover the transaction manager for most major application servers. |
| Occasionally, however, you might have to point OpenJPA to the transaction |
| manager for an unrecognized or non-standard application server setup. This is |
| accomplished through the <a href="#openjpa.ManagedRuntime" title="5.39. openjpa.ManagedRuntime"><code class="literal"> |
| openjpa.ManagedRuntime</code></a> configuration property. This |
| property describes an |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/ee/ManagedRuntime.html" target="_top"><code class="classname"> |
| org.apache.openjpa.ee.ManagedRuntime</code></a> implementation to use |
| for transaction manager discovery. You can specify your own implementation, |
| or use one of the built-ins: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">auto</code>: This is the default. It is an alias for the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/ee/AutomaticManagedRuntime.html" target="_top"> |
| <code class="classname">org.apache.openjpa.ee.AutomaticManagedRuntime</code></a> |
| class. This managed runtime is able to automatically integrate with several |
| common application servers. |
| </p></li><li><p> |
| <code class="literal">invocation</code>: An alias for the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/ee/InvocationManagedRuntime.html" target="_top"> |
| <code class="classname">org.apache.openjpa.ee.InvocationManagedRuntime</code></a> |
| class. You can configure this runtime to invoke any static |
| method in order to obtain the appserver's transaction manager. |
| </p></li><li><p> |
| <code class="literal">jndi</code>: An alias for the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/ee/JNDIManagedRuntime.html" target="_top"> |
| <code class="classname">org.apache.openjpa.ee.JNDIManagedRuntime</code></a> |
| class. You can configure this runtime to look up the transaction manager at |
| any JNDI location. |
| </p></li></ul></div><p> |
| See the Javadoc for of each class for details on the bean properties |
| you can pass to these plugins in your configuration string. |
| </p><div class="example"><a name="ref_guide_enterprise_transex"></a><p class="title"><b>Example 8.1. Configuring Transaction Manager Integration</b></p><div class="example-contents"><pre class="programlisting"> |
| <property name="openjpa.TransactionMode" value="managed"/> |
| <property name="openjpa.ManagedRuntime" value="jndi(TransactionManagerName=java:/TransactionManager)"/> |
| </pre></div></div><br class="example-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_enterprise_xa"></a>3. |
| XA Transactions |
| </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#ref_guide_enterprise_xa_req">3.1. |
| Using OpenJPA with XA Transactions |
| </a></span></dt></dl></div><a class="indexterm" name="d0e28281"></a><a class="indexterm" name="d0e28286"></a><p> |
| The X/Open Distributed Transaction Processing (X/Open DTP) model, designed by |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="http://www.xopen.org" target="_top">Open Group</a> (a vendor consortium), |
| defines a standard communication architecture that provides the following: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| Concurrent execution of applications on shared resources. |
| </p></li><li><p> |
| Coordination of transactions across applications. |
| </p></li><li><p> |
| Components, interfaces, and protocols that define the architecture and provide |
| portability of applications. |
| </p></li><li><p> |
| Atomicity of transaction systems. |
| </p></li><li><p> |
| Single-thread control and sequential function-calling. |
| </p></li></ul></div><p> |
| The X/Open DTP XA standard defines the application programming interfaces that a |
| resource manager uses to communicate with a transaction manager. The XA |
| interfaces enable resource managers to join transactions, to perform two-phase |
| commit, and to recover in-doubt transactions following a failure. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_enterprise_xa_req"></a>3.1. |
| Using OpenJPA with XA Transactions |
| </h3></div></div></div><p> |
| OpenJPA supports XA-compliant transactions when used in a properly configured |
| managed environment. The following components are required: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| A managed environment that provides an XA compliant transaction manager. |
| Examples of this are application servers such as WebLogic or JBoss. |
| </p></li><li><p> |
| Instances of a <code class="classname">javax.sql.XADataSource</code> for each of the |
| <code class="classname">DataSource</code>s that OpenJPA will use. |
| </p></li></ul></div><p> |
| Given these components, setting up OpenJPA to participate in distributed |
| transactions is a simple two-step process: |
| </p><div class="orderedlist"><ol type="1"><li><p> |
| Integrate OpenJPA with your application server's transaction manager, as |
| detailed in <a href="#ref_guide_enterprise_trans" title="2. Integrating with the Transaction Manager">Section 2, “ |
| Integrating with the Transaction Manager |
| ”</a> above. |
| </p></li><li><p> |
| Point OpenJPA at an enlisted <code class="classname">XADataSource</code>, and configure |
| a second non-enlisted data source. See |
| <a href="#ref_guide_dbsetup_thirdparty_enlist" title="2.1. Managed and XA DataSources">Section 2.1, “ |
| Managed and XA DataSources |
| ”</a>. |
| </p></li></ol></div></div></div></div><div class="chapter" lang="en" id="ref_guide_runtime"><div class="titlepage"><div><div><h2 class="title"><a name="ref_guide_runtime"></a>Chapter 9. |
| Runtime Extensions |
| </h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#ref_guide_runtime_arch">1. |
| Architecture |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_runtime_broker_finalization">1.1. |
| Broker Finalization |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_runtime_broker_extension">1.2. |
| Broker Customization and Eviction |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_runtime_jpa">2. |
| JPA Extensions |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_runtime_emfactory">2.1. |
| OpenJPAEntityManagerFactory |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_runtime_em">2.2. |
| OpenJPAEntityManager |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_runtime_jpaquery">2.3. |
| OpenJPAQuery |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_runtime_jpaextent">2.4. |
| Extent |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_runtime_jpacache">2.5. |
| StoreCache |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_runtime_jpaquerycache">2.6. |
| QueryResultCache |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_runtime_jpafetch">2.7. |
| FetchPlan |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_runtime_openjpaentitytransaction">2.8. |
| OpenJPAEntityTransaction |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_runtime_openjpapersistence">2.9. |
| OpenJPAPersistence |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_locking">3. |
| Object Locking |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_locking_default">3.1. |
| Configuring Default Locking |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_locking_runtime">3.2. |
| Configuring Lock Levels at Runtime |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_locking_apis">3.3. |
| Object Locking APIs |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_locking_lockmgr">3.4. |
| Lock Manager |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_locking_rules">3.5. |
| Rules for Locking Behavior |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_locking_issues">3.6. |
| Known Issues and Limitations |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_savepoints">4. |
| Savepoints |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#reg_guide_savepoints_using">4.1. |
| Using Savepoints |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_savepoints_conf">4.2. |
| Configuring Savepoints |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_enterprise_methodql">5. |
| MethodQL |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_sequence">6. |
| Generators |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_sequence_runtime">6.1. |
| Runtime Access |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_runtime_pm_event">7. |
| Transaction Events |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_enterprise_abstractstore">8. |
| Non-Relational Stores |
| </a></span></dt></dl></div><p> |
| This chapter describes OpenJPA extensions to the standard JPA |
| interfaces, and outlines some additional features of the OpenJPA runtime. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_runtime_arch"></a>1. |
| Architecture |
| </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#ref_guide_runtime_broker_finalization">1.1. |
| Broker Finalization |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_runtime_broker_extension">1.2. |
| Broker Customization and Eviction |
| </a></span></dt></dl></div><p> |
| Internally, OpenJPA does not adhere to any persistence specification. The |
| OpenJPA kernel has its own set of APIs and components. Specifications like JPA |
| and JDO are simply different "personalities" that OpenJPA's native kernel |
| can adopt. |
| </p><p> |
| As an OpenJPA user, you will not normally see beneath |
| OpenJPA's JPA personality. OpenJPA allows you to access its feature set without |
| leaving the comfort of JPA. Where OpenJPA goes beyond standard JPA |
| functionality, we have crafted JPA-specific APIs to each OpenJPA extension for |
| as seamless an experience as possible. |
| </p><p> |
| When writing OpenJPA plugins or otherwise extending the OpenJPA runtime, |
| however, you will use OpenJPA's native APIs. So that you won't feel lost, the |
| list below associates each specification interface with its backing native |
| OpenJPA component: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="classname">javax.persistence.EntityManagerFactory</code>: <span class="emphasis"><em> |
| <code class="classname">org.apache.openjpa.kernel.BrokerFactory</code></em></span> |
| </p></li><li><p> |
| <code class="classname">javax.persistence.EntityManager</code>: <span class="emphasis"><em><code class="classname"> |
| org.apache.openjpa.kernel.Broker</code></em></span> |
| </p></li><li><p> |
| <code class="classname">javax.persistence.Query</code>: <span class="emphasis"><em><code class="classname"> |
| org.apache.openjpa.kernel.Query</code></em></span> |
| </p></li><li><p> |
| <code class="classname">org.apache.openjpa.persistence.Extent</code>: <span class="emphasis"><em> |
| <code class="classname">org.apache.openjpa.kernel.Extent</code></em></span> |
| </p></li><li><p> |
| <code class="classname">org.apache.openjpa.persistence.StoreCache</code>: <span class="emphasis"><em> |
| <code class="classname">org.apache.openjpa.datacache.DataCache</code></em></span> |
| </p></li><li><p> |
| <code class="classname">org.apache.openjpa.persistence.QueryResultCache</code>: |
| <span class="emphasis"><em><code class="classname">org.apache.openjpa.datacache.QueryCache</code> |
| </em></span> |
| </p></li><li><p> |
| <code class="classname">org.apache.openjpa.persistence.FetchPlan</code>: <span class="emphasis"><em> |
| <code class="classname">org.apache.openjpa.kernel.FetchConfiguration</code></em></span> |
| </p></li><li><p> |
| <code class="classname">org.apache.openjpa.persistence.Generator</code>: <span class="emphasis"><em> |
| <code class="classname">org.apache.openjpa.kernel.Seq</code></em></span> |
| </p></li></ul></div><p> |
| The <a href="#ref_guide_runtime_openjpapersistence" title="2.9. OpenJPAPersistence"><code class="classname"> |
| org.apache.openjpa.persistence.OpenJPAPersistence</code></a> helper |
| allows you to convert between <code class="classname">EntityManagerFactories</code> and |
| <code class="classname">BrokerFactories</code>, <code class="classname">EntityManager</code>s |
| and <code class="classname">Broker</code>s. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_runtime_broker_finalization"></a>1.1. |
| Broker Finalization |
| </h3></div></div></div><a class="indexterm" name="d0e28471"></a><p> |
| Outside of a Java EE 5 application server or other JPA persistence container |
| environment, the default OpenJPAEntityManager implementation automatically |
| closes itself during instance finalization. This guards against accidental |
| resource leaks that may occur if a developer fails to explicitly close |
| EntityManagers when finished with them, but it also incurs a scalability |
| bottleneck, since the JVM must perform synchronization during instance creation, |
| and since the finalizer thread will have more instances to monitor. To avoid |
| this overhead, set the |
| <a href="#openjpa.BrokerImpl" title="5.4. openjpa.BrokerImpl"><code class="literal">openjpa.BrokerImpl</code></a> |
| configuration property to <code class="literal">non-finalizing</code>. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_runtime_broker_extension"></a>1.2. |
| Broker Customization and Eviction |
| </h3></div></div></div><a class="indexterm" name="d0e28490"></a><p> |
| As a <a href="#ref_guide_conf_plugins" title="4. Plugin Configuration">plugin string</a>, this property |
| can be used to configure the <code class="classname"> BrokerImpl</code> with the |
| following properties: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">EvictFromDataCache</code>: When evicting an object through the |
| <code class="methodname">OpenJPAEntityManager.evict</code> methods, whether to also |
| evict it from the OpenJPA's <a href="#ref_guide_cache" title="1. Data Cache">data cache</a>. |
| Defaults to <code class="literal">false</code>. |
| </p></li></ul></div><div class="example"><a name="ref_guide_runtime_pm_evictex"></a><p class="title"><b>Example 9.1. |
| Evict from Data Cache |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| <property name="openjpa.BrokerImpl" value="EvictFromDataCache=true"/> |
| </pre></div></div><br class="example-break"><p> |
| Additionally, some advanced users may want to add capabilities to OpenJPA's |
| internal <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/kernel/BrokerImpl.html" target="_top"> |
| <code class="classname">org.apache.openjpa.kernel.BrokerImpl</code></a>. You can |
| configure OpenJPA to use a custom subclass of <code class="classname">BrokerImpl</code> |
| with the <a href="#openjpa.BrokerImpl" title="5.4. openjpa.BrokerImpl"><code class="literal">openjpa.BrokerImpl |
| </code></a> configuration property. Set this property to the full class |
| name of your custom subclass. When implementing your subclass, consider the |
| finalization issues mentioned in |
| <a href="#ref_guide_runtime_broker_finalization" title="1.1. Broker Finalization">Section 1.1, “ |
| Broker Finalization |
| ”</a>. It may be appropriate |
| to create a subtype of both |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/kernel/BrokerImpl.html" target="_top"> |
| <code class="classname">org.apache.openjpa.kernel.BrokerImpl</code></a> and |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/kernel/FinalizingBrokerImpl.html" target="_top"> |
| <code class="classname">org.apache.openjpa.kernel.FinalizingBrokerImpl</code></a>. |
| </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_runtime_jpa"></a>2. |
| JPA Extensions |
| </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#ref_guide_runtime_emfactory">2.1. |
| OpenJPAEntityManagerFactory |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_runtime_em">2.2. |
| OpenJPAEntityManager |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_runtime_jpaquery">2.3. |
| OpenJPAQuery |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_runtime_jpaextent">2.4. |
| Extent |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_runtime_jpacache">2.5. |
| StoreCache |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_runtime_jpaquerycache">2.6. |
| QueryResultCache |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_runtime_jpafetch">2.7. |
| FetchPlan |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_runtime_openjpaentitytransaction">2.8. |
| OpenJPAEntityTransaction |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_runtime_openjpapersistence">2.9. |
| OpenJPAPersistence |
| </a></span></dt></dl></div><p> |
| The following sections outline the runtime interfaces you can use to access |
| OpenJPA-specific functionality from JPA. Each interface contains services and |
| convenience methods missing from the JPA specification. OpenJPA strives to use |
| the same naming conventions and API patterns as standard JPA methods in all |
| extensions, so that OpenJPA extension APIs feel as much as possible like |
| standard JPA. |
| </p><p> |
| You may have noticed the examples throughout this document using the |
| <code class="methodname">OpenJPAPersistence.cast</code> methods to cast from standard |
| JPA interfaces to OpenJPA extended interfaces. This is the recommended practice. |
| Some application server vendors may proxy OpenJPA's JPA implementation, |
| preventing a straight cast. <code class="classname">OpenJPAPersistence</code>'s |
| <code class="methodname">cast</code> methods work around these proxies. |
| </p><pre class="programlisting"> |
| public static OpenJPAEntityManagerFactory cast(EntityManagerFactory emf); |
| public static OpenJPAEntityManager cast(EntityManager em); |
| public static OpenJPAQuery cast(Query q); |
| </pre><p> |
| We provide additional information on the <code class="classname">OpenJPAPersistence |
| </code> helper <a href="#ref_guide_runtime_openjpapersistence" title="2.9. OpenJPAPersistence"> |
| below</a>. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_runtime_emfactory"></a>2.1. |
| OpenJPAEntityManagerFactory |
| </h3></div></div></div><a class="indexterm" name="d0e28579"></a><a class="indexterm" name="d0e28582"></a><p> |
| The <code class="classname">org.apache.openjpa.persistence.OpenJPAEntityManagerFactory |
| </code> interface extends the basic <code class="classname"> |
| javax.persistence.EntityManagerFactory</code> with OpenJPA-specific |
| features. The <code class="classname">OpenJPAEntityManagerFactory</code> offers APIs to |
| access the OpenJPA data and query caches and to perform other OpenJPA-specific |
| operations. See the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/OpenJPAEntityManagerFactory.html" target="_top"> |
| interface Javadoc</a> for details. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_runtime_em"></a>2.2. |
| OpenJPAEntityManager |
| </h3></div></div></div><a class="indexterm" name="d0e28606"></a><a class="indexterm" name="d0e28609"></a><p> |
| All OpenJPA <code class="classname">EntityManager</code>s implement the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/OpenJPAEntityManager.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.OpenJPAEntityManager</code> |
| </a> interface. This interface extends the standard <code class="classname"> |
| javax.persistence.EntityManager</code>. Just as the standard <code class="classname"> |
| EntityManager</code> is the primary window into JPA services, the |
| <code class="classname">OpenJPAEntityManager</code> is the primary window from JPA into |
| OpenJPA-specific functionality. We strongly encourage you to investigate the API |
| extensions this interface contains. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_runtime_jpaquery"></a>2.3. |
| OpenJPAQuery |
| </h3></div></div></div><a class="indexterm" name="d0e28639"></a><a class="indexterm" name="d0e28642"></a><p> |
| OpenJPA extends JPA's standard query functionality with the <code class="classname"> |
| org.apache.openjpa.persistence.OpenJPAQuery</code> interface. See its |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/OpenJPAQuery.html" target="_top">Javadoc |
| </a> for details on the convenience methods it provides. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_runtime_jpaextent"></a>2.4. |
| Extent |
| </h3></div></div></div><a class="indexterm" name="d0e28660"></a><a class="indexterm" name="d0e28663"></a><p> |
| An <code class="classname">Extent</code> is a logical view of all persistent instances |
| of a given entity class, possibly including subclasses. OpenJPA adds the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/Extent.html" target="_top"><code class="classname"> |
| org.apache.openjpa.persistence.Extent</code></a> class to the set of |
| Java Persistence APIs. The following code illustrates iterating over all |
| instances of the <code class="classname">Magazine</code> entity, without subclasses: |
| </p><div class="example"><a name="ref_guide_runtime_jpaextentex"></a><p class="title"><b>Example 9.2. |
| Using a JPA Extent |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| import org.apache.openjpa.persistence.*; |
| |
| ... |
| |
| OpenJPAEntityManager kem = OpenJPAPersistence.cast(em); |
| Extent<Magazine> mags = kem.getExtent(Magazine.class, false); |
| for (Magazine m : mags) |
| processMagazine (m); |
| </pre></div></div><br class="example-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_runtime_jpacache"></a>2.5. |
| StoreCache |
| </h3></div></div></div><a class="indexterm" name="d0e28690"></a><p> |
| In addition to the <code class="classname">EntityManager</code> object cache mandated by |
| the JPA specification, OpenJPA includes a flexible datastore-level cache. You |
| can access this cache from your JPA code using the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/StoreCache.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.StoreCache</code></a> facade. |
| <a href="#ref_guide_cache" title="1. Data Cache">Section 1, “ |
| Data Cache |
| ”</a> has detailed information on OpenJPA's |
| data caching system, including the <code class="classname">StoreCache</code> facade. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_runtime_jpaquerycache"></a>2.6. |
| QueryResultCache |
| </h3></div></div></div><a class="indexterm" name="d0e28711"></a><p> |
| OpenJPA can cache query results as well as persistent object data. The |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/QueryResultCache.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.QueryResultCache</code></a> |
| is an JPA-flavored facade to OpenJPA's internal query cache. See |
| <a href="#ref_guide_cache_query" title="1.3. Query Cache">Section 1.3, “ |
| Query Cache |
| ”</a> for details on query caching in |
| OpenJPA. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_runtime_jpafetch"></a>2.7. |
| FetchPlan |
| </h3></div></div></div><a class="indexterm" name="d0e28726"></a><a class="indexterm" name="d0e28729"></a><p> |
| Many of the aforementioned OpenJPA interfaces give you access to an <code class="classname"> |
| org.apache.openjpa.persistence.FetchPlan</code> instance. The <code class="classname"> |
| FetchPlan</code> allows you to exercise some control over how objects are |
| fetched from the datastore, including <a href="#ref_guide_dbsetup_lrs" title="10. Large Result Sets"> |
| large result set support</a>, <a href="#ref_guide_fetch" title="7. Fetch Groups">custom fetch |
| groups</a>, and <a href="#ref_guide_locking" title="3. Object Locking">lock levels</a>. |
| </p><p> |
| OpenJPA goes one step further, extending <code class="classname">FetchPlan</code> with |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/jdbc/JDBCFetchPlan.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.jdbc.JDBCFetchPlan</code></a> |
| to add additional JDBC-specific tuning methods. Unless you have customized |
| OpenJPA to use a non-relational back-end (see |
| <a href="#ref_guide_enterprise_abstractstore" title="8. Non-Relational Stores">Section 8, “ |
| Non-Relational Stores |
| ”</a> ), all <code class="classname"> |
| FetchPlan</code>s in OpenJPA implement <code class="classname"> |
| JDBCFetchPlan</code>, so feel free to cast to this interface. |
| </p><p> |
| Fetch plans pass on from parent components to child components. The <code class="classname"> |
| EntityManagerFactory</code> settings (via your configuration properties) |
| for things like the fetch size, result set type, and custom fetch groups are |
| passed on to the fetch plan of the <code class="classname">EntityManager</code>s it |
| produces. The settings of each <code class="classname">EntityManager</code>, in turn, |
| are passed on to each <code class="classname">Query</code> and <code class="classname">Extent |
| </code> it returns. Note that the opposite, however, is not true. Modifying |
| the fetch plan of a <code class="classname">Query</code> or <code class="classname">Extent |
| </code> does not affect the <code class="classname">EntityManager</code>'s |
| configuration. Likewise, modifying an <code class="classname">EntityManager</code>'s |
| configuration does not affect the <code class="classname"> EntityManagerFactory</code>. |
| </p><p> |
| <a href="#ref_guide_fetch" title="7. Fetch Groups">Section 7, “ |
| Fetch Groups |
| ”</a> includes examples using <code class="classname"> |
| FetchPlan</code>s. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_runtime_openjpaentitytransaction"></a>2.8. |
| OpenJPAEntityTransaction |
| </h3></div></div></div><a class="indexterm" name="d0e28811"></a><p> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/OpenJPAEntityTransaction.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.OpenJPAEntityTransaction</code></a> |
| extends <code class="classname">javax.persistence.EntityTransaction</code> to provide |
| additional transaction-debugging capabilities and some concurrency-related |
| commit and rollback features. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_runtime_openjpapersistence"></a>2.9. |
| OpenJPAPersistence |
| </h3></div></div></div><a class="indexterm" name="d0e28827"></a><p> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/OpenJPAPersistence.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.OpenJPAPersistence</code></a> |
| is a static helper class that adds OpenJPA-specific utility methods to |
| <code class="classname">javax.persistence.Persistence</code>. |
| </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_locking"></a>3. |
| Object Locking |
| </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#ref_guide_locking_default">3.1. |
| Configuring Default Locking |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_locking_runtime">3.2. |
| Configuring Lock Levels at Runtime |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_locking_apis">3.3. |
| Object Locking APIs |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_locking_lockmgr">3.4. |
| Lock Manager |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_locking_rules">3.5. |
| Rules for Locking Behavior |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_locking_issues">3.6. |
| Known Issues and Limitations |
| </a></span></dt></dl></div><a class="indexterm" name="d0e28843"></a><p> |
| Controlling how and when objects are locked is an important part of maximizing |
| the performance of your application under load. This section describes OpenJPA's |
| APIs for explicit locking, as well as its rules for implicit locking. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_locking_default"></a>3.1. |
| Configuring Default Locking |
| </h3></div></div></div><a class="indexterm" name="d0e28851"></a><p> |
| <a class="indexterm" name="d0e28858"></a> |
| <a class="indexterm" name="d0e28864"></a> |
| <a class="indexterm" name="d0e28868"></a> |
| You can control OpenJPA's default transactional read and write lock levels |
| through the <a href="#openjpa.ReadLockLevel" title="5.52. openjpa.ReadLockLevel"><code class="literal"> |
| openjpa.ReadLockLevel</code></a> and |
| <a href="#openjpa.WriteLockLevel" title="5.61. openjpa.WriteLockLevel"><code class="literal">openjpa.WriteLockLevel</code> |
| </a> configuration properties. Each property accepts a value of <code class="literal"> |
| none</code>, <code class="literal">read</code>, <code class="literal">write</code>, or a number |
| corresponding to a lock level defined by the |
| <a href="#ref_guide_locking_lockmgr" title="3.4. Lock Manager">lock manager</a> in use. These |
| properties apply only to non-optimistic transactions; during optimistic |
| transactions, OpenJPA never locks objects by default. |
| </p><p> |
| <a class="indexterm" name="d0e28895"></a> |
| <a class="indexterm" name="d0e28899"></a> |
| You can control the default amount of time OpenJPA will wait when trying to |
| obtain locks through the <a href="#openjpa.LockTimeout" title="5.37. openjpa.LockTimeout"><code class="literal"> |
| openjpa.LockTimeout</code></a> configuration property. Set this property |
| to the number of milliseconds you are willing to wait for a lock before OpenJPA |
| will throw an exception, or to -1 for no limit. It defaults to -1. |
| </p><div class="example"><a name="ref_guide_locking_default_conf"></a><p class="title"><b>Example 9.3. |
| Setting Default Lock Levels |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| <property name="openjpa.ReadLockLevel" value="none"/> |
| <property name="openjpa.WriteLockLevel" value="write"/> |
| <property name="openjpa.LockTimeout" value="30000"/> |
| </pre></div></div><br class="example-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_locking_runtime"></a>3.2. |
| Configuring Lock Levels at Runtime |
| </h3></div></div></div><a class="indexterm" name="d0e28917"></a><p> |
| At runtime, you can override the default lock levels through the <code class="classname"> |
| FetchPlan</code> interface described above. At the beginning of each |
| datastore transaction, OpenJPA initializes the <code class="classname"> EntityManager |
| </code>'s fetch plan with the default lock levels and timeouts described |
| in the previous section. By changing the fetch plan's locking properties, you |
| can control how objects loaded at different points in the transaction are |
| locked. You can also use the fetch plan of an individual <code class="classname">Query |
| </code> to apply your locking changes only to objects loaded through that |
| <code class="classname">Query</code>. |
| </p><pre class="programlisting"> |
| public LockModeType getReadLockMode(); |
| public FetchPlan setReadLockMode(LockModeType mode); |
| public LockModeType getWriteLockMode(); |
| public FetchPlan setWriteLockMode(LockModeType mode); |
| long getLockTimeout(); |
| FetchPlan setLockTimeout(long timeout); |
| </pre><p> |
| Controlling locking through these runtime APIs works even during optimistic |
| transactions. At the end of the transaction, OpenJPA resets the fetch plan's |
| lock levels to <code class="literal">none</code>. You cannot lock objects outside of a |
| transaction. |
| </p><div class="example"><a name="ref_guide_locking_fetch"></a><p class="title"><b>Example 9.4. |
| Setting Runtime Lock Levels |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| import org.apache.openjpa.persistence.*; |
| |
| ... |
| |
| EntityManager em = ...; |
| em.getTransaction().begin(); |
| |
| // load stock we know we're going to update at write lock mode |
| Query q = em.createQuery("select s from Stock s where symbol = :s"); |
| q.setParameter("s", symbol); |
| OpenJPAQuery oq = OpenJPAPersistence.cast(q); |
| FetchPlan fetch = oq.getFetchPlan (); |
| fetch.setReadLockMode(LockModeType.WRITE); |
| fetch.setLockTimeout(3000); // 3 seconds |
| Stock stock = (Stock) q.getSingleResult(); |
| |
| // load an object we don't need locked at none lock mode |
| fetch = OpenJPAPersistence.cast(em).getFetchPlan(); |
| fetch.setReadLockMode(null); |
| Market market = em.find(Market.class, marketId); |
| |
| stock.setPrice(market.calculatePrice(stock)); |
| em.getTransaction().commit(); |
| </pre></div></div><br class="example-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_locking_apis"></a>3.3. |
| Object Locking APIs |
| </h3></div></div></div><a class="indexterm" name="d0e28951"></a><p> |
| In addition to allowing you to control implicit locking levels, OpenJPA provides |
| explicit APIs to lock objects and to retrieve their current lock level. |
| </p><pre class="programlisting"> |
| public LockModeType OpenJPAEntityManager.getLockMode(Object pc); |
| </pre><p> |
| Returns the level at which the given object is currently locked. |
| </p><p> |
| In addition to the standard |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="http://java.sun.com/javaee/5/docs/api/javax/persistence/EntityManager.html" target="_top"> |
| <code class="methodname">EntityManager.lock(Object, LockModeType)</code></a> |
| method, the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/OpenJPAEntityManager.html" target="_top"> |
| <code class="classname">OpenJPAEntityManager</code></a> exposes the following |
| methods to lock objects explicitly: |
| </p><pre class="programlisting"> |
| public void lock(Object pc); |
| public void lock(Object pc, LockModeType mode, long timeout); |
| public void lockAll(Object... pcs); |
| public void lockAll(Object... pcs, LockModeType mode, long timeout); |
| public void lockAll(Collection pcs); |
| public void lockAll(Collection pcs, LockModeType mode, long timeout); |
| </pre><p> |
| Methods that do not take a lock level or timeout parameter default to the |
| current fetch plan. The example below demonstrates these methods in action. |
| </p><div class="example"><a name="ref_guide_locking_explicit"></a><p class="title"><b>Example 9.5. |
| Locking APIs |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| import org.apache.openjpa.persistence.*; |
| |
| // retrieve the lock level of an object |
| OpenJPAEntityManager oem = OpenJPAPersistence.cast(em); |
| Stock stock = ...; |
| LockModeType level = oem.getLockMode(stock); |
| if (level == OpenJPAModeType.WRITE) ... |
| |
| ... |
| |
| oem.setOptimistic(true); |
| oem.getTransaction().begin (); |
| |
| // override default of not locking during an opt trans to lock stock object |
| oem.lock(stock, LockModeType.WRITE, 1000); |
| stock.setPrice(market.calculatePrice(stock)); |
| |
| oem.getTransaction().commit(); |
| </pre></div></div><br class="example-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_locking_lockmgr"></a>3.4. |
| Lock Manager |
| </h3></div></div></div><a class="indexterm" name="d0e28986"></a><p> |
| <a class="indexterm" name="d0e28993"></a> |
| OpenJPA delegates the actual work of locking objects to the system's |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/kernel/LockManager.html" target="_top"><code class="classname"> |
| org.apache.openjpa.kernel.LockManager</code></a>. This plugin is |
| controlled by the <a href="#openjpa.LockManager" title="5.36. openjpa.LockManager"><code class="literal"> |
| openjpa.LockManager</code></a> configuration property. You can write your |
| own lock manager, or use one of the bundled options: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">pessimistic</code>: This is an alias for the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/kernel/PessimisticLockManager.html" target="_top"> |
| <code class="classname">o |
| rg.apache.openjpa.jdbc.kernel.PessimisticLockManager</code></a>, which |
| uses SELECT FOR UPDATE statements (or the database's equivalent) to lock the |
| database rows corresponding to locked objects. This lock |
| manager does not distinguish between read locks and write locks; all locks are |
| write locks. |
| </p><p> |
| The <code class="literal">pessimistic</code> LockManager can be configued to additionally |
| perform the version checking and incrementing behavior of the <code class="literal">version |
| </code> lock manager described below by setting its <code class="literal"> |
| VersionCheckOnReadLock</code> and <code class="literal">VersionUpdateOnWriteLock</code> |
| properties: |
| </p><pre class="programlisting"> |
| <property name="openjpa.LockManager" value="pessimistic(VersionCheckOnReadLock=true,VersionUpdateOnWriteLock=true)"/> |
| </pre></li><li><p> |
| <code class="literal">none</code>: An alias for the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/kernel/NoneLockManager.html" target="_top"> |
| <code class="classname">org.apache.openjpa.kernel.NoneLockManager</code></a>, which |
| does not perform any locking at all. |
| </p></li><li><p> |
| <code class="literal">version</code>: An alias for the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/kernel/VersionLockManager.html" target="_top"> |
| <code class="classname">org.apache.openjpa.kernel.VersionLockManager</code></a>. |
| This lock manager does not perform any exclusive locking, but instead ensures |
| read consistency by verifying that the version of all read-locked instances is |
| unchanged at the end of the transaction. Furthermore, a write lock will force an |
| increment to the version at the end of the transaction, even if the object is |
| not otherwise modified. This ensures read consistency with non-blocking |
| behavior. |
| </p><p> |
| This is the default <code class="literal">openjpa.LockManager</code> setting in JPA. |
| </p></li></ul></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| In order for the <code class="literal">version</code> lock manager to prevent the dirty |
| read phenomenon, the underlying data store's transaction isolation level must be |
| set to the equivalent of "read committed" or higher. |
| </p></div><div class="example"><a name="ref_guide_locking_disable"></a><p class="title"><b>Example 9.6. |
| Disabling Locking |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| <property name="openjpa.LockManager" value="none"/> |
| </pre></div></div><br class="example-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_locking_rules"></a>3.5. |
| Rules for Locking Behavior |
| </h3></div></div></div><a class="indexterm" name="d0e29074"></a><a class="indexterm" name="d0e29079"></a><p> |
| Advanced persistence concepts like lazy-loading and object uniquing create |
| several locking corner-cases. The rules below outline OpenJPA's implicit locking |
| behavior in these cases. |
| </p><div class="orderedlist"><ol type="1"><li><p> |
| When an object's state is first read within a transaction, the object is locked |
| at the fetch plan's current read lock level. Future reads of additional lazy |
| state for the object will use the same read lock level, even if the fetch plan's |
| level has changed. |
| </p></li><li><p> |
| When an object's state is first modified within a transaction, the object is |
| locked at the write lock level in effect when the object was first read, even if |
| the fetch plan's level has changed. If the object was not read previously, the |
| current write lock level is used. |
| </p></li><li><p> |
| When objects are accessed through a persistent relation field, the related |
| objects are loaded with the fetch plan's current lock levels, not the lock |
| levels of the object owning the field. |
| </p></li><li><p> |
| Whenever an object is accessed within a transaction, the object is re-locked at |
| the current read lock level. The current read and write lock levels become those |
| that the object "remembers" according to rules one and two above. |
| </p></li><li><p> |
| If you lock an object explicitly through the APIs demonstrated above, it is |
| re-locked at the specified level. This level also becomes both the read and |
| write level that the object "remembers" according to rules one and two above. |
| </p></li><li><p> |
| When an object is already locked at a given lock level, re-locking at a lower |
| level has no effect. Locks cannot be downgraded during a transaction. |
| </p></li></ol></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_locking_issues"></a>3.6. |
| Known Issues and Limitations |
| </h3></div></div></div><a class="indexterm" name="d0e29108"></a><p> |
| Due to performance concerns and database limitations, locking cannot be perfect. |
| You should be aware of the issues outlined in this section, as they may affect |
| your application. |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| Typically, during optimistic transactions OpenJPA does not start an actual |
| database transaction until you flush or the optimistic transaction commits. This |
| allows for very long-lived transactions without consuming database resources. |
| When using the pessimistic lock manager, however, OpenJPA must begin a database |
| transaction whenever you decide to lock an object during an optimistic |
| transaction. This is because the pessimistic lock manager uses database locks, |
| and databases cannot lock rows without a transaction in progress. OpenJPA will |
| log an INFO message to the <code class="literal">openjpa.Runtime</code> logging channel |
| when it begins a datastore transaction just to lock an object. |
| </p></li><li><p> |
| In order to maintain reasonable performance levels when loading object state, |
| OpenJPA can only guarantee that an object is locked at the proper lock level |
| <span class="emphasis"><em>after</em></span> the state has been retrieved from the database. This |
| means that it is technically possible for another transaction to "sneak in" and |
| modify the database record after OpenJPA retrieves the state, but before it |
| locks the object. The only way to positively guarantee that the object is locked |
| and has the most recent state to refresh the object after locking it. |
| </p><p> |
| When using the pessimistic lock manager, the case above can only occur when |
| OpenJPA cannot issue the state-loading SELECT as a locking statement due to |
| database limitations. For example, some databases cannot lock SELECTs that use |
| joins. The pessimistic lock manager will log an INFO message to the <code class="literal"> |
| openjpa.Runtime</code> logging channel whenever it cannot lock the initial |
| SELECT due to database limitations. By paying attention to these log messages, |
| you can see where you might consider using an object refresh to guarantee that |
| you have the most recent state, or where you might rethink the way you load the |
| state in question to circumvent the database limitations that prevent OpenJPA |
| from issuing a locking SELECT in the first place. |
| </p></li></ul></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_savepoints"></a>4. |
| Savepoints |
| </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#reg_guide_savepoints_using">4.1. |
| Using Savepoints |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_savepoints_conf">4.2. |
| Configuring Savepoints |
| </a></span></dt></dl></div><a class="indexterm" name="d0e29136"></a><p> |
| Savepoints allow for fine grained control over the transactional behavior of |
| your application. OpenJPA's savepoint API allow you to set intermediate rollback |
| points in your transaction. You can then choose to rollback changes made only |
| after a specific savepoint, then commit or continue making new changes in the |
| transaction. This feature is useful for multi-stage transactions, such as |
| editing a set of objects over several web pages or user screens. Savepoints also |
| provide more flexibilty to conditional transaction behavior, such as choosing to |
| commit or rollback a portion of the transaction based on the results of the |
| changes. This chapter describes how to use and configure OpenJPA savepoints. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="reg_guide_savepoints_using"></a>4.1. |
| Using Savepoints |
| </h3></div></div></div><p> |
| OpenJPA's |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/OpenJPAEntityManager.html" target="_top"> |
| <code class="classname">OpenJPAEntityManager</code></a> have the following |
| methods to control savepoint behavior. Note that the savepoints work in tandem |
| with the current transaction. This means that savepoints require an open |
| transaction, and that a rollback of the transaction will rollback all of the |
| changes in the transaction regardless of any savepoints set. |
| </p><pre class="programlisting"> |
| void setSavepoint(String name); |
| void releaseSavepoint(String name); |
| void rollbackToSavepoint(String name); |
| </pre><p> |
| To set a savepoint, simply call <code class="methodname">setSavepoint</code>, passing |
| in a symbolic savepoint name. This savepoint will define a point at which you |
| can preserve the state of transactional objects for the duration of the current |
| transaction. |
| </p><p> |
| Having set a named savepoint, you can rollback changes made after that point by |
| calling <code class="methodname">rollbackToSavepoint</code>. This method will keep the |
| current transaction active, while restoring all transactional instances back to |
| their saved state. Instances that were deleted after the save point will no |
| longer be marked for deletion. Similarly, transient instances that were made |
| persistent after the savepoint will become transient again. Savepoints made |
| after this savepoint will be released and no longer valid, although you can |
| still set new savepoints. Savepoints will also be cleared after the current |
| transaction is committed or rolled back. |
| </p><p> |
| If a savepoint is no longer needed, you can release any resources it is |
| consuming resources by calling <code class="methodname">releaseSavepoint</code>. This |
| method should not be called for savepoints that have been |
| released automatically through other means, such as commit of a transaction or |
| rollback to a prior savepoint. While savepoints made after this savepoint will |
| also be released, there are no other effects on the current transaction. |
| </p><p> |
| The following simple example illustrates setting, releasing, and rolling back to |
| a savepoint. |
| </p><div class="example"><a name="ref_guide_savepoints_example"></a><p class="title"><b>Example 9.7. |
| Using Savepoints |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| import org.apache.openjpa.persistence.*; |
| |
| ... |
| |
| OpenJPAEntityManager oem = OpenJPAPersistence.cast(em); |
| oem.getTransaction().begin(); |
| |
| Magazine mag = oem.find(Magazine.class, id); |
| mag.setPageCount(300); |
| oem.setSavepoint("pages"); |
| |
| mag.setPrice(mag.getPageCount() * pricePerPage); |
| // we decide to release "pages"... |
| oem.releaseSavepoint("pages"); |
| // ... and set a new savepoint which includes all changes |
| oem.setSavepoint("price"); |
| |
| mag.setPrice(testPrice); |
| // we determine the test price is not good |
| oem.rollbackToSavepoint("price"); |
| // had we chosen to not release "pages", we might have rolled back to |
| // "pages" instead |
| |
| // the price is now restored to mag.getPageCount() * pricePerPage |
| oem.getTransaction().commit(); |
| </pre></div></div><br class="example-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_savepoints_conf"></a>4.2. |
| Configuring Savepoints |
| </h3></div></div></div><p> |
| OpenJPA uses the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/kernel/SavepointManager" target="_top"> |
| <code class="classname">org.apache.openjpa.kernel.SavepointManager</code></a> |
| <a href="#ref_guide_conf_plugins" title="4. Plugin Configuration">plugin</a> to handle perserving the |
| savepoint state. OpenJPA includes the following <code class="classname">SavepointManager |
| </code> plugins: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">in-mem</code>: The default. This is an alias for the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="org.apache.openjpa.kernel.InMemorySavepointManager" target="_top"><code class="classname"> |
| org.apache.openjpa.kernel.InMemorySavepointManager</code></a>. This |
| plugin stores all state, including field values, in memory. Due to this |
| behavior, each set savepoint is designed for small to medium transactional |
| object counts. |
| </p></li><li><p> |
| <code class="literal">jdbc</code>: This is an alias for the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="org.apache.openjpa.jdbc.kernel.JDBCSavepointManager" target="_top"><code class="classname"> |
| org.apache.openjpa.jdbc.kernel.JDBCSavepointManager</code></a>. This |
| plugin requires <code class="literal">JDBC 3</code> and <code class="classname"> java.sql.Savepoint |
| </code> support to operate. Note that this plugin implements savepoints by |
| issuing a flush to the database. |
| </p></li><li><p> |
| <code class="literal">oracle</code>: This is an alias for the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="org.apache.openjpa.jdbc.sql.OracleSavepointManager" target="_top"><code class="classname"> |
| org.apache.openjpa.jdbc.sql.OracleSavepointManager</code></a>. This |
| plugin operates similarly to the <code class="literal">JDBC</code> plugin; however, it |
| uses Oracle-specific calls. This plugin requires using the Oracle JDBC driver |
| and database, versions <code class="literal">9.2</code> or higher. Note that this plugin |
| implements savepoints by issuing a flush to the database. |
| </p></li></ul></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_enterprise_methodql"></a>5. |
| MethodQL |
| </h2></div></div></div><a class="indexterm" name="d0e29238"></a><a class="indexterm" name="d0e29241"></a><p> |
| If JPQL and SQL queries do not match your needs, OpenJPA also allows you to name |
| a Java method to use to load a set of objects. In a <span class="emphasis"><em>MethodQL |
| </em></span> query, the query string names a static method to invoke to determine |
| the matching objects: |
| </p><pre class="programlisting"> |
| import org.apache.openjpa.persistence.*; |
| |
| ... |
| |
| // the method query language is 'openjpa.MethodQL'. |
| // set the query string to the method to execute, including full class name; if |
| // the class is in the candidate class' package or in the query imports, you |
| // can omit the package; if the method is in the candidate class, you can omit |
| // the class name and just specify the method name |
| OpenJPAEntityManager oem = OpenJPAPersistence.cast(emf); |
| OpenJPAQuery q = oem.createQuery("openjpa.MethodQL", "com.xyz.Finder.getByName"); |
| |
| // set the type of objects that the method returns |
| q.setResultClass(Person.class); |
| |
| // parameters are passed the same way as in standard queries |
| q.setParameter("firstName", "Fred").setParameter("lastName", "Lucas"); |
| |
| // this executes your method to get the results |
| List results = q.getResultList(); |
| </pre><p> |
| For datastore queries, the method must have the following signature: |
| </p><pre class="programlisting"> |
| public static <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/lib/rop/ResultObjectProvider.html" target="_top">ResultObjectProvider</a> xxx(<a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/kernel/StoreContext.html" target="_top">StoreContext</a> ctx, <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/meta/ClassMetaData.html" target="_top">ClassMetaData</a> meta, boolean subclasses, Map params, <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/kernel/FetchConfiguration.html" target="_top">FetchConfiguration </a> fetch) |
| </pre><p> |
| The returned result object provider should produce objects of the candidate |
| class that match the method's search criteria. If the returned objects do not |
| have all fields in the given fetch configuration loaded, OpenJPA will make |
| additional trips to the datastore as necessary to fill in the data for the |
| missing fields. |
| </p><p> |
| In-memory execution is slightly different, taking in one object at a time and |
| returning a boolean on whether the object matches the query: |
| </p><pre class="programlisting"> |
| public static boolean xxx(<a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/kernel/StoreContext.html" target="_top">StoreContext</a> ctx, <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/meta/ClassMetaData.html" target="_top">ClassMetaData</a> meta, boolean subclasses, Object obj, Map params, <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/kernel/FetchConfiguration.html" target="_top">FetchConfiguration</a> fetch) |
| </pre><p> |
| In both method versions, the given <code class="literal">params</code> map contains the |
| names and values of all the parameters for the query. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_sequence"></a>6. |
| Generators |
| </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#ref_guide_sequence_runtime">6.1. |
| Runtime Access |
| </a></span></dt></dl></div><a class="indexterm" name="d0e29295"></a><p> |
| The JPA Overview's <a href="#jpa_overview_mapping" title="Chapter 12. Mapping Metadata">Chapter 12, <i xmlns:xlink="http://www.w3.org/1999/xlink"> |
| Mapping Metadata |
| </i></a> details using |
| generators to automatically populate identity fields in JPA. |
| </p><p> |
| OpenJPA represents all generators internally with the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/kernel/Seq.html" target="_top"><code class="classname"> |
| org.apache.openjpa.kernel.Seq</code></a> interface. This interface |
| supplies all the context you need to create your own custom generators, |
| including the current persistence environment, the JDBC <code class="classname">DataSource |
| </code>, and other essentials. The |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/kernel/AbstractJDBCSeq.html" target="_top"> |
| <code class="classname">org.apache.openjpa.jdbc.kernel.AbstractJDBCSeq</code></a> |
| helps you create custom JDBC-based sequences. OpenJPA also supplies the |
| following built-in <code class="classname">Seq</code>s: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <a class="indexterm" name="d0e29325"></a> |
| <code class="literal">table</code>: This is OpenJPA's default implementation. It is an |
| alias for the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/kernel/TableJDBCSeq.html" target="_top"> |
| <code class="classname">org.apache.openjpa.jdbc.kernel.TableJDBCSeq</code></a> |
| class. The <code class="classname">TableJDBCSeq</code> uses a special single-row table |
| to store a global sequence number. If the table does not already exist, it is |
| created the first time you run the |
| <a href="#ref_guide_mapping_mappingtool" title="1. Forward Mapping">mapping tool</a> on a class |
| that requires it. You can also use the class's <code class="methodname">main</code> |
| method to manipulate the table; see the |
| <code class="methodname">TableJDBCSeq.main</code> method Javadoc for usage details. |
| </p><p> |
| This <code class="classname">Seq</code> has the following properties: |
| </p><div class="itemizedlist"><ul type="circle"><li><p> |
| <code class="literal">Table</code>: The name of the sequence number table to use. |
| Defaults to <code class="literal">OPENJPA_SEQUENCE_TABLE</code>. If the entities are |
| mapped to the same table name but with different schema name within one |
| PersistenceUnit, one <code class="literal">OPENJPA_SEQUENCE_TABLE</code> is created |
| for each schema. |
| </p></li><li><p> |
| <code class="literal">PrimaryKeyColumn</code>: The name of the primary key column for the |
| sequence table. Defaults to <code class="literal">ID</code>. |
| </p></li><li><p> |
| <code class="literal">SequenceColumn</code>: The name of the column that will hold the |
| current sequence value. Defaults to <code class="literal">SEQUENCE_VALUE</code>. |
| </p></li><li><p> |
| <code class="literal">Allocate</code>: The number of values to allocate on each database |
| trip. Defaults to 50, meaning the class will set aside the next 50 numbers each |
| time it accesses the sequence table, which in turn means it only has to make a |
| database trip to get new sequence numbers once every 50 sequence number |
| requests. |
| </p></li></ul></div></li><li><p> |
| <a class="indexterm" name="d0e29396"></a> |
| <code class="literal">class-table</code>: This is an alias for the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/kernel/ClassTableJDBCSeq.html" target="_top"> |
| <code class="classname">org.apache.openjpa.jdbc.kernel.ClassTableJDBCSeq</code></a> |
| . This <code class="classname">Seq</code> is like the <code class="classname">TableJDBCSeq |
| </code> above, but maintains a separate table row, and therefore a separate |
| sequence number, for each base persistent class. It has all the properties of |
| the <code class="classname">TableJDBCSeq</code>. Its table name defaults to <code class="literal"> |
| OPENJPA_SEQUENCES_TABLE</code>. It also adds the following properties: |
| </p><div class="itemizedlist"><ul type="circle"><li><p> |
| <code class="literal">IgnoreUnmapped</code>: Whether to ignore unmapped base classes, and |
| instead use one row per least-derived mapped class. Defaults to <code class="literal"> |
| false</code>. |
| </p></li><li><p> |
| <code class="literal">UseAliases</code>: Whether to use each class' entity name as the |
| primary key value of each row, rather than the full class name. Defaults to |
| <code class="literal">false</code>. |
| </p></li></ul></div><p> |
| As with the <code class="classname">TableJDBCSeq</code>, the <code class="classname"> |
| ClassTableJDBCSeq</code> creates its table automatically during mapping |
| tool runs. However, you can manually manipulate the table through the class' |
| <code class="methodname">main</code> method. See the Javadoc for the |
| <code class="methodname"> ClassTableJDBCSeq.main</code> method for usage details. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e29458"></a> |
| <code class="literal">value-table</code>: This is an alias for the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/kernel/ValueTableJDBCSeq.html" target="_top"> |
| <code class="classname">org.apache.openjpa.jdbc.kernel.ValueTableJDBCSeq</code></a> |
| . This <code class="classname">Seq</code> is like the <code class="classname">ClassTableJDBCSeq |
| </code> above, but has an arbitrary number of rows for sequence values, |
| rather than a fixed pattern of one row per class. Its table defaults to |
| <code class="literal">OPENJPA_SEQUENCES_TABLE</code>. It has all the properties of the |
| <code class="classname">TableJDBCSeq</code>, plus: |
| </p><div class="itemizedlist"><ul type="circle"><li><p> |
| <code class="literal">PrimaryKeyValue</code>: The primary key value used by this instance. |
| </p></li></ul></div><p> |
| As with the <code class="classname">TableJDBCSeq</code>, the <code class="classname"> |
| ValueTableJDBCSeq</code> creates its table automatically during mapping |
| tool runs. However, you can manually manipulate the table through the class' |
| <code class="methodname">main</code> method. See the Javadoc for the |
| <code class="methodname">ValueTableJDBCSeq.main</code> method for usage details. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e29508"></a> |
| <code class="literal">native</code>: This is an alias for the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/kernel/NativeJDBCSeq.html" target="_top"> |
| <code class="classname">org.apache.openjpa.jdbc.kernel.NativeJDBCSeq</code></a>. |
| Many databases have a concept of "native sequences" - a built-in mechanism for |
| obtaining incrementing numbers. For example, in Oracle, you can create a |
| database sequence with a statement like <code class="literal">CREATE SEQUENCE MYSEQUENCE |
| </code>. Sequence values can then be atomically obtained and incremented |
| with the statement <code class="literal">SELECT MYSEQUENCE.NEXTVAL FROM DUAL</code>. |
| OpenJPA provides support for this common mechanism of sequence generation with |
| the <code class="classname"> NativeJDBCSeq</code>, which accepts the following |
| properties: |
| </p><div class="itemizedlist"><ul type="circle"><li><p> |
| <code class="literal">Sequence</code>: The name of the database sequence. Defaults to |
| <code class="literal">OPENJPA_SEQUENCE</code>. |
| </p></li><li><p> |
| <code class="literal">InitialValue</code>: The initial sequence value. Defaults to 1. |
| </p></li><li><p> |
| <code class="literal">Increment</code>: The amount the sequence increments. Defaults to 1. |
| </p></li><li><p> |
| <code class="literal">Allocate</code>: Some database can allocate values in-memory to |
| service subsequent sequence requests faster. |
| </p></li></ul></div></li><li><p> |
| <a class="indexterm" name="d0e29562"></a> |
| <code class="literal">time</code>: This is an alias for the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/kernel/TimeSeededSeq.html" target="_top"> |
| <code class="classname">org.apache.openjpa.kernel.TimeSeededSeq</code></a>. This |
| type uses an in-memory static counter, initialized to the current time in |
| milliseconds and monotonically incremented for each value requested. It is only |
| suitable for single-JVM environments. |
| </p></li></ul></div><p> |
| You can use JPA <code class="literal">SequenceGenerator</code>s to describe any built-in |
| <code class="classname">Seq</code>s or your own <code class="classname">Seq</code> |
| implementation. Set the <code class="literal">sequenceName</code> attribute to a plugin |
| string describing your choice. |
| </p><div class="blockquote"><blockquote class="blockquote"><p> |
| If specifying your own class name, you must include parentheses at the end of |
| the class name, even if you have no plugin properties to configure. |
| (E.g., <code class="literal">sequenceName="com.example.SeqImpl()"</code>. |
| </p></blockquote></div><p> |
| See <a href="#jpa_overview_mapping_sequence" title="5. Generators">Section 5, “ |
| Generators |
| ”</a> in the JPA Overview for |
| details on defining <code class="literal">SequenceGenerator</code>s. |
| </p><p> |
| See <a href="#ref_guide_conf_plugins" title="4. Plugin Configuration">Section 4, “ |
| Plugin Configuration |
| ”</a> for plugin string formatting. |
| </p><div class="example"><a name="ref_guide_sequence_named"></a><p class="title"><b>Example 9.8. |
| Named Seq Sequence |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| @Entity |
| @Table(name="AUTO") |
| public class Author { |
| |
| @Id |
| @GeneratedValue(strategy=GenerationType.SEQUENCE, generator="AuthorSeq") |
| @SequenceGenerator(name="AuthorSeq" sequence="table(Table=AUTO_SEQ, Increment=100)") |
| @Column(name="AID") |
| private long id; |
| |
| ... |
| } |
| </pre><p> |
| Note that if you want to use a plugin string without any arguments, you must |
| still suffix the plugin type with <code class="literal">()</code> to differentiate it from |
| a sequence name in the <code class="literal"> SequenceGenerator.sequence</code> attribute: |
| </p><pre class="programlisting"> |
| @SequenceGenerator(name="AuthorSeq", sequence="table()") |
| </pre></div></div><br class="example-break"><p> |
| OpenJPA maintains a <span class="emphasis"><em>system</em></span> sequence to generate datastore |
| identity values for classes that do not declare a specific datastore identity |
| strategy. You can configure the system sequence through the |
| <a href="#openjpa.Sequence" title="5.59. openjpa.Sequence"><code class="literal">openjpa.Sequence</code></a> |
| configuration property. This property accepts a plugin string describing a |
| <code class="classname">Seq</code> instance. |
| </p><div class="example"><a name="ref_guide_sequence_systemex"></a><p class="title"><b>Example 9.9. |
| System Sequence Configuration |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| <property name="openjpa.Sequence" value="table(Table=OPENJPASEQ, Increment=100)"/> |
| </pre></div></div><br class="example-break"><p> |
| In JPA, set your <code class="literal">GeneratedValue</code> annotation's <code class="literal"> |
| strategy</code> attribute to <code class="literal">AUTO</code> to use the configured |
| system sequence. Or, because <code class="literal">AUTO</code> is the default strategy, |
| use the annotation without attributes: |
| </p><pre class="programlisting"> |
| @GeneratedValue |
| private long id; |
| </pre><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_sequence_runtime"></a>6.1. |
| Runtime Access |
| </h3></div></div></div><a class="indexterm" name="d0e29658"></a><p> |
| OpenJPA allows you to access named generators at runtime through the |
| <code class="methodname">OpenJPAEntityManager.getNamedGenerator</code> method: |
| </p><pre class="programlisting"> |
| public Generator getNamedGenerator(String name); |
| </pre><p> |
| The returned |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/Generator.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.Generator</code></a> is a |
| facade over an internal OpenJPA <code class="classname">Seq</code>. |
| </p><p> |
| The <code class="classname">OpenJPAEntityManager</code> includes additional APIs to |
| retrieve the identity generator of any class, or the generator of any field. |
| With these APIs, you do not have to know the generator name. Additionally, they |
| allow you to access the implicit generator used by default for datastore |
| identity classes. See the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/OpenJPAEntityManager.html" target="_top"> |
| Javadoc</a> for the <code class="methodname"> OpenJPAEntityManager.getIdentityGenerator |
| </code> and <code class="methodname">OpenJPAEntityManager.getFieldGenerator |
| </code> methods for API details. |
| </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_runtime_pm_event"></a>7. |
| Transaction Events |
| </h2></div></div></div><a class="indexterm" name="d0e29697"></a><p> |
| The OpenJPA runtime supports broadcasting transaction-related events. By |
| registering one or more |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/event/TransactionListener.html" target="_top"> |
| <code class="classname">org.apache.openjpa.event.TransactionListener</code></a> s, |
| you can receive notifications when transactions begin, flush, rollback, commit, |
| and more. Where appropriate, event notifications include the set of |
| persistence-capable objects participating in the transaction. |
| </p><pre class="programlisting"> |
| public void addTransactionListener(Object listener); |
| public void removeTransactionListener(Object listener); |
| </pre><p> |
| These <code class="classname">OpenJPAEntityManagerSPI</code> methods allow you to add |
| and remove listeners. These methods are outside the bounds of the published OpenJPA APIs, and are subject to change in the future. |
| </p><p> |
| For details on the transaction framework, see the <code class="literal"> |
| org.apache.openjpa.event</code> package |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/event/package.html" target="_top">Javadoc</a>. |
| Also see <a href="#ref_guide_event" title="2. Remote Event Notification Framework">Section 2, “ |
| Remote Event Notification Framework |
| ”</a> for a description of OpenJPA's |
| remote event support. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_enterprise_abstractstore"></a>8. |
| Non-Relational Stores |
| </h2></div></div></div><p> |
| It is possible to adapt OpenJPA to access a non-relational datastore by creating |
| an implementation of the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/kernel/StoreManager.html" target="_top"><code class="literal"> |
| org.apache.openjpa.kernel.StoreManager</code></a> interface. OpenJPA |
| provides an abstract <code class="literal">StoreManager</code> implementation to |
| facilitate this process. See the <code class="literal">org.apache.openjpa.abstractstore |
| </code> package <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/abstractstore" target="_top"> |
| Javadoc</a> for details. |
| </p></div></div><div class="chapter" lang="en" id="ref_guide_caching"><div class="titlepage"><div><div><h2 class="title"><a name="ref_guide_caching"></a>Chapter 10. |
| Caching |
| </h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#ref_guide_cache">1. |
| Data Cache |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_cache_conf">1.1. |
| Data Cache Configuration |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_cache_use">1.2. |
| Data Cache Usage |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_cache_query">1.3. |
| Query Cache |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_cache_extension">1.4. |
| Cache Extension |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_cache_notes">1.5. |
| Important Notes |
| </a></span></dt><dt><span class="section"><a href="#datastore_cache_issues">1.6. |
| Known Issues and Limitations |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_cache_querycomp">2. |
| Query Compilation Cache |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_cache_querysql">3. |
| Query SQL Cache |
| </a></span></dt></dl></div><p> |
| OpenJPA utilizes several configurable caches to maximize performance. This |
| chapter explores OpenJPA's data cache, query cache, and query compilation cache. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_cache"></a>1. |
| Data Cache |
| </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#ref_guide_cache_conf">1.1. |
| Data Cache Configuration |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_cache_use">1.2. |
| Data Cache Usage |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_cache_query">1.3. |
| Query Cache |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_cache_extension">1.4. |
| Cache Extension |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_cache_notes">1.5. |
| Important Notes |
| </a></span></dt><dt><span class="section"><a href="#datastore_cache_issues">1.6. |
| Known Issues and Limitations |
| </a></span></dt></dl></div><a class="indexterm" name="d0e29753"></a><p> |
| The OpenJPA data cache is an optional cache of persistent object data that |
| operates at the <code class="classname">EntityManagerFactory</code> level. This cache is |
| designed to significantly increase performance while remaining in full |
| compliance with the JPA standard. This means that turning on the caching option |
| can transparently increase the performance of your application, with no changes |
| to your code. |
| </p><p> |
| OpenJPA's data cache is not related to the <code class="classname">EntityManager</code> |
| cache dictated by the JPA specification. The JPA specification mandates behavior |
| for the <code class="classname">EntityManager</code> cache aimed at guaranteeing |
| transaction isolation when operating on persistent objects. |
| </p><p> |
| OpenJPA's data cache is designed to provide significant performance increases |
| over cacheless operation, while guaranteeing that behavior will be identical in |
| both cache-enabled and cacheless operation. |
| </p><p> |
| There are five ways to access data via the OpenJPA APIs: standard relation |
| traversal, large result set relation traversal, queries, looking up an object by |
| id, and iteration over an <code class="classname">Extent</code>. OpenJPA's cache plugin |
| accelerates three of these mechanisms. It does not provide any caching of large |
| result set relations or <code class="classname">Extent</code> iterators. If you find |
| yourself in need of higher-performance <code class="classname">Extent</code> iteration, |
| see <a href="#ref_guide_cache_limits_extent" title="Example 10.15. Query Replaces Extent">Example 10.15, “ |
| Query Replaces Extent |
| ”</a>. |
| </p><div class="table"><a name="d0e29786"></a><p class="title"><b>Table 10.1. |
| Data access methods |
| </b></p><div class="table-contents"><table summary="
 Data access methods
 " border="1"><colgroup><col align="left"><col align="left"></colgroup><thead><tr><th align="left">Access method</th><th align="left">Uses cache</th></tr></thead><tbody><tr><td align="left"> |
| Standard relation traversal |
| </td><td align="left"> |
| Yes |
| </td></tr><tr><td align="left"> |
| Large result set relation traversal |
| </td><td align="left">No</td></tr><tr><td align="left">Query</td><td align="left">Yes</td></tr><tr><td align="left"> |
| Lookups by object id |
| </td><td align="left">Yes</td></tr><tr><td align="left"> |
| Iteration over an <code class="classname">Extent</code> |
| </td><td align="left">No</td></tr></tbody></table></div></div><br class="table-break"><p> |
| When enabled, the cache is checked before making a trip to the datastore. Data |
| is stored in the cache when objects are committed and when persistent objects |
| are loaded from the datastore. |
| </p><p> |
| OpenJPA's data cache can in both single-JVM and multi-JVM environments. |
| Multi-JVM caching is achieved through the use of the distributed event |
| notification framework described in <a href="#ref_guide_event" title="2. Remote Event Notification Framework">Section 2, “ |
| Remote Event Notification Framework |
| ”</a>, or |
| through custom integrations with a third-party distributed cache. |
| </p><p> |
| The single JVM mode of operation maintains and shares a data cache across all |
| <code class="classname">EntityManager</code> instances obtained from a particular |
| <code class="classname">EntityManagerFactory</code>. This is not appropriate for use in |
| a distributed environment, as caches in different JVMs or created from different |
| <code class="classname">EntityManagerFactory</code> objects will not be synchronized. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_cache_conf"></a>1.1. |
| Data Cache Configuration |
| </h3></div></div></div><p> |
| To enable the basic single-factory cache set the |
| <a href="#openjpa.DataCache" title="5.25. openjpa.DataCache"><code class="literal">openjpa.DataCache</code></a> |
| property to <code class="literal">true</code>, and set the |
| <a href="#openjpa.RemoteCommitProvider" title="5.53. openjpa.RemoteCommitProvider"><code class="literal"> |
| openjpa.RemoteCommitProvider</code></a> property to <code class="literal">sjvm |
| </code>: |
| </p><div class="example"><a name="ref_guide_cache_conf_sjvm"></a><p class="title"><b>Example 10.1. |
| Single-JVM Data Cache |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| <property name="openjpa.DataCache" value="true"/> |
| <property name="openjpa.RemoteCommitProvider" value="sjvm"/> |
| </pre></div></div><br class="example-break"><p> |
| To configure the data cache to remain up-to-date in a distributed environment, |
| set the <a href="#openjpa.RemoteCommitProvider" title="5.53. openjpa.RemoteCommitProvider"><code class="literal"> |
| openjpa.RemoteCommitProvider</code></a> property appropriately, or |
| integrate OpenJPA with a third-party caching solution. Remote commit providers |
| are described in <a href="#ref_guide_event" title="2. Remote Event Notification Framework">Section 2, “ |
| Remote Event Notification Framework |
| ”</a>. |
| </p><p> |
| <a class="indexterm" name="d0e29878"></a> |
| OpenJPA's default implementation maintains a map of object |
| ids to cache data. By default, 1000 elements are kept in cache. When the cache |
| overflows, random entries are evicted. The maximum cache size can be |
| adjusted by setting the <code class="literal">CacheSize</code> property in your plugin |
| string - see below for an example. Objects that are pinned into the cache are |
| not counted when determining if the cache size exceeds its maximum size. |
| </p><p> |
| Expired objects are moved to a soft reference map, so they may stick around for |
| a little while longer. You can control the number of soft references OpenJPA |
| keeps with the <code class="literal">SoftReferenceSize</code> property. Soft references |
| are unlimited by default. Set to 0 to disable soft references completely. |
| </p><div class="example"><a name="ref_guide_cache_conf_size"></a><p class="title"><b>Example 10.2. |
| Data Cache Size |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| <property name="openjpa.DataCache" value="true(CacheSize=5000, SoftReferenceSize=0)"/> |
| </pre></div></div><br class="example-break"><p> |
| <a class="indexterm" name="d0e29899"></a> |
| You can specify a cache timeout value for a class by setting the timeout |
| <a href="#ref_guide_meta_ext" title="4. Metadata Extensions">metadata extension</a> to the amount of |
| time in milliseconds a class's data is valid. Use a value of -1 for no |
| expiration. This is the default value. |
| </p><div class="example"><a name="ex_timeout_cache"></a><p class="title"><b>Example 10.3. |
| Data Cache Timeout |
| </b></p><div class="example-contents"><p> |
| Timeout <code class="classname">Employee</code> objects after 10 seconds. |
| </p><pre class="programlisting"> |
| @Entity |
| @DataCache(timeout=10000) |
| public class Employee { |
| ... |
| } |
| </pre></div></div><br class="example-break"><p> |
| <a class="indexterm" name="d0e29920"></a> |
| Entities may be explicitly excluded from the cache by providing a |
| list of fully qualified class names in the ExcludedTypes argument. |
| The entities provided via ExcludedTypes will not be cached |
| regardless of the @DataCache annotation. |
| </p><div class="example"><a name="ex_exclude_types_from_cache"></a><p class="title"><b>Example 10.4. |
| Excluding entities |
| </b></p><div class="example-contents"><p> |
| Exclude entities foo.bar.Person and foo.bar.Employee from the cache. |
| </p><pre class="programlisting"> |
| <property name="openjpa.DataCache" value="true(ExcludedTypes=foo.bar.Person;foo.bar.Employee)"/> |
| </pre><p> |
| </p></div></div><br class="example-break"><p> |
| <a class="indexterm" name="d0e29936"></a> |
| Entities may be explicitly included from the cache by providing a |
| list of fully qualified class names in the Types argument. The |
| entities provided via ExcludedTypes will not cached regardless of |
| the @DataCache annotation. Any entities which are not included in |
| this list will not be cached. |
| </p><div class="example"><a name="ex_include_types_in_cache"></a><p class="title"><b>Example 10.5. |
| Including entities |
| </b></p><div class="example-contents"><p> |
| Include only entity foo.bar.FullTimeEmployee from the cache. |
| </p><pre class="programlisting"> |
| <property name="openjpa.DataCache" value="true(Types=foo.bar.FullTimeEmployee)"/> |
| </pre><p> |
| </p></div></div><br class="example-break"><p> |
| See the <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/DataCache.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.DataCache</code></a> Javadoc |
| for more information on the <code class="classname">DataCache</code> annotation. |
| </p><p> |
| <a class="indexterm" name="d0e29962"></a> |
| A cache can specify that it should be cleared at certain times rather than using |
| data timeouts. The <code class="literal">EvictionSchedule</code> property of OpenJPA's |
| cache implementation accepts a <code class="literal">cron</code> style eviction schedule. |
| The format of this property is a whitespace-separated list of five tokens, where |
| the <code class="literal">*</code> symbol (asterisk), indicates match all. The tokens are, |
| in order: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| Minute |
| </p></li><li><p> |
| Hour of Day |
| </p></li><li><p> |
| Day of Month |
| </p></li><li><p> |
| Month |
| </p></li><li><p> |
| Day of Week |
| </p></li></ul></div><p> |
| For example, the following <code class="literal">openjpa.DataCache</code> setting |
| schedules the default cache to evict values from the cache at 15 and 45 minutes |
| past 3 PM on Sunday. |
| </p><pre class="programlisting"> |
| true(EvictionSchedule='15,45 15 * * 1') |
| </pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_cache_use"></a>1.2. |
| Data Cache Usage |
| </h3></div></div></div><p> |
| The <code class="literal">org.apache.openjpa.datacache</code> package defines OpenJPA's |
| data caching framework. While you may use this framework directly (see its |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/datacache/package-summary.html" target="_top"> |
| Javadoc</a> for details), its APIs are meant primarily for service |
| providers. In fact, <a href="#ref_guide_cache_extension" title="1.4. Cache Extension">Section 1.4, “ |
| Cache Extension |
| ”</a> below has |
| tips on how to use this package to extend OpenJPA's caching service yourself. |
| </p><p> |
| Rather than use the low-level <code class="literal">org.apache.openjpa.datacache</code> |
| package APIs, JPA users should typically access the data cache through OpenJPA's |
| high-level |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/StoreCache.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.StoreCache</code></a> facade. |
| This facade has methods to pin and unpin records, evict data from the cache, and |
| more. |
| </p><pre class="programlisting"> |
| public StoreCache getStoreCache(); |
| </pre><p> |
| You obtain the <code class="classname">StoreCache</code> through the <code class="methodname"> |
| OpenJPAEntityManagerFactory.getStoreCache</code> method. |
| </p><div class="example"><a name="ref_guide_cache_access_jpa"></a><p class="title"><b>Example 10.6. |
| Accessing the StoreCache |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| import org.apache.openjpa.persistence.*; |
| |
| ... |
| |
| OpenJPAEntityManagerFactory oemf = OpenJPAPersistence.cast(emf); |
| StoreCache cache = oemf.getStoreCache(); |
| ... |
| </pre></div></div><br class="example-break"><pre class="programlisting"> |
| public void evict(Class cls, Object oid); |
| public void evictAll(); |
| public void evictAll(Class cls, Object... oids); |
| public void evictAll(Class cls, Collection oids); |
| </pre><p> |
| The <code class="methodname">evict</code> methods tell the cache to release data. Each |
| method takes an entity class and one or more identity values, and releases the |
| cached data for the corresponding persistent instances. The <code class="methodname"> |
| evictAll</code> method with no arguments clears the cache. Eviction is |
| useful when the datastore is changed by a separate process outside OpenJPA's |
| control. In this scenario, you typically have to manually evict the data from |
| the datastore cache; otherwise the OpenJPA runtime, oblivious to the changes, |
| will maintain its stale copy. |
| </p><pre class="programlisting"> |
| public void pin(Class cls, Object oid); |
| public void pinAll(Class cls, Object... oids); |
| public void pinAll(Class cls, Collection oids); |
| public void unpin(Class cls, Object oid); |
| public void unpinAll(Class cls, Object... oids); |
| public void unpinAll(Class cls, Collection oids); |
| </pre><p> |
| Most caches are of limited size. Pinning an identity to the cache ensures that |
| the cache will not kick the data for the corresponding instance out of the |
| cache, unless you manually evict it. Note that even after manual eviction, the |
| data will get pinned again the next time it is fetched from the store. You can |
| only remove a pin and make the data once again available for normal cache |
| overflow eviction through the <code class="methodname">unpin</code> methods. Use |
| pinning when you want a guarantee that a certain object will always be available |
| from cache, rather than requiring a datastore trip. |
| </p><div class="example"><a name="ref_guide_cache_use_jpa"></a><p class="title"><b>Example 10.7. |
| StoreCache Usage |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| import org.apache.openjpa.persistence.*; |
| |
| ... |
| |
| OpenJPAEntityManagerFactory oemf = OpenJPAPersistence.cast(emf); |
| StoreCache cache = oemf.getStoreCache(); |
| cache.pin(Magazine.class, popularMag.getId()); |
| cache.evict(Magazine.class, changedMag.getId()); |
| </pre></div></div><br class="example-break"><p> |
| See the <code class="classname">StoreCache</code> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/StoreCache.html" target="_top"> |
| Javadoc</a> for information on additional functionality it provides. Also, |
| <a href="#ref_guide_runtime" title="Chapter 9. Runtime Extensions">Chapter 9, <i xmlns:xlink="http://www.w3.org/1999/xlink"> |
| Runtime Extensions |
| </i></a> discusses OpenJPA's other extensions |
| to the standard set of JPA runtime interfaces. |
| </p><p> |
| The examples above include calls to <code class="methodname">evict</code> to manually |
| remove data from the data cache. Rather than evicting objects from the data |
| cache directly, you can also configure OpenJPA to automatically evict objects |
| from the data cache when you use the <code class="classname"> |
| OpenJPAEntityManager</code>'s eviction APIs. |
| </p><div class="example"><a name="ref_guide_cache_pmevict"></a><p class="title"><b>Example 10.8. |
| Automatic Data Cache Eviction |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| <property name="openjpa.BrokerImpl" value="EvictFromDataCache=true"/> |
| </pre><pre class="programlisting"> |
| import org.apache.openjpa.persistence.*; |
| |
| ... |
| |
| OpenJPAEntityManager oem = OpenJPAPersistence.cast(em); |
| oem.evict(changedMag); // will evict from data cache also |
| </pre></div></div><br class="example-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_cache_query"></a>1.3. |
| Query Cache |
| </h3></div></div></div><a class="indexterm" name="d0e30088"></a><a class="indexterm" name="d0e30093"></a><p> |
| In addition to the data cache, the <code class="literal">org.apache.openjpa.datacache |
| </code> package defines service provider interfaces for a query cache. The |
| query cache is enabled by default when the data cache is enabled. The query |
| cache stores the object ids returned by query executions. When you run a query, |
| OpenJPA assembles a key based on the query properties and the parameters used at |
| execution time, and checks for a cached query result. If one is found, the |
| object ids in the cached result are looked up, and the resultant |
| persistence-capable objects are returned. Otherwise, the query is executed |
| against the database, and the object ids loaded by the query are put into the |
| cache. The object id list is not cached until the list returned at query |
| execution time is fully traversed. |
| </p><p> |
| OpenJPA exposes a high-level interface to the query cache through the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/QueryResultCache.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.QueryResultCache</code></a> |
| class. You can access this class through the <code class="classname"> |
| OpenJPAEntityManagerFactory</code>. |
| </p><div class="example"><a name="ref_guide_cache_queryaccess"></a><p class="title"><b>Example 10.9. |
| Accessing the QueryResultCache |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| import org.apache.openjpa.persistence.*; |
| |
| ... |
| |
| OpenJPAEntityManagerFactory oemf = OpenJPAPersistence.cast(emf); |
| QueryResultCache qcache = oemf.getQueryResultCache(); |
| </pre></div></div><br class="example-break"><p> |
| The default query cache implementation caches 100 query executions in a |
| least-recently-used cache. This can be changed by setting the cache size in the |
| <code class="literal">CacheSize</code> plugin property. Like the data cache, the query |
| cache also has a backing soft reference map. The <code class="literal">SoftReferenceSize |
| </code> property controls the size of this map. It is disabled by default. |
| </p><div class="example"><a name="ref_guide_cache_cachesize"></a><p class="title"><b>Example 10.10. |
| Query Cache Size |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| <property name="openjpa.QueryCache" value="CacheSize=1000, SoftReferenceSize=100"/> |
| </pre></div></div><br class="example-break"><p> |
| To disable the query cache completely, set the <code class="literal">openjpa.QueryCache |
| </code> property to <code class="literal">false</code>: |
| </p><div class="example"><a name="ref_guide_cache_disablequery"></a><p class="title"><b>Example 10.11. |
| Disabling the Query Cache |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| <property name="openjpa.QueryCache" value="false"/> |
| </pre></div></div><br class="example-break"><p> |
| There are certain situations in which the query cache is bypassed: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| Caching is not used for in-memory queries (queries in which the candidates are a |
| collection instead of a class or <code class="classname">Extent</code>). |
| </p></li><li><p> |
| Caching is not used in transactions that have <code class="literal">IgnoreChanges</code> |
| set to <code class="literal">false</code> and in which modifications to classes in the |
| query's access path have occurred. If none of the classes in the access path |
| have been touched, then cached results are still valid and are used. |
| </p></li><li><p> |
| Caching is not used in pessimistic transactions, since OpenJPA must go to the |
| database to lock the appropriate rows. |
| </p></li><li><p> |
| Caching is not used when the data cache does not have any cached data for an |
| id in a query result. |
| </p></li><li><p> |
| Queries that use persistence-capable objects as parameters are only cached if |
| the parameter is directly compared to field, as in: |
| </p><pre class="programlisting"> |
| select e from Employee e where e.company.address = :addr |
| </pre><p> |
| If you extract field values from the parameter in your query string, or if the |
| parameter is used in collection element comparisons, the query is not cached. |
| </p></li><li><p> |
| Queries that result in projections of custom field types or <code class="classname"> |
| BigDecimal</code> or <code class="classname">BigInteger</code> fields are not |
| cached. |
| </p></li></ul></div><p> |
| Cache results are removed from the cache when instances of classes in a cached |
| query's access path are touched. That is, if a query accesses data in class |
| <code class="classname">A</code>, and instances of class <code class="classname">A</code> are |
| modified, deleted, or inserted, then the cached query result is dropped from the |
| cache. |
| </p><p> |
| It is possible to tell the query cache that a class has been altered. This is |
| only necessary when the changes occur via direct modification of the database |
| outside of OpenJPA's control. You can also evict individual queries, or clear |
| the entire cache. |
| </p><pre class="programlisting"> |
| public void evict(Query q); |
| public void evictAll(Class cls); |
| public void evictAll(); |
| </pre><p> |
| For JPA queries with parameters, set the desired parameter values into the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="http://java.sun.com/javaee/5/docs/api/javax/persistence/Query.html" target="_top"> |
| <code class="classname">Query</code></a> instance before calling the above methods. |
| </p><div class="example"><a name="ref_guide_cache_query_classchange"></a><p class="title"><b>Example 10.12. |
| Evicting Queries |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| import org.apache.openjpa.persistence.*; |
| |
| ... |
| |
| OpenJPAEntityManagerFactory oemf = OpenJPAPersistence.cast(emf); |
| QueryResultCache qcache = oemf.getQueryResultCache(); |
| |
| // evict all queries that can be affected by changes to Magazines |
| qcache.evictAll(Magazine.class); |
| |
| // evict an individual query with parameters |
| EntityManager em = emf.createEntityManager(); |
| Query q = em.createQuery(...). |
| setParameter(0, paramVal0). |
| setParameter(1, paramVal1); |
| qcache.evict (q); |
| </pre></div></div><br class="example-break"><p> |
| When using one of OpenJPA's distributed cache implementations, it is necessary |
| to perform this in every JVM - the change notification is not propagated |
| automatically. When using a third-party coherent caching solution, |
| it is not necessary to do this in every JVM (although it won't hurt to do so), |
| as the cache results are stored directly in the coherent cache. |
| </p><p> |
| Queries can also be pinned and unpinned through the <code class="classname"> |
| QueryResultCache</code>. The semantics of these operations are the same |
| as pinning and unpinning data from the data cache. |
| </p><pre class="programlisting"> |
| public void pin(Query q); |
| public void unpin(Query q); |
| </pre><p> |
| For JPA queries with parameters, set the desired parameter values into the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="http://java.sun.com/javaee/5/docs/api/javax/persistence/Query.html" target="_top"> |
| <code class="classname">Query</code></a> instance before calling the above methods. |
| </p><p> |
| The following example shows these APIs in action. |
| </p><div class="example"><a name="ref_guide_cache_query_pin"></a><p class="title"><b>Example 10.13. |
| Pinning, and Unpinning Query Results |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| import org.apache.openjpa.persistence.*; |
| |
| ... |
| |
| OpenJPAEntityManagerFactory oemf = OpenJPAPersistence.cast(emf); |
| QueryResultCache qcache = oemf.getQueryResultCache(); |
| EntityManager em = emf.createEntityManager(); |
| |
| Query pinQuery = em.createQuery(...). |
| setParameter(0, paramVal0). |
| setParameter(1, paramVal1); |
| qcache.pin(pinQuery); |
| Query unpinQuery = em.createQuery(...). |
| setParameter(0, paramVal0). |
| setParameter(1, paramVal1); |
| qcache.unpin(unpinQuery); |
| </pre></div></div><br class="example-break"><p> |
| Pinning data into the cache instructs the cache to not expire the pinned results |
| when cache flushing occurs. However, pinned results will be removed from the |
| cache if an event occurs that invalidates the results. |
| </p><p> |
| You can disable caching on a per-<code class="classname">EntityManager</code> or |
| per-<code class="classname">Query</code> basis: |
| </p><div class="example"><a name="ref_guide_cache_query_disable"></a><p class="title"><b>Example 10.14. |
| Disabling and Enabling Query Caching |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| import org.apache.openjpa.persistence.*; |
| |
| ... |
| |
| // temporarily disable query caching for all queries created from em |
| OpenJPAEntityManager oem = OpenJPAPersistence.cast(em); |
| oem.getFetchPlan ().setQueryResultCacheEnabled(false); |
| |
| // re-enable caching for a particular query |
| OpenJPAQuery oq = oem.createQuery(...); |
| oq.getFetchPlan().setQueryResultCacheEnabled(true); |
| </pre></div></div><br class="example-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_cache_extension"></a>1.4. |
| Cache Extension |
| </h3></div></div></div><a class="indexterm" name="d0e30249"></a><a class="indexterm" name="d0e30256"></a><p> |
| The provided data cache classes can be easily extended to add additional |
| functionality. If you are adding new behavior, you should extend <code class="classname"> |
| org.apache.openjpa.datacache.DataCacheImpl</code>. To use your own storage |
| mechanism, extend <code class="classname">org.apache.openjpa.datacache.AbstractDataCache |
| </code>, or implement <code class="classname">org.apache.openjpa.datacache.DataCache |
| </code> directly. If you want to implement a distributed cache that uses an |
| unsupported method for communications, create an implementation of <code class="classname"> |
| org.apache.openjpa.event.RemoteCommitProvider</code>. This process is |
| described in greater detail in |
| <a href="#ref_guide_event_customization" title="2.2. Customization">Section 2.2, “ |
| Customization |
| ”</a>. |
| </p><p> |
| The query cache is just as easy to extend. Add functionality by extending the |
| default <code class="classname">org.apache.openjpa.datacache.QueryCacheImpl</code>. |
| Implement your own storage mechanism for query results by extending <code class="classname"> |
| org.apache.openjpa.datacache.AbstractQueryCache</code> or implementing the |
| <code class="classname">org.apache.openjpa.datacache.QueryCache</code> interface |
| directly. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_cache_notes"></a>1.5. |
| Important Notes |
| </h3></div></div></div><div class="itemizedlist"><ul type="disc"><li><p> |
| The default cache implementations <span class="emphasis"><em>do not</em></span> automatically |
| refresh objects in other <code class="classname">EntityManager</code>s when the cache |
| is updated or invalidated. This behavior would not be compliant with the JPA |
| specification. |
| </p></li><li><p> |
| Invoking <code class="methodname">OpenJPAEntityManager.evict</code><span class="emphasis"><em> does not |
| </em></span> result in the corresponding data being dropped from the data cache, |
| unless you have set the proper configuration options as explained above (see |
| <a href="#ref_guide_cache_pmevict" title="Example 10.8. Automatic Data Cache Eviction">Example 10.8, “ |
| Automatic Data Cache Eviction |
| ”</a>). Other methods related to the |
| <code class="classname">EntityManager</code> cache also do not affect the data cache. |
| </p><p> |
| The data cache assumes that it is up-to-date with respect to the datastore, so |
| it is effectively an in-memory extension of the database. To manipulate the data |
| cache, you should generally use the data cache facades presented in this |
| chapter. |
| </p></li><li><p> |
| You must specify a <code class="classname">org.apache.openjpa.event.RemoteCommitProvider |
| </code> (via the <a href="#openjpa.RemoteCommitProvider" title="5.53. openjpa.RemoteCommitProvider"><code class="literal"> |
| openjpa.RemoteCommitProvider</code></a> property) in order to use the data |
| cache, even when using the cache in a single-JVM mode. When using it in a |
| single-JVM context, set this property to <code class="literal">sjvm</code>. |
| </p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="datastore_cache_issues"></a>1.6. |
| Known Issues and Limitations |
| </h3></div></div></div><a class="indexterm" name="d0e30334"></a><div class="itemizedlist"><ul type="disc"><li><p> |
| When using datastore (pessimistic) transactions in concert with the distributed |
| caching implementations, it is possible to read stale data when reading data |
| outside a transaction. |
| </p><p> |
| For example, if you have two JVMs (JVM A and JVM B) both communicating with each |
| other, and JVM A obtains a data store lock on a particular object's underlying |
| data, it is possible for JVM B to load the data from the cache without going to |
| the datastore, and therefore load data that should be locked. This will only |
| happen if JVM B attempts to read data that is already in its cache during the |
| period between when JVM A locked the data and JVM B received and processed the |
| invalidation notification. |
| </p><p> |
| This problem is impossible to solve without putting together a two-phase commit |
| system for cache notifications, which would add significant overhead to the |
| caching implementation. As a result, we recommend that people use optimistic |
| locking when using data caching. If you do not, then understand that some of |
| your non-transactional data may not be consistent with the datastore. |
| </p><p> |
| Note that when loading objects in a transaction, the appropriate datastore |
| transactions will be obtained. So, transactional code will maintain its |
| integrity. |
| </p></li><li><p> |
| <code class="classname">Extent</code>s are not cached. So, if you plan on iterating |
| over a list of all the objects in an <code class="classname">Extent</code> on a regular |
| basis, you will only benefit from caching if you do so with a <code class="classname">Query |
| </code> instead: |
| </p><div class="example"><a name="ref_guide_cache_limits_extent"></a><p class="title"><b>Example 10.15. |
| Query Replaces Extent |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| import org.apache.openjpa.persistence.*; |
| |
| ... |
| |
| OpenJPAEntityManager oem = OpenJPAPersistence.cast(em); |
| Extent extent = oem.getExtent(Magazine.class, false); |
| |
| // This iterator does not benefit from caching... |
| Iterator uncachedIterator = extent.iterator(); |
| |
| // ... but this one does. |
| OpenJPAQuery extentQuery = oem.createQuery(...); |
| extentQuery.setSubclasses(false); |
| Iterator cachedIterator = extentQuery.getResultList().iterator(); |
| </pre></div></div><br class="example-break"></li></ul></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_cache_querycomp"></a>2. |
| Query Compilation Cache |
| </h2></div></div></div><a class="indexterm" name="d0e30369"></a><p> |
| The query compilation cache is a <code class="classname">Map</code> used to cache |
| parsed query strings. As a result, most queries are only parsed once in |
| OpenJPA, and cached thereafter. You can control the compilation cache through |
| the <a href="#openjpa.QueryCompilationCache" title="5.51. openjpa.QueryCompilationCache"><code class="literal"> |
| openjpa.QueryCompilationCache</code></a> configuration property. This |
| property accepts a plugin string (see <a href="#ref_guide_conf_plugins" title="4. Plugin Configuration">Section 4, “ |
| Plugin Configuration |
| ”</a>) |
| describing the <code class="classname">Map</code> used to associate query strings and |
| their parsed form. This property accepts the following aliases: |
| </p><div class="table"><a name="d0e30388"></a><p class="title"><b>Table 10.2. |
| Pre-defined aliases |
| </b></p><div class="table-contents"><table summary="
 Pre-defined aliases
 " border="1"><colgroup><col align="left"><col align="left"></colgroup><thead><tr><th align="left">Alias</th><th align="left">Value</th><th align="left">Notes</th></tr></thead><tbody><tr><td align="left"> |
| <code class="literal">true</code> |
| </td><td align="left"> |
| <code class="literal">org.apache.openjpa.util.CacheMap</code> |
| </td><td align="left"> |
| The default option. Uses a |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/util/CacheMap.html" target="_top"> |
| <code class="literal">CacheMap</code></a> to store compilation data. |
| <code class="literal">CacheMap</code> maintains a fixed number of cache entries, and an |
| optional soft reference map for entries that are moved out of the LRU space. |
| So, for applications that have a monotonically increasing number of distinct |
| queries, this option can be used to ensure that a fixed amount of memory is |
| used by the cache. |
| </td></tr><tr><td align="left"><code class="literal">all</code></td><td align="left"> |
| <code class="literal">org.apache.openjpa.lib.util.ConcurrentHashMap</code> |
| </td><td align="left"> |
| This is the fastest option, but compilation data is never dropped from the |
| cache, so if you use a large number of dynamic queries, this option may result |
| in ever-increasing memory usage. Note that if your queries only differ in the |
| values of the parameters, this should not be an issue. |
| </td></tr><tr><td align="left"><code class="literal">false</code></td><td align="left"><span class="emphasis"><em>none</em></span></td><td align="left"> |
| Disables the compilation cache. |
| </td></tr></tbody></table></div></div><br class="table-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_cache_querysql"></a>3. |
| Query SQL Cache |
| </h2></div></div></div><a class="indexterm" name="d0e30448"></a><p> |
| The query SQL cache is a <code class="classname">Map</code> used to cache |
| pushed-down SQL query strings for the find operation. As a result, |
| the SQL queries are only generated once in OpenJPA, and cached thereafter. |
| This query SQL cache is shared across entity managers and the fetch plan |
| is part of the cache key. You can control the SQL cache through |
| the <a href="#openjpa.jdbc.QuerySQLCache" title="6.10. openjpa.jdbc.QuerySQLCache"><code class="literal"> |
| openjpa.jdbc.QuerySQLCache</code></a> configuration property. This |
| property accepts a plugin string (see <a href="#ref_guide_conf_plugins" title="4. Plugin Configuration">Section 4, “ |
| Plugin Configuration |
| ”</a>) |
| describing the <code class="classname">Map</code> used to associate query strings and |
| their parsed form. This property accepts the following aliases: |
| </p><div class="table"><a name="d0e30467"></a><p class="title"><b>Table 10.3. |
| Pre-defined aliases |
| </b></p><div class="table-contents"><table summary="
 Pre-defined aliases
 " border="1"><colgroup><col align="left"><col align="left"></colgroup><thead><tr><th align="left">Alias</th><th align="left">Value</th><th align="left">Notes</th></tr></thead><tbody><tr><td align="left"> |
| <code class="literal">true</code> |
| </td><td align="left"> |
| <code class="literal">org.apache.openjpa.util.CacheMap</code> |
| </td><td align="left"> |
| The default option. Uses a |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/util/CacheMap.html" target="_top"> |
| <code class="literal">CacheMap</code></a> to store sql string. |
| <code class="literal">CacheMap</code> maintains a fixed number of cache entries, and an |
| optional soft reference map for entries that are moved out of the LRU space. |
| So, for applications that have a monotonically increasing number of distinct |
| queries, this option can be used to ensure that a fixed amount of memory is |
| used by the cache. |
| </td></tr><tr><td align="left"><code class="literal">all</code></td><td align="left"> |
| <code class="literal">org.apache.openjpa.lib.util.ConcurrentHashMap</code> |
| </td><td align="left"> |
| This is the fastest option, but sql string is never dropped from the |
| cache, so if you use a large number of dynamic queries, this option may result |
| in ever-increasing memory usage. Note that if your queries only differ in the |
| values of the parameters, this should not be an issue. |
| </td></tr><tr><td align="left"><code class="literal">false</code></td><td align="left"><span class="emphasis"><em>none</em></span></td><td align="left"> |
| Disables the sql cache. |
| </td></tr></tbody></table></div></div><br class="table-break"></div></div><div class="chapter" lang="en" id="ref_guide_remote"><div class="titlepage"><div><div><h2 class="title"><a name="ref_guide_remote"></a>Chapter 11. |
| Remote and Offline Operation |
| </h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#ref_guide_detach">1. |
| Detach and Attach |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_detach_behavior">1.1. |
| Detach Behavior |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_attach_behavior">1.2. |
| Attach Behavior |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_detach_graph">1.3. |
| Defining the Detached Object Graph |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_detach_field">1.3.1. |
| Detached State Field |
| </a></span></dt></dl></dd></dl></dd><dt><span class="section"><a href="#ref_guide_event">2. |
| Remote Event Notification Framework |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_event_conf">2.1. |
| Remote Commit Provider Configuration |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_event_conf_jms">2.1.1. |
| JMS |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_event_conf_tcp">2.1.2. |
| TCP |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_event_conf_common">2.1.3. |
| Common Properties |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_event_customization">2.2. |
| Customization |
| </a></span></dt></dl></dd></dl></div><a class="indexterm" name="d0e30528"></a><a class="indexterm" name="d0e30531"></a><p> |
| The standard JPA runtime environment is <span class="emphasis"><em>local</em></span> and |
| <span class="emphasis"><em>online</em></span>. It is <span class="emphasis"><em>local</em></span> in that components |
| such as <code class="classname">EntityManager</code>s and queries connect directly to |
| the datastore and execute their actions in the same JVM as the code using them. |
| It is <span class="emphasis"><em>online</em></span> in that all changes to managed objects must be |
| made in the context of an active <code class="classname"> EntityManager</code>. These |
| two properties, combined with the fact that <code class="classname"> |
| EntityManager</code>s cannot be serialized for storage or network transfer, |
| make the standard JPA runtime difficult to incorporate into some enterprise and |
| client/server program designs. |
| </p><p> |
| OpenJPA extends the standard runtime to add <span class="emphasis"><em>remote</em></span> and |
| <span class="emphasis"><em>offline</em></span> capabilities in the form of enhanced |
| <a href="#ref_guide_detach" title="1. Detach and Attach">Detach and Attach APIs</a> and |
| <a href="#ref_guide_event" title="2. Remote Event Notification Framework">Remote Commit Events</a>. The following |
| sections explain these capabilities in detail. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_detach"></a>1. |
| Detach and Attach |
| </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#ref_guide_detach_behavior">1.1. |
| Detach Behavior |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_attach_behavior">1.2. |
| Attach Behavior |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_detach_graph">1.3. |
| Defining the Detached Object Graph |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_detach_field">1.3.1. |
| Detached State Field |
| </a></span></dt></dl></dd></dl></div><a class="indexterm" name="d0e30576"></a><a class="indexterm" name="d0e30579"></a><p> |
| The JPA Overview describes the specification's standard detach and attach APIs |
| in <a href="#jpa_overview_em_lifecycle" title="2. Entity Lifecycle Management">Section 2, “ |
| Entity Lifecycle Management |
| ”</a>. This section enumerates |
| OpenJPA's enhancements to the standard behavior. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_detach_behavior"></a>1.1. |
| Detach Behavior |
| </h3></div></div></div><a class="indexterm" name="d0e30591"></a><p> |
| In JPA, objects detach automatically when they are serialized or when a |
| <a href="#jpa_overview_emfactory_perscontext" title="3. Persistence Context">persistence context</a> |
| ends. The specification does not define any way to explicitly detach objects. |
| The extended |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/OpenJPAEntityManager.html" target="_top"> |
| <code class="classname">OpenJPAEntityManager</code></a>, however, allows you to |
| explicitly detach objects at any time. |
| </p><pre class="programlisting"> |
| public Object detach(Object pc): |
| public Object[] detachAll(Object... pcs): |
| public Collection detachAll(Collection pcs): |
| </pre><p> |
| Each detach method returns detached copies of the given instances. The copy |
| mechanism is similar to serialization, except that only certain fields are |
| traversed. We will see how to control which fields are detached in a later |
| section. |
| </p><p> |
| <a class="indexterm" name="d0e30612"></a> |
| When detaching an instance that has been modified in the current transaction |
| (and thus made dirty), the current transaction is flushed. This means that when |
| subsequently re-attaching the detached instances, OpenJPA assumes that the |
| transaction from which they were originally detached was committed; if it has |
| been rolled back, then the re-attachment process will throw an optimistic |
| concurrency exception. |
| </p><p> |
| You can stop OpenJPA from assuming the transaction will commit in the following |
| ways : |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| Invoke <code class="methodname">EntityTransaction.setRollbackOnly |
| </code> prior to detachingyour objects. Setting the |
| <code class="literal">RollbackOnly</code> flag prevents OpenJPA from |
| flushing when detaching dirty objects; instead OpenJPA just |
| runs its pre-flush actions (see the |
| <code class="methodname">OpenJPAEntityManager.preFlush</code> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/OpenJPAEntityManager.html" target="_top"> |
| Javadoc</a> for details). |
| </p><p> |
| This allows you to use the same instances in multiple |
| attach/modify/detach/rollback cycles. |
| </p></li><li><p> |
| Make your modifications outside of a transaction (with <code class="literal"> |
| NontransactionalWrite</code> enabled) before detaching. |
| </p></li><li><p> |
| Set <code class="literal">flushBeforeDetach</code> |
| to false (see <code class="methodname">Compatibility.setFlushBeforeDetach |
| </code> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/conf/Compatibility.html" target="_top"> |
| Javadoc</a> ). This option is similar to the first option, but does not |
| affect the current transaction. |
| </p></li></ul></div><p> |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_attach_behavior"></a>1.2. |
| Attach Behavior |
| </h3></div></div></div><a class="indexterm" name="d0e30660"></a><p> |
| When attaching, OpenJPA uses several strategies to determine the optimal way to |
| merge changes made to the detached instance. As you will see, these strategies |
| can even be used to attach changes made to a transient instance which was never |
| detached in the first place. |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| If the instance was detached and <a href="#ref_guide_detach_graph" title="1.3. Defining the Detached Object Graph"> |
| detached state</a> is enabled, OpenJPA will use the detached state to |
| determine the object's version and primary key values. In addition, this state |
| will tell OpenJPA which fields were loaded at the time of detach, and in turn |
| where to expect changes. Loaded detached fields with null values will set the |
| attached instance's corresponding fields to null. |
| </p></li><li><p> |
| If the instance has a <code class="literal">Version</code> field, |
| OpenJPA will consider the object detached if the version field has a non-default |
| value, and new otherwise. Similarly, if the instance has |
| <code class="literal">GeneratedValue</code> primary key fields, OpenJPA will consider the |
| object detached if any of these fields have non-default values, and new |
| otherwise. |
| </p><p> |
| When attaching null fields in these cases, OpenJPA cannot distinguish between a |
| field that was unloaded and one that was intentionally set to null. In this |
| case, OpenJPA will use the current <a href="#ref_guide_detach_graph" title="1.3. Defining the Detached Object Graph"> |
| detach state</a> setting to determine how to handle null fields: fields that |
| would have been included in the detached state are treated as loaded, and will |
| in turn set the corresponding attached field to null. |
| </p></li><li><p> |
| If neither of the above cases apply, OpenJPA will check to see if an instance |
| with the same primary key values exists in the database. If so, the object is |
| considered detached. Otherwise, it is considered new. |
| </p></li></ul></div><p> |
| These strategies will be assigned on a per-instance basis, such that during the |
| attachment of an object graph more than one of the above strategies may be used. |
| </p><p> |
| If you attempt to attach a versioned instance whose representation has changed |
| in the datastore since detachment, OpenJPA will throw an optimistic concurrency |
| exception upon commit or flush, just as if a normal optimistic conflict was |
| detected. When attaching an instance whose database record has been deleted |
| since detaching, or when attaching a detached instance into a manager that has a |
| stale version of the object, OpenJPA will throw an optimistic concurrency |
| exception from the attach method. In these cases, OpenJPA sets the <code class="literal"> |
| RollbackOnly</code> flag on the transaction. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_detach_graph"></a>1.3. |
| Defining the Detached Object Graph |
| </h3></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#ref_guide_detach_field">1.3.1. |
| Detached State Field |
| </a></span></dt></dl></div><a class="indexterm" name="d0e30701"></a><p> |
| When detached objects lose their association with the OpenJPA runtime, they also |
| lose the ability to load additional state from the datastore. It is important, |
| therefore, to populate objects with all the persistent state you will need |
| before detaching them. While you are free to do this manually, OpenJPA includes |
| facilities for automatically populating objects when they detach. The |
| <a href="#openjpa.DetachState" title="5.28. openjpa.DetachState"><code class="literal">openjpa.DetachState</code> |
| </a> configuration property determines which fields and relations are |
| detached by default. All settings are recursive. They are: |
| </p><div class="orderedlist"><ol type="1"><li><p> |
| <code class="literal">loaded</code>: Detach all fields and relations that are already |
| loaded, but don't include unloaded fields in the detached graph. This is the |
| default. |
| </p></li><li><p> |
| <code class="literal">fetch-groups</code>: Detach all fields and relations in the current |
| <a href="#ref_guide_runtime" title="Chapter 9. Runtime Extensions">fetch configuration</a>. For more |
| information on custom fetch groups, see <a href="#ref_guide_fetch" title="7. Fetch Groups">Section 7, “ |
| Fetch Groups |
| ”</a>. |
| </p></li><li><p> |
| <code class="literal">all</code>: Detach all fields and relations. Be very careful when |
| using this mode; if you have a highly-connected domain model, you could end up |
| bringing every object in the database into memory! |
| </p></li></ol></div><p> |
| Any field that is not included in the set determined by the detach mode is set |
| to its Java default value in the detached instance. |
| </p><p> |
| The <code class="literal">openjpa.DetachState</code> option is actually a plugin string |
| (see <a href="#ref_guide_conf_plugins" title="4. Plugin Configuration">Section 4, “ |
| Plugin Configuration |
| ”</a>) that allows you to also |
| configure the following options related to detached state: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">DetachedStateField</code>: As described in |
| <a href="#ref_guide_attach_behavior" title="1.2. Attach Behavior">Section 1.2, “ |
| Attach Behavior |
| ”</a> above, OpenJPA can take |
| advantage of a <span class="emphasis"><em>detached state field</em></span> to make the attach |
| process more efficient. This field is added by the enhancer and is not visible |
| to your application. Set this property to one of the following values: |
| </p><div class="itemizedlist"><ul type="circle"><li><p> |
| <code class="literal">transient</code>: Use a transient detached state field. This gives |
| the benefits of a detached state field to local objects that are never |
| serialized, but retains serialization compatibility for client tiers without |
| access to the enhanced versions of your classes. This is the default. |
| </p></li><li><p> |
| <code class="literal">true</code>: Use a non-transient detached state field so that |
| objects crossing serialization barriers can still be attached efficiently. This |
| requires, however, that your client tier have the enhanced versions of your |
| classes and the OpenJPA libraries. |
| </p></li><li><p> |
| <code class="literal">false</code>: Do not use a detached state field. |
| </p></li></ul></div><p> |
| You can override the setting of this property or declare your own detached state |
| field on individual classes using OpenJPA's metadata extensions. See |
| <a href="#ref_guide_detach_field" title="1.3.1. Detached State Field">Section 1.3.1, “ |
| Detached State Field |
| ”</a> below. |
| </p></li><li><p> |
| <code class="literal">DetachedStateManager</code>: Whether to use a detached state |
| manager. A detached state manager makes attachment much more efficient. Like a |
| detached state field, however, it breaks serialization compatibility with the |
| unenhanced class if it isn't transient. |
| </p><p> |
| This setting piggybacks on the <code class="literal">DetachedStateField</code> setting |
| above. If your detached state field is transient, the detached state manager |
| will also be transient. If the detached state field is disabled, the detached |
| state manager will also be disabled. This is typically what you'll want. By |
| setting <code class="literal"> DetachedStateField</code> to true (or transient) and |
| setting this property to false, however, you can use a detached state field |
| <span class="bold"><strong>without</strong></span> using a detached state manager. This |
| may be useful for debugging or for legacy OpenJPA users who find differences |
| between OpenJPA's behavior with a detached state manager and OpenJPA's older |
| behavior without one. |
| </p></li><li><p> |
| <code class="literal">AccessUnloaded</code>: Whether to allow access to unloaded fields |
| of detached objects. Defaults to true. Set to false to throw an exception |
| whenever an unloaded field is accessed. This option is only available when you |
| use detached state managers, as determined by the settings above. |
| </p></li></ul></div><div class="example"><a name="ref_guide_detach_graph_confex"></a><p class="title"><b>Example 11.1. |
| Configuring Detached State |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| <property name="openjpa.DetachState" value="fetch-groups(DetachedStateField=true)"/> |
| </pre></div></div><br class="example-break"><p> |
| You can also alter the set of fields that will be included in the detached graph |
| at runtime. |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/OpenJPAEntityManager.html" target="_top"> |
| <code class="classname">OpenJPAEntityManager</code></a>s expose the following APIs |
| for controlling detached state: |
| </p><pre class="programlisting"> |
| public DetachStateType getDetachState(); |
| public void setDetachState(DetachStateType type); |
| </pre><p> |
| The <code class="classname">DetachStateType</code> enum contains the following values: |
| </p><pre class="programlisting"> |
| enum DetachStateType { |
| FETCH_GROUPS, |
| LOADED, |
| ALL |
| } |
| </pre><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="ref_guide_detach_field"></a>1.3.1. |
| Detached State Field |
| </h4></div></div></div><a class="indexterm" name="d0e30828"></a><p> |
| When the detached state field is enabled, the OpenJPA enhancer adds an |
| additional field to the enhanced version of your class. This field of type |
| <code class="classname">Object</code>. OpenJPA uses this field for bookkeeping |
| information, such as the versioning data needed to detect optimistic concurrency |
| violations when the object is re-attached. |
| </p><p> |
| It is possible to define this detached state field yourself. Declaring this |
| field in your class metadata prevents the enhancer from adding any extra fields |
| to the class, and keeps the enhanced class serialization-compatible with the |
| unenhanced version. The detached state field must not be persistent. See |
| <a href="#detached-state-field" title="4.1.3. Detached State">Section 4.1.3, “ |
| Detached State |
| ”</a> for details on how to declare a |
| detached state field. |
| </p><pre class="programlisting"> |
| import org.apache.openjpa.persistence.*; |
| |
| @Entity |
| public class Magazine |
| implements Serializable { |
| |
| private String name; |
| @DetachedState private Object state; |
| ... |
| } |
| </pre></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_event"></a>2. |
| Remote Event Notification Framework |
| </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#ref_guide_event_conf">2.1. |
| Remote Commit Provider Configuration |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_event_conf_jms">2.1.1. |
| JMS |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_event_conf_tcp">2.1.2. |
| TCP |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_event_conf_common">2.1.3. |
| Common Properties |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#ref_guide_event_customization">2.2. |
| Customization |
| </a></span></dt></dl></div><a class="indexterm" name="d0e30847"></a><a class="indexterm" name="d0e30852"></a><p> |
| <a class="indexterm" name="d0e30861"></a> |
| <a class="indexterm" name="d0e30869"></a> |
| The remote event notification framework allows a subset of the information |
| available through OpenJPA's transaction events (see |
| <a href="#ref_guide_runtime_pm_event" title="7. Transaction Events">Section 7, “ |
| Transaction Events |
| ”</a>) to be broadcast to remote |
| listeners. OpenJPA's <a href="#ref_guide_cache" title="1. Data Cache">data cache</a>, for |
| example, uses remote events to remain synchronized when deployed in multiple |
| JVMs. |
| </p><p> |
| To enable remote events, you must configure the <code class="classname"> EntityManagerFactory |
| </code> to use a <code class="literal">RemoteCommitProvider</code> (see below). |
| </p><p> |
| When a <code class="literal">RemoteCommitProvider</code> is properly configured, you can |
| register |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/event/RemoteCommitListener.html" target="_top"> |
| <code class="classname">RemoteCommitListener</code></a>s that will be alerted with |
| a list of modified object ids whenever a transaction on a remote machine |
| successfully commits. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_event_conf"></a>2.1. |
| Remote Commit Provider Configuration |
| </h3></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#ref_guide_event_conf_jms">2.1.1. |
| JMS |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_event_conf_tcp">2.1.2. |
| TCP |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_event_conf_common">2.1.3. |
| Common Properties |
| </a></span></dt></dl></div><a class="indexterm" name="d0e30903"></a><p> |
| OpenJPA includes built in remote commit providers for JMS and TCP communication. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="ref_guide_event_conf_jms"></a>2.1.1. |
| JMS |
| </h4></div></div></div><a class="indexterm" name="d0e30915"></a><p> |
| The JMS remote commit provider can be configured by setting the |
| <a href="#openjpa.RemoteCommitProvider" title="5.53. openjpa.RemoteCommitProvider"><code class="literal"> |
| openjpa.RemoteCommitProvider</code></a> property to contain the |
| appropriate configuration properties. The JMS provider understands the following |
| properties: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">Topic</code>: The topic that the remote commit provider should |
| publish notifications to and subscribe to for notifications sent from other |
| JVMs. Defaults to <code class="literal">topic/OpenJPACommitProviderTopic</code> |
| </p></li><li><p> |
| <code class="literal">TopicConnectionFactory</code>: The JNDI name of a <code class="classname"> |
| javax.jms.TopicConnectionFactory</code> factory to use for finding topics. |
| Defaults to <code class="literal"> java:/ConnectionFactory</code>. This setting may vary |
| depending on the application server in use; consult the application server's |
| documentation for details of the default JNDI name for the <code class="classname"> |
| javax.jms.TopicConnectionFactory</code> instance. For example, under |
| Weblogic, the JNDI name for the TopicConnectionFactory is <code class="literal"> |
| javax.jms.TopicConnectionFactory</code>. |
| </p></li><li><p> |
| <code class="literal">ExceptionReconnectAttempts</code>: The number of times to attempt |
| to reconnect if the JMS system notifies OpenJPA of a serious connection error. |
| Defaults to 0, meaning OpenJPA will log the error but otherwise ignore it, |
| hoping the connection is still valid. |
| </p></li><li><p> |
| <code class="literal">*</code>: All other configuration properties will be interpreted as |
| settings to pass to the JNDI <code class="classname">InitialContext</code> on |
| construction. For example, you might set the <code class="literal">java.naming.provider.url |
| </code> property to the URL of the context provider. |
| </p></li></ul></div><p> |
| To configure a factory to use the JMS provider, your properties might look like |
| the following: |
| </p><div class="example"><a name="ref_guide_event_conf_jmsex"></a><p class="title"><b>Example 11.2. |
| JMS Remote Commit Provider Configuration |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| <property name="openjpa.RemoteCommitProvider" |
| value="jms(ExceptionReconnectAttempts=5)"/> |
| </pre></div></div><br class="example-break"><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| Because of the nature of JMS, it is important that you invoke <code class="methodname"> |
| EntityManagerFactory.close</code> when finished with a factory. If you do |
| not do so, a daemon thread will stay up in the JVM, preventing the JVM from |
| exiting. |
| </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="ref_guide_event_conf_tcp"></a>2.1.2. |
| TCP |
| </h4></div></div></div><a class="indexterm" name="d0e30990"></a><p> |
| The TCP remote commit provider has several options that are defined as host |
| specifications containing a host name or IP address and an optional port |
| separated by a colon. For example, the host specification <code class="literal"> |
| saturn.bea.com:1234</code> represents an <code class="classname">InetAddress</code> |
| retrieved by invoking <code class="methodname">InetAddress.getByName("saturn.bea.com") |
| </code> and a port of 1234. |
| </p><p> |
| <a class="indexterm" name="d0e31010"></a> |
| The TCP provider can be configured by setting the <code class="literal"> |
| openjpa.RemoteCommitProvider</code> plugin property to contain the |
| appropriate configuration settings. The TCP provider understands the following |
| properties: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">Port</code>: The TCP port that the provider should listen on for |
| commit notifications. Defaults to 5636. |
| </p></li><li><p> |
| <code class="literal">Addresses</code>: A semicolon-separated list of IP addresses to |
| which notifications should be sent. No default value. |
| </p></li><li><p> |
| <code class="literal">NumBroadcastThreads</code>: The number of threads to create for the |
| purpose of transmitting events to peers. You sould increase this value as the |
| number of concurrent transactions increases. The maximum number of concurrent |
| transactions is a function of the size of the connection pool. See the |
| <code class="literal">MaxActive</code> property of <code class="literal"> |
| openjpa.ConnectionFactoryProperties</code> in |
| <a href="#ref_guide_dbsetup_builtin" title="1. Using the OpenJPA DataSource">Section 1, “ |
| Using the OpenJPA DataSource |
| ”</a>. Setting a value of 0 will |
| result in behavior where the thread invoking <code class="methodname">commit</code> |
| will perform the broadcast directly. Defaults to 2. |
| </p></li><li><p> |
| <code class="literal">RecoveryTimeMillis</code>: Amount of time to wait in milliseconds |
| before attempting to reconnect to a peer of the cluster when connectivity to the |
| peer is lost. Defaults to 15000. |
| </p></li><li><p> |
| <code class="literal">MaxIdle</code>: The number of TCP sockets (channels) to keep open |
| to each peer in the cluster for the transmission of events. Defaults to 2. |
| </p></li><li><p> |
| <code class="literal">MaxActive</code>: The maximum allowed number of TCP sockets |
| (channels) to open simultaneously between each peer in the cluster. Defaults to |
| 2. |
| </p></li></ul></div><p> |
| To configure a factory to use the TCP provider, your properties might look like |
| the following: |
| </p><div class="example"><a name="ref_guide_event_conf_tcpex"></a><p class="title"><b>Example 11.3. |
| TCP Remote Commit Provider Configuration |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| <property name="openjpa.RemoteCommitProvider" |
| value="tcp(Addresses=10.0.1.10;10.0.1.11;10.0.1.12;10.0.1.13)"/> |
| </pre></div></div><br class="example-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="ref_guide_event_conf_common"></a>2.1.3. |
| Common Properties |
| </h4></div></div></div><a class="indexterm" name="d0e31075"></a><p> |
| In addition to the provider-specific configuration options above, all providers |
| accept the following plugin properties: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">TransmitPersistedObjectIds</code>: Whether remote commit events |
| will include the object ids of instances persisted in the transaction. By |
| default only the class names of types persisted in the transaction are sent. |
| This results in smaller events and more efficient network utilization. If you |
| have registered your own remote commit listeners, however, you may require the |
| persisted object ids as well. |
| </p></li></ul></div><p> |
| To transmit persisted object ids in our remote commit events using the JMS |
| provider, we modify the previous example as follows: |
| </p><div class="example"><a name="ref_guide_event_conf_jms2ex"></a><p class="title"><b>Example 11.4. |
| JMS Remote Commit Provider transmitting Persisted Object Ids |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| <property name="openjpa.RemoteCommitProvider" |
| value="jms(ExceptionReconnectAttempts=5, TransmitPersistedObjectIds=true)"/> |
| </pre></div></div><br class="example-break"></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_event_customization"></a>2.2. |
| Customization |
| </h3></div></div></div><a class="indexterm" name="d0e31101"></a><p> |
| You can develop additional mechanisms for remote event notification be by |
| creating an implementation of the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/event/RemoteCommitProvider.html" target="_top"> |
| <code class="classname"> RemoteCommitProvider</code></a> interface, possibly by |
| extending the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/event/AbstractRemoteCommitProvider.html" target="_top"> |
| <code class="classname">AbstractRemoteCommitProvider</code></a> abstract class.. |
| </p></div></div></div><div class="chapter" lang="en" id="ref_guide_slice"><div class="titlepage"><div><div><h2 class="title"><a name="ref_guide_slice"></a>Chapter 12. |
| Distributed Persistence |
| </h2></div><div><h2 class="title"><a name="ref_guide_slice"></a>Chapter 12. |
| Distributed Persistence |
| </h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#slice_overview">1. Overview</a></span></dt><dt><span class="section"><a href="#Features and Limitations">2. Salient Features</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e31151">2.1. Transparency</a></span></dt><dt><span class="section"><a href="#d0e31159">2.2. Custom Distribution Policy</a></span></dt><dt><span class="section"><a href="#d0e31188">2.3. Heterogeneous Database</a></span></dt><dt><span class="section"><a href="#d0e31193">2.4. Parallel Execution</a></span></dt><dt><span class="section"><a href="#d0e31198">2.5. Distributed Query</a></span></dt><dt><span class="section"><a href="#d0e31232">2.6. Targeted Query</a></span></dt><dt><span class="section"><a href="#d0e31249">2.7. Distributed Transaction</a></span></dt><dt><span class="section"><a href="#collocation_constraint">2.8. Collocation Constraint</a></span></dt></dl></dd><dt><span class="section"><a href="#slice_configuration">3. Usage</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e31286">3.1. How to activate Slice Runtime?</a></span></dt><dt><span class="section"><a href="#d0e31297">3.2. How to configure each database slice?</a></span></dt><dt><span class="section"><a href="#distribution_policy">3.3. Implement DistributionPolicy interface</a></span></dt><dt><span class="section"><a href="#d0e31411">3.4. </a></span></dt></dl></dd><dt><span class="section"><a href="#d0e31422">4. Global Properties</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e31425">4.1. openjpa.slice.DistributionPolicy</a></span></dt><dt><span class="section"><a href="#d0e31439">4.2. openjpa.slice.Lenient</a></span></dt><dt><span class="section"><a href="#d0e31455">4.3. openjpa.slice.Master</a></span></dt><dt><span class="section"><a href="#d0e31467">4.4. openjpa.slice.Names</a></span></dt><dt><span class="section"><a href="#d0e31482">4.5. openjpa.slice.ThreadingPolicy</a></span></dt><dt><span class="section"><a href="#d0e31553">4.6. openjpa.slice.TransactionPolicy</a></span></dt></dl></dd><dt><span class="section"><a href="#d0e31599">5. Per-Slice Properties</a></span></dt></dl></div><p> |
| The standard JPA runtime environment works with a <span class="emphasis"><em>single</em></span> |
| database instance. OpenJPA can be extended via plug-in to work with |
| multiple databases within the same transaction without any change to the |
| existing application. This capability of OpenJPA for distributed |
| database environment is called <span class="emphasis"><em>Slice</em></span> and is explained in |
| the following sections. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="slice_overview"></a>1. Overview</h2></div></div></div><p> |
| Enterprise applications are increasingly deployed for distributed database |
| environments. The reasons for distributed, often horizontally-partitioned |
| database environment can be to counter massive data growth, to |
| support multiple external clients on a hosted platform or many other |
| practical scenarios that can benefit from data partitioning. |
| </p><p> |
| Any JPA-based user application has to address serious technical and conceptual |
| challenges to directly interact with a set of physical databases |
| within a single transaction. |
| Slice encapsulates the complexity of distributed database environment |
| via the abstraction of <span class="emphasis"><em>virtual</em></span> database which internally |
| manages multiple physical databases. We refer each physical database instance |
| as <span class="emphasis"><em>slice</em></span>. |
| <span class="emphasis"><em>Virtualization</em></span> of distributed databases |
| makes OpenJPA object management kernel and |
| the user application to work in the same way as in the case of a single physical |
| database. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="Features and Limitations"></a>2. Salient Features</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#d0e31151">2.1. Transparency</a></span></dt><dt><span class="section"><a href="#d0e31159">2.2. Custom Distribution Policy</a></span></dt><dt><span class="section"><a href="#d0e31188">2.3. Heterogeneous Database</a></span></dt><dt><span class="section"><a href="#d0e31193">2.4. Parallel Execution</a></span></dt><dt><span class="section"><a href="#d0e31198">2.5. Distributed Query</a></span></dt><dt><span class="section"><a href="#d0e31232">2.6. Targeted Query</a></span></dt><dt><span class="section"><a href="#d0e31249">2.7. Distributed Transaction</a></span></dt><dt><span class="section"><a href="#collocation_constraint">2.8. Collocation Constraint</a></span></dt></dl></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e31151"></a>2.1. Transparency</h3></div></div></div><p> |
| The existing application or the persistent domain model requires |
| <span class="emphasis"><em>no change</em></span> to upgrade from a single database |
| to a distributed database environment. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e31159"></a>2.2. Custom Distribution Policy</h3></div></div></div><p> |
| User application decides how the newly persistent instances be |
| distributed across the database slices. The data |
| distribution policy across the slices may be based on the attribute |
| of the data itself. For example, all Customer whose first name begins with |
| character 'A' to 'M' will be stored in one slice while names |
| beginning with 'N' to 'Z' will be stored in another slice. |
| </p><p> |
| This custom data distribution policy is specified by implementing |
| <code class="classname">org.apache.openjpa.slice.DistributionPolicy</code> |
| interface by the user application. |
| </p><p> |
| Slice tracks the original database for existing instances. When |
| an application issues a query, the resultant instances can be loaded |
| from different slices. This tracking is important as subsequent |
| update to any of these instances is committed to the appropriate |
| original database slice. |
| </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| You can find the original slice of an instance <code class="code">pc</code> by |
| the static utility method |
| <code class="methodname">SlicePersistence.getSlice(pc)</code>. |
| This method returns the slice identifier string associated with the |
| given <span class="emphasis"><em>managed</em></span> instance. If the instance is not |
| being managed then the method return null because any unmanaged or |
| detached instance is not associated with any slice. |
| </p></div><p> |
| </p><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3>Currently, there is no provision for migrating an |
| existing instance from one slice to another. |
| </div><p> |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e31188"></a>2.3. Heterogeneous Database</h3></div></div></div><p> |
| Each slice can be configured independently with its own JDBC |
| driver and other connection parameters. Hence the target database |
| environment can constitute of heterogeneous databases. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e31193"></a>2.4. Parallel Execution</h3></div></div></div><p> |
| All database operations such as query, commit or flush operates |
| in parallel across the database slices. The execution threading |
| policy is configurable. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e31198"></a>2.5. Distributed Query</h3></div></div></div><p> |
| The queries are executed across all slices and the results are |
| merged into a single list. The query result that includes |
| <code class="code">ORDER BY</code> clause are sorted correctly by merging |
| results from each individual slice. |
| </p> |
| The queries that specify an aggregate projection such as |
| <code class="code">COUNT()</code>, <code class="code">MAX()</code>, <code class="code">MIN()</code> |
| and <code class="code">SUM()</code> |
| are correctly evaluated <span class="emphasis"><em>only if</em></span> they |
| return a single result. |
| <p> |
| </p><p> |
| </p><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3> |
| The aggregate operation <code class="code">AVG()</code> is not supported. |
| </div><p> |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e31232"></a>2.6. Targeted Query</h3></div></div></div><p> |
| You can target the query only to a subset of slices rather than |
| all slices by setting a <span class="emphasis"><em>hint</em></span>. The hint key |
| <code class="code">openjpa.hint.slice.Target</code> is set on any query and |
| hint value is |
| comma-separated list of slice identifiers. The following |
| example shows how to target a query only to slice <code class="code">"One"</code> |
| |
| </p><pre class="programlisting"> |
| EntityManager em = ...; |
| em.getTransaction().begin(); |
| String hint = "openjpa.hint.slice.Target"; |
| Query query = em.createQuery("SELECT p FROM PObject").setHint(hint, "One"); |
| List result = query.getResultList(); |
| // verify that each instance is originaing from the given slice |
| for (Object pc : result) { |
| String sliceOrigin = SlicePersistence.getSlice(pc); |
| assertTrue ("One", sliceOrigin); |
| } |
| |
| </pre><p> |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e31249"></a>2.7. Distributed Transaction</h3></div></div></div><p> |
| The database slices participate in a global transaction provided |
| each slice is configured with a XA-compliant JDBC driver, even |
| when the persistence unit is configured for <code class="code">RESOURCE_LOCAL</code> |
| transaction. |
| </p><p> |
| </p><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3> |
| If any of the configured slices is not XA-compliant <span class="emphasis"><em>and</em></span> |
| the persistence unit is configured for <code class="code">RESOURCE_LOCAL</code> |
| transaction then each slice is committed without any two-phase |
| commit protocol. If commit on any slice fails, then atomic nature of |
| the transaction is not ensured. |
| </div><p> |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="collocation_constraint"></a>2.8. Collocation Constraint</h3></div></div></div><p> |
| No relationship can exist across database slices. In O-R mapping parlance, |
| this condition translates to the limitation that the closure of an object graph must be |
| <span class="emphasis"><em>collocated</em></span> in the same database. |
| For example, consider a domain model where Person relates to Adress. |
| Person X refers to Address A while Person Y refers to Address B. |
| Collocation Constraint means that <span class="emphasis"><em>both</em></span> X and A |
| must be stored in the same |
| database slice. Similarly Y and B must be stored in a single slice. |
| </p><p> |
| Slice, however, helps to maintain collocation constraint automatically. |
| The instances in the closure set of any newly persistent instance |
| reachable via cascaded relationship is stored in the same slice. |
| The user-defined distribution policy requires to supply the slice |
| for the root instance only. |
| </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="slice_configuration"></a>3. Usage</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#d0e31286">3.1. How to activate Slice Runtime?</a></span></dt><dt><span class="section"><a href="#d0e31297">3.2. How to configure each database slice?</a></span></dt><dt><span class="section"><a href="#distribution_policy">3.3. Implement DistributionPolicy interface</a></span></dt><dt><span class="section"><a href="#d0e31411">3.4. </a></span></dt></dl></div><p> |
| Slice is activated via the following property settings: |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e31286"></a>3.1. How to activate Slice Runtime?</h3></div></div></div><p> |
| The basic configuration property is |
| </p><pre class="programlisting"> |
| <property name="openjpa.BrokerFactory" value="slice"/> |
| </pre><p> |
| This critical configuration activates a specialized factory class aliased |
| as <code class="code">slice</code> to create object management kernel that |
| can work against multiple databases. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e31297"></a>3.2. How to configure each database slice?</h3></div></div></div><p> |
| Each database slice is identified by a logical name unique within a |
| persistent unit. The list of the slices is specified by |
| <code class="code">openjpa.slice.Names</code> property. |
| For example, specify three slices named <code class="code">"One"</code>, |
| <code class="code">"Two"</code> and <code class="code">"Three"</code> as follows: |
| </p><pre class="programlisting"> |
| <property name="openjpa.slice.Names" value="One, Two, Three"/> |
| </pre><p> |
| </p><p> |
| This property is not mandatory. If this property is not specified then |
| the configuration is scanned for logical slice names. Any property |
| <code class="code">"abc"</code> of the form <code class="code">openjpa.slice.XYZ.abc</code> will |
| register a slice with logical |
| name <code class="code">"XYZ"</code>. |
| </p><p> |
| The order of the names is significant when no <code class="code">openjpa.slice.Master</code> |
| property is not specified. Then the persistence unit is scanned to find |
| all configured slice names and they are ordered alphabetically. |
| </p><p> |
| Each database slice properties can be configured independently. |
| For example, the |
| following configuration will register two slices with logical name |
| <code class="code">One</code> and <code class="code">Two</code>. |
| </p><pre class="programlisting"> |
| <property name="openjpa.slice.One.ConnectionURL" value="jdbc:mysql:localhost//slice1"/> |
| <property name="openjpa.slice.Two.ConnectionURL" value="jdbc:mysql:localhost//slice2"/> |
| </pre><p> |
| </p><p> |
| Any OpenJPA specific property can be configured per slice basis. |
| For example, the following configuration will use two different JDBC |
| drivers for slice <code class="code">One</code> and <code class="code">Two</code>. |
| </p><pre class="programlisting"> |
| <property name="openjpa.slice.One.ConnectionDriverName" value="com.mysql.jdbc.Driver"/> |
| <property name="openjpa.slice.Two.ConnectionDriverName" value="com.mysql.jdbc.jdbc2.optional.MysqlXADataSource"/> |
| </pre><p> |
| </p><p> |
| Any property if unspecified for a particular slice will be defaulted by |
| corresponding OpenJPA property. For example, consider following three slices |
| </p><pre class="programlisting"> |
| <property name="openjpa.slice.One.ConnectionURL" value="jdbc:mysql:localhost//slice1"/> |
| <property name="openjpa.slice.Two.ConnectionURL" value="jdbc:mysql:localhost//slice2"/> |
| <property name="openjpa.slice.Three.ConnectionURL" value="jdbc:oracle:localhost//slice3"/> |
| |
| <property name="openjpa.ConnectionDriverName" value="com.mysql.jdbc.Driver"/> |
| <property name="openjpa.slice.Three.ConnectionDriverName" value="oracle.jdbc.Driver"/> |
| </pre><p> |
| In this example, <code class="code">Three</code> will use slice-specific |
| <code class="code">oracle.jdbc.Driver</code> driver while slice |
| <code class="code">One</code> and <code class="code">Two</code> will use |
| the driver <code class="code">com.mysql.jdbc.Driver</code> as |
| specified by <code class="code">openjpa.ConnectionDriverName</code> |
| property value. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="distribution_policy"></a>3.3. Implement DistributionPolicy interface</h3></div></div></div><p> |
| Slice needs to determine which slice will persist a new instance. |
| The application can only decide this policy (for example, |
| all PurchaseOrders before April 30 goes to slice <code class="code">One</code>, |
| all the rest goes to slice <code class="code">Two</code>). This is why |
| the application has to implement |
| <code class="code">org.apache.openjpa.slice.DistributionPolicy</code> and |
| specify the implementation class in configuration |
| </p><pre class="programlisting"> |
| <property name="openjpa.slice.DistributionPolicy" value="com.acme.foo.MyOptimialDistributionPolicy"/> |
| </pre><p> |
| </p><p> |
| The interface <code class="code">org.apache.openjpa.slice.DistributionPolicy</code> |
| is simple with a single method. The complete listing of the |
| documented interface follows: |
| </p><pre class="programlisting"> |
| |
| public interface DistributionPolicy { |
| /** |
| * Gets the name of the slice where a given instance will be stored. |
| * |
| * @param pc The newly persistent or to-be-merged object. |
| * @param slices name of the configured slices. |
| * @param context persistence context managing the given instance. |
| * |
| * @return identifier of the slice. This name must match one of the |
| * configured slice names. |
| * @see DistributedConfiguration#getSliceNames() |
| */ |
| String distribute(Object pc, List<String> slices, Object context); |
| } |
| |
| </pre><p> |
| </p><p> |
| While implementing a distribution policy the most important thing to |
| remember is <a href="#collocation_constraint" title="2.8. Collocation Constraint">collocation constraint</a>. |
| Because Slice can not establish or query any cross-database relationship, all the |
| related instances must be stored in the same database slice. |
| |
| Slice can determine the closure of a root object by traversal of |
| cascaded relationships. Hence user-defined policy has to only decide the |
| database for the root instance that is the explicit argument to |
| <code class="methodname">EntityManager.persist()</code> call. |
| Slice will ensure that all other related instances that gets persisted by cascade |
| is assigned to the same database slice as that of the root instance. |
| However, the user-defined distribution policy must return the |
| same slice identifier for the instances that are logically related but |
| not cascaded for persist. |
| </p></div><div class="section" lang="en"><div class="titlepage"></div></div></div><p> |
| The properties to configure Slice can be classified in two broad groups. |
| The <span class="emphasis"><em>global</em></span> properties apply to all the slices, for example, |
| the thread pool used to execute the queries in parallel or the transaction |
| manager used to coordinate transaction across multiple slices. |
| The <span class="emphasis"><em>per-slice</em></span> properties apply to individual slice, for example, |
| the JDBC connection URL of a slice. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e31422"></a>4. Global Properties</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#d0e31425">4.1. openjpa.slice.DistributionPolicy</a></span></dt><dt><span class="section"><a href="#d0e31439">4.2. openjpa.slice.Lenient</a></span></dt><dt><span class="section"><a href="#d0e31455">4.3. openjpa.slice.Master</a></span></dt><dt><span class="section"><a href="#d0e31467">4.4. openjpa.slice.Names</a></span></dt><dt><span class="section"><a href="#d0e31482">4.5. openjpa.slice.ThreadingPolicy</a></span></dt><dt><span class="section"><a href="#d0e31553">4.6. openjpa.slice.TransactionPolicy</a></span></dt></dl></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e31425"></a>4.1. openjpa.slice.DistributionPolicy</h3></div></div></div><p> |
| This <span class="emphasis"><em>mandatory</em></span> plug-in property determines how newly |
| persistent instances are distributed across individual slices. |
| The value of this property is a fully-qualified class name that implements |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/slice/DistributionPolicy.html" target="_top"> |
| <code class="classname">org.apache.openjpa.slice.DistributionPolicy</code> |
| </a> interface. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e31439"></a>4.2. openjpa.slice.Lenient</h3></div></div></div><p> |
| This boolean plug-in property controls the behavior when one or more slice |
| can not be connected or unavailable for some other reasons. |
| If <code class="code">true</code>, the unreachable slices are ignored. If |
| <code class="code">false</code> then any unreachable slice will raise an exception |
| during startup. |
| </p><p> |
| By default this value is set to <code class="code">false</code> i.e. all configured |
| slices must be available. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e31455"></a>4.3. openjpa.slice.Master</h3></div></div></div><p> |
| This plug-in property can be used to identify the name of the master slice. |
| Master slice is used when a primary key is to be generated from a database sequence. |
| </p><p> |
| By default the master slice is the first slice in the list of configured slice names. |
| </p><p> |
| </p><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3> |
| Currently, there is no provision to use sequence from |
| multiple database slices. |
| </div><p> |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e31467"></a>4.4. openjpa.slice.Names</h3></div></div></div><p> |
| This plug-in property can be used to register the logical slice names. |
| The value of this property is comma-separated list of slice names. |
| The ordering of the names in this list is |
| <span class="emphasis"><em>significant</em></span> because |
| <a href="#distribution_policy" title="3.3. Implement DistributionPolicy interface">DistributionPolicy</a> receives |
| the input argument of the slice names in the same order. |
| </p><p> |
| If logical slice names are not registered explicitly via this property, |
| then all logical slice names available in the persistence unit are |
| registered. The ordering of the slice names in this case is alphabetical. |
| </p><p> |
| If logical slice names are registered explicitly via this property, then |
| any logical slice that is available in the persistence unit but excluded |
| from this list is ignored. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e31482"></a>4.5. openjpa.slice.ThreadingPolicy</h3></div></div></div><p> |
| This plug-in property determines the nature of thread pool being used |
| for database operations such as query or flush on individual slices. |
| The value of the property is a |
| fully-qualified class name that implements |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/concurrent/ExecutorService.html" target="_top"> |
| <code class="classname">java.util.concurrent.ExecutorService</code> |
| </a> interface. |
| Two pre-defined pools can be chosen via their aliases namely |
| <code class="code">fixed</code> or <code class="code">cached</code>. |
| </p><p> |
| The pre-defined alias <code class="code">cached</code> activates a |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/concurrent/Executors.html#newCachedThreadPool()" target="_top">cached thread pool</a>. |
| A cached thread pool creates new threads as needed, but will reuse |
| previously constructed threads when they are available. This pool |
| is suitable in scenarios that execute many short-lived asynchronous tasks. |
| The way Slice uses the thread pool to execute database operations is |
| akin to such scenario and hence <code class="code">cached</code> is the default |
| value for this plug-in property. |
| </p><p> |
| The <code class="code">fixed</code> alias activates a |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/concurrent/Executors.html#newFixedThreadPool(int)" target="_top">fixed thread pool</a>. |
| The fixed thread pool can be further parameterized with |
| <code class="code">CorePoolSize</code>, <code class="code">MaximumPoolSize</code>, |
| <code class="code">KeepAliveTime</code> and <code class="code">RejectedExecutionHandler</code>. |
| The meaning of these parameters are described in |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/concurrent/ThreadPoolExecutor.html" target="_top">JavaDoc</a>. |
| The users can exercise finer control on thread pool behavior via these |
| parameters. |
| By default, the core pool size is <code class="code">10</code>, maximum pool size is |
| also <code class="code">10</code>, keep alive time is <code class="code">60</code> seconds and |
| rejected execution is |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/concurrent/ThreadPoolExecutor.AbortPolicy.html" target="_top">aborted</a>. |
| </p><p> |
| Both of the pre-defined aliases can be parameterized with a fully-qualified |
| class name that implements |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/concurrent/ThreadFactory.html" target="_top"> |
| <code class="classname">java.util.concurrent.ThreadFactory</code> |
| </a> interface. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e31553"></a>4.6. openjpa.slice.TransactionPolicy</h3></div></div></div><p> |
| This plug-in property determines the policy for transaction commit |
| across multiple slices. The value of this property is a fully-qualified |
| class name that implements |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="http://java.sun.com/j2ee/sdk_1.3/techdocs/api/javax/transaction/TransactionManager.html" target="_top"> |
| <code class="classname">javax.transaction.TransactionManager</code> |
| </a> interface. |
| </p><p> |
| Three pre-defined policies can be chosen |
| by their aliases namely <code class="code">default</code>, |
| <code class="code">xa</code> and <code class="code">jndi</code>. |
| </p><p> |
| The <code class="code">default</code> policy employs |
| a Transaction Manager that commits or rolls back transaction on individual |
| slices <span class="emphasis"><em>without</em></span> a two-phase commit protocol. |
| It does <span class="emphasis"><em>not</em></span> |
| guarantee atomic nature of transaction across all the slices because if |
| one or more slice fails to commit, there is no way to rollback the transaction |
| on other slices that committed successfully. |
| </p><p> |
| The <code class="code">xa</code> policy employs a Transaction Manager that that commits |
| or rolls back transaction on individual |
| slices using a two-phase commit protocol. The prerequisite to use this scheme |
| is, of course, that all the slices must be configured to use |
| XA-compliant JDBC driver. |
| </p><p> |
| The <code class="code">jndi</code> policy employs a Transaction Manager by looking up the |
| JNDI context. The prerequisite to use this transaction |
| manager is, of course, that all the slices must be configured to use |
| XA-compliant JDBC driver. |
| </p><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3>This JNDI based policy is not available currently.</div><p> |
| </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e31599"></a>5. Per-Slice Properties</h2></div></div></div><p> |
| Any OpenJPA property can be configured for each individual slice. The property name |
| is of the form <code class="code">openjpa.slice.[Logical slice name].[OpenJPA Property Name]</code>. |
| For example, <code class="code">openjpa.slice.One.ConnectionURL</code> where <code class="code">One</code> |
| is the logical slice name and <code class="code">ConnectionURL</code> is an OpenJPA property |
| name. |
| </p><p> |
| If a property is not configured for a specific slice, then the value for |
| the property equals to the corresponding <code class="code">openjpa.*</code> property. |
| </p></div></div><div class="chapter" lang="en" id="ref_guide_integration"><div class="titlepage"><div><div><h2 class="title"><a name="ref_guide_integration"></a>Chapter 13. |
| Third Party Integration |
| </h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#ref_guide_integration_ant">1. |
| Apache Ant |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#ref_guide_integration_conf">1.1. |
| Common Ant Configuration Options |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_integration_enhance">1.2. |
| Enhancer Ant Task |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_integration_appidtool">1.3. |
| Application Identity Tool Ant Task |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_integration_mappingtool">1.4. |
| Mapping Tool Ant Task |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_integration_revmappingtool">1.5. |
| Reverse Mapping Tool Ant Task |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_integration_schematool">1.6. |
| Schema Tool Ant Task |
| </a></span></dt></dl></dd></dl></div><p> |
| OpenJPA provides a number of mechanisms for integrating with third-party tools. |
| The following chapter will illustrate these integration features. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_integration_ant"></a>1. |
| Apache Ant |
| </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#ref_guide_integration_conf">1.1. |
| Common Ant Configuration Options |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_integration_enhance">1.2. |
| Enhancer Ant Task |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_integration_appidtool">1.3. |
| Application Identity Tool Ant Task |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_integration_mappingtool">1.4. |
| Mapping Tool Ant Task |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_integration_revmappingtool">1.5. |
| Reverse Mapping Tool Ant Task |
| </a></span></dt><dt><span class="section"><a href="#ref_guide_integration_schematool">1.6. |
| Schema Tool Ant Task |
| </a></span></dt></dl></div><a class="indexterm" name="d0e31630"></a><p> |
| Ant is a very popular tool for building Java projects. It is similar to the |
| <code class="literal">make</code> command, but is Java-centric and has more modern |
| features. Ant is open source, and can be downloaded from Apache's Ant web page |
| at <a xmlns:xlink="http://www.w3.org/1999/xlink" href="http://jakarta.apache.org/ant/" target="_top"> http://jakarta.apache.org/ant/ |
| </a>. Ant has become the de-facto standard build tool for Java, and many |
| commercial integrated development environments provide some support for using |
| ant build files. The remainder of this section assumes familiarity with writing |
| Ant <code class="filename">build.xml</code> files. |
| </p><p> |
| OpenJPA provides pre-built Ant task definitions for all bundled tools: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <a href="#ref_guide_integration_enhance" title="1.2. Enhancer Ant Task">Enhancer Task</a> |
| </p></li><li><p> |
| <a href="#ref_guide_integration_appidtool" title="1.3. Application Identity Tool Ant Task">Application Identity Tool Task |
| </a> |
| </p></li><li><p> |
| <a href="#ref_guide_integration_mappingtool" title="1.4. Mapping Tool Ant Task">Mapping Tool Task</a> |
| </p></li><li><p> |
| <a href="#ref_guide_integration_revmappingtool" title="1.5. Reverse Mapping Tool Ant Task">Reverse Mapping Tool Task |
| </a> |
| </p></li><li><p> |
| <a href="#ref_guide_integration_schematool" title="1.6. Schema Tool Ant Task">Schema Tool Task</a> |
| </p></li></ul></div><p> |
| The source code for all the ant tasks is provided with the distribution under |
| the <code class="filename">src</code> directory. This allows you to customize various |
| aspects of the ant tasks in order to better integrate into your development |
| environment. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_integration_conf"></a>1.1. |
| Common Ant Configuration Options |
| </h3></div></div></div><a class="indexterm" name="d0e31685"></a><p> |
| All OpenJPA tasks accept a nested <code class="literal">config</code> element, which |
| defines the configuration environment in which the specified task will run. The |
| attributes for the <code class="literal">config</code> tag are defined by the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/conf/JDBCConfiguration.html" target="_top"> |
| <code class="classname">JDBCConfiguration</code></a> bean methods. Note that |
| excluding the <code class="literal">config</code> element will cause the Ant task to use |
| the default system configuration mechanism, such as the configuration defined in |
| the <code class="filename">org.apache.openjpa.xml</code> file. |
| </p><p> |
| Following is an example of how to use the nested <code class="literal">config</code> tag |
| in a <code class="filename">build.xml</code> file: |
| </p><div class="example"><a name="ref_guide_integration_conf_config"></a><p class="title"><b>Example 13.1. |
| Using the <config> Ant Tag |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| <mappingtool> |
| <fileset dir="${basedir}"> |
| <include name="**/model/*.java" /> |
| </fileset> |
| <config connectionUserName="scott" connectionPassword="tiger" |
| connectionURL="jdbc:oracle:thin:@saturn:1521:solarsid" |
| connectionDriverName="oracle.jdbc.driver.OracleDriver" /> |
| </mappingtool> |
| </pre></div></div><br class="example-break"><p> |
| It is also possible to specify a <code class="literal">properties</code> or <code class="literal"> |
| propertiesFile</code> attribute on the <code class="literal">config</code> tag, which |
| will be used to locate a properties resource or file. The resource will be |
| loaded relative to the current CLASSPATH. |
| </p><div class="example"><a name="ref_guide_integration_props"></a><p class="title"><b>Example 13.2. |
| Using the Properties Attribute of the <config> Tag |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| <mappingtool> |
| <fileset dir="${basedir}"> |
| <include name="**/model/*.java"/> |
| </fileset> |
| <config properties="openjpa-dev.xml"/> |
| </mappingtool> |
| </pre></div></div><br class="example-break"><div class="example"><a name="ref_guide_integration_propsfile"></a><p class="title"><b>Example 13.3. |
| Using the PropertiesFile Attribute of the <config> Tag |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| <mappingtool> |
| <fileset dir="${basedir}"> |
| <include name="**/model/*.java"/> |
| </fileset> |
| <config propertiesFile="../conf/openjpa-dev.xml"/> |
| </mappingtool> |
| </pre></div></div><br class="example-break"><p> |
| Tasks also accept a nested <code class="literal">classpath</code> element, which you can |
| use in place of the default classpath. The <code class="literal">classpath</code> argument |
| behaves the same as it does for Ant's standard <code class="literal">javac</code> element. |
| It is sometimes the case that projects are compiled to a separate directory than |
| the source tree. If the target path for compiled classes is not included in the |
| project's classpath, then a <code class="literal">classpath</code> element that includes |
| the target class directory needs to be included so the enhancer and mapping tool |
| can locate the relevant classes. |
| </p><p> |
| Following is an example of using a <code class="literal">classpath</code> tag: |
| </p><div class="example"><a name="ref_guide_integration_conf_classpath"></a><p class="title"><b>Example 13.4. |
| Using the <classpath> Ant Tag |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| <openjpac> |
| <fileset dir="${basedir}/source"> |
| <include name="**/model/*.java" /> |
| </fileset> |
| <classpath> |
| <pathelement location="${basedir}/classes"/> |
| <pathelement location="${basedir}/source"/> |
| <pathelement path="${java.class.path}"/> |
| </classpath> |
| </openjpac> |
| </pre></div></div><br class="example-break"><p> |
| Finally, tasks that invoke code-generation tools like the application identity |
| tool and reverse mapping tool accept a nested <code class="literal">codeformat</code> |
| element. See the code formatting documentation in |
| <a href="#ref_guide_conf_devtools_format" title="3.1. Code Formatting">Section 3.1, “ |
| Code Formatting |
| ”</a> for a list of code |
| formatting attributes. |
| </p><div class="example"><a name="ref_guide_integration_conf_codeformat"></a><p class="title"><b>Example 13.5. |
| Using the <codeformat> Ant Tag |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| <reversemappingtool package="com.xyz.jdo" directory="${basedir}/src"> |
| <codeformat tabSpaces="4" spaceBeforeParen="true" braceOnSameLine="false"/> |
| </reversemappingtool> |
| </pre></div></div><br class="example-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_integration_enhance"></a>1.2. |
| Enhancer Ant Task |
| </h3></div></div></div><a class="indexterm" name="d0e31782"></a><a class="indexterm" name="d0e31787"></a><p> |
| The enhancer task allows you to invoke the OpenJPA enhancer directly from within |
| the Ant build process. The task's parameters correspond exactly to the long |
| versions of the command-line arguments to the |
| <a href="#ref_guide_pc_enhance" title="2. Enhancement"><code class="classname"> |
| org.apache.openjpa.enhance.PCEnhancer</code></a>. |
| </p><p> |
| The enhancer task accepts a nested <code class="literal">fileset</code> tag to specify the |
| files that should be processed. You can specify <code class="filename">.java</code> or |
| <code class="filename">.class</code> files. If you do not specify any files, the task |
| will run on the classes listed in your <code class="filename">persistence.xml</code> or |
| <a href="#openjpa.MetaDataFactory" title="5.42. openjpa.MetaDataFactory"><code class="literal"> |
| openjpa.MetaDataFactory</code></a> property. |
| </p><p> |
| Following is an example of using the enhancer task in a <code class="filename">build.xml |
| </code> file: |
| </p><div class="example"><a name="ref_guide_integration_enhance_task"></a><p class="title"><b>Example 13.6. |
| Invoking the Enhancer from Ant |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| <target name="enhance"> |
| <!-- define the openjpac task; this can be done at the top of the --> |
| <!-- build.xml file, so it will be available for all targets --> |
| <taskdef name="openjpac" classname="org.apache.openjpa.ant.PCEnhancerTask"/> |
| |
| <!-- invoke enhancer on all .java files below the model directory --> |
| <openjpac> |
| <fileset dir="."> |
| <include name="**/model/*.java" /> |
| </fileset> |
| </openjpac> |
| </target> |
| </pre></div></div><br class="example-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_integration_appidtool"></a>1.3. |
| Application Identity Tool Ant Task |
| </h3></div></div></div><a class="indexterm" name="d0e31829"></a><a class="indexterm" name="d0e31834"></a><p> |
| The application identity tool task allows you to invoke the application identity |
| tool directly from within the Ant build process. The task's parameters |
| correspond exactly to the long versions of the command-line arguments to the |
| <a href="#ref_guide_pc_appid_appidtool" title="Example 5.7. Using the Application Identity Tool"><code class="classname"> |
| org.apache.openjpa.enhance.ApplicationIdTool</code></a>. |
| </p><p> |
| The application identity tool task accepts a nested <code class="literal">fileset</code> |
| tag to specify the files that should be processed. You can specify <code class="filename"> |
| .java</code> or <code class="filename">.class</code> files. If you do not specify any |
| files, the task will run on the classes listed in your <code class="filename">persistence.xml |
| </code> file or <a href="#openjpa.MetaDataFactory" title="5.42. openjpa.MetaDataFactory"><code class="literal"> |
| openjpa.MetaDataFactory</code></a> property. |
| </p><p> |
| Following is an example of using the application identity tool task in a |
| <code class="filename">build.xml</code> file: |
| </p><div class="example"><a name="ref_guide_integration_appidtool_task"></a><p class="title"><b>Example 13.7. |
| Invoking the Application Identity Tool from Ant |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| <target name="appids"> |
| <!-- define the appidtool task; this can be done at the top of --> |
| <!-- the build.xml file, so it will be available for all targets --> |
| <taskdef name="appidtool" classname="org.apache.openjpa.ant.ApplicationIdToolTask"/> |
| |
| <!-- invoke tool on all .jdo files below the current directory --> |
| <appidtool> |
| <fileset dir="."> |
| <include name="**/model/*.java" /> |
| </fileset> |
| <codeformat spaceBeforeParen="true" braceOnSameLine="false"/> |
| </appidtool> |
| </target> |
| </pre></div></div><br class="example-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_integration_mappingtool"></a>1.4. |
| Mapping Tool Ant Task |
| </h3></div></div></div><a class="indexterm" name="d0e31876"></a><a class="indexterm" name="d0e31881"></a><p> |
| The mapping tool task allows you to directly invoke the mapping tool from within |
| the Ant build process. It is useful for making sure that the database schema and |
| object-relational mapping data is always synchronized with your persistent class |
| definitions, without needing to remember to invoke the mapping tool manually. |
| The task's parameters correspond exactly to the long versions of the |
| command-line arguments to the <a href="#ref_guide_mapping_mappingtool" title="1. Forward Mapping"> |
| <code class="classname">org.apache.openjpa.jdbc.meta.MappingTool</code></a>. |
| </p><p> |
| The mapping tool task accepts a nested <code class="literal">fileset</code> tag to specify |
| the files that should be processed. You can specify <code class="filename">.java</code> |
| or <code class="filename">.class</code> files. If you do not specify any files, the task |
| will run on the classes listed in your <code class="filename">persistence.xml</code> file |
| or <a href="#openjpa.MetaDataFactory" title="5.42. openjpa.MetaDataFactory"><code class="literal"> |
| openjpa.MetaDataFactory</code></a> property. |
| </p><p> |
| Following is an example of a <code class="filename">build.xml</code> target that invokes |
| the mapping tool: |
| </p><div class="example"><a name="ref_guide_integration_mappingtool_task"></a><p class="title"><b>Example 13.8. |
| Invoking the Mapping Tool from Ant |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| <target name="refresh"> |
| <!-- define the mappingtool task; this can be done at the top of --> |
| <!-- the build.xml file, so it will be available for all targets --> |
| <taskdef name="mappingtool" classname="org.apache.openjpa.jdbc.ant.MappingToolTask"/> |
| |
| <!-- add the schema components for all .jdo files below the --> |
| <!-- current directory --> |
| <mappingtool action="buildSchema"> |
| <fileset dir="."> |
| <include name="**/*.jdo" /> |
| </fileset> |
| </mappingtool> |
| </target> |
| </pre></div></div><br class="example-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_integration_revmappingtool"></a>1.5. |
| Reverse Mapping Tool Ant Task |
| </h3></div></div></div><a class="indexterm" name="d0e31924"></a><a class="indexterm" name="d0e31929"></a><p> |
| The reverse mapping tool task allows you to directly invoke the reverse mapping |
| tool from within Ant. While many users will only run the reverse mapping process |
| once, others will make it part of their build process. The task's parameters |
| correspond exactly to the long versions of the command-line arguments to the |
| <a href="#ref_guide_pc_reverse_reversemappingtool" title="Example 7.9. Using the Reverse Mapping Tool"><code class="classname"> |
| org.apache.openjpa.jdbc.meta.ReverseMappingTool</code></a>. |
| </p><p> |
| Following is an example of a <code class="filename">build.xml</code> target that invokes |
| the reverse mapping tool: |
| </p><div class="example"><a name="ref_guide_integration_revmappingtool_task"></a><p class="title"><b>Example 13.9. |
| Invoking the Reverse Mapping Tool from Ant |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| <target name="reversemap"> |
| <!-- define the reversemappingtool task; this can be done at the top of --> |
| <!-- the build.xml file, so it will be available for all targets --> |
| <taskdef name="reversemappingtool" |
| classname="org.apache.openjpa.jdbc.ant.ReverseMappingToolTask"/> |
| |
| <!-- reverse map the entire database --> |
| <reversemappingtool package="com.xyz.model" directory="${basedir}/src" |
| customizerProperties="${basedir}/conf/reverse.properties"> |
| <codeformat tabSpaces="4" spaceBeforeParen="true" braceOnSameLine="false"/> |
| </reversemappingtool> |
| </target> |
| </pre></div></div><br class="example-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_integration_schematool"></a>1.6. |
| Schema Tool Ant Task |
| </h3></div></div></div><a class="indexterm" name="d0e31953"></a><a class="indexterm" name="d0e31958"></a><p> |
| The schema tool task allows you to directly invoke the schema tool from within |
| the Ant build process. The task's parameters correspond exactly to the long |
| versions of the command-line arguments to the |
| <a href="#ref_guide_schema_schematool" title="13. Schema Tool"><code class="classname"> |
| org.apache.openjpa.jdbc.schema.SchemaTool</code></a>. |
| </p><p> |
| Following is an example of a <code class="filename">build.xml</code> target that invokes |
| the schema tool: |
| </p><div class="example"><a name="ref_guide_integration_schematool_task"></a><p class="title"><b>Example 13.10. |
| Invoking the Schema Tool from Ant |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| <target name="schema"> |
| <!-- define the schematool task; this can be done at the top of --> |
| <!-- the build.xml file, so it will be available for all targets --> |
| <taskdef name="schematool" classname="org.apache.openjpa.jdbc.ant.SchemaToolTask"/> |
| |
| <!-- add the schema components for all .schema files below the --> |
| <!-- current directory --> |
| <schematool action="add"> |
| <fileset dir="."> |
| <include name="**/*.schema" /> |
| </fileset> |
| </schematool> |
| </target> |
| </pre></div></div><br class="example-break"></div></div></div><div class="chapter" lang="en" id="ref_guide_optimization"><div class="titlepage"><div><div><h2 class="title"><a name="ref_guide_optimization"></a>Chapter 14. |
| Optimization Guidelines |
| </h2></div></div></div><a class="indexterm" name="d0e31983"></a><p> |
| There are numerous techniques you can use in order to ensure that OpenJPA |
| operates in the fastest and most efficient manner. Following are some |
| guidelines. Each describes what impact it will have on performance and |
| scalability. Note that general guidelines regarding performance or scalability |
| issues are just that - guidelines. Depending on the particular characteristics |
| of your application, the optimal settings may be considerably different than |
| what is outlined below. |
| </p><p> |
| In the following table, each row is labeled with a list of italicized keywords. |
| These keywords identify what characteristics the row in question may improve |
| upon. Many of the rows are marked with one or both of the <span class="emphasis"><em>performance |
| </em></span> and <span class="emphasis"><em>scalability</em></span> labels. It is important to bear |
| in mind the differences between performance and scalability (for the most part, |
| we are referring to system-wide scalability, and not necessarily only |
| scalability within a single JVM). The performance-related hints will probably |
| improve the performance of your application for a given user load, whereas the |
| scalability-related hints will probably increase the total number of users that |
| your application can service. Sometimes, increasing performance will decrease |
| scalability, and vice versa. Typically, options that reduce the amount of work |
| done on the database server will improve scalability, whereas those that push |
| more work onto the server will have a negative impact on scalability. |
| </p><div class="table"><a name="d0e31996"></a><p class="title"><b>Table 14.1. |
| Optimization Guidelines |
| </b></p><div class="table-contents"><table summary="
 Optimization Guidelines
 " border="1"><colgroup><col align="left"><col align="left"></colgroup><tbody valign="top"><tr><td align="left"> |
| <span class="bold"><strong> |
| Plugin in a Connection Pool |
| </strong></span> |
| <p> |
| <span class="emphasis"><em>performance, scalability</em></span> |
| </p> |
| </td><td align="left"> |
| OpenJPA's built-in datasource does not perform connection pooling or |
| prepared statement caching. Plugging in a third-party pooling datasource may |
| drastically improve performance. |
| </td></tr><tr><td align="left"> |
| <span class="bold"><strong> |
| Optimize database indexes |
| </strong></span> |
| <p> |
| <span class="emphasis"><em>performance, scalability</em></span> |
| </p> |
| </td><td align="left"> |
| The default set of indexes created by OpenJPA's mapping tool may not always be |
| the most appropriate for your application. Manually setting indexes in your |
| mapping metadata or manually manipulating database indexes to include |
| frequently-queried fields (as well as dropping indexes on rarely-queried |
| fields) can yield significant performance benefits. |
| <p> |
| A database must do extra work on insert, update, and delete to maintain an |
| index. This extra work will benefit selects with WHERE clauses, which will |
| execute much faster when the terms in the WHERE clause are appropriately |
| indexed. So, for a read-mostly application, appropriate indexing will slow down |
| updates (which are rare) but greatly accelerate reads. This means that the |
| system as a whole will be faster, and also that the database will experience |
| less load, meaning that the system will be more scalable. |
| </p> |
| <p> |
| Bear in mind that over-indexing is a bad thing, both for scalability and |
| performance, especially for applications that perform lots of inserts, updates, |
| or deletes. |
| </p> |
| </td></tr><tr><td align="left"> |
| <span class="bold"><strong> |
| JVM optimizations |
| </strong></span> |
| <p> |
| <span class="emphasis"><em>performance, reliability</em></span> |
| </p> |
| </td><td align="left"> |
| Manipulating various parameters of the Java Virtual Machine (such as hotspot |
| compilation modes and the maximum memory) can result in performance |
| improvements. For more details about optimizing the JVM execution environment, |
| please see <a xmlns:xlink="http://www.w3.org/1999/xlink" href="http://java.sun.com/docs/hotspot/PerformanceFAQ.html" target="_top">http://java.sun.com/docs/hotspot/PerformanceFAQ.html</a>. |
| </td></tr><tr><td align="left"> |
| <span class="bold"><strong> |
| Use the data cache |
| </strong></span> |
| <p> |
| <span class="emphasis"><em>performance, scalability</em></span> |
| </p> |
| </td><td align="left"> |
| Using OpenJPA's <a href="#ref_guide_cache" title="1. Data Cache">data and query caching</a> |
| features can often result in a dramatic improvement in performance. |
| Additionally, these caches can significantly reduce the amount of load on |
| the database, increasing the scalability characteristics of your application. |
| </td></tr><tr><td align="left"> |
| <span class="bold"><strong> |
| Set <code class="literal">LargeTransaction</code> to true, |
| or set <code class="literal"> PopulateDataCache</code> to |
| false |
| </strong></span> |
| <p> |
| <span class="emphasis"><em>performance vs. scalability</em></span> |
| </p> |
| </td><td align="left"> |
| When using OpenJPA's <a href="#ref_guide_cache" title="1. Data Cache">data caching</a> |
| features in a transaction that will delete, modify, or create a very large |
| number of objects you can set <code class="literal">LargeTransaction</code> to true and |
| perform periodic flushes during your transaction to reduce its memory |
| requirements. See the Javadoc: |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/OpenJPAEntityManager.html" target="_top"> |
| OpenJPAEntityManager.setTrackChangesByType</a>. Note that transactions in |
| large mode have to more aggressively flush items from the data cache. |
| <p> |
| If your transaction will visit objects that you know are very unlikely to be |
| accessed by other transactions, for example an exhaustive report run only once a |
| month, you can turn off population of the data cache so that the transaction |
| doesn't fill the entire data cache with objects that won't be accessed again. |
| Again, see the Javadoc: |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/OpenJPAEntityManager.html" target="_top"> |
| OpenJPAEntityManager.setPopulateDataCache</a> |
| </p> |
| </td></tr><tr><td align="left"> |
| <span class="bold"><strong> |
| Run the OpenJPA enhancer on your persistent classes, |
| either at build-time or deploy-time. |
| </strong></span> |
| <p> |
| <span class="emphasis"><em>performance, scalability, memory footprint</em></span> |
| </p> |
| </td><td align="left"> |
| OpenJPA performs best when your persistent classes have been run through the |
| OpenJPA post-compilation bytecode enhancer. When dealing with enhanced classes, |
| OpenJPA can make a number of assumptions that reduce memory footprint and |
| accelerate persistent data access. When evaluating OpenJPA's performance, |
| build-time or deploy-time enhancement should be enabled. See |
| <a href="#ref_guide_pc_enhance" title="2. Enhancement">Section 2, “ |
| Enhancement |
| ”</a> for details. |
| </td></tr><tr><td align="left"> |
| <span class="bold"><strong> |
| Disable logging, performance tracking |
| </strong></span> |
| <p> |
| <span class="emphasis"><em>performance</em></span> |
| </p> |
| </td><td align="left"> |
| Developer options such as verbose logging and the JDBC performance tracker can |
| result in serious performance hits for your application. Before evaluating |
| OpenJPA's performance, these options should all be disabled. |
| </td></tr><tr><td align="left"> |
| <span class="bold"><strong> |
| Set <code class="literal">IgnoreChanges</code> to true, or |
| set <code class="literal">FlushBeforeQueries</code> to true |
| </strong></span> |
| <p> |
| <span class="emphasis"><em>performance vs. scalability</em></span> |
| </p> |
| </td><td align="left"> |
| When both the <a href="#openjpa.IgnoreChanges" title="5.33. openjpa.IgnoreChanges"><code class="literal"> |
| openjpa.IgnoreChanges</code></a> and |
| <a href="#openjpa.FlushBeforeQueries" title="5.32. openjpa.FlushBeforeQueries"><code class="literal">openjpa.FlushBeforeQueries |
| </code></a> properties are set to false, OpenJPA needs to consider |
| in-memory dirty instances during queries. This can sometimes result in OpenJPA |
| needing to evaluate the entire extent objects in order to return the correct |
| query results, which can have drastic performance consequences. If it is |
| appropriate for your application, configuring <code class="literal">FlushBeforeQueries |
| </code> to automatically flush before queries involving dirty objects will |
| ensure that this never happens. Setting <code class="literal">IgnoreChanges</code> to |
| false will result in a small performance hit even if <code class="literal">FlushBeforeQueries |
| </code> is true, as incremental flushing is not as efficient overall as |
| delaying all flushing to a single operation during commit. |
| <p> |
| Setting <code class="literal">IgnoreChanges</code> to <code class="literal">true</code> will help |
| performance, since dirty objects can be ignored for queries, meaning that |
| incremental flushing or client-side processing is not necessary. It will also |
| improve scalability, since overall database server usage is diminished. On the |
| other hand, setting <code class="literal">IgnoreChanges</code> to <code class="literal">false</code> |
| will have a negative impact on scalability, even when using automatic flushing |
| before queries, since more operations will be performed on the database server. |
| </p> |
| </td></tr><tr><td align="left"> |
| <span class="bold"><strong> |
| Configure <code class="literal">openjpa.ConnectionRetainMode |
| </code> appropriately |
| </strong></span> |
| <p> |
| <span class="emphasis"><em>performance vs. scalability</em></span> |
| </p> |
| </td><td align="left"> |
| The <a href="#openjpa.ConnectionRetainMode" title="5.24. openjpa.ConnectionRetainMode"><code class="literal">ConnectionRetainMode |
| </code></a> configuration option controls when OpenJPA will obtain a |
| connection, and how long it will hold that connection. The optimal settings for |
| this option will vary considerably depending on the particular behavior of |
| your application. You may even benefit from using different retain modes for |
| different parts of your application. |
| <p> |
| The default setting of <code class="literal">on-demand</code> minimizes the amount of time |
| that OpenJPA holds onto a datastore connection. This is generally the best |
| option from a scalability standpoind, as database resources are held for a |
| minimal amount of time. However, if you are not using connection pooling, or |
| if your <code class="classname">DataSource</code> is not efficient at managing its |
| pool, then this default value could cause undesirable pool contention. |
| </p> |
| </td></tr><tr><td align="left"> |
| <span class="bold"><strong> |
| Use flat inheritance |
| </strong></span> |
| <p> |
| <span class="emphasis"><em>performance, scalability vs. disk space</em></span> |
| </p> |
| </td><td align="left"> |
| Mapping inheritance hierarchies to a single database table is faster for most |
| operations than other strategies employing multiple tables. If it is |
| appropriate for your application, you should use this strategy whenever |
| possible. |
| <p> |
| However, this strategy will require more disk space on the database side. Disk |
| space is relatively inexpensive, but if your object model is particularly large, |
| it can become a factor. |
| </p> |
| </td></tr><tr><td align="left"> |
| <span class="bold"><strong> |
| High sequence increment |
| </strong></span> |
| <p> |
| <span class="emphasis"><em>performance, scalability</em></span> |
| </p> |
| </td><td align="left"> |
| For applications that perform large bulk inserts, the retrieval of sequence |
| numbers can be a bottleneck. Increasing sequence increments and using |
| table-based rather than native database sequences can reduce or eliminate |
| this bottleneck. In some cases, implementing your own sequence factory can |
| further optimize sequence number retrieval. |
| </td></tr><tr><td align="left"> |
| <span class="bold"><strong> |
| Use optimistic transactions |
| </strong></span> |
| <p> |
| <span class="emphasis"><em>performance, scalability</em></span> |
| </p> |
| </td><td align="left"> |
| Using datastore transactions translates into pessimistic database row locking, |
| which can be a performance hit (depending on the database). If appropriate for |
| your application, optimistic transactions are typically faster than datastore |
| transactions. |
| <p> |
| Optimistic transactions provide the same transactional guarantees as datastore |
| transactions, except that you must handle a potential optimistic verification |
| exception at the end of a transaction instead of assuming that a transaction |
| will successfully complete. In many applications, it is unlikely that different |
| concurrent transactions will operate on the same set of data at the same time, |
| so optimistic verification increases the concurrency, and therefore both the |
| performance and scalability characteristics, of the application. A common |
| approach to handling optimistic verification exceptions is to simply present the |
| end user with the fact that concurrent modifications happened, and require that |
| the user redo any work. |
| </p> |
| </td></tr><tr><td align="left"> |
| <span class="bold"><strong> |
| Use query aggregates and projections |
| </strong></span> |
| <p> |
| <span class="emphasis"><em>performance, scalability</em></span> |
| </p> |
| </td><td align="left"> |
| Using aggregates to compute reporting data on the database server can |
| drastically speed up queries. Similarly, using projections when you are |
| interested in specific object fields or relations rather than the entire object |
| state can reduce the amount of data OpenJPA must transfer from the database to |
| your application. |
| </td></tr><tr><td align="left"> |
| <span class="bold"><strong> |
| Always close resources |
| </strong></span> |
| <p> |
| <span class="emphasis"><em>scalability</em></span> |
| </p> |
| </td><td align="left"> |
| <p> |
| Under certain settings, <code class="classname"> EntityManager</code> s, OpenJPA |
| <code class="classname">Extent</code> iterators, and <code class="classname">Query</code> |
| results may be backed by resources in the database. |
| </p> |
| <p> |
| For example, if you have configured OpenJPA to use scrollable cursors and lazy |
| object instantiation by default, each query result will hold open a <code class="classname"> |
| ResultSet</code> object, which, in turn, will hold open a <code class="classname"> |
| Statement</code> object (preventing it from being re-used). Garbage |
| collection will clean up these resources, so it is never necessary to explicitly |
| close them, but it is always faster if it is done at the application level. |
| </p> |
| </td></tr><tr><td align="left"> |
| <span class="bold"><strong> |
| Use detached state managers |
| </strong></span> |
| <p> |
| <span class="emphasis"><em>performance</em></span> |
| </p> |
| </td><td align="left"> |
| <p> |
| Attaching and even persisting instances can be more efficient when your detached |
| objects use detached state managers. By default, OpenJPA does not use detached |
| state managers when serializing an instance across tiers. See |
| <a href="#ref_guide_detach_graph" title="1.3. Defining the Detached Object Graph">Section 1.3, “ |
| Defining the Detached Object Graph |
| ”</a> for how to force OpenJPA to use |
| detached state managers across tiers, and for other options for more efficient |
| attachment. |
| </p> |
| <p> |
| The downside of using a detached state manager across tiers is that your |
| enhanced persistent classes and the OpenJPA libraries must be available on the |
| client tier. |
| </p> |
| </td></tr><tr><td align="left"> |
| <span class="bold"><strong> |
| Utilize the <code class="classname">EntityManager</code> |
| cache |
| </strong></span> |
| <p> |
| <span class="emphasis"><em>performance, scalability</em></span> |
| </p> |
| </td><td align="left"> |
| When possible and appropriate, re-using <code class="classname">EntityManager</code>s |
| and setting the <a href="#openjpa.RetainState" title="5.55. openjpa.RetainState"><code class="literal">RetainState |
| </code></a> configuration option to <code class="literal">true</code> may result in |
| significant performance gains, since the <code class="classname">EntityManager</code>'s |
| built-in object cache will be used. |
| </td></tr><tr><td align="left"> |
| <span class="bold"><strong> |
| Enable multithreaded operation only when necessary |
| </strong></span> |
| <p> |
| <span class="emphasis"><em>performance</em></span> |
| </p> |
| </td><td align="left"> |
| OpenJPA respects the <a href="#openjpa.Multithreaded" title="5.44. openjpa.Multithreaded"><code class="literal"> |
| openjpa.Multithreaded</code></a> option in that it does not impose as |
| much synchronization overhead for applications that do not set this value to |
| <code class="literal">true</code>. If your application is guaranteed to only use |
| single-threaded access to OpenJPA resources and persistent objects, leaving |
| this option as <code class="literal">false</code> will reduce synchronization overhead, |
| and may result in a modest performance increase. |
| </td></tr><tr><td align="left"> |
| <span class="bold"><strong> |
| Enable large data set handling |
| </strong></span> |
| <p> |
| <span class="emphasis"><em>performance, scalability</em></span> |
| </p> |
| </td><td align="left"> |
| If you execute queries that return large numbers of objects or have relations |
| (collections or maps) that are large, and if you often only access parts of |
| these data sets, enabling <a href="#ref_guide_dbsetup_lrs" title="10. Large Result Sets">large result |
| set handling</a> where appropriate can dramatically speed up your |
| application, since OpenJPA will bring the data sets into memory from the |
| database only as necessary. |
| </td></tr><tr><td align="left"> |
| <span class="bold"><strong> |
| Disable large data set handling |
| </strong></span> |
| <p> |
| <span class="emphasis"><em>performance, scalability</em></span> |
| </p> |
| </td><td align="left"> |
| If you have enabled scrollable result sets and on-demand loading but do you not |
| require it, consider disabling it again. Some JDBC drivers and databases |
| (SQLServer for example) are much slower when used with scrolling result sets. |
| </td></tr><tr><td align="left"> |
| <span class="bold"><strong> |
| Use the <code class="classname">DynamicSchemaFactory</code> |
| </strong></span> |
| <p> |
| <span class="emphasis"><em>performance, validation</em></span> |
| </p> |
| </td><td align="left"> |
| If you are using an <a href="#openjpa.jdbc.SchemaFactory" title="6.13. openjpa.jdbc.SchemaFactory"><code class="literal"> |
| openjpa.jdbc.SchemaFactory</code></a> setting of something other than |
| the default of <code class="literal">dynamic</code>, consider switching back. While other |
| factories can ensure that object-relational mapping information is valid when |
| a persistent class is first used, this can be a slow process. Though the |
| validation is only performed once for each class, switching back to the |
| <code class="classname">DynamicSchemaFactory</code> can reduce the warm-up time for |
| your application. |
| </td></tr><tr><td align="left"> |
| <span class="bold"><strong> |
| Do not use XA transactions |
| </strong></span> |
| <p> |
| <span class="emphasis"><em>performance, scalability</em></span> |
| </p> |
| </td><td align="left"> |
| <a href="#ref_guide_enterprise_xa" title="3. XA Transactions">XA transactions</a> can be orders of |
| magnitude slower than standard transactions. Unless distributed transaction |
| functionality is required by your application, use standard transactions. |
| <p> |
| Recall that XA transactions are distinct from managed transactions - managed |
| transaction services such as that provided by EJB declarative transactions can |
| be used both with XA and non-XA transactions. XA transactions should only be |
| used when a given business transaction involves multiple different transactional |
| resources (an Oracle database and an IBM transactional message queue, for |
| example). |
| </p> |
| </td></tr><tr><td align="left"> |
| <span class="bold"><strong> |
| Use <code class="classname">Set</code>s instead of |
| <code class="classname">List/Collection</code>s |
| </strong></span> |
| <p> |
| <span class="emphasis"><em>performance, scalability</em></span> |
| </p> |
| </td><td align="left"> |
| There is a small amount of extra overhead for OpenJPA to maintain collections |
| where each element is not guaranteed to be unique. If your application does |
| not require duplicates for a collection, you should always declare your |
| fields to be of type <code class="classname">Set, SortedSet, HashSet,</code> or |
| <code class="classname">TreeSet</code>. |
| </td></tr><tr><td align="left"> |
| <span class="bold"><strong> |
| Use query parameters instead of encoding search |
| data in filter strings |
| </strong></span> |
| <p> |
| <span class="emphasis"><em>performance</em></span> |
| </p> |
| </td><td align="left"> |
| If your queries depend on parameter data only known at runtime, you should use |
| query parameters rather than dynamically building different query strings. |
| OpenJPA performs aggressive caching of query compilation data, and the |
| effectiveness of this cache is diminished if multiple query filters are used |
| where a single one could have sufficed. |
| </td></tr><tr><td align="left"> |
| <span class="bold"><strong> |
| Tune your fetch groups appropriately |
| </strong></span> |
| <p> |
| <span class="emphasis"><em>performance, scalability</em></span> |
| </p> |
| </td><td align="left"> |
| The <a href="#ref_guide_fetch" title="7. Fetch Groups">fetch groups</a> used when loading an |
| object control how much data is eagerly loaded, and by extension, which fields |
| must be lazily loaded at a future time. The ideal fetch group configuration |
| loads all the data that is needed in one fetch, and no extra fields - this |
| minimizes both the amount of data transferred from the database, and the |
| number of trips to the database. |
| <p> |
| If extra fields are specified in the fetch groups (in particular, large fields |
| such as binary data, or relations to other persistence-capable objects), then |
| network overhead (for the extra data) and database processing (for any necessary |
| additional joins) will hurt your application's performance. If too few fields |
| are specified in the fetch groups, then OpenJPA will have to make additional |
| trips to the database to load additional fields as necessary. |
| </p> |
| </td></tr><tr><td align="left"> |
| <span class="bold"><strong> |
| Use eager fetching |
| </strong></span> |
| <p> |
| <span class="emphasis"><em>performance, scalability</em></span> |
| </p> |
| </td><td align="left"> |
| Using <a href="#ref_guide_perfpack_eager" title="8. Eager Fetching">eager fetching</a> when |
| loading subclass data or traversing relations for each instance in a large |
| collection of results can speed up data loading by orders of magnitude. |
| </td></tr><tr><td align="left"> |
| <span class="bold"><strong> |
| Disable BrokerImpl finalization |
| </strong></span> |
| <p> |
| <span class="emphasis"><em>performance, scalability</em></span> |
| </p> |
| </td><td align="left"> |
| Outside of a Java EE 5 application server or other JPA persistence container, |
| OpenJPA's EntityManagers use finalizers to ensure that resources |
| get cleaned up. If you are properly managing your resources, this finalization |
| is not necessary, and will introduce unneeded synchronization, leading to |
| scalability problems. You can disable this protective behavior by setting the |
| <code class="literal">openjpa.BrokerImpl</code> property to |
| <code class="literal">non-finalizing</code>. See <a href="#ref_guide_runtime_broker_finalization" title="1.1. Broker Finalization">Section 1.1, “ |
| Broker Finalization |
| ”</a> for details. |
| </td></tr><tr><td align="left"> |
| <span class="bold"><strong> |
| Preload MetaDataRepository |
| </strong></span> |
| <p> |
| <span class="emphasis"><em>scalability</em></span> |
| </p> |
| </td><td align="left"> |
| By default, the MetaDataRepository is lazily loaded which means that fair amounts of locking |
| is used to ensure that metadata is processed properly. Enabling preloading allows OpenJPA to |
| load metadata upfront and remove locking. See <a href="#ref_guide_meta_repository" title="2. Metadata Repository">Section 2, “Metadata Repository”</a> for details. |
| </td></tr></tbody></table></div></div><br class="table-break"></div></div><div class="appendix" lang="en" id="jpa_resources"><div class="titlepage"><div><div><h2 class="title"><a name="jpa_resources"></a>Appendix 1. |
| JPA Resources |
| </h2></div></div></div><div class="itemizedlist"><ul type="disc"><li><p> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="http://java.sun.com/aboutJava/communityprocess/jsr/jsr_220_dataobj.html" target="_top"> |
| EJB 3 JSR page</a> |
| </p></li><li><p> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="http://java.sun.com/products/ejb" target="_top">Sun EJB page</a> |
| </p></li><li><p> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="http://java.sun.com/javaee/5/docs/api/index.html" target="_top"> |
| javax.persistence Javadoc</a> |
| </p></li><li><p> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/index.html" target="_top">OpenJPA Javadoc</a> |
| </p></li><li><p> |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="Persistence.pdf" target="_top">Locally mirrored JPA specification</a> |
| </p></li></ul></div></div><div class="appendix" lang="en" id="supported_databases"><div class="titlepage"><div><div><h2 class="title"><a name="supported_databases"></a>Appendix 2. |
| Supported Databases |
| </h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#dbsupport_derby">1. |
| Apache Derby |
| </a></span></dt><dt><span class="section"><a href="#dbsupport_interbase">2. |
| Borland Interbase |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#dbsupport_interbase_issues">2.1. |
| Known issues with Interbase |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#dbsupport_jdatastore">3. |
| JDataStore |
| </a></span></dt><dt><span class="section"><a href="#dbsupport_db2">4. |
| IBM DB2 |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#dbsupport_db2_issues">4.1. |
| Known issues with DB2 |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#dbsupport_empress">5. |
| Empress |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#dbsupport_empress_issues">5.1. |
| Known issues with Empress |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#dbsupport_h2">6. |
| H2 Database Engine |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#dbsupport_h2_issues">6.1. |
| Known issues with H2 Database Engine |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#dbsupport_hypersonic">7. |
| Hypersonic |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#dbsupport_hypersonic_issues">7.1. |
| Known issues with Hypersonic |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#dbsupport_firebird">8. |
| Firebird |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#dbsupport_firebird_issues">8.1. |
| Known issues with Firebird |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#dbsupport_informix">9. |
| Informix |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#dbsupport_informix_issues">9.1. |
| Known issues with Informix |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#dbsupport_intersystems_cache">10. |
| InterSystems Cache |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#dbsupport_intersystems_cache_issues">10.1. |
| Known issues with InterSystems Cache |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#dbsupport_access">11. |
| Microsoft Access |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#dbsupport_access_issues">11.1. |
| Known issues with Microsoft Access |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#dbsupport_sqlserver">12. |
| Microsoft SQL Server |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#dbsupport_sqlserver_issues">12.1. |
| Known issues with SQL Server |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#dbsupport_foxpro">13. |
| Microsoft FoxPro |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#dbsupport_foxpro_issues">13.1. |
| Known issues with Microsoft FoxPro |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#dbsupport_mysql">14. |
| MySQL |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#dbsupport_mysql_issues">14.1. |
| Known issues with MySQL |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#dbsupport_oracle">15. |
| Oracle |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#dbsupport_oracle_query_hints">15.1. |
| Using Query Hints with Oracle |
| </a></span></dt><dt><span class="section"><a href="#dbsupport_oracle_issues">15.2. |
| Known issues with Oracle |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#dbsupport_pointbase">16. |
| Pointbase |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#dbsupport_pointbase_issues">16.1. |
| Known issues with Pointbase |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#dbsupport_postgresql">17. |
| PostgreSQL |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#dbsupport_postgresql_issues">17.1. |
| Known issues with PostgreSQL |
| </a></span></dt></dl></dd><dt><span class="section"><a href="#dbsupport_sybase">18. |
| Sybase Adaptive Server |
| </a></span></dt><dd><dl><dt><span class="section"><a href="#dbsupport_sybase_issues">18.1. |
| Known issues with Sybase |
| </a></span></dt></dl></dd></dl></div><p> |
| Following is a table of the database and JDBC driver versions that are supported |
| by OpenJPA. |
| </p><div class="table"><a name="d0e32625"></a><p class="title"><b>Table 2.1. |
| Supported Databases and JDBC Drivers |
| </b></p><div class="table-contents"><table summary="
 Supported Databases and JDBC Drivers
 " border="1"><colgroup><col align="left"><col align="left"><col align="left"><col align="left"></colgroup><thead><tr><th align="left"> |
| Database Name |
| </th><th align="left"> |
| Database Version |
| </th><th align="left"> |
| JDBC Driver Name |
| </th><th align="left"> |
| JDBC Driver Version |
| </th></tr></thead><tbody><tr><td align="left"> |
| Apache Derby |
| </td><td align="left"> |
| 10.1.2.1 |
| </td><td align="left"> |
| Apache Derby Embedded JDBC Driver |
| </td><td align="left"> |
| 10.1.2.1 |
| </td></tr><tr><td align="left"> |
| Borland Interbase |
| </td><td align="left"> |
| 7.1.0.202 |
| </td><td align="left"> |
| Interclient |
| </td><td align="left"> |
| 4.5.1 |
| </td></tr><tr><td align="left"> |
| Borland JDataStore |
| </td><td align="left"> |
| 6.0 |
| </td><td align="left"> |
| Borland JDataStore |
| </td><td align="left"> |
| 6.0 |
| </td></tr><tr><td align="left"> |
| DB2 |
| </td><td align="left"> |
| 8.1 |
| </td><td align="left"> |
| IBM DB2 JDBC Universal Driver |
| </td><td align="left"> |
| 1.0.581 |
| </td></tr><tr><td align="left"> |
| Empress |
| </td><td align="left"> |
| 8.62 |
| </td><td align="left"> |
| Empress Category 2 JDBC Driver |
| </td><td align="left"> |
| 8.62 |
| </td></tr><tr><td align="left"> |
| Firebird |
| </td><td align="left"> |
| 1.5 |
| </td><td align="left"> |
| JayBird JCA/JDBC driver |
| </td><td align="left"> |
| 1.0.1 |
| </td></tr><tr><td align="left"> |
| H2 Database Engine |
| </td><td align="left"> |
| 1.0 |
| </td><td align="left"> |
| H2 |
| </td><td align="left"> |
| 1.0 |
| </td></tr><tr><td align="left"> |
| Hypersonic Database Engine |
| </td><td align="left"> |
| 1.8.0 |
| </td><td align="left"> |
| Hypersonic |
| </td><td align="left"> |
| 1.8.0 |
| </td></tr><tr><td align="left"> |
| Informix Dynamic Server |
| </td><td align="left"> |
| 9.30.UC10 |
| </td><td align="left"> |
| Informix JDBC driver |
| </td><td align="left"> |
| 2.21.JC2 |
| </td></tr><tr><td align="left"> |
| InterSystems Cache |
| </td><td align="left"> |
| 5.0 |
| </td><td align="left"> |
| Cache JDBC Driver |
| </td><td align="left"> |
| 5.0 |
| </td></tr><tr><td align="left"> |
| Microsoft Access |
| </td><td align="left"> |
| 9.0 (a.k.a. "2000") |
| </td><td align="left"> |
| DataDirect SequeLink |
| </td><td align="left"> |
| 5.4.0038 |
| </td></tr><tr><td align="left"> |
| Microsoft SQL Server |
| </td><td align="left"> |
| 9.00.1399 (SQL Server 2005) |
| </td><td align="left"> |
| SQLServer |
| </td><td align="left"> |
| 1.0.809.102 |
| </td></tr><tr><td align="left"> |
| Microsoft Visual FoxPro |
| </td><td align="left"> |
| 7.0 |
| </td><td align="left"> |
| DataDirect SequeLink |
| </td><td align="left"> |
| 5.4.0038 |
| </td></tr><tr><td align="left"> |
| MySQL |
| </td><td align="left"> |
| 3.23.43-log |
| </td><td align="left"> |
| MySQL Driver |
| </td><td align="left"> |
| 3.0.14 |
| </td></tr><tr><td align="left"> |
| MySQL |
| </td><td align="left"> |
| 5.0.26 |
| </td><td align="left"> |
| MySQL Driver |
| </td><td align="left"> |
| 3.0.14 |
| </td></tr><tr><td align="left"> |
| Oracle |
| </td><td align="left"> |
| 8.1,9.2,10.1 |
| </td><td align="left"> |
| Oracle JDBC driver |
| </td><td align="left"> |
| 10.2.0.1.0 |
| </td></tr><tr><td align="left"> |
| Pointbase |
| </td><td align="left"> |
| 4.4 |
| </td><td align="left"> |
| Pointbase JDBC driver |
| </td><td align="left"> |
| 4.4 (4.4) |
| </td></tr><tr><td align="left"> |
| PostgreSQL |
| </td><td align="left"> |
| 7.2.1 |
| </td><td align="left"> |
| PostgreSQL Native Driver |
| </td><td align="left"> |
| 8.1 |
| </td></tr><tr><td align="left"> |
| PostgreSQL |
| </td><td align="left"> |
| 8.1.5 |
| </td><td align="left"> |
| PostgreSQL Native Driver |
| </td><td align="left"> |
| 8.1 |
| </td></tr><tr><td align="left"> |
| Sybase Adaptive Server Enterprise |
| </td><td align="left"> |
| 12.5 |
| </td><td align="left"> |
| jConnect |
| </td><td align="left"> |
| 5.5 (5.5) |
| </td></tr></tbody></table></div></div><br class="table-break"><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="dbsupport_derby"></a>1. |
| Apache Derby |
| </h2></div></div></div><div class="example"><a name="example_props_derby"></a><p class="title"><b>Example 2.1. |
| Example properties for Derby |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| openjpa.ConnectionDriverName: org.apache.derby.jdbc.EmbeddedDriver |
| openjpa.ConnectionURL: jdbc:derby:DB_NAME;create=true |
| </pre></div></div><br class="example-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="dbsupport_interbase"></a>2. |
| Borland Interbase |
| </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#dbsupport_interbase_issues">2.1. |
| Known issues with Interbase |
| </a></span></dt></dl></div><div class="example"><a name="example_props_interbase"></a><p class="title"><b>Example 2.2. |
| Example properties for Interbase |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| openjpa.ConnectionDriverName: interbase.interclient.Driver |
| openjpa.ConnectionURL: jdbc:interbase://SERVER_NAME:SERVER_PORT/DB_PATH |
| </pre></div></div><br class="example-break"><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="dbsupport_interbase_issues"></a>2.1. |
| Known issues with Interbase |
| </h3></div></div></div><div class="itemizedlist"><ul type="disc"><li><p> |
| Interbase does not support record locking, so |
| datastore transactions cannot use the pessimistic lock manager. |
| </p></li><li><p> |
| Interbase does not support the <code class="literal">LOWER</code>, <code class="literal">SUBSTRING |
| </code>, or <code class="literal">INSTR</code> SQL functions> |
| </p></li></ul></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="dbsupport_jdatastore"></a>3. |
| JDataStore |
| </h2></div></div></div><div class="example"><a name="example_props_jdatastore"></a><p class="title"><b>Example 2.3. |
| Example properties for JDataStore |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| openjpa.ConnectionDriverName: com.borland.datastore.jdbc.DataStoreDriver |
| openjpa.ConnectionURL: jdbc:borland:dslocal:db-jdatastore.jds;create=true |
| </pre></div></div><br class="example-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="dbsupport_db2"></a>4. |
| IBM DB2 |
| </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#dbsupport_db2_issues">4.1. |
| Known issues with DB2 |
| </a></span></dt></dl></div><div class="example"><a name="example_props_db2"></a><p class="title"><b>Example 2.4. |
| Example properties for IBM DB2 |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| openjpa.ConnectionDriverName: com.ibm.db2.jcc.DB2Driver |
| openjpa.ConnectionURL: jdbc:db2://SERVER_NAME:SERVER_PORT/DB_NAME |
| </pre></div></div><br class="example-break"><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="dbsupport_db2_issues"></a>4.1. |
| Known issues with DB2 |
| </h3></div></div></div><div class="itemizedlist"><ul type="disc"><li><p> |
| Floats and doubles may lose precision when stored. |
| </p></li><li><p> |
| Empty char values are stored as NULL. |
| </p></li><li><p> |
| Fields of type BLOB and CLOB are limited to 1M. This number can be increased by |
| extending <code class="classname">DB2Dictionary</code>. |
| </p></li><li><p> |
| Explicit creation of indexes specified by the OpenJPA @Index annotation will |
| fail on DB2 for iSeries if the default schema used by the JDBC driver does not |
| exist. If a default schema is not specified on the connection, the iSeries |
| will default to the user profile name. If a schema of that name does not |
| exist, DB2 on iSeries will not create the schema, resulting in a failure when |
| creating the index. The failure message will look similar to: "[SQL0204] |
| USERNAME in QSYS type *LIB not found." To work around this issue, specify a |
| default schema on the JDBC URL or data source property and make sure that |
| schema exists or create a schema which matches the user profile of the |
| connection. |
| </p></li><li><p> |
| Use of DB2 on z/OS with the IBM JCC driver requires the DESCSTAT subsystem |
| parameter value to be set to 'YES'. If this parameter is set to 'NO', the |
| mapping tool will fail with a persistence exception containing this text: |
| "Invalid parameter: Unknown column name TABLE_SCHEM". After changing the value |
| of DESCSTAT, DB2 metadata tables must be recreated by running the DSNTIJMS job. |
| See DB2 for z/OS documentation for additional information. |
| </p></li></ul></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="dbsupport_empress"></a>5. |
| Empress |
| </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#dbsupport_empress_issues">5.1. |
| Known issues with Empress |
| </a></span></dt></dl></div><div class="example"><a name="example_props_empress"></a><p class="title"><b>Example 2.5. |
| Example properties for Empress |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| openjpa.ConnectionDriverName: empress.jdbc.empressDriver |
| openjpa.ConnectionURL: jdbc:empress://SERVER=yourserver;PORT=6322;DATABASE=yourdb |
| </pre></div></div><br class="example-break"><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="dbsupport_empress_issues"></a>5.1. |
| Known issues with Empress |
| </h3></div></div></div><div class="itemizedlist"><ul type="disc"><li><p> |
| Empress enforces pessimistic semantics (lock on |
| read) when not using <code class="literal">AllowConcurrentRead</code> property (which |
| bypasses row locking) for <code class="classname">EmpressDictionary</code>. |
| </p></li><li><p> |
| Only the category 2 non-local driver is supported. |
| </p></li></ul></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="dbsupport_h2"></a>6. |
| H2 Database Engine |
| </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#dbsupport_h2_issues">6.1. |
| Known issues with H2 Database Engine |
| </a></span></dt></dl></div><div class="example"><a name="example_props_h2"></a><p class="title"><b>Example 2.6. |
| Example properties for H2 Database Engine |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| openjpa.ConnectionDriverName: org.h2.Driver |
| openjpa.ConnectionURL: jdbc:h2:DB_NAME |
| </pre></div></div><br class="example-break"><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="dbsupport_h2_issues"></a>6.1. |
| Known issues with H2 Database Engine |
| </h3></div></div></div><div class="itemizedlist"><ul type="disc"><li><p> |
| H2 does not support cross joins |
| </p></li></ul></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="dbsupport_hypersonic"></a>7. |
| Hypersonic |
| </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#dbsupport_hypersonic_issues">7.1. |
| Known issues with Hypersonic |
| </a></span></dt></dl></div><div class="example"><a name="example_props_hypersonic"></a><p class="title"><b>Example 2.7. |
| Example properties for Hypersonic |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| openjpa.ConnectionDriverName: org.hsqldb.jdbcDriver |
| openjpa.ConnectionURL: jdbc:hsqldb:DB_NAME |
| </pre></div></div><br class="example-break"><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="dbsupport_hypersonic_issues"></a>7.1. |
| Known issues with Hypersonic |
| </h3></div></div></div><div class="itemizedlist"><ul type="disc"><li><p> |
| Hypersonic does not support pessimistic locking, so non-optimistic transactions |
| will fail unless the <code class="literal">SimulateLocking</code> property is set for the |
| <a href="#openjpa.jdbc.DBDictionary" title="6.2. openjpa.jdbc.DBDictionary"> openjpa.jdbc.DBDictionary</a> |
| </p></li></ul></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="dbsupport_firebird"></a>8. |
| Firebird |
| </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#dbsupport_firebird_issues">8.1. |
| Known issues with Firebird |
| </a></span></dt></dl></div><div class="example"><a name="example_props_firebird"></a><p class="title"><b>Example 2.8. |
| Example properties for Firebird |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| openjpa.ConnectionDriverName: org.firebirdsql.jdbc.FBDriver |
| openjpa.ConnectionURL: jdbc:firebirdsql://SERVER_NAME:SERVER_PORT/DB_PATH |
| </pre></div></div><br class="example-break"><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="dbsupport_firebird_issues"></a>8.1. |
| Known issues with Firebird |
| </h3></div></div></div><div class="itemizedlist"><ul type="disc"><li><p> |
| Firebird does not support auto-increment columns. |
| </p></li><li><p> |
| Firebird does not support the <code class="literal">LOWER</code>, <code class="literal">SUBSTRING |
| </code>, or <code class="literal">INSTR</code> SQL functions. |
| </p></li></ul></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="dbsupport_informix"></a>9. |
| Informix |
| </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#dbsupport_informix_issues">9.1. |
| Known issues with Informix |
| </a></span></dt></dl></div><div class="example"><a name="example_props_informix"></a><p class="title"><b>Example 2.9. |
| Example properties for Informix Dynamic Server |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| openjpa.ConnectionDriverName: com.informix.jdbc.IfxDriver |
| openjpa.ConnectionURL: \ |
| jdbc:informix-sqli://SERVER_NAME:SERVER_PORT/DB_NAME:INFORMIXSERVER=SERVER_ID |
| </pre></div></div><br class="example-break"><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="dbsupport_informix_issues"></a>9.1. |
| Known issues with Informix |
| </h3></div></div></div><div class="itemizedlist"><ul type="disc"><li><p> |
| None |
| </p></li></ul></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="dbsupport_intersystems_cache"></a>10. |
| InterSystems Cache |
| </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#dbsupport_intersystems_cache_issues">10.1. |
| Known issues with InterSystems Cache |
| </a></span></dt></dl></div><div class="example"><a name="example_props_intersystems_cache"></a><p class="title"><b>Example 2.10. |
| Example properties for InterSystems Cache |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| openjpa.ConnectionDriverName: com.intersys.jdbc.CacheDriver |
| openjpa.ConnectionURL: jdbc:Cache://SERVER_NAME:SERVER_PORT/DB_NAME |
| </pre></div></div><br class="example-break"><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="dbsupport_intersystems_cache_issues"></a>10.1. |
| Known issues with InterSystems Cache |
| </h3></div></div></div><div class="itemizedlist"><ul type="disc"><li><p> |
| Support for Cache is done via SQL access over JDBC, not through their object |
| database APIs. |
| </p></li></ul></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="dbsupport_access"></a>11. |
| Microsoft Access |
| </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#dbsupport_access_issues">11.1. |
| Known issues with Microsoft Access |
| </a></span></dt></dl></div><div class="example"><a name="example_props_access"></a><p class="title"><b>Example 2.11. |
| Example properties for Microsoft Access |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| openjpa.ConnectionDriverName: com.ddtek.jdbc.sequelink.SequeLinkDriver |
| openjpa.ConnectionURL: jdbc:sequelink://SERVER_NAME:SERVER_PORT |
| </pre></div></div><br class="example-break"><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="dbsupport_access_issues"></a>11.1. |
| Known issues with Microsoft Access |
| </h3></div></div></div><div class="itemizedlist"><ul type="disc"><li><p> |
| Using the Sun JDBC-ODBC bridge to connect is not supported. |
| </p></li></ul></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="dbsupport_sqlserver"></a>12. |
| Microsoft SQL Server |
| </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#dbsupport_sqlserver_issues">12.1. |
| Known issues with SQL Server |
| </a></span></dt></dl></div><div class="example"><a name="example_props_sqlserver"></a><p class="title"><b>Example 2.12. |
| Example properties for Microsoft SQLServer |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| openjpa.ConnectionDriverName: com.microsoft.sqlserver.jdbc.SQLServerDriver |
| openjpa.ConnectionURL: \ |
| jdbc:sqlserver://SERVER_NAME:1433;DatabaseName=DB_NAME;selectMethod=cursor;sendStringParametersAsUnicode=false |
| </pre></div></div><br class="example-break"><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="dbsupport_sqlserver_issues"></a>12.1. |
| Known issues with SQL Server |
| </h3></div></div></div><div class="itemizedlist"><ul type="disc"><li><p> |
| SQL Server date fields are accurate only to the nearest 3 milliseconds, |
| possibly resulting in precision loss in stored dates. |
| </p></li><li><p> |
| The ConnectionURL must always contain the " <code class="literal">selectMethod=cursor |
| </code> " string. |
| </p></li><li><p> |
| Adding <code class="literal">sendStringParametersAsUnicode=false</code> to the |
| ConnectionURL may significantly increase performance. |
| </p></li><li><p> |
| The Microsoft SQL Server driver only emulates batch updates. The DataDirect JDBC |
| driver has true support for batch updates, and may result in a significant |
| performance gain. |
| </p></li><li><p> |
| Floats and doubles may lose precision when stored. |
| </p></li><li><p> |
| <code class="literal">TEXT</code> columns cannot be used in queries. |
| </p></li><li><p> |
| When using a SQL Server instance that has been configured to be case-sensitive |
| in schema names, you need to set the "schemaCase=preserve" parameter in the |
| <a href="#openjpa.jdbc.DBDictionary" title="6.2. openjpa.jdbc.DBDictionary">openjpa.jdbc.DBDictionary</a> |
| property. |
| </p></li><li><p> |
| SQL Server 2005 does not support native sequences. If you would like to use |
| generated values with SQL Server you should use GenerationType.IDENTITY, |
| GenerationType.TABLE, or GenerationType.AUTO. |
| </p></li></ul></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="dbsupport_foxpro"></a>13. |
| Microsoft FoxPro |
| </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#dbsupport_foxpro_issues">13.1. |
| Known issues with Microsoft FoxPro |
| </a></span></dt></dl></div><div class="example"><a name="example_props_foxpro"></a><p class="title"><b>Example 2.13. |
| Example properties for Microsoft FoxPro |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| openjpa.ConnectionDriverName: com.ddtek.jdbc.sequelink.SequeLinkDriver |
| openjpa.ConnectionURL: jdbc:sequelink://SERVER_NAME:SERVER_PORT |
| </pre></div></div><br class="example-break"><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="dbsupport_foxpro_issues"></a>13.1. |
| Known issues with Microsoft FoxPro |
| </h3></div></div></div><div class="itemizedlist"><ul type="disc"><li><p> |
| Using the Sun JDBC-ODBC bridge to connect is not supported. |
| </p></li></ul></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="dbsupport_mysql"></a>14. |
| MySQL |
| </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#dbsupport_mysql_issues">14.1. |
| Known issues with MySQL |
| </a></span></dt></dl></div><div class="example"><a name="example_props_mysql"></a><p class="title"><b>Example 2.14. |
| Example properties for MySQL |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| openjpa.ConnectionDriverName: com.mysql.jdbc.Driver |
| openjpa.ConnectionURL: jdbc:mysql://SERVER_NAME/DB_NAME |
| </pre></div></div><br class="example-break"><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="dbsupport_mysql_issues"></a>14.1. |
| Known issues with MySQL |
| </h3></div></div></div><div class="itemizedlist"><ul type="disc"><li><p> |
| The default table types that MySQL uses do not support transactions, which will |
| prevent OpenJPA from being able to roll back transactions. Use the |
| <code class="literal">InnoDB</code> table type for any tables that OpenJPA will access. |
| </p></li><li><p> |
| MySQL does not support sub-selects in versions prior to 4.1, and are disabled by |
| default. Some operations (such as the <code class="function">isEmpty()</code> method in a |
| query) will fail due to this. If you are using MySQL 4.1 or later, you can lift |
| this restriction by setting the <code class="literal">SupportsSubselect=true</code> |
| parameter of the <a href="#openjpa.jdbc.DBDictionary" title="6.2. openjpa.jdbc.DBDictionary"> |
| openjpa.jdbc.DBDictionary</a> property. |
| </p></li><li><p> |
| Rollback due to database error or optimistic lock violation is not supported |
| unless the table type is one of the MySQL transactional types. Explicit calls to |
| <code class="function">rollback()</code> before a transaction has been committed, |
| however, are always supported. |
| </p></li><li><p> |
| Floats and doubles may lose precision when stored in some datastores. |
| </p></li><li><p> |
| When storing a field of type <code class="classname">java.math.BigDecimal</code>, some |
| datastores will add extraneous trailing 0 characters, causing an equality |
| mismatch between the field that is stored and the field that is retrieved. |
| </p></li><li><p> |
| Some version of the MySQL JDBC driver have a bug that prevents OpenJPA from |
| being able to interrogate the database for foreign keys. Version 3.0.14 (or |
| higher) of the MySQL driver is required in order to get around this bug. |
| </p></li></ul></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="dbsupport_oracle"></a>15. |
| Oracle |
| </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#dbsupport_oracle_query_hints">15.1. |
| Using Query Hints with Oracle |
| </a></span></dt><dt><span class="section"><a href="#dbsupport_oracle_issues">15.2. |
| Known issues with Oracle |
| </a></span></dt></dl></div><div class="example"><a name="example_props_oracle"></a><p class="title"><b>Example 2.15. |
| Example properties for Oracle |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| openjpa.ConnectionDriverName: oracle.jdbc.driver.OracleDriver |
| openjpa.ConnectionURL: jdbc:oracle:thin:@SERVER_NAME:1521:DB_NAME |
| </pre></div></div><br class="example-break"><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="dbsupport_oracle_query_hints"></a>15.1. |
| Using Query Hints with Oracle |
| </h3></div></div></div><p> |
| Oracle has support for "query hints", which are formatted comments embedded in |
| SQL that provide some hint for how the query should be executed. These hints are |
| usually designed to provide suggestions to the Oracle query optimizer for how to |
| efficiently perform a certain query, and aren't typically needed for any but |
| the most intensive queries. |
| </p><div class="example"><a name="dbsupport_oracle_query_hints_ex"></a><p class="title"><b>Example 2.16. |
| Using Oracle Hints |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| Query query = em.createQuery(...); |
| query.setHint("openjpa.hint.OracleSelectHint", "/*+ first_rows(100) */"); |
| List results = query.getResultList(); |
| </pre></div></div><br class="example-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="dbsupport_oracle_issues"></a>15.2. |
| Known issues with Oracle |
| </h3></div></div></div><div class="itemizedlist"><ul type="disc"><li><p> |
| The Oracle JDBC driver has significant differences between different versions. |
| It is important to use the officially supported version of the driver |
| (10.2.0.1.0), which is backward compatible with previous versions of the Oracle |
| server. It can be downloaded from |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="http://www.oracle.com/technology/software/tech/java/sqlj_jdbc/htdocs/jdbc101040.html" target="_top"> |
| http://www.oracle.com/technology/software/tech/java/sqlj_jdbc/htdocs/jdbc101040.html</a>. |
| </p></li><li><p> |
| For VARCHAR fields, <code class="literal">null</code> and a blank string are equivalent. |
| This means that an object that stores a null string field will have it get read |
| back as a blank string. |
| </p></li><li><p> |
| Oracle corp's JDBC driver for Oracle has only limited support for batch updates. |
| The result for OpenJPA is that in some cases, the exact object that failed an |
| optimistic lock check cannot be determined, and OpenJPA will throw an |
| <code class="classname">OptimisticVerificationException</code> with more failed objects |
| than actually failed. |
| </p></li><li><p> |
| Oracle cannot store numbers with more than 38 digits in numeric columns. |
| </p></li><li><p> |
| Floats and doubles may lose precision when stored. |
| </p></li><li><p> |
| CLOB columns cannot be used in queries. |
| </p></li></ul></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="dbsupport_pointbase"></a>16. |
| Pointbase |
| </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#dbsupport_pointbase_issues">16.1. |
| Known issues with Pointbase |
| </a></span></dt></dl></div><div class="example"><a name="example_props_pointbase"></a><p class="title"><b>Example 2.17. |
| Example properties for Pointbase |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| openjpa.ConnectionDriverName: com.pointbase.jdbc.jdbcUniversalDriver |
| openjpa.ConnectionURL: \ |
| jdbc:pointbase:DB_NAME,database.home=pointbasedb,create=true,cache.size=10000,database.pagesize=30720 |
| </pre></div></div><br class="example-break"><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="dbsupport_pointbase_issues"></a>16.1. |
| Known issues with Pointbase |
| </h3></div></div></div><div class="itemizedlist"><ul type="disc"><li><p> |
| Fields of type BLOB and CLOB are limited to 1M. Set the <code class="literal">BlobTypeName |
| </code> and/or <code class="literal">ClobTypeName</code> properties of the |
| <code class="literal">openjpa.jdbc.DBDictionary</code> setting to override. |
| </p></li></ul></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="dbsupport_postgresql"></a>17. |
| PostgreSQL |
| </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#dbsupport_postgresql_issues">17.1. |
| Known issues with PostgreSQL |
| </a></span></dt></dl></div><div class="example"><a name="example_props_postgresql"></a><p class="title"><b>Example 2.18. |
| Example properties for PostgreSQL |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| openjpa.ConnectionDriverName: org.postgresql.Driver |
| openjpa.ConnectionURL: jdbc:postgresql://SERVER_NAME:5432/DB_NAME |
| </pre></div></div><br class="example-break"><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="dbsupport_postgresql_issues"></a>17.1. |
| Known issues with PostgreSQL |
| </h3></div></div></div><div class="itemizedlist"><ul type="disc"><li><p> |
| Floats and doubles may lose precision when stored. |
| </p></li><li><p> |
| PostgreSQL cannot store very low and very high dates. |
| </p></li><li><p> |
| Empty string/char values are stored as NULL. |
| </p></li></ul></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="dbsupport_sybase"></a>18. |
| Sybase Adaptive Server |
| </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#dbsupport_sybase_issues">18.1. |
| Known issues with Sybase |
| </a></span></dt></dl></div><div class="example"><a name="example_props_sybase"></a><p class="title"><b>Example 2.19. |
| Example properties for Sybase |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| openjpa.ConnectionDriverName: com.sybase.jdbc2.jdbc.SybDriver |
| openjpa.ConnectionURL: \ |
| jdbc:sybase:Tds:SERVER_NAME:4100/DB_NAME?ServiceName=DB_NAME&BE_AS_JDBC_COMPLIANT_AS_POSSIBLE=true |
| </pre></div></div><br class="example-break"><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="dbsupport_sybase_issues"></a>18.1. |
| Known issues with Sybase |
| </h3></div></div></div><div class="itemizedlist"><ul type="disc"><li><p> |
| The "<code class="literal">DYNAMIC_PREPARE</code>" parameter of the Sybase JDBC driver |
| cannot be used with OpenJPA. |
| </p></li><li><p> |
| Datastore locking cannot be used when manipulating many-to-many relations using |
| the default OpenJPA schema created by the schematool, unless an auto-increment |
| primary key field is manually added to the table. |
| </p></li><li><p> |
| Persisting a zero-length string results in a string with a single space |
| characted being returned from Sybase, Inc.'s JDBC driver. |
| </p></li><li><p> |
| The <code class="literal">BE_AS_JDBC_COMPLIANT_AS_POSSIBLE</code> is required in order to |
| use datastore (pessimistic) locking. Failure to set this property may lead to |
| obscure errors like " <code class="literal">FOR UPDATE can not be used in a SELECT which is |
| not part of the declaration of a cursor or which is not inside a stored |
| procedure.</code> ". |
| </p></li><li><p> |
| Applications performing update/insert data of the BigDecimal java type may fail |
| with OptimisticException if the data exceeds the scale or precision of the |
| column on Sybase. To avoid this problem, applications can specify the precision |
| and scale for the numeric type by setting numericTypeName='NUMERIC(p,s)' for |
| the column type mapped by the BigDecimal java type. See |
| <a href="#openjpa.jdbc.DBDictionary" title="6.2. openjpa.jdbc.DBDictionary">openjpa.jdbc.DBDictionary</a> for |
| more detail. Alternatively, application can set the precision and scale using |
| the standard <code class="classname">Column</code> annotation, described in |
| <a href="#jpa_overview_mapping_column" title="3. Column">Section 3, “ |
| Column |
| ”</a>. |
| </p></li></ul></div></div></div></div></div></body></html> |