openjpa-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From dwo...@apache.org
Subject svn commit: r926255 - in /openjpa/branches/1.3.x/openjpa-project/src/doc/manual: migration_considerations.xml ref_guide_pc.xml ref_guide_remote.xml
Date Mon, 22 Mar 2010 19:01:47 GMT
Author: dwoods
Date: Mon Mar 22 19:01:47 2010
New Revision: 926255

URL: http://svn.apache.org/viewvc?rev=926255&view=rev
Log:
OPENJPA-1097 Add a note in the Migration Considerations doc about the 'fixed' serialization
behavior and how DetachedStateField can be used to modify the Proxies behavior.

Modified:
    openjpa/branches/1.3.x/openjpa-project/src/doc/manual/migration_considerations.xml
    openjpa/branches/1.3.x/openjpa-project/src/doc/manual/ref_guide_pc.xml
    openjpa/branches/1.3.x/openjpa-project/src/doc/manual/ref_guide_remote.xml

Modified: openjpa/branches/1.3.x/openjpa-project/src/doc/manual/migration_considerations.xml
URL: http://svn.apache.org/viewvc/openjpa/branches/1.3.x/openjpa-project/src/doc/manual/migration_considerations.xml?rev=926255&r1=926254&r2=926255&view=diff
==============================================================================
--- openjpa/branches/1.3.x/openjpa-project/src/doc/manual/migration_considerations.xml (original)
+++ openjpa/branches/1.3.x/openjpa-project/src/doc/manual/migration_considerations.xml Mon
Mar 22 19:01:47 2010
@@ -50,6 +50,28 @@
                     demonstrate the behavioral differences.
             </para>
         </section>
+        <section id="serialization">
+            <title>
+                Serialization of Entities
+            </title>
+            <para>
+                    In prior releases of OpenJPA, when an entity was serialized
+                    after calling EntityManager.find(), detach() or detachAll()
+                    then all <xref linkend="ref_guide_pc_scos_proxy"/>
+                    were removed as expected, but when the same entity instance
+                    was serialized after calling EntityManager.clear() the
+                    proxy classes were not removed.
+            </para>
+            <para>
+                    Starting with OpenJPA 1.3, this behavior has been
+                    modified, so that by default all proxies will be removed
+                    during serialization.  See
+                    <xref linkend="ref_guide_detach_state"/>
+                    on how the behavior changes based on the
+                    <literal>DetachedStateField</literal> setting along with
+                    how to override the default behavior.
+            </para>
+        </section>
         <section id="prePostUpdate">
             <title>
                 PreUpdate/PostUpdate Life Cycle Callbacks

Modified: openjpa/branches/1.3.x/openjpa-project/src/doc/manual/ref_guide_pc.xml
URL: http://svn.apache.org/viewvc/openjpa/branches/1.3.x/openjpa-project/src/doc/manual/ref_guide_pc.xml?rev=926255&r1=926254&r2=926255&view=diff
==============================================================================
--- openjpa/branches/1.3.x/openjpa-project/src/doc/manual/ref_guide_pc.xml (original)
+++ openjpa/branches/1.3.x/openjpa-project/src/doc/manual/ref_guide_pc.xml Mon Mar 22 19:01:47
2010
@@ -1411,6 +1411,61 @@ You can plug your custom proxy manager i
 </programlisting>
                 </example>
             </section>
+            <section id="ref_guide_pc_scos_proxy_serial">
+                <title>
+                    Serialization
+                </title>
+                <indexterm zone="ref_guide_pc_scos_proxy_serial">
+                    <primary>
+                        proxies
+                    </primary>
+                    <secondary>
+                        serialization
+                    </secondary>
+                </indexterm>
+                <indexterm zone="ref_guide_pc_scos_proxy_serial">
+                    <primary>
+                        proxies
+                    </primary>
+                    <secondary>
+                        DetachedStateField
+                    </secondary>
+                </indexterm>
+                <para>
+When objects are serialized, the <literal>DetachedStateField</literal> in
+section <xref linkend="ref_guide_detach_state"/>
+will be used to help determine when build time proxies will be removed.
+If runtime created proxies are being used (proxies not supplied by OpenJPA)
+or if an entity has already been detached, then any found proxies will be
+removed during serialization.
+                </para>
+                <itemizedlist>
+                    <listitem>
+                        <para>
+<literal>transient</literal>: 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 or the OpenJPA runtime.
+All proxies will be removed during serialization.  This is the default.
+                        </para>
+                    </listitem>
+                    <listitem>
+                        <para>
+<literal>true</literal>: 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 runtime.
+No OpenJPA provided proxies will be removed during serialization.
+                        </para>
+                    </listitem>
+                    <listitem>
+                        <para>
+<literal>false</literal>: Do not use a detached state field.
+All proxies will be removed during serialization.
+                        </para>
+                    </listitem>
+                </itemizedlist>
+            </section>
         </section>
         <section id="ref_guide_pc_extern">
             <title>

Modified: openjpa/branches/1.3.x/openjpa-project/src/doc/manual/ref_guide_remote.xml
URL: http://svn.apache.org/viewvc/openjpa/branches/1.3.x/openjpa-project/src/doc/manual/ref_guide_remote.xml?rev=926255&r1=926254&r2=926255&view=diff
==============================================================================
--- openjpa/branches/1.3.x/openjpa-project/src/doc/manual/ref_guide_remote.xml (original)
+++ openjpa/branches/1.3.x/openjpa-project/src/doc/manual/ref_guide_remote.xml Mon Mar 22
19:01:47 2010
@@ -249,89 +249,110 @@ When detached objects lose their associa
 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
-<link linkend="openjpa.DetachState"><literal>openjpa.DetachState</literal>
+facilities for automatically populating objects when they detach.
+            </para>
+            <section id="ref_guide_detach_state">
+                <title>
+                    Detached State
+                </title>
+                <indexterm zone="ref_guide_detach_state">
+                    <primary>
+                        detachment
+                    </primary>
+                    <secondary>
+                        detached state
+                    </secondary>
+                </indexterm>
+                <para>
+The <link linkend="openjpa.DetachState"><literal>openjpa.DetachState</literal>
 </link> configuration property determines which fields and relations are
 detached by default. All settings are recursive. They are:
-            </para>
-            <orderedlist>
-                <listitem>
-                    <para>
+                </para>
+                <orderedlist>
+                    <listitem>
+                        <para>
 <literal>loaded</literal>: Detach all fields and relations that are already
 loaded, but don't include unloaded fields in the detached graph. This is the
 default.
-                    </para>
-                </listitem>
-                <listitem>
-                    <para>
+                        </para>
+                    </listitem>
+                    <listitem>
+                        <para>
 <literal>fetch-groups</literal>: Detach all fields and relations in the current
 <link linkend="ref_guide_runtime">fetch configuration</link>. For more
 information on custom fetch groups, see <xref linkend="ref_guide_fetch"/>.
-                    </para>
-                </listitem>
-                <listitem>
-                    <para>
+                        </para>
+                    </listitem>
+                    <listitem>
+                        <para>
 <literal>all</literal>: 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!
-                    </para>
-                </listitem>
-            </orderedlist>
-            <para>
+                        </para>
+                    </listitem>
+                </orderedlist>
+                <para>
 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.
-            </para>
-            <para>
+                </para>
+                <para>
 The <literal>openjpa.DetachState</literal> option is actually a plugin string
 (see <xref linkend="ref_guide_conf_plugins"/>) that allows you to also
 configure the following options related to detached state:
-            </para>
-            <itemizedlist>
-                <listitem>
-                    <para>
+                </para>
+                <itemizedlist>
+                    <listitem>
+                        <para>
 <literal>DetachedStateField</literal>: As described in
 <xref linkend="ref_guide_attach_behavior"/> above, OpenJPA can take
 advantage of a <emphasis>detached state field</emphasis> 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:
-                    </para>
-                    <itemizedlist>
-                        <listitem>
-                            <para>
+                        </para>
+                        <itemizedlist>
+                            <listitem>
+                                <para>
 <literal>transient</literal>: 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.
-                            </para>
-                        </listitem>
-                        <listitem>
-                            <para>
+access to the enhanced versions of your classes or the OpenJPA runtime.
+This is the default.
+                                </para>
+                            </listitem>
+                            <listitem>
+                                <para>
 <literal>true</literal>: 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.
-                            </para>
-                        </listitem>
-                        <listitem>
-                            <para>
-<literal>false</literal>: Do not use a detached state field.
-                            </para>
-                        </listitem>
-                    </itemizedlist>
-                    <para>
+classes and the OpenJPA runtime.
+                                </para>
+                            </listitem>
+                            <listitem>
+                                <para>
+<literal>false</literal>: Do not use a detached state field. No OpenJPA runtime
+will be required for client tiers.
+                                </para>
+                            </listitem>
+                        </itemizedlist>
+                        <para>
+The detached state field is also used to determine when proxies should be
+removed from entities during serialization.  See the 
+<xref linkend="ref_guide_pc_scos_proxy_serial"/> section for more details.
+                        </para>
+                        <para>
 You can override the setting of this property or declare your own detached state
 field on individual classes using OpenJPA's metadata extensions. See
 <xref linkend="ref_guide_detach_field"/> below.
-                    </para>
-                </listitem>
-                <listitem>
-                    <para>
+                        </para>
+                    </listitem>
+                    <listitem>
+                        <para>
 <literal>DetachedStateManager</literal>: 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.
-                    </para>
-                    <para>
+                        </para>
+                        <para>
 This setting piggybacks on the <literal>DetachedStateField</literal> 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
@@ -342,46 +363,47 @@ setting this property to false, however,
 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.
-                    </para>
-                </listitem>
-                <listitem>
-                    <para>
+                        </para>
+                    </listitem>
+                    <listitem>
+                        <para>
 <literal>AccessUnloaded</literal>: 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.
-                    </para>
-                </listitem>
-            </itemizedlist>
-            <example id="ref_guide_detach_graph_confex">
-                <title>
-                    Configuring Detached State
-                </title>
+                        </para>
+                    </listitem>
+                </itemizedlist>
+                <example id="ref_guide_detach_graph_confex">
+                    <title>
+                        Configuring Detached State
+                    </title>
 <programlisting>
-&lt;property name="openjpa.DetachState" value="fetch-groups(DetachedStateField=true)"/&gt;
+    &lt;property name="openjpa.DetachState" value="fetch-groups(DetachedStateField=true)"/&gt;
 </programlisting>
-            </example>
-            <para>
+                </example>
+                <para>
 You can also alter the set of fields that will be included in the detached graph
 at runtime.
 <ulink url="../javadoc/org/apache/openjpa/persistence/OpenJPAEntityManager.html">
 <classname>OpenJPAEntityManager</classname></ulink>s expose the following
APIs
 for controlling detached state:
-            </para>
+                </para>
 <programlisting>
-public DetachStateType getDetachState();
-public void setDetachState(DetachStateType type);
+    public DetachStateType getDetachState();
+    public void setDetachState(DetachStateType type);
 </programlisting>
-            <para>
+                <para>
 The <classname>DetachStateType</classname> enum contains the following values:
-            </para>
+                </para>
 <programlisting>
-enum DetachStateType {
-    FETCH_GROUPS,
-    LOADED,
-    ALL
-}
+    enum DetachStateType {
+        FETCH_GROUPS,
+        LOADED,
+        ALL
+    }
 </programlisting>
+            </section>
             <section id="ref_guide_detach_field">
                 <title>
                     Detached State Field



Mime
View raw message