+ Serialization of Entities +

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 + + + + proxies + + + serialization + + + + + proxies + + + DetachedStateField + + + +When objects are serialized, the DetachedStateField in +section +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. + + + + +transient: 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. + + + + +true: 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. + + + + +false: Do not use a detached state field. +All proxies will be removed during serialization. + + + +

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 + + + + detachment + + + detached state + + + +The openjpa.DetachState configuration property determines which fields and relations are detached by default. All settings are recursive. They are: - - - - + + + + loaded: Detach all fields and relations that are already loaded, but don't include unloaded fields in the detached graph. This is the default. - - - - + + + + fetch-groups: Detach all fields and relations in the current fetch configuration. For more information on custom fetch groups, see . - - - - + + + + all: 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! - - - - + + + + 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. - - + + The openjpa.DetachState option is actually a plugin string (see ) that allows you to also configure the following options related to detached state: - - - - + + + + DetachedStateField: As described in above, OpenJPA can take advantage of a detached state field 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: - - - - + + + + transient: 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. - - - - +access to the enhanced versions of your classes or the OpenJPA runtime. +This is the default. + + + + true: 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. - - - - -false: Do not use a detached state field. - - - - +classes and the OpenJPA runtime. + + + + +false: Do not use a detached state field. No OpenJPA runtime +will be required for client tiers. + + + + +The detached state field is also used to determine when proxies should be +removed from entities during serialization. See the + section for more details. + + You can override the setting of this property or declare your own detached state field on individual classes using OpenJPA's metadata extensions. See below. - - - - + + + + DetachedStateManager: 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. - - + + This setting piggybacks on the DetachedStateField 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. - - - - + + + + AccessUnloaded: 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. - - - - - - Configuring Detached State - + + + + + + Configuring Detached State + -<property name="openjpa.DetachState" value="fetch-groups(DetachedStateField=true)"/> + <property name="openjpa.DetachState" value="fetch-groups(DetachedStateField=true)"/> - - + + You can also alter the set of fields that will be included in the detached graph at runtime. OpenJPAEntityManagers expose the following APIs for controlling detached state: - + -public DetachStateType getDetachState(); -public void setDetachState(DetachStateType type); + public DetachStateType getDetachState(); + public void setDetachState(DetachStateType type); - + The DetachStateType enum contains the following values: - + -enum DetachStateType { - FETCH_GROUPS, - LOADED, - ALL -} + enum DetachStateType { + FETCH_GROUPS, + LOADED, + ALL + } +