uima-docbook-v3-users-guide/src/docbook/uv3.new_extended_apis.xml

<?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.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>
    
    <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>
  
  <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>
    
    <para>Similarly to version 2, iterator methods <code>moveToFirst, moveToLast, and moveTo(a_positioning_Feature_Structure)</code>
      "reset" the iterator to be able to "see" the current state of the indexes.  This corresponds to resetting the
      concurrent modification detection sensing in version 2, when these methods are used.
    </para>
    
    <para>Note that the phrase <emphasis>Concurrent Modification</emphasis> is being used here in a single threading
      context, to mean that within a single thread, while an iterator is active, some modifications are being done
      to the indexes.  UIMA does not support multi-threaded write access to the CAS; it does support multi-threaded
      read access to a set of CAS Views, concurrent with one thread having write access (to different views).</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
      semi-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 4 new methods to allow comparing two annotations.
      The first method (<code>compareAnnotation</code>) uses
      the standard annotation comparator (two keys: begin (ascending) and end (descending)). 
      A second method (<code>compareAnnotation(other, linear_type_order)</code>) adds a 3rd comparison,
      used if the Annotations compare equal), which uses a linear_type_order to compare the two types.
      Another two methods extend these two methods with an additional key - the Annotation's ID,
      used only if the previous comparsions are all equal.
      All of these return the standard Java compare result allowing discrimination between equal, &gt;, and &lt;.
      </para>
  </section>

  <section id="uv3.new_extended_apis.reorganized">
    <title>Reorganized APIs</title>
    
    <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 the non-internal UIMA APIs
      should not be affected by these reorganizations.
    </para>

    <para>As an example, version 2 had two different Java objects representing particular Feature Structures, such as
    "Annotation".  One was used (<code>org.apache.uima.jcas.tcas.Annotation</code>) if the JCas was enabled; 
    the other (<code>org.apache.uima.cas.impl.AnnotationImpl</code>)otherwise.  In version 3, there's only one implementation;
    the other (AnnotationImpl) is converted to an interface.  Annotation now "implements AnnotationImpl.</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>