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>
<!--
*******************************************************************************
-->
