Class FsIndex_annotation<T extends AnnotationFS>

java.lang.Object
java.util.AbstractCollection<T>
org.apache.uima.cas.impl.FsIndex_iicp<T>
org.apache.uima.cas.impl.FsIndex_annotation<T>
All Implemented Interfaces:
Comparable<FsIndex_iicp<? extends FeatureStructure>>, Iterable<T>, Collection<T>, Comparator<FeatureStructure>, FSIndex<T>, LowLevelIndex<T>, AnnotationIndex<T>

public class FsIndex_annotation<T extends AnnotationFS> extends FsIndex_iicp<T> implements AnnotationIndex<T>
Implementation of annotation indexes. Implements AnnotationIndex replaces AnnotationIndexImpl in v2
  • Constructor Details

  • Method Details

    • iterator

      public LowLevelIterator<T> iterator(boolean ambiguous)
      Description copied from interface: AnnotationIndex
      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(). In other words, the b annotation's start will be large enough to not overlap the span of a.

      An unambiguous iterator makes a snapshot copy of the index containing just the disambiguated items, and iterates over that. It doesn't check for concurrent index modifications (the ambiguous iterator does check for this).

      Specified by:
      iterator in interface AnnotationIndex<T extends AnnotationFS>
      Parameters:
      ambiguous - If set to false, iterator will be unambiguous.
      Returns:
      A annotation iterator.
    • iterator

      public LowLevelIterator<T> iterator(boolean ambiguous, boolean strict, boolean orderNotNeeded, boolean ignoreType)
      Parameters:
      ambiguous - false for unambiguous
      strict - true for strict
      orderNotNeeded - true for unordered
      ignoreType - -
      Returns:
      -
    • subiterator

      public FSIterator<T> subiterator(AnnotationFS annot)
      Description copied from interface: AnnotationIndex
      Return a subiterator whose bounds are defined by the input annotation.

      The annot is used for 3 purposes:

      • It is used to compute the position in the index where the iteration starts.
      • It is used to compute end point where the iterator stops when moving forward.
      • It is used to specify which annotations will be skipped while iterating.

      The starting position is computed by first finding a position whose annotation compares equal with the annot (this might be one of several), and then advancing until reaching a position where the annotation there is not equal to the annot. If no item in the index is equal (meaning it has the same begin, the same end, and is the same type as the annot) then the iterator is positioned to the first annotation which is greater than the annot, or if there are no annotations greater than the annot, the iterator is marked invalid.

      The iterator will stop (become invalid) when

      • it runs out of items in the index going forward or backwards, or
      • while moving forward, it reaches a point where the annotation at that position has a start is beyond the annot's end position, or
      • while moving backwards, it reaches a position in front of its original starting position.

      While iterating, it operates like a strict iterator; annotations whose end positions are > the end position of annot are skipped.

      This is equivalent to returning annotations b such that

      • annot < b, and
      • annot.getEnd() >= b.getBegin(), skipping b's whose end position is > annot.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 have 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).

      Specified by:
      subiterator in interface AnnotationIndex<T extends AnnotationFS>
      Parameters:
      annot - Defines the boundaries of the subiterator.
      Returns:
      A subiterator.
    • subiterator

      public FSIterator<T> subiterator(AnnotationFS annot, boolean ambiguous, boolean strict)
      Description copied from interface: AnnotationIndex
      Return a subiterator whose bounds are defined by the annot.

      The annot is used in 2 or 3 ways.

      • It specifies the left-most position in the index where the iteration starts.
      • It specifies an end point where the iterator stops.
      • If strict is specified, the end point also specifies which annotations will be skipped while iterating.

      The starting position is computed by first finding the position whose annotation compares equal with the annot, and then advancing until reaching a position where the annotation there is not equal to the annot. If no item in the index is equal (meaning it has the same begin, the same end, and is the same type as the annot) then the iterator is positioned to the first annotation which is greater than the annot, or if there are no annotations greater than the annot, the iterator is marked invalid.

      The iterator will stop (become invalid) when

      • it runs out of items in the index going forward or backwards, or
      • while moving forward, it reaches a point where the annotation at that position has a start is beyond the annot's end position, or
      • while moving backwards, it reaches a position in front of its original starting position

      Ignoring strict and ambiguous for a moment, this is equivalent to returning annotations b such that

      • annot < b using the standard annotation comparator, and
      • annot.getEnd() >= b.getBegin(), and also bounded by the index itself.

      A strict subiterator skips annotations where annot.getEnd() < b.getEnd().

      A ambiguous = false specification produces an unambigouse iterator, which computes a subset of the annotations, going forward, such that annotations whose begin is contained within the previous returned annotation's span, are skipped.

      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 = true then annotations whose end is > annot.getEnd() are skipped.

      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 have 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.

      Specified by:
      subiterator in interface AnnotationIndex<T extends AnnotationFS>
      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

      public AnnotationTree<T> tree(T annot)
      Description copied from interface: AnnotationIndex
      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.
      Specified by:
      tree in interface AnnotationIndex<T extends AnnotationFS>
      Parameters:
      annot - The annotation at the root of the tree. This must be of type T or a subtype
      Returns:
      The annotation tree rooted at annot.
    • addChildren

      private void addChildren(AnnotationTreeNodeImpl<T> node, FSIterator<T> it)
    • withSnapshotIterators

      public FSIndex<T> withSnapshotIterators()
      Description copied from interface: FSIndex
      Creates a shared copy of this FSIndex configured to produce snapshot iterators that don't throw ConcurrentModificationExceptions.
      Specified by:
      withSnapshotIterators in interface FSIndex<T extends AnnotationFS>
      Overrides:
      withSnapshotIterators in class FsIndex_iicp<T extends AnnotationFS>
      Returns:
      a light-weight copy of this FSIndex, configured such that any iterator created using it will be a snapshot iterator - one where a snapshot is made of the state of the index at the time the iterator is created, and where subsequent modifications to the underlying index are allowed, but don't affect the iterator (which iterates over the read-only snapshot). Iterators produced with this won't throw ConcurrentModificationExceptions.