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/12/21 18:50:39 UTC
svn commit: r1775528 - in
/uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook:
uv3.backwards_compatibility.xml uv3.migration.xml uv3.new_extended_apis.xml
version_3_users_guide.xml
Author: schor
Date: Wed Dec 21 18:50:39 2016
New Revision: 1775528
URL: http://svn.apache.org/viewvc?rev=1775528&view=rev
Log:
[UIMA-5137] doc update - fix spelling in include, update bkwds compat, migration tooling, add new or extended APIs section
Modified:
uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/uv3.backwards_compatibility.xml
uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/uv3.migration.xml
uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/uv3.new_extended_apis.xml
uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/version_3_users_guide.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=1775528&r1=1775527&r2=1775528&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 Wed Dec 21 18:50:39 2016
@@ -34,9 +34,30 @@ under the License.
<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. The JCas class changes include no longer needing, using, or supporting the <code>Xyz_Type</code>
- sister classes for each main JCas class. Methods in the JCas API that gave access to these class instances
- have been removed.</para>
+ a later chapter.
+ </para>
+
+ <section id="uv3.backwards_compatibility.jcas">
+ <title>JCas and non-JCas APIs</title>
+
+ <para>The JCas class changes include no longer needing, using, or supporting the <code>Xyz_Type</code>
+ sister classes for each main JCas class. Methods in the JCas API that gave access to these class instances
+ have been removed. New internal-use methods and fields have been added to the JCas classes. The
+ names for these have been carefully designed to reduce the likelihood of collision with previously
+ existing user code names; the usual technique is to start the names with a leading underscore character.
+ Users should consider these methods as internal use and subject to change with new releases.
+ </para>
+
+ <para>The specialized non-JCas Java cover classes for built-in types have been removed;
+ these were unlikely to have been used. If used, the update is to replace these with their
+ JCas class equivalents. For example, if you used <code>AnnotationImpl</code>, replace with
+ <code>Annotation</code>.
+ </para>
+
+
+
+ </section>
+
<section id="uv3.backwards_compatibility.serialization">
<title>Serialization forms</title>
@@ -165,4 +186,23 @@ under the License.
objects, if the type system returned from <code>commit</code> is not identical (==) to the
one being committed.</para>
</section>
+
+ <section id="uv3.backards_compatibility.checking">
+ <title>Some checks moved to native Java</title>
+
+ <para>In the interest of performance, some duplicate checks, such as whether an array index is within bounds,
+ have been removed from UIMA when they are already being checked by the underlying Java runtime.
+ This has affected some of the internal APIs, such as the JCas's <code>checkArrayBounds</code>
+ which was removed because it was no longer being used.
+ </para>
+ </section>
+
+ <section id="uv3.backards_compatibility.class_hierarchy">
+ <title>Some class hierarchies have been modified</title>
+
+ <para>The various JCas Classes implementing the built-ins for arrays have some additional
+ interfaces added, grouping them into <code>CommonPrimitiveArray</code> or
+ <code>CommonArray</code>. These changes are internal, and should not affect users.
+ </para>
+ </section>
</chapter>
\ No newline at end of file
Modified: uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/uv3.migration.xml
URL: http://svn.apache.org/viewvc/uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/uv3.migration.xml?rev=1775528&r1=1775527&r2=1775528&view=diff
==============================================================================
--- uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/uv3.migration.xml (original)
+++ uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/uv3.migration.xml Wed Dec 21 18:50:39 2016
@@ -24,8 +24,8 @@ specific language governing permissions
under the License.
-->
<chapter id="uv3.migration">
- <title>Migrating from Version 2 to 3</title>
- <titleabbrev>Migrating</titleabbrev>
+ <title>Migrating JCas classes from Version 2 to 3</title>
+ <titleabbrev>Migrating JCas</titleabbrev>
<para>To migrate a UIMA application / pipeline to version 3, you need to replace the Version 2 JCas
classes with version 3 classes. This is best done by running the migration tool, which is available
@@ -42,8 +42,7 @@ under the License.
If all is OK, the migration will say that it "finished with no unusual conditions", at the end.
</para></blockquote>
- <para>To complete the migration, do any packaging you wish to the converted JCas files
- and update your UIMA application to use these classes in place of the version 2 JCas classes.
+ <para>To complete the migration, update your UIMA application to use these classes in place of the version 2 JCas classes.
</para>
<para>The migration tool is able to scan multiple directory trees, looking for existing Java
@@ -80,11 +79,12 @@ under the License.
-->
<note><para>The compilation step (done after the source-to-source transformation) requires that a Java compiler is available
- (which is the case if you're running with a Java JDK, not a JRE).
+ (which will be the case if you're running with a Java JDK, not a JRE).
</para></note>
- <note><para>After running the tool, it is important to confirm that the migration completed without any unusual conditions, by
- examining the console output and logs.
+ <note><para>After running the tool, it is important to examining the console output and logs.
+ You can confirm that the migration completed without any unusual conditions, or, if something
+ unusual was encountered, you can take corrective action.
</para></note>
<section id="uv3.migration.tool_guide.running">
@@ -94,65 +94,97 @@ under the License.
If you run this without any arguments, it will show a brief help for the arguments.
</para>
- <para>There is also an Eclipse launch configuration, which is available if you have the uimaj-examples project
- in your Eclipse workspace. This is used by selecting a project whose class path is the one needed by the
- JCas definitions to be migrated, and then launching "UIMA run V3 migrate JCas from classes roots" and following
- the two prompts - one to enter a directory which is the root directory of the JCas classes to be converted, and
- another directory to use as the output directory; these two inputs are "prompted" for by this Eclipse launcher.
- </para>
-
- <para>No matter how the tool is started, the input to the tool is one or more directory tree roots;
- the tool will scan the file system under these roots (including inside Jars and PEARs),
- looking for definitions to migrate.
- </para>
+ <para>There are also a pair of Eclipse launch configuration, which are available if you have the uimaj-examples project
+ (included in the binary distribution of UIMA) in your Eclipse workspace.
+ </para>
+
+ <section id="uv3.migration.tool_guide.running.eclipse">
+ <title>Using Eclipse to run the migration tool</title>
+
+ <para>There are two Eclipse launch configurations; one works with source code, the other with compiled classes
+ or Jars or PEARs. The launch configurations are named:
+ <itemizedlist spacing="compact">
+ <listitem><para>UIMA Run V3 migrate JCas from sources roots</para></listitem>
+ <listitem><para>UIMA Run V3 migrate JCas from classes roots</para></listitem>
+ </itemizedlist>
+ When running from classes roots, the classes must not have compile errors, and may contain Jars and PEARs.
+ </para>
+
+ <para>
+ To use these launchers,
+ <itemizedlist spacing="compact">
+ <listitem><para>First select the eclipse project; this project's "build path" will supply the
+ classpath used during migration for decompiling and compiling the sources.</para></listitem>
+ <listitem><para>run the launcher - it will prompt for two values:
+ <itemizedlist spacing="compact">
+ <listitem><para>the root directory to scan recursively looking for JCas sources or classes/Jars/Pears to be converted</para></listitem>
+ <listitem><para>an output directory - a writable folder, such as /temp/migrate</para></listitem>
+ </itemizedlist>
+ </para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>No matter how the tool is started, the input to the tool is one or more directory tree roots;
+ the tool will scan the file system under these roots (including inside Jars and PEARs when running from
+ compiled classes), looking for definitions to migrate.
+ </para>
<!-- <blockquote><para>It can also be run with a list of specific JCas classes
to migrate.</para></blockquote> -->
-
- <section id="uv3.migration.tool_guide.running.inputs">
- <title>Specifying input sources</title>
-
- <para>Input is specified using these arguments:
- <variablelist>
-
- <varlistentry>
- <term><emphasis role="strong">"-sourcesRoots"</emphasis></term>
- <listitem>
- <para>a list of one or more directories, separated by the
- a path separator character (";" for Windows, ":" for others).
- </para>
- <para>Migrates each candidate source file found in any of the file tree roots,
- skipping over non-JCas classes.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis role="strong">"-classesRoots"</emphasis></term>
- <listitem>
- <para>a list of one or more directories or Jars or PEARs, separated by the
- a path separator character (";" for Windows, ":" for others).
- </para>
- <para>Decompiles, then migrates each candidate class file found in any of the file tree roots
- (skipping over non-JCas classes).
- </para>
- </listitem>
- </varlistentry>
-
- </variablelist>
- </para>
+
</section>
-
- <section id="uv3.migration.tool_guide.classpath">
- <title>Specifying a classpath for the migration</title>
- <para>A classpath is required for the proper operation of the decompiling and compiling steps of
- the migration. This is provided using the argument <code>-migrateClasspath</code>.
- The Eclipse launcher "UIMA run V3 migrate JCas from classes roots" sets this argument using
- the selected Eclipse project's classpath.
- When migrating within a PEAR, the migration tool automatically adds the PEAR classes to the
- classpath.
- </para>
- </section>
-
+
+
+ <section id="uv3.migration.tool_guide.running.cmd_line">
+ <title>Running from the command line</title>
+
+ <section id="uv3.migration.tool_guide.running.inputs">
+ <title>Command line: Specifying input sources</title>
+
+ <para>Input is specified using these arguments:
+ <variablelist>
+
+ <varlistentry>
+ <term><emphasis role="strong">"-sourcesRoots"</emphasis></term>
+ <listitem>
+ <para>a list of one or more directories, separated by the
+ a path separator character (";" for Windows, ":" for others).
+ </para>
+ <para>Migrates each candidate source file found in any of the file tree roots,
+ skipping over non-JCas classes.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="strong">"-classesRoots"</emphasis></term>
+ <listitem>
+ <para>a list of one or more directories
+ containing class files or Jars or PEARs, separated by the
+ a path separator character (";" for Windows, ":" for others).
+ </para>
+ <para>Decompiles, then migrates each candidate class file found in any of the file tree roots
+ (skipping over non-JCas classes).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </para>
+ </section>
+
+ <section id="uv3.migration.tool_guide.classpath">
+ <title>Command line: Specifying a classpath for the migration</title>
+ <para>A classpath is required for the proper operation of the decompiling and compiling steps of
+ the migration. This is provided using the argument <code>-migrateClasspath</code>.
+ The Eclipse launcher "UIMA run V3 migrate JCas from classes roots" sets this argument using
+ the selected Eclipse project's classpath.
+ When migrating within a PEAR, the migration tool automatically adds the PEAR classes to the
+ classpath.
+ </para>
+ </section>
+
+ </section>
+
<section id="uv3.migration.tool_guide.duplicates">
<title>Handling duplicate definitions</title>
<para>Sometimes, a classpath or directory tree may contain multiple instances of the same JCas class.
@@ -177,7 +209,7 @@ under the License.
</para>
<blockquote><para>
- These are arranged in parallel directories, allowing Eclipse's "compare" to work on both directory
+ These are arranged in parallel directories, allowing Eclipse's multi-file directory "compare" to work on both directory
collections and conveniently show for all the migrated files the change details.
</para></blockquote>
Modified: uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/uv3.new_extended_apis.xml
URL: http://svn.apache.org/viewvc/uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/uv3.new_extended_apis.xml?rev=1775528&r1=1775527&r2=1775528&view=diff
==============================================================================
--- uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/uv3.new_extended_apis.xml (original)
+++ uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/uv3.new_extended_apis.xml Wed Dec 21 18:50:39 2016
@@ -27,6 +27,25 @@ under the License.
<title>New and Extended APIs</title>
<titleabbrev>New/Extended APIs</titleabbrev>
+ <section id="uv3.new_extended_apis.jcas_static_fields">
+ <title>JCas additional static fields</title>
+
+ <para>(Also in UIMA Version 2 after release 2.10.0) Static final string fields are declared for each JCas cover class
+ and for each feature that is part of that UIMA type. The fields look like
+ this example, taken from the Sofa class:
+ <programlisting>public final static String _TypeName = "org.apache.uima.jcas.cas.Sofa";
+public final static String _FeatName_sofaNum = "sofaNum";
+public final static String _FeatName_sofaID = "sofaID";
+public final static String _FeatName_mimeType = "mimeType";
+public final static String _FeatName_sofaArray = "sofaArray";
+public final static String _FeatName_sofaString = "sofaString";
+public final static String _FeatName_sofaURI = "sofaURI";</programlisting>
+ Each string has a generated name corresponding to the name of the type or the feature, and
+ a string value constant which of the type or feature name. These can be useful in
+ Java Annotations.
+ </para>
+ </section>
+
<section id="uv3.new_extended_apis.java8">
<title>Java 8 integrations</title>
@@ -53,41 +72,109 @@ under the License.
</para>
</section>
+ </section>
+
+ <section id="uv3.new_extended_apis.fsiterator_implements_list">
+ <title>UIMA FSIterators improvements</title>
+
+ <para>To enable more seamless integration with popular Java idioms, the UIMA iterators for iterating
+ over UIMA Indexes (the FSIterator interface) now implements the Java ListIterator Interface.
+ </para>
+
+ <para>The iterators over indexes no longer throw concurrent modification exceptions if the index is modified
+ while it is being iterated over. Instead, the iterators use a lazily-created copy-on-write approach that, when
+ some portion of the index is updated, prior to the update, copies the original state of that portion, and continues
+ to iterate over that. While this is helpful if you are explicitly modifying the indexes in a loop, it
+ can be especially helpful when modifying Feature Structures as you iterate, because
+ the UIMA support for detecting and avoiding possible index corruption if you modify some feature being used by
+ some index as a key, is automatically (under the covers) temporarily removing the Feature Structure from indexes,
+ doing the modification, and then adding it back.
+ </para>
+ </section>
- <section id="uv3.new_extended_apis.fsiterator_implements_list">
- <title>UIMA FSIterators improvements</title>
-
- <para>To enable more seamless integration with popular Java idioms, the UIMA iterators for iterating
- over UIMA Indexes (the FSIterator interface) now implements the Java List Interface.
- </para>
-
- <para>The iterators over indexes no longer throw concurrent modification exceptions if the index is modified
- while it is being iterated over. Instead, the iterators use a lazily-created copy-on-write approach that, when
- some portion of the index is updated, prior to the update, copies the original state of that portion, and continues
- to iterate over that. While this is helpful if you are explicitly modifying the indexes in a loop, it
- can be especially helpful when modifying Feature Structures as you iterate, because
- the UIMA support for detecting and avoiding possible index corruption if you modify some feature being used by
- some index as a key, is automatically (under the covers) temporarily removing the Feature Structure from indexes,
- doing the modification, and then adding it back.
+ <section id="uv3.new_extended_apis.select">
+ <title>New Select API</title>
+
+ <para>A versatile new Select framework for accessing and acting on Feature Structures
+ selected from the CAS or from Indexes or from other collection objects is documented in
+ a separate chapter. This API is integrated with Java 8's Stream facility.
+ </para>
+ </section>
+
+ <section id="uv3.new_extended_apis.custom_java_objects">
+ <title>New custom Java objects in the CAS framework</title>
+
+ <para>There is a new framework that supports allowing you to add your own custom Java objects as
+ objects transportable in the CAS. The following chapter describes this facility, and some new
+ built-in types that make use of it.
+ </para>
+ </section>
+
+ <section id="uv3.new_extended_apis.lists_and_arrays">
+ <title>Built-in lists and arrays</title>
+
+ <para>
+ A new set of static methods on UIMA built-in lists and arrays, <code>create(jcas, array_source)</code>
+ is available; these take a Java array of items, and creates
+ a corresponding UIMA built-in list or array populated with items from the array_source.
+ </para>
+
+ <para>For lists, new static methods <code>getEmptyList(JCas jcas)</code> on each of the 4
+ kinds of built-in lists (FS, Integer, Float, and String) retrieve a
+ shared, common instance of the EmptyXxxList for a CAS.
+ </para>
+
+ <para>For lists, a new <code>push(item)</code> API on an existing list node creates a new
+ non-empty node, sets its head to <code>item</code> and its tail to the existing list node.
+ This allows easy construction of a list in backwards order.
+ There is also a <code>pushNode()</code> which just creates and links in a new node to the front of the list.
+ And finally, there's a <code>createNonEmptyNode()</code>, which just creates a node of the
+ same type, in the same CAS, without linking it.</para>
+
+ <section id="uv3.new_extended_apis.reorganized.lists_and_arrays">
+ <title>Built-in lists and arrays have common super classes / interfaces</title>
+ <para>Some methods common to multiple implements were moved to the super classes,
+ some classes were made abstract (to prevent them from being instantiated, which would be an error).
+ For arrays, a new method common to all arrays, <code>copyValuesFrom()</code> copies values from arrays of the same type.
+ </para>
+ </section>
+ </section>
+
+ <section id="uv3.new_extended_apis.annotation">
+ <title>Annotation comparator methods</title>
+
+ <para>The built-in type Annotation has multiple new methods to allow comparing two annotations.
+ The first method uses
+ the standard annotation comparator (two keys: begin (ascending) and end (descending)).
+ A second method adds a 3rd key, the linear type order.
+ Another two methods extend these two methods with an additional key - the Annotation's ID.
+ All of these return the standard Java compare result allowing discrimination between equal, >, and <.
</para>
- </section>
+ </section>
- <section id="uv3.new_extended_apis.select">
- <title>New Select API</title>
-
- <para>A versatile new Select framework for accessing and acting on Feature Structures
- selected from the CAS or from Indexes or from other collection objects is documented in
- a separate chapter. This API is integrated with Java 8's Stream facility.
- </para>
- </section>
+ <section id="uv3.new_extended_apis.reorganized">
+ <title>Reorganized APIs</title>
- <section id="uv3.new_extended_apis.custom_java_objects">
- <title>New custom Java objects in the CAS framework</title>
-
- <para>There is a new framework that supports allowing you to add your own custom Java objects as
- objects transportable in the CAS. The following chapter describes this facility, and some new
- built-in types that make use of it.
- </para>
- </section>
- </section>
+ <para>Some APIs were reorganized. Some of the reorganizations include altering the super class
+ and implements hierarchies, making some classes abstract, making use of Java 8's new
+ <code>default</code> mechanisms to supply default implementations in interfaces,
+ and moving methods to more common places. Users of these APIs
+ should not be affected by these reorganizations.
+ </para>
+
+ </section>
+
+ <section id="uv3.new_extended_apis.other">
+ <title>Other changes</title>
+
+ <para>The utility class <code>org.apache.uima.util.FileUtils</code> has a new method
+ <code>writeToFile(path, string)</code>, which efficiently writes a string using UTF-8 encoding to
+ <code>path</code>.
+ </para>
+
+ <para>Many error messages were changed or added, causing changes to localization classes.
+ For coding efficiency, some of the structure of the internal error reporting calls was changed
+ to make use of Java's variable number of arguments syntax.</para>
+ </section>
+
</chapter>
\ No newline at end of file
Modified: uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/version_3_users_guide.xml
URL: http://svn.apache.org/viewvc/uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/version_3_users_guide.xml?rev=1775528&r1=1775527&r2=1775528&view=diff
==============================================================================
--- uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/version_3_users_guide.xml (original)
+++ uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/version_3_users_guide.xml Wed Dec 21 18:50:39 2016
@@ -27,7 +27,7 @@ under the License.
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="uv3.overview.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="uv3.backwards_compatibility.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="uv3.new_or_extended_apis.xml"/>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="uv3.new_extended_apis.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="uv3.select.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="uv3.custom_java_objects.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="uv3.migration.xml"/>