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>