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

[sc...@apache.org]

Author: schor
Date: Fri Jan 26 20:23:53 2018
New Revision: 1822343

URL: http://svn.apache.org/viewvc?rev=1822343&view=rev
Log:
[UIMA-5662] better document setting of v2 mode

Modified:
    uima/uv3/uimaj-v3/trunk/uima-docbook-v3-users-guide/src/docbook/uv3.backwards_compatibility.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=1822343&r1=1822342&r2=1822343&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 Jan 26 20:23:53 2018
@@ -156,25 +156,27 @@ under the License.
       are not eligible for garbage collection. 
     </para>
     
-    <para>This mode is set on individual CASs via a new API.  Once set on a CAS, it remains until set to a different value;
+    <para>This mode is set on individual CASs via a new API; a default value may optionally be specified.
+      Once set on a CAS, it remains until set to a different value;
       CAS Reset does not affect the setting, nor does checking it into / out of a CAS Pool.  
     </para>
     
-    <para>When a new CAS is created, this setting gets a default value, which comes from two sources:
+    <para>When a new CAS is created, this mode is set according to two sources:
       <itemizedlist>
         <listitem><para>a <code>-Duima.default_v2_id_references</code> system property, read once when the 
         UIMA framework classes are loaded.</para>
         </listitem>
-        <listitem><para>A setting called <code>defaultV2IdRefs</code>, kept per thread.  The 
+        <listitem><para>A run-time value kept per thread, managed by an API on the LowLevelCAS interface.  The 
           setting is inherited by any child threads the thread creates, and 
           overrides the system property if used.</para></listitem>
+        <listitem><para>If neither of these are used, then the default is to not be in the sepcial v2-mode.</para></listitem>
       </itemizedlist> 
     </para>
     
     <para>The APIs for this are part of the LowLevelCAS.  The controlling APIs all return an instance
-      of AutoClosable, which can be used to reset the setting to its previous value.
+      of AutoClosableNoException, which can be used to reset the setting to its previous value.
       A recommended way of using these is with the Java <code>try with resources</code> construct: 
-    <programlisting>try (AutoClosable w = llcas.ll_enableV2IdRefs) {
+    <programlisting>try (AutoClosableNoException w = llcas.ll_enableV2IdRefs) {
   ... some operations
 } // automatically restores previous value 
 </programlisting>