You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@uima.apache.org by sc...@apache.org on 2016/11/13 16:11:59 UTC
svn commit: r1769511 -
/uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/uv3.backwards_compatibility.xml
Author: schor
Date: Sun Nov 13 16:11:59 2016
New Revision: 1769511
URL: http://svn.apache.org/viewvc?rev=1769511&view=rev
Log:
[UIMA-5137] clarify backwards compatibility for v3
Modified:
uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/uv3.backwards_compatibility.xml
Modified: uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/uv3.backwards_compatibility.xml
URL: http://svn.apache.org/viewvc/uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/uv3.backwards_compatibility.xml?rev=1769511&r1=1769510&r2=1769511&view=diff
==============================================================================
--- uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/uv3.backwards_compatibility.xml (original)
+++ uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/uv3.backwards_compatibility.xml Sun Nov 13 16:11:59 2016
@@ -27,8 +27,14 @@ under the License.
<title>Backwards Compatibility</title>
<titleabbrev>Backwards Compatibility</titleabbrev>
- <para>Version 3 is designed to be backwards compatible, except for needing a new set of JCas classes (if these were
- previously being used).</para>
+ <para>The UIMA project realizes that many users have made substantial investment in developing
+ applications using this framework. One of our goals is to protect this investment, by enabling
+ Annotators and applications developed under previous versions to be able to be used in
+ subsequent versions of the framework.</para>
+
+ <para>To this end, version 3 is designed to be backwards compatible, except for needing a new set of JCas classes (if these were
+ previously being used). There is a migration tool to handle the upgrading of the JCas classes, described in
+ a later chapter.</para>
<section id="uv3.backwards_compatibility.serialization">
<title>Serialization forms</title>
@@ -38,12 +44,12 @@ under the License.
possible to have a UIMA-AS services working with a client, where the client is a version 3 instance, but the
server is still a version 2 (or vice versa).</para>
- <para>Exception: Formats like Binary and BinaryCompressedForm4 require the type systems match exactly.
- Version 3 adds some new built-in types, so the type systems won't match exactly. An accommodation is made
- when the version 3 deserialization detects that the serialized CAS was serialized with version 2, so
- version 3 is able to load version 2 serialized CASs, even for binary formats. A planned extension for
+ <para>Some formats like Binary and BinaryCompressedForm4 require the type systems match exactly.
+ Version 3 adds some new built-in types, so the type systems won't match exactly; an accommodation is made
+ when the version 3 deserialization detects that the serialized CAS was serialized with version 2, that
+ enables version 3 to load version 2 serialized CASs, even for binary formats. A planned extension for
UIMA-AS will allow version 3 clients to detect when a service is running version 2 code, and have the
- serialization altered to be compatible with version 2 (provided new built-in types are not being used).
+ serialization altered to be compatible with version 2 (provided that the new, built-in, types are not being used).
</para>
</section>
@@ -59,12 +65,11 @@ under the License.
<para>In Version 3 these APIs are still supported, but are no longer higher performance, and should be avoided.
The APIs only remain for backwards compatibility. An example of this is the Binary Serialization protocol. This
- remains, for backward compatibility, and because it's used for the <code>C/C++</code> interoperability layer,
- but that use requires modeling the exact layout of how Version 2 stored CASs and converting between these two
- forms, so it is not particularly efficient.</para>
+ remains, for backward compatibility, and because it's used for the <code>C/C++</code> interoperability layer.
+ </para>
- <para>One consequence of the move toward storing Feature Structures as
- Java objects, is that the low level Feature Structure creation APIs (which return an int handle)
+ <para>One consequence of the representing Feature Structures as
+ Java objects is that the low level Feature Structure creation APIs (which return an int handle)
must create an artificial reference to the Java object to keep it from being Garbage Collected (GC'd).
</para>
</section>
@@ -74,8 +79,9 @@ under the License.
<para>Pears are supported in Version 3. If they use JCas, their JCas classes need to be migrated.
</para>
- <para>The new Java Object support does not support multiple JCas class definitions for the same
- UIMA Type, inside and outside of the PEAR context. When this is detected, an exception is thrown.</para>
+
+ <para>The new Java Object support does not support multiple, different JCas class definitions for the same
+ UIMA Type, inside and outside of the PEAR context. If this is detected, a runtime exception is thrown.</para>
</section>
<section id="uv3.backards_compatibility.typesystem_sharing">