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/16 20:42:03 UTC
svn commit: r1774661 - in
/uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook:
uv3.backwards_compatibility.xml uv3.new_extended_apis.xml uv3.overview.xml
version_3_users_guide.xml
Author: schor
Date: Fri Dec 16 20:42:03 2016
New Revision: 1774661
URL: http://svn.apache.org/viewvc?rev=1774661&view=rev
Log:
[UIMA-5207][UIMA-5208] more on new features and backwards compatibility details
Added:
uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/uv3.new_extended_apis.xml
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.overview.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=1774661&r1=1774660&r2=1774661&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 Fri Dec 16 20:42:03 2016
@@ -72,23 +72,38 @@ under the License.
</section>
<section id="uv3.backards_compatibility.low_level_apis">
- <title>Low Level APIs</title>
+ <title>APIs for creating and modifying Feature Structures</title>
- <para>Version 2 had APIs called "low level"; these were designed to be used in situations where high performance
- was needed, at the expense of being much more susceptible to uncaught user errors.
- Use of these APIs typically avoided creating Java objects,
- and used, in many cases, untyped (and unchecked) plain <code>ints</code> as handles to Feature Structures.
+ <para>There are 3 sets of APIs for creating and modifying Feature Structures.
+ <itemizedlist spacing="compact">
+ <listitem>
+ <para>Using the JCas classes</para>
+ </listitem>
+ <listitem>
+ <para>Using the normal CAS interface with Type and Feature objects</para>
+ </listitem>
+ <listitem>
+ <para>Using the low level CAS interface with int codes for Types and Features</para>
+ </listitem>
+ </itemizedlist>
</para>
- <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.
+ <para>Version 3 retains all 3 sets, to enable backward compatibility.</para>
+ <para>The low level CAS interface was originally provided to enable a extra-high-performance
+ (but without type safety checks) mode. In Version 3, this mode is actually somewhat slower than the others,
+ and no longer has any advantages.
</para>
-
- <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>Using the low level CAS interface also blocks one of the new features of Version 3 - namely, automatic
+ garbage collection of unreachable Feature Structures. This is because creating a Feature Structure using the
+ low level API creates the Java object for that Feature Structure, but returns an "int" handle to it.
+ In order to be able to find the Feature Structure, given that int handle, an entry is made in an internal map.
+ This map holds a reference to this Feature Structure, which prevents it from being garbage collected (until of coursse,
+ the CAS is reset).
</para>
+
+ <para>The normal CAS APIs allow writing Annotators where the type system is unknown at compile time; these
+ are fully supported.</para>
+
</section>
<section id="uv3.backards_compatibility.PEARs">
Added: 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=1774661&view=auto
==============================================================================
--- uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/uv3.new_extended_apis.xml (added)
+++ uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/uv3.new_extended_apis.xml Fri Dec 16 20:42:03 2016
@@ -0,0 +1,93 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"[
+<!ENTITY imgroot "images/version_3_users_guide/new_extended_apis/">
+<!ENTITY % uimaents SYSTEM "../../target/docbook-shared/entities.ent">
+%uimaents;
+]>
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+<chapter id="uv3.new_extended_apis">
+ <title>New and Extended APIs</title>
+ <titleabbrev>New/Extended APIs</titleabbrev>
+
+ <section id="uv3.new_extended_apis.java8">
+ <title>Java 8 integrations</title>
+
+ <para>Several of the the JCas cover classes provide additional
+ integrations with Java 8 facilities.</para>
+
+ <section id="uv3.new_extended_apis.java8.lists">
+ <title>Built-in UIMA Arrays and Lists integration with Java 8</title>
+
+ <para>The <code>iterator()</code> methods for <code>IntegerList
+ IntegerArrayList, IntegerArray,
+ DoubleArray,</code> and <code>LongArray</code> return
+ an <code>OfInt / OfDouble / OfLong</code> instances. These are a subtype of
+ <code>Iterator</code> with an additional methods nextInt / nextLong / nextDouble which avoid the
+ boxing of the normal iterator.
+ </para>
+
+ <para>The built-in collection types support a <code>stream()</code> method
+ returning a Stream or a type-specialized sub interface of Stream for primitives
+ (IntStream, LongStream, DoubleStream)
+ over the objects in the collection.</para>
+
+ <para>The new <code>select</code> framework supports stream operations; see the "select" chapter for details.
+ </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.
+ </para>
+ </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.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>
+</chapter>
\ No newline at end of file
Modified: uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/uv3.overview.xml
URL: http://svn.apache.org/viewvc/uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/uv3.overview.xml?rev=1774661&r1=1774660&r2=1774661&view=diff
==============================================================================
--- uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/uv3.overview.xml (original)
+++ uima/uimaj/branches/experiment-v3-jcas/uima-docbook-v3-users-guide/src/docbook/uv3.overview.xml Fri Dec 16 20:42:03 2016
@@ -110,19 +110,19 @@ under the License.
<varlistentry>
<term><emphasis role="strong">FSArrayList</emphasis></term>
<listitem>
- <para>a Java ArrayList of Feature Structures</para>
+ <para>a Java ArrayList of Feature Structures. The JCas class implements the List API.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="strong">IntegerArrayList</emphasis></term>
<listitem>
- <para>a variable length int array</para>
+ <para>a variable length int array. Supports OfInt iterators.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="strong">FSHashSet</emphasis></term>
<listitem>
- <para>a Java HashSet containing Feature Structures</para>
+ <para>a Java HashSet containing Feature Structures. This JCas class implements the Set API.</para>
</listitem>
</varlistentry>
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=1774661&r1=1774660&r2=1774661&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 Fri Dec 16 20:42:03 2016
@@ -27,6 +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.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"/>