Author: schor Date: Tue Dec 19 18:52:21 2017 New Revision: 1818699 URL: http://svn.apache.org/viewvc?rev=1818699&view=rev Log: [UIMA-5662]
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.logging.xml uima/uv3/uimaj-v3/trunk/uima-docbook-v3-users-guide/src/docbook/uv3.migration.aids.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=1818699&r1=1818698&r2=1818699&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 Tue Dec 19 18:52:21 2017 @@ -137,6 +137,66 @@ under the License. </section> + <section id="uv3.backwards_compatibility.preserve_v2_ids"> + <title>Preserving V2 ids, with low level CAS Api accessibility</title> + <titleabbrev>Preserving V2 Ids</titleabbrev> + + <para> + Some V2 applications made use of the Feature Structure address, using these as an integer identifier + and using the low level CAS APIs to access the Feature Structure, given this integer. These applications also + used the stability of these ids across some serialization/deserializations. + </para> + + <para> + Normally in V3, deserialization of CASs having these ids occurs without preserving the ids, and without setting + up the low level CAS APIs to be able to access these using the integer IDs. If an existing application depends + on the low level access via the address, a special mode, called <code>id_to_fs_map mode</code>, can be specified, which will support this. + It comes at a cost however, which is that all new Feature Structures created (or deserialized) will be added to + an internal table to enable the low level CAS getFSForRef(int) method to work. As a result, these Feature Structures + will never be eligible for garbage collection. + </para> + + <para>This mode is set on individual CASs via a new API. It is also defaulted for all CASs by + the value of a system property, + which can be set using <code>-Duima.enable_id_to_feature_structure_map_for_all_fss</code>. + This mode supplies a default value for all CASs; each individual CAS can also specify a specific value + for this, which overrides. + + </para> + + <para>The APIs for programmatically setting this mode on a CAS instance are on the LowLevelCAS. The APIs are:</para> + <programlisting> +// set the mode, return a AutoClosable instance +// whose close() method resets the mode to its previous value +AutoClosable ll_enable_id_to_fs_map() + +// same, but with explicit set or reset of the mode +AutoClosable ll_enable_id_to_fs_map(true/false) + +// return true if the mode is enabled +boolean is_ll_enable_id_to_fs_map() +</programlisting> + <para>A recommended way of using this is with the Java try-with-resources construct:</para> + <programlisting>try (AutoClosable w = + llcas.ll_enable_id_to_fs_map) { + ... some operations +} // automatically restores previous value +</programlisting> + + <para>This mode modifies deserialization by having the newly created Feature structures + have IDs which match the serialized form ids (that is, the UIMA V2 "addresses"). + Serialized forms like Xmi and XCAS have the ids + included in the external form; other serialized forms impute the id from the ordering of the + serialized Feature Structures.</para> + + <para>New FSs created after deserialization will have addresses greater than the last deserialized one. + Furthermore, if this mode is still enabled, the id will match what the v2 address would have been. + (If the mode is not enabled, the v3 design assigns incrementing-by-1 ids to new Feature Structures.) + </para> + + <para>Note that this mode, once set on a CAS, is not affected by CAS reset.</para> + </section> + <section id="uv3.backwards_compatibility.PEARs"> <title>PEAR support</title> @@ -251,6 +311,7 @@ under the License. </para> </section> + <!-- Not implemented <section id="uv3.backwards_compatibility.deserializing_0_length"> <title>Deserializing 0 length items in a CAS</title> @@ -260,7 +321,8 @@ under the License. depending on object non-identity equality for these items. </para> </section> - + --> + <section id="uv3.backwards_compatibility.checking"> <title>Some checks moved to native Java</title> Modified: uima/uv3/uimaj-v3/trunk/uima-docbook-v3-users-guide/src/docbook/uv3.logging.xml URL: http://svn.apache.org/viewvc/uima/uv3/uimaj-v3/trunk/uima-docbook-v3-users-guide/src/docbook/uv3.logging.xml?rev=1818699&r1=1818698&r2=1818699&view=diff ============================================================================== --- uima/uv3/uimaj-v3/trunk/uima-docbook-v3-users-guide/src/docbook/uv3.logging.xml (original) +++ uima/uv3/uimaj-v3/trunk/uima-docbook-v3-users-guide/src/docbook/uv3.logging.xml Tue Dec 19 18:52:21 2017 @@ -136,8 +136,8 @@ under the License. <informaltable frame="all" rowsep="1" colsep="1"> <tgroup cols="2"> - <colspec colnum="1" colname="key" colwidth="1*"/> - <colspec colnum="2" colname="description" colwidth="3*"/> + <colspec colnum="1" colname="key" colwidth="3*"/> + <colspec colnum="2" colname="description" colwidth="5*"/> <spanspec spanname="fullwidth" namest="key" nameend="description" align="center"/> @@ -188,7 +188,7 @@ under the License. <title>Markers used in UIMA Java core logging</title> <note><para><emphasis role="bold">Not (yet) implemented; for planning purposes only.</emphasis></para></note> - + <!-- <para> Markers are used to group log calls associated with specific kinds of things together, so they can be enabled/disabled as a group. The Marker can also be included in a trace record. @@ -219,8 +219,10 @@ under the License. <entry><para>org.apache.uima.finest</para></entry> <entry><para>sub category of trace, corresponds to FINEST</para></entry> </row> - + --> <!-- ******************************************************************************* --> + + <!-- <row> <entry spanname="fullwidth"><emphasis role="bold">Markers used to classify some tracing logging</emphasis></entry> </row> @@ -262,6 +264,7 @@ under the License. </tbody> </tgroup> </informaltable> + --> </section> Modified: uima/uv3/uimaj-v3/trunk/uima-docbook-v3-users-guide/src/docbook/uv3.migration.aids.xml URL: http://svn.apache.org/viewvc/uima/uv3/uimaj-v3/trunk/uima-docbook-v3-users-guide/src/docbook/uv3.migration.aids.xml?rev=1818699&r1=1818698&r2=1818699&view=diff ============================================================================== --- uima/uv3/uimaj-v3/trunk/uima-docbook-v3-users-guide/src/docbook/uv3.migration.aids.xml (original) +++ uima/uv3/uimaj-v3/trunk/uima-docbook-v3-users-guide/src/docbook/uv3.migration.aids.xml Tue Dec 19 18:52:21 2017 @@ -92,7 +92,14 @@ under the License. <para>In version 3, normally, Feature Structures are not added to the map used by the Low Level CAS API to map from int ids to Feature Structures. This has the benefit that no longer referenced Feature Structures may be - garbaged collected. This behavior may be overridden by this property.</para></entry> + garbaged collected. This behavior may be overridden by this property.</para> + <para>This property supplies default values, per CAS, for that CAS's + <code>ll_enable_id_to_fs_map</code> mode. This mode is programmatically + settable, which overrides the default. The mode changes how + Feature Structures are created, serialized, and deserialized, all in an + effort to make V2 code that uses low level CAS Apis and <code>ll_getFSForRef</code> + methods continue to work; see the backwards compatibility section for details.</para> + </entry> </row> <!-- ******************************************************************************* -->