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 2015/05/04 22:23:01 UTC
svn commit: r1677671 -
/uima/uimaj/trunk/uimaj-core/src/main/java/org/apache/uima/cas/impl/package.html
Author: schor
Date: Mon May 4 20:23:00 2015
New Revision: 1677671
URL: http://svn.apache.org/r1677671
Log:
no Jira, add documatation of some CAS Internals for Indexes and Iterators to package.html.
Modified:
uima/uimaj/trunk/uimaj-core/src/main/java/org/apache/uima/cas/impl/package.html
Modified: uima/uimaj/trunk/uimaj-core/src/main/java/org/apache/uima/cas/impl/package.html
URL: http://svn.apache.org/viewvc/uima/uimaj/trunk/uimaj-core/src/main/java/org/apache/uima/cas/impl/package.html?rev=1677671&r1=1677670&r2=1677671&view=diff
==============================================================================
--- uima/uimaj/trunk/uimaj-core/src/main/java/org/apache/uima/cas/impl/package.html (original)
+++ uima/uimaj/trunk/uimaj-core/src/main/java/org/apache/uima/cas/impl/package.html Mon May 4 20:23:00 2015
@@ -18,19 +18,123 @@
* under the License.
***************************************************************
-->
+
+ <!-- This page is maintained by cutting/pasting the <body> content into/from
+ a local installation of tinyMCE, a wysiwig rich text editor (go to tools - source, paste everything
+ between the body tags, including the html markup. Edit there, and then goto tools - source and copy back) -->
<html>
<head>
<title>Implementation and low-level API for the CAS interfaces</title>
</head>
<body>
- Implementation and Low-Level API for the CAS Interfaces.
- <p>
-
-Internal APIs. Use these APIs at your own risk. APIs in this package are subject to change
-without notice, even in minor releases. Use of this package is not supported.
-If you think you have found a bug in this package, please try to reproduce
-it with the officially supported APIs before reporting it.
- </p>
+<p>Implementation and Low-Level API for the CAS Interfaces.</p>
+<p>Internal APIs. Use these APIs at your own risk. APIs in this package are subject to change without notice, even in minor releases. Use of this package is not supported. If you think you have found a bug in this package, please try to reproduce it with the officially supported APIs before reporting it.</p>
+<hr />
+<h1>Internals documentation</h1>
+<p>NOTE: This documentation is plain HTML, generated from a WYSIWIG editor "tinymce". The way to work on this: after setting up a small web page with the tinymce (running from a local file), use the Tools - source code to cut/paste between this file's source and that editor.</p>
+<h2>Java Cover Objects</h2>
+<p>It is possible to run UIMA without creating Java cover objects for FSs. However, for convenience, many of the APIs return Java objects that provide, in turn, various APIs for accessing features, updating in indexes, etc.</p>
+<p>There are two kinds of Java cover objects:</p>
+<ul>
+<li>Basic - this provides a generic API that works for all FSs.</li>
+<li>JCas - this provides a custom Java Class for a type that gives get/set style accessors for the Features.</li>
+</ul>
+<p>Both of these inherit from the <code>FeatureStructure</code> Interface. Use of the JCas is optional; if the JCas cover classes are available (in the class path), they are used. </p>
+<h2>UIMA Indexes</h2>
+<p>Indexes are defined for a pipeline, and are kept as part of the general CAS definition.</p>
+<p>Each CAS View has its own instantiation of the defined indexes (there's one definition for all views), and as a result, a particular FS may be added-to-indexes and indexed in some views, and not in others.</p>
+<p>There are 3 kinds of indexes: Sorted, Set, and Bag. The basic object type for an index is <code>FSLeafIndexImpl</code>. This has 3 subtypes, one for each of the index types:</p>
+<ul>
+<li>FSBagIndex</li>
+<li>FSIntArrayIndex (for Sorted)</li>
+<li>FSRBTSetIndex (for Set)</li>
+</ul>
+<p>The leaf index is just for one type (and doesn't include entries for any subtypes).</p>
+<p>Indexes are connected to specific index definitions; these definitions include a type which is the top type for elements of this index. The index definition logically includes that type and all of its subtypes.</p>
+<p>An additional data struction, the IndexIteratorCachePair, is associated with each index definition. It holds references to the subtype FSLeafIndexImpls for all subtypes of an index; this list is created lazily, only when an iterator is created over this index at a particular type level (which can be the type the index was defined for, or any subtype). This lazy aspect is important, because UIMA is often used in cases where there's a giant type system, with lots of subtypes, only a few of which are used in a particular pipeline instance.</p>
+<p>There are two tasks that indexes accomplish:</p>
+<ul>
+<li>updating the index with adds and removes of FSs. This update operation is optimized by
+<ul>
+<li>keeping each type indexed separately, so only that data structure for the particular type need be updated (this design choice has a cost in iteration, though)</li>
+<li>treating more common use cases efficiently - the main one being that of adding something "to the end" of the items in the index.</li>
+</ul>
+</li>
+<li>iterating over an index for a type and its subtypes.
+<ul>
+<li>For indexes having no subtypes, this is done by iterating over the FSLeafIndexImpl for that index and type. </li>
+<li>For indexing with subtypes, this is done by creating individual iterators for the type and all of its subtypes, each iterating over the FSLeafIndexImpl for that type. These iterators are then logically combined into one iterator.</li>
+</ul>
+</li>
+</ul>
+<h2>Iterators</h2>
+<p>There are two main kinds of iterators:</p>
+<ul>
+<li>Iterators over UIMA Indexes</li>
+<li>Iterators over other UIMA objects, such as Views, or internal structures.</li>
+</ul>
+<h3>Iterators over UIMA indexes</h3>
+<p>There are two main kinds of iterators over UIMA indexes:</p>
+<ul>
+<li>those returning int values representing the location of the FS in the heap.</li>
+<li>those returning Java cover objects representing the FS. This is typically implemented as a wrapper around the one returning the int value. (It can't be a subclass, overriding the get() method, because you can't change the return type when overriding).</li>
+</ul>
+<p>The basic int iterators are implemented with instances of the classes:</p>
+<ul>
+<li><strong><code>FSIntIteratorImplBase<T extends FeatureStructure></code></strong> - the common superclass
+<ul>
+<li><strong><code>IntIterator4bag<T extends FeatureStructure></code></strong></li>
+<li><strong><code>IntIterator4set<T extends FeatureStructure></code></strong></li>
+<li><strong><code>IntIterator4sorted<T extends FeatureStructure></code></strong></li>
+</ul>
+</li>
+</ul>
+<p>All of these implement an iterator over the corresponding <strong>FSLeafIndexImpl</strong> for one type.</p>
+<p>The class <strong>PointerIterator</strong> in FSIndexRepositoryImpl is an int iterator that combines iterators for type and their subtypes, into one aggregated iterator, taking into account the comparator sorting order among the various iterators. So, for instance, if you do a moveTo operation, it does a move to on all the individual iterators, and then figures out which of those is the left-most one in the comparator ordering.</p>
+<p><strong>PointerIteratorUnordered</strong> is a variant that also combines iterators for a type and its subtypes, but doesn't try to keep these in order. It is designed to be used when iterating through all instances of a type and its subtypes, in an arbitrary order, such as what the method <strong><code>getAllIndexedFS(type)</code></strong> does.</p>
+<p><strong>SnapshotPointerIterator</strong> is a variant which creates a snapshot when the iterator is created, and then (ignoring any subsequent index updates) iterates over that. This iterator won't throw <strong><code>ConcurrentModificationException</code></strong>.</p>
+<hr />
+<p>Iterators which return Java cover object:</p>
+<p> </p>
+<ul>
+<li><strong>FSIteratorImplBase<T></strong> abstract class implements FSIterator
+<ul>
+<li><strong>FSIteratorWrapper<T></strong> - this is the standard wrapper around the above int iterators.</li>
+<li><strong>FSIteratorAggregate<T> - </strong>created with a list of iterators, operates like PointerIteratorUnordered, except the underlying iterators are ones returning Java cover objects</li>
+<li><strong>FSIteratorFlat<T> </strong>- iterates over a corresponding "flattened" iterator of a type and its subtypes (an optimization).</li>
+<li><strong>FSIteratorWrapperDoublecheck<T> - </strong>only used for debugging</li>
+<li><strong>FilteredIterator<T> </strong>- wraps an FSIterator, and applies a FSMatchConstraint</li>
+<li><strong>Subiterator<T> - </strong>created from an AnnotationIndex; wraps a plain FSIterator</li>
+<li><strong>UnambiguousIteratorImpl<T> - </strong>created from an AnnotationIndex; wraps a plain FSIterator</li>
+</ul>
+</li>
+</ul>
+<p>Plain FSIterators are created from index instances via the <code>iterator()</code> method; corresponding int iterators are created from low-level indexes via <code>ll_iterator()</code>. This method picks the appropriate underlying iterator based on</p>
+<ul>
+<li>the index kind (BAG/SET/SORTED)</li>
+<li>whether or not the index has subtypes</li>
+<li>index extended function flags (snapshot)</li>
+<li>whether or not the index has a currently valid "flat" version (for SORTED indexes)</li>
+</ul>
+<h4>Iterator Interfaces</h4>
+<p>There are several overlapping interfaces (probably due to historical reasons) for these iterators.</p>
+<p>First, interfaces for iterators returning ints:</p>
+<ul>
+<li><strong>IntPointerIterator</strong> - returns an int, implements isValid, inc/dec, moveToFirst, moveToLast, get, copy</li>
+<li><strong>ComparableIntPointerIterator<T></strong> - combines IntPointerIterater and the standard Java Comparable. This is the main interface for a full-function instance iterators over a FSLeafIndexImpl.
+<ul>
+<li>The comparable is to allow the iterators to be compared (which means to compare the values of the FSs the iterators are positioned at), which is only used when ordering multiple iterators in use when iterating over a type and its subtypes (one iterator for each).</li>
+</ul>
+</li>
+<li><strong>LowLevelIterator</strong> - like IntPointerIterator, has moveToFirst/Last, and isValid; difference: has: ll_get, moveToNext/Previous, and moveTo(fs), also ll_indexSize and ll_getIndex.</li>
+</ul>
+<p>Next, interfaces for iterators returning Java cover objects:</p>
+<ul>
+<li><strong>FSIterator</strong> - extends the standard Java interface: hasNext, next, remove, with isValid, get, moveToNext/Previous/First/Last, moveTo(fs), copy.</li>
+</ul>
+<p> </p>
+<p> </p>
+<p> </p>
</body>
</html>