org.apache.uima.cas.text
Interface AnnotationIndex<T extends AnnotationFS>

All Superinterfaces:
FSIndex<T>, Iterable<T>

public interface AnnotationIndex<T extends AnnotationFS>
extends FSIndex<T>

An annotation index provides additional iterator functionality that applies only to instances of uima.tcas.Annotation. You can obtain an AnnotationIndex by calling:

AnnotationIndex idx = (AnnotationIndex)cas.getAnnotationIndex();
(the typecast is necessary for historical reasons).

Note that the AnnotationIndex defines the following sort order between two annotations:

In the method descriptions below, the notation a < b, where a and b are annotations, should be taken to mean a comes before b in the index, according to the above rules.


Field Summary
 
Fields inherited from interface org.apache.uima.cas.FSIndex
BAG_INDEX, DEFAULT_BAG_INDEX, SET_INDEX, SORTED_INDEX
 
Method Summary
 FSIterator<T> iterator(boolean ambiguous)
          Return an iterator over annotations that can be constrained to be unambiguous.
 FSIterator<T> subiterator(AnnotationFS annot)
          Return a subiterator whose bounds are defined by the input annotation.
 FSIterator<T> subiterator(AnnotationFS annot, boolean ambiguous, boolean strict)
          Return a subiterator whose bounds are defined by the input annotation.
 AnnotationTree<T> tree(T annot)
          Create an annotation tree with annot as root node.
 
Methods inherited from interface org.apache.uima.cas.FSIndex
compare, contains, find, getIndexingStrategy, getType, iterator, iterator, size
 

Method Detail

iterator

FSIterator<T> iterator(boolean ambiguous)
Return an iterator over annotations that can be constrained to be unambiguous.

A disambiguated iterator is defined as follows. The first annotation returned is the same as would be returned by the corresponding ambiguous iterator. If the unambiguous iterator has returned a previously, it will next return the smallest b s.t. a < b and a.getEnd() <= b.getBegin().

Parameters:
ambiguous - If set to false, iterator will be unambiguous.
Returns:
A annotation iterator.

subiterator

FSIterator<T> subiterator(AnnotationFS annot)
Return a subiterator whose bounds are defined by the input annotation.

The subiterator will return annotations b s.t. annot < b, annot.getBegin() <= b.getBegin() and annot.getEnd() >= b.getEnd(). For annotations x, y, x < y here is to be interpreted as "x comes before y in the index", according to the rules defined in the description of this class.

This definition implies that annotations b that have the same span as annot may or may not be returned by the subiterator. This is determined by the type priorities; the subiterator will only return such an annotation b if the type of annot precedes the type of b in the type priorities definition. If you have not specified the priority, or if annot and b are of the same type, then the behavior is undefined.

For example, if you an annotation s of type Sentence and an annotation p of type Paragraph that have the same span, and you have defined Paragraph before Sentence in your type priorities, then subiterator(p) will give you an iterator that will return s, but subiterator(s) will give you an iterator that will NOT return p. The intuition is that a Paragraph is conceptually larger than a Sentence, as defined by the type priorities.

Calling subiterator(a) is equivalent to calling subiterator(a, true, true).. See subiterator(AnnotationFS, boolean, boolean).

Parameters:
annot - Defines the boundaries of the subiterator.
Returns:
A subiterator.

subiterator

FSIterator<T> subiterator(AnnotationFS annot,
                          boolean ambiguous,
                          boolean strict)
Return a subiterator whose bounds are defined by the input annotation.

A strict subiterator is defined as follows: it will return annotations b s.t. annot < b, annot.getBegin() <= b.getBegin() and annot.getEnd() >= b.getEnd(). For annotations x,y, x < y here is to be interpreted as "x comes before y in the index", according to the rules defined in the description of this class.

If strict is set to false, the boundary conditions are relaxed as follows: return annotations b s.t. annot < b and annot.getBegin() <= b.getBegin() <= annot.getEnd(). The resulting iterator may also be disambiguated.

These definitions imply that annotations b that have the same span as annot may or may not be returned by the subiterator. This is determined by the type priorities; the subiterator will only return such an annotation b if the type of annot precedes the type of b in the type priorities definition. If you have not specified the priority, or if annot and b are of the same type, then the behavior is undefined.

For example, if you an annotation s of type Sentence and an annotation p of type Paragraph that have the same span, and you have defined Paragraph before Sentence in your type priorities, then subiterator(p) will give you an iterator that will return s, but subiterator(s) will give you an iterator that will NOT return p. The intutition is that a Paragraph is conceptually larger than a Sentence, as defined by the type priorities.

Parameters:
annot - Annotation setting boundary conditions for subiterator.
ambiguous - If set to false, resulting iterator will be unambiguous.
strict - Controls if annotations that overlap to the right are considered in or out.
Returns:
A subiterator.

tree

AnnotationTree<T> tree(T annot)
Create an annotation tree with annot as root node. The tree is defined as follows: for each node in the tree, the children are the sequence of annotations that would be obtained from a strict, unambiguous subiterator of the node's annotation.

Parameters:
annot - The annotation at the root of the tree.
Returns:
The annotation tree rooted at annot.


Copyright © 2010 The Apache Software Foundation. All Rights Reserved.