svn commit: r1772790 - /uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/uv3.backwards_compatibility.xml

[sc...@apache.org]

Author: schor
Date: Mon Dec  5 20:36:40 2016
New Revision: 1772790

URL: http://svn.apache.org/viewvc?rev=1772790&view=rev
Log:
[UIMA-4663] document throwing exception for delta cas in v2 format being deserialized by v3

Modified:
    uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/uv3.backwards_compatibility.xml

Modified: uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/uv3.backwards_compatibility.xml
URL: http://svn.apache.org/viewvc/uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/uv3.backwards_compatibility.xml?rev=1772790&r1=1772789&r2=1772790&view=diff
==============================================================================
--- uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/uv3.backwards_compatibility.xml (original)
+++ uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/uv3.backwards_compatibility.xml Mon Dec  5 20:36:40 2016
@@ -52,6 +52,21 @@ under the License.
 	  serialization altered to be compatible with version 2 (provided that the new, built-in, types are not being used).
 	  </para>
 	  
+	  <section id="uv3.backwards_compatibility.serialization.deltas">  
+	    <title>Delta CAS Version 2 Binary deserialization not supported</title>
+	    
+	    <para>The binary serialization forms, including Compressed Binary Form 4, build an
+	      internal model of the v2 CAS in order to be able to deserialize v2 generated
+	      versions.  For delta CAS, this model cannot be accurately built, because version 3
+	      excludes from the model all unreachable Feature Structures, so in most cases it
+	      won't match the version 2 layout.  
+	    </para>
+	    
+	    <para>Version 3 will throw an exception if delta CAS deserialization of a version 2
+	      delta CAS is attempted.
+	    </para>
+    </section>
+	  
   </section>
   
   <section id="uv3.backards_compatibility.low_level_apis">
@@ -80,8 +95,37 @@ under the License.
     <para>Pears are supported in Version 3.  If they use JCas, their JCas classes need to be migrated.
     </para>
     
-    <para>The new Java Object support does not support multiple, different JCas class definitions for the same 
-      UIMA Type, inside and outside of the PEAR context.  If this is detected, a runtime exception is thrown.</para>
+    <para>When a PEAR contains a JCas class definition different from the surrounding non-PEAR context,
+    each Feature Structure instance within that PEAR has a lazily-created "dual" representation using
+    the PEAR's JCas class definition.  The UIMA framework things storing references to Feature Structures
+    are modified to store the non-PEAR version of the Feature Structure, but to return (when in 
+    a particular PEAR component in the pipeline) the dual version.  The intent is that this be 
+    "invisible" to the PEAR's annotators.  Both of these representations share the same 
+    underlying CAS data, so modifications to one are seen in the other.
+    </para>
+    
+    <para>If a user builds code that holds onto Feature Structure references, outside of 
+    annotators (e.g., as a shared External Resource), and sets and references these from
+    both outside and inside one (or more) PEARs, they should adopt a strategy of storing
+    the non-PEAR form.  To get the non-PEAR form from a Feature Structure, use the method
+    <code>myFeatureStructure._maybeGetBaseForPearFs()</code>.
+    </para>
+    
+    <blockquote><para>Similarly, if code running in an Annotator within a PEAR wants to
+    work with a Feature Structure extracted from non-UIMA managed data outside of annotators
+    (e.g., such as a shared External Resource) where the form stored is the non-PEAR form,
+    you can convert to the PEAR form using the method 
+    <code>myFeatureStructure.__maybeGetPearFs()</code>.  This method checks to see if
+    the processing context of the pipeline is currently within a PEAR, and if that PEAR has
+    a different definition for that JCas class, and if so, it returns that version of the
+    Feature Structure. 
+    </para></blockquote>
+    
+    <para>The new Java Object support does not support multiple, 
+      different JCas class definitions for the same 
+      UIMA Type, inside and outside of the PEAR context.  
+      If this is detected, a runtime exception is thrown.
+    </para>
   </section>
   
   <section id="uv3.backards_compatibility.typesystem_sharing">