Author: schor
Date: Thu Jan 11 18:35:51 2018
New Revision: 1820906
URL: http://svn.apache.org/viewvc?rev=1820906&view=rev
Log:
[UIMA-5698] describe partial support for multiple type systems with common JCas
classes
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=1820906&r1=1820905&r2=1820906&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
Thu Jan 11 18:35:51 2018
@@ -185,7 +185,7 @@ under the License.
AutoClosable ll_enableV2IdRefs()
// same, but with explicit set or reset of the mode
-AutoClosable ll_enableV2IdRefs(true/false)
+AutoClosableNoException ll_enableV2IdRefs(true/false)
// return true if the mode is enabled
boolean is_ll_enableV2IdRefs()
@@ -194,10 +194,10 @@ boolean is_ll_enableV2IdRefs()
<para>Static LowLevelCas APIs for setting the default value for this mode
for new CASs on a particular thread:</para>
<programlisting>
// set the default
-AutoClosable LowLeveCas.ll_defaultV2IdRefs()
+AutoClosableNoException LowLeveCas.ll_defaultV2IdRefs()
// same, but with explicit set or reset of the mode
-AutoClosable LowLeveCas.ll_defaultV2IdRefs(true/false)
+AutoClosableNoException LowLeveCas.ll_defaultV2IdRefs(true/false)
// return true if the mode is enabled
boolean LowLeveCas.is_ll_defaultV2IdRefs()
@@ -381,4 +381,36 @@ boolean LowLeveCas.is_ll_defaultV2IdRefs
<code>CommonArray</code>. These changes are internal, and should not
affect users.
</para>
</section>
+
+ <section
id="uv3.backwards_compatibility.multiple_type_systems_with_common_jcas">
+ <title>Enabling multiple versions of type systems to work with a single
common JCas class</title>
+ <titleabbrev>Multi-TypeSystems single JCas</titleabbrev>
+
+ <para>Some applications may use a JCas class definition, defining for type
T features f1, f2, f3 (for example), in a mode
+ where under a single class loader (for example, in one Java
application), multiple CASs are loaded and processed,
+ where each CAS might have other versions of the type system, defining
for type T a subset of the features in the JCas.
+ </para>
+
+ <para>In order to make this scenario possible, v3 takes an extra step,
right before type system commit time, of
+ loading the JCas classes corresponding to the types, and then augmenting
the type definitions with additional
+ features defined in the JCas but not in the type description. After
this is done, the type system is committed,
+ and offsets are assigned to the JCas class that are constant, even when
a subsequent type system is loaded
+ that defines more features (provided that no new features are
introduced).</para>
+
+ <para>This feature represents a trade-off between highly efficient,
locked-down offsets for features, and
+ some limited flexibility to handle a somewhat common use case where
additional features exist in the JCas.
+ The JCas loading code always checks to insure compatibility between the
offsets in the JCas classes, as first set up,
+ and any subsequent type system being used with that JCas.
+ </para>
+
+ <para>This accommodation doesn't handle many possible scenarios. Some of
these include situations where a
+ supertype might subsequently add extra feature slots, or the features
end up after merging to have a different
+ ordering.</para>
+
+ <para>For cases where this accommodation is insufficient, the workaround
is to run separate UIMA applications, each
+ under its own class loader, for the incompatible situations.</para>
+
+ <para>PEARs, because they are loaded lazily after the type system has been
committed, do not support this kind of
+ augmentation of types from the Pear-specific JCas class
definition.</para>
+ </section>
</chapter>
\ No newline at end of file
