svn commit: r1812137 - in /uima/uv3/uimaj-v3/trunk/uima-docbook-v3-users-guide/src/docbook: uv3.backwards_compatibility.xml uv3.new_extended_apis.xml

[sc...@apache.org]

Author: schor
Date: Fri Oct 13 14:55:44 2017
New Revision: 1812137

URL: http://svn.apache.org/viewvc?rev=1812137&view=rev
Log:
no Jira clarify another use case for typesystem commit backwards compatibility.  minor update to extended apis chapter

Modified:
    uima/uv3/uimaj-v3/trunk/uima-docbook-v3-users-guide/src/docbook/uv3.backwards_compatibility.xml
    uima/uv3/uimaj-v3/trunk/uima-docbook-v3-users-guide/src/docbook/uv3.new_extended_apis.xml

Modified: uima/uv3/uimaj-v3/trunk/uima-docbook-v3-users-guide/src/docbook/uv3.backwards_compatibility.xml
URL: http://svn.apache.org/viewvc/uima/uv3/uimaj-v3/trunk/uima-docbook-v3-users-guide/src/docbook/uv3.backwards_compatibility.xml?rev=1812137&r1=1812136&r2=1812137&view=diff
==============================================================================
--- uima/uv3/uimaj-v3/trunk/uima-docbook-v3-users-guide/src/docbook/uv3.backwards_compatibility.xml (original)
+++ uima/uv3/uimaj-v3/trunk/uima-docbook-v3-users-guide/src/docbook/uv3.backwards_compatibility.xml Fri Oct 13 14:55:44 2017
@@ -228,21 +228,27 @@ under the License.
     <title>Type System sharing</title>   
     
     <para>Type System definitions are shared when they are equal.  After type systems 
-    have been built up from type definitions, and are committed, a check is made to see if an
-    identical type system already exists.  This is often the case when a UIMA application is
+    have been built up from type definitions, at "commit" time, a check is made to see if an
+    identical type system already exists (same types and features).  
+    This is often the case when a UIMA application is
     scaling up by adding multiple pipelines, all using the same type system.  
     </para>
     
-    <para>If an identical type system is already created, then the commit operation returns 
-    the already created one, and the one just built is discarded.  Normally, this is not an issue.
-    However, some application code (for example, test cases) may construct type systems
-    programmatically, and along the way save references to defined types and features.  These
-    references can then become invalid when the type system is created and perhaps replaced with
-    an already existing one.</para>
+    <para>If an identical committed type system already exists, then the commit operation returns 
+    it, and the one just built is discarded.  Normally, this is not an issue.
+    However, some application code may save references to the type system object or to defined types and features.  
+    These references end up pointing to the discarded version, when the commit operation finds an already 
+    committed equal version.</para>
     
-    <para>Application code may code around this by re-acquiring references to type and feature
+    <para>Application code may code around this by re-acquiring references to the type system object, and to any type and feature
     objects, if the type system instance object returned from <code>commit</code> is not identical (==) to the
-    one being committed.</para>
+    one being committed.
+    The type system commit APIs are changed to return the type system - either the one being committed, or an
+    already existing equal committed type system.  So when coding
+    <code>myTypesystem.commit();</code> if you later refer to <code>myTypesystem</code>, change this to
+    <code>myTypesystem = myTypesystem.commit();</code>, to keep the variable <code>myTypesystem</code> always
+    referring to to the committed type system.
+    </para>
   </section>
   
   <section id="uv3.backwards_compatibility.checking">

Modified: uima/uv3/uimaj-v3/trunk/uima-docbook-v3-users-guide/src/docbook/uv3.new_extended_apis.xml
URL: http://svn.apache.org/viewvc/uima/uv3/uimaj-v3/trunk/uima-docbook-v3-users-guide/src/docbook/uv3.new_extended_apis.xml?rev=1812137&r1=1812136&r2=1812137&view=diff
==============================================================================
--- uima/uv3/uimaj-v3/trunk/uima-docbook-v3-users-guide/src/docbook/uv3.new_extended_apis.xml (original)
+++ uima/uv3/uimaj-v3/trunk/uima-docbook-v3-users-guide/src/docbook/uv3.new_extended_apis.xml Fri Oct 13 14:55:44 2017
@@ -299,9 +299,9 @@ public final static String _FeatName_sof
   <section id="uv3.new_extended_apis.other">
     <title>Other changes</title>
     
-    <para>The convenience methods in the JCas have been duplicated in the CAS, including <code>getAllIndexFS</code>.</para>
+    <para>The convenience methods in the JCas have been duplicated in the CAS, e.g. <code>getAllIndexFS</code>.</para>
     
-    <para>New methods <code>getIndexedFSs(Type)</code> and <code>getIndexedFSs(MyJCas.class)</code> return 
+    <para>New methods <code>getIndexedFSs(myUimaType)</code> and <code>getIndexedFSs(MyJCas.class)</code> return 
     unmodifiable, unordered Collections of all indexed Feature Structures of the specified type and its subtypes in 
     this CAS's view.  This collection can be
     used in a Java extended-for loop construction. <code>getIndexedFSs()</code> is the same but is for all Feature Structures,
@@ -313,9 +313,6 @@ public final static String _FeatName_sof
       user-specified JCas classes associated with the type system.  If not specified, it defaults to the class
       loader used to load the UIMA framework.
     </para>
-      
-    <para>The CAS interface has additional convenience method to get the Annotation index:  <code>getAnnotationIndex()</code>.
-    </para>
         
     <para>The utility class <code>org.apache.uima.util.FileUtils</code> has a new method
       <code>writeToFile(path, string)</code>, which efficiently writes a string using UTF-8 encoding to