| <html><head> | |
| <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | |
| <title>2. OpenJPA 2.2.0</title><base href="display"><link rel="stylesheet" type="text/css" href="css/docbook.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="manual.html" title="Apache OpenJPA 3.0 User's Guide"><link rel="up" href="migration_considerations.html" title="Appendix 3. Migration Considerations"><link rel="prev" href="migration_considerations.html" title="Appendix 3. Migration Considerations"><link rel="next" href="jpa_2.3.html" title="3. OpenJPA 2.3.0"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">2. | |
| OpenJPA 2.2.0 | |
| </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="migration_considerations.html">Prev</a> </td><th width="60%" align="center">Appendix 3. | |
| Migration Considerations | |
| </th><td width="20%" align="right"> <a accesskey="n" href="jpa_2.3.html">Next</a></td></tr></table><hr></div><div class="section" id="jpa_2.2"><div class="titlepage"><div><div><h2 class="title" style="clear: both">2. | |
| OpenJPA 2.2.0 | |
| </h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="section"><a href="jpa_2.2.html#jpa_2.2_incompatibilities">2.1. Incompatibilities</a></span></dt><dd><dl><dt><span class="section"><a href="jpa_2.2.html#jpa_2.2_allocationSize">2.1.1. | |
| allocationSize Property of Sequence Generator | |
| </a></span></dt><dt><span class="section"><a href="jpa_2.2.html#jpa_2.2_metamodelArrays">2.1.2. | |
| MetaModel Attributes for Arrays | |
| </a></span></dt><dt><span class="section"><a href="jpa_2.2.html#jpa_2.2_SupportsSetClob">2.1.3. | |
| supportsSetClob Property. | |
| </a></span></dt><dt><span class="section"><a href="jpa_2.2.html#jpa_2.2_UseNativeSequenceCache">2.1.4. | |
| useNativeSequenceCache Property. | |
| </a></span></dt><dt><span class="section"><a href="jpa_2.2.html#jpa_2.2_cascadePersist">2.1.5. | |
| Cascade persist behavior | |
| </a></span></dt><dt><span class="section"><a href="jpa_2.2.html#jpa_2.2_LifecycleEventManager">2.1.6. | |
| Life Cycle Event Manager Callback Behavior | |
| </a></span></dt><dt><span class="section"><a href="jpa_2.2.html#jpa_2.2_sharedCacheMode">2.1.7. | |
| shared-cache-mode Property | |
| </a></span></dt></dl></dd></dl></div> | |
| <div class="section" id="jpa_2.2_incompatibilities"><div class="titlepage"><div><div><h3 class="title">2.1. Incompatibilities</h3></div></div></div><div class="toc"><dl class="toc"><dt><span class="section"><a href="jpa_2.2.html#jpa_2.2_allocationSize">2.1.1. | |
| allocationSize Property of Sequence Generator | |
| </a></span></dt><dt><span class="section"><a href="jpa_2.2.html#jpa_2.2_metamodelArrays">2.1.2. | |
| MetaModel Attributes for Arrays | |
| </a></span></dt><dt><span class="section"><a href="jpa_2.2.html#jpa_2.2_SupportsSetClob">2.1.3. | |
| supportsSetClob Property. | |
| </a></span></dt><dt><span class="section"><a href="jpa_2.2.html#jpa_2.2_UseNativeSequenceCache">2.1.4. | |
| useNativeSequenceCache Property. | |
| </a></span></dt><dt><span class="section"><a href="jpa_2.2.html#jpa_2.2_cascadePersist">2.1.5. | |
| Cascade persist behavior | |
| </a></span></dt><dt><span class="section"><a href="jpa_2.2.html#jpa_2.2_LifecycleEventManager">2.1.6. | |
| Life Cycle Event Manager Callback Behavior | |
| </a></span></dt><dt><span class="section"><a href="jpa_2.2.html#jpa_2.2_sharedCacheMode">2.1.7. | |
| shared-cache-mode Property | |
| </a></span></dt></dl></div> | |
| <p> | |
| The following sections indicate changes that are incompatible | |
| between OpenJPA 2.1.x releases and the 2.2.0 release. | |
| </p> | |
| <div class="section" id="jpa_2.2_allocationSize"><div class="titlepage"><div><div><h4 class="title">2.1.1. | |
| allocationSize Property of Sequence Generator | |
| </h4></div></div></div> | |
| <p> | |
| In previous releases, specifying the <code class="literal">allocationSize</code> property of | |
| <a class="link" href="jpa_overview_mapping_sequence.html#jpa_overview_mapping_sequence_seqgen" title="5.1. Sequence Generator">sequence generator</a> | |
| affected only sequence definition in the database. During | |
| schema creation, the <code class="literal">INCREMENT BY</code> clause of | |
| <code class="literal">CREATE SEQUENCE</code> statement always | |
| had a value of 1 and on DB2, Oracle and PostgreSQL databases a <code class="literal">CACHE</code> clause | |
| was added with the value of <code class="literal">allocationSize</code> property. Such a statement caused | |
| sequence values being cached in the database. Starting with OpenJPA 2.2.0, | |
| sequence values are cached in the jvm memory and the <code class="literal">allocationSize</code> | |
| property determines size of that cache. The <code class="literal">CACHE</code> clause is no longer used, | |
| instead the <code class="literal">INCREMENT BY</code> clause gets its value equal to the | |
| <code class="literal">allocationSize</code> property. Such a strategy reduces the number of database roundtrips | |
| required for retrieving sequence values considerably. | |
| </p> | |
| <p> | |
| In order for the existing applications to work with OpenJPA | |
| 2.2.0, you have to manually recreate or redefine sequences, specifying | |
| the correct <code class="literal">INCREMENT BY</code> value and, possibly, correct initial sequence value. | |
| Note that the default value of the <code class="literal">allocationSize</code> property is 50 and that | |
| value is used if the property is not specified. | |
| </p> | |
| <p> | |
| The requirement for sequence modification applies to all databases that support sequences, regardless of | |
| the <code class="literal">CACHE</code> clause being supported. The only exception is Firebird database - | |
| since with this database the increment step is determined during sequence | |
| value fetch, no migration activity is needed. | |
| </p> | |
| <p> | |
| To maintain the old behavior of sequence generator in OpenJPA 2.2.0, you can: | |
| </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> | |
| <p> | |
| Set the <code class="literal">allocationSize</code> property value to 1. | |
| </p> | |
| </li><li class="listitem"> | |
| <p> | |
| Additionally, if the <code class="literal">CACHE</code> clause has to be emitted in sequence definition, | |
| this can be accomplished by overriding the | |
| <a class="ulink" href="../../apidocs/org/apache/openjpa/jdbc/sql/DBDictionary.html#getCreateSequenceSQL(org.apache.openjpa.jdbc.schema.Sequence)" target="_top"> | |
| <code class="methodname">DBDictionary.getCreateSequenceSQL</code></a> method. | |
| </p> | |
| </li></ul></div><p> | |
| </p> | |
| </div> | |
| <div class="section" id="jpa_2.2_metamodelArrays"><div class="titlepage"><div><div><h4 class="title">2.1.2. | |
| MetaModel Attributes for Arrays | |
| </h4></div></div></div> | |
| <p> | |
| In previous releases OpenJPA's MetaModel implementation generated a ListAttribute for every array. This behavior is correct if the array | |
| is annotated as a PersistentCollection, but not correct for un-annotated arrays (e.g. byte[], char[]). In OpenJPA 2.2.0 this behavior was corrected | |
| so that arrays which are not stored as PersistentCollections will use a SingularAttribute instead of a ListAttribute. | |
| </p> | |
| <p> | |
| If your application uses the MetaModel API and your entities contain arrays of any of the following types: byte[], Byte[], char[], Character[] and | |
| do not use the @PersistentCollection annotation with those fields you will need to update your application to use OpenJPA 2.2.0. | |
| </p> | |
| <p> In order for the existing applications to work with OpenJPA you may: | |
| </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> | |
| <p> Regenerate the canonical metamodel classes</p> | |
| </li><li class="listitem"> | |
| <p> Set the Compatibility property <code class="literal">UseListAttributeForArrays</code> to <code class="literal">true</code> in persistence.xml | |
| </p><pre class="programlisting"> <property name="openjpa.Compatibility" value="UseListAttributeForArrays=true"/></pre><p> | |
| </p> | |
| </li></ul></div><p> | |
| </p> | |
| </div> | |
| <div class="section" id="jpa_2.2_SupportsSetClob"><div class="titlepage"><div><div><h4 class="title">2.1.3. | |
| supportsSetClob Property. | |
| </h4></div></div></div> | |
| <p> | |
| In OpenJPA 2.2.0, code was added to allow the setting of CLOB or XML data larger than 4000 bytes. This functionality | |
| was eventually back ported to previous releases, and enabled by the <code class="literal">supportsSetClob</code> property on the OracleDictionary. Setting this property | |
| has no effect in 2.2.0 and later releases and any occurrence of it should be removed. | |
| </p> | |
| </div> | |
| <div class="section" id="jpa_2.2_UseNativeSequenceCache"><div class="titlepage"><div><div><h4 class="title">2.1.4. | |
| useNativeSequenceCache Property. | |
| </h4></div></div></div> | |
| <p> | |
| In OpenJPA 2.2.0, code was added which changed the way sequences were generated, please see | |
| <a class="xref" href="jpa_2.2.html#jpa_2.2_allocationSize" title="2.1.1. allocationSize Property of Sequence Generator">Section 2.1.1, “ | |
| allocationSize Property of Sequence Generator | |
| ”</a> for details. This functionality was eventually back ported | |
| to previous releases, and enabled by the <code class="literal">useNativeSequenceCache</code> property on the DBDictionary. Setting this property | |
| has no effect in 2.2.0 and later releases and any occurrence of it should be removed. If previous behavior is | |
| desired (i.e. <code class="literal">useNativeSequenceCache=true</code>), please see the details described in section | |
| <a class="xref" href="jpa_2.2.html#jpa_2.2_allocationSize" title="2.1.1. allocationSize Property of Sequence Generator">Section 2.1.1, “ | |
| allocationSize Property of Sequence Generator | |
| ”</a>. | |
| </p> | |
| </div> | |
| <div class="section" id="jpa_2.2_cascadePersist"><div class="titlepage"><div><div><h4 class="title">2.1.5. | |
| Cascade persist behavior | |
| </h4></div></div></div> | |
| <p> | |
| In previous releases, OpenJPA would check the database for the | |
| existence of the related Entity before persisting the relationship to | |
| that Entity. This resulted in an extra Select being sent to the | |
| database. In 2.2.0, code was added so that when cascading a persist to | |
| a related Entity without persistence state, the persist (insert) will | |
| happen without first checking the database. This may result in an | |
| EntityExistsException if the related Entity already exists in the | |
| database. To revert this behavior to the previous release, set the | |
| value of the <code class="literal">openjpa.Compatibility</code> | |
| property <code class="literal">CheckDatabaseForCascadePersistToDetachedEntity</code> | |
| to <code class="literal">true</code>. | |
| </p> | |
| </div> | |
| <div class="section" id="jpa_2.2_LifecycleEventManager"><div class="titlepage"><div><div><h4 class="title">2.1.6. | |
| Life Cycle Event Manager Callback Behavior | |
| </h4></div></div></div> | |
| <p> | |
| Life cycle event manager is used to manage entity's life cycle event callback. | |
| In previous releases, Life cycle event manager is scoped to EntityManagerFactory. | |
| This means listeners registered to an individual EntityManager may get life cycle | |
| event callbacks for entity that it does not manage. | |
| </p> | |
| <p> | |
| From 2.2.1 release, the default callback behavior of the life cycle event manager | |
| is changed to scope to each EntityManager. | |
| To revert this behavior to the previous release, set the | |
| value of the <code class="literal">openjpa.Compatibility</code> | |
| property <code class="literal">SingletonLifecycleEventManager</code> | |
| to <code class="literal">true</code>. | |
| </p> | |
| </div> | |
| <div class="section" id="jpa_2.2_sharedCacheMode"><div class="titlepage"><div><div><h4 class="title">2.1.7. | |
| shared-cache-mode Property | |
| </h4></div></div></div> | |
| <p> | |
| In the previous release, when the shared-cache-mode is enabled and the DataCache property is not set | |
| or set to false, there will be no data caching. | |
| </p> | |
| <p> | |
| From 2.2.2 release, the caching will be turned on if the shared-cache-mode is enabled. Please see the | |
| details described in section <a class="xref" href="ref_guide_caching.html#ref_guide_shared_cache_mode_integration" title="1.1.2. Integration with JPA standard shared cache mode">Section 1.1.2, “ | |
| Integration with JPA standard shared cache mode | |
| ”</a>. | |
| </p> | |
| </div> | |
| </div> | |
| </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="migration_considerations.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="migration_considerations.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="jpa_2.3.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Appendix 3. | |
| Migration Considerations | |
| </td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top"> 3. | |
| OpenJPA 2.3.0 | |
| </td></tr></table></div></body></html> |