org.apache.uima.cas.impl

## Class AnnotationIndexImpl<T extends AnnotationFS>

- java.lang.Object
- - org.apache.uima.cas.impl.AnnotationIndexImpl<T>

- All Implemented Interfaces:
    Iterable<T>, FSIndex<T>, AnnotationIndex<T>

      public class AnnotationIndexImpl<T extends AnnotationFS>
      extends Object
      implements AnnotationIndex<T>

  Implementation of annotation indexes. A wrapper not an extend, because the constructor argument index has customization for additional fns and a ref to it's enclosing instance of the FSIndexRepositoryImpl.

- - ### Field Summary

    - ### Fields inherited from interface org.apache.uima.cas.FSIndex

      `BAG_INDEX, DEFAULT_BAG_INDEX, SET_INDEX, SORTED_INDEX`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `AnnotationIndexImpl(FSIndex<T> index)`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `int` | `compare(FeatureStructure fs1, FeatureStructure fs2)` Compare two feature structures according to the ordering relation of the index.
    `boolean` | `contains(FeatureStructure fs)` Check if the index contains an element equal to the given feature structure according to the comparators defined for this index.
    `FeatureStructure` | `find(FeatureStructure fs)` Find an entry in the index "equal to" the given feature structure according to the comparators specified for this index.
    `int` | `getIndexingStrategy()` Return the indexing strategy.
    `Type` | `getType()` Return the type of feature structures this index contains.
    `FSIterator<T>` | `iterator()` Return an iterator over the index.
    `FSIterator<T>` | `iterator(boolean ambiguous)` Return an iterator over annotations that can be constrained to be unambiguous.
    `FSIterator<T>` | `iterator(FeatureStructure fs)` Return an iterator over the index.
    `int` | `size()` Return the number of feature structures in this index.
    `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 `annot`.
    `AnnotationTree<T>` | `tree(T annot)` Create an annotation tree with `annot` as root node.
    `FSIndex<T>` | `withSnapshotIterators()` Creates a shared copy of this FSIndex configured to produce snapshot iterators that don't throw ConcurrentModificationExceptions.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

    - ### Methods inherited from interface java.lang.Iterable

      `forEach, spliterator`

- - ### Constructor Detail

    - #### AnnotationIndexImpl

          public AnnotationIndexImpl(FSIndex<T> index)

  - ### Method Detail

    - #### size

          public int size()

      Description copied from interface: `FSIndex`
      Return the number of feature structures in this index.
      Specified by:
        `size` in interface `FSIndex<T extends AnnotationFS>`
      Returns:
        The number of FSs in this index.

    - #### getType

          public Type getType()

      Description copied from interface: `FSIndex`
      Return the type of feature structures this index contains.
      Specified by:
        `getType` in interface `FSIndex<T extends AnnotationFS>`
      Returns:
        The type of feature structures in this index.

    - #### contains

          public boolean contains(FeatureStructure fs)

      Description copied from interface: `FSIndex`
      Check if the index contains an element equal to the given feature structure according to the comparators defined for this index. For bag indexes (which have no comparators), the equality test means the identical feature structure. Note that this is in general not the same as feature structure identity.
      Specified by:
        `contains` in interface `FSIndex<T extends AnnotationFS>`
      Parameters:
        `fs` - A Feature Structure used a template to match for equality with the FSs in the index.
      Returns:
        `true` if the index contains such an element.

    - #### find

          public FeatureStructure find(FeatureStructure fs)

      Description copied from interface: `FSIndex`
      Find an entry in the index "equal to" the given feature structure according to the comparators specified for this index. Note that this is in general not the same as feature structure identity. For BAG indexes, it is identity, for others it means the found feature structure compares equal with the parameter in terms of the defined comparators for the index.
      Specified by:
        `find` in interface `FSIndex<T extends AnnotationFS>`
      Parameters:
        `fs` - A Feature Structure used a template to match with the Feature Structures in the index.
      Returns:
        A FS equal to the template argument, or `null` if no such FS exists.
      See Also:
        `FSIterator.moveTo(FeatureStructure)`

    - #### compare

          public int compare(FeatureStructure fs1,
                             FeatureStructure fs2)

      Description copied from interface: `FSIndex`
      Compare two feature structures according to the ordering relation of the index. If the input feature structures are not of the type of the index, the result is undefined.
      Specified by:
        `compare` in interface `FSIndex<T extends AnnotationFS>`
      Parameters:
        `fs1` - the first Feature Structure to compare
        `fs2` - the second Feature Structure to compare
      Returns:
        `-1` if `fs1 < fs2`; `0` if `fs1 = fs2`; `1` else.

    - #### iterator

          public FSIterator<T> iterator()

      Description copied from interface: `FSIndex`
      Return an iterator over the index. The iterator will be set to the start position of the index.
      Specified by:
        `iterator` in interface `Iterable<T extends AnnotationFS>`
      Specified by:
        `iterator` in interface `FSIndex<T extends AnnotationFS>`
      Returns:
        An iterator over the index.

    - #### iterator

          public FSIterator<T> iterator(FeatureStructure fs)

      Description copied from interface: `FSIndex`
      Return an iterator over the index. The position of the iterator will be set such that the feature structure returned by a call to the iterator's `get()` method is greater than or equal to `fs`, and any previous FS is less than `FS` (the iterator is positioned at the earliest of equal values). If no such position exists, the iterator will be invalid.
      Specified by:
        `iterator` in interface `FSIndex<T extends AnnotationFS>`
      Parameters:
        `fs` - The feature structure at which the iterator should be positioned.
      Returns:
        An iterator positioned at `fs`, if it exists. An invalid iterator, else.

    - #### getIndexingStrategy

          public int getIndexingStrategy()

      Description copied from interface: `FSIndex`
      Return the indexing strategy.
      Specified by:
        `getIndexingStrategy` in interface `FSIndex<T extends AnnotationFS>`
      Returns:
        One of `SORTED_INDEX`, `BAG_INDEX` or `SET_INDEX`.

    - #### iterator

          public FSIterator<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.

    - #### 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 unambiguous 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`.

    - #### 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>`
      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.

Copyright © 2006–2021 The Apache Software Foundation. All rights reserved.