org.apache.uima.cas.impl

## Class FsIndex_annotation<T extends AnnotationFS>

- java.lang.Object
- - java.util.AbstractCollection<T>
  - - org.apache.uima.cas.impl.FsIndex_annotation<T>

- All Implemented Interfaces:
    Comparable<org.apache.uima.cas.impl.FsIndex_iicp<? extends FeatureStructure>>, Iterable<T>, Collection<T>, Comparator<FeatureStructure>, FSIndex<T>, LowLevelIndex<T>, AnnotationIndex<T>

      public class FsIndex_annotation<T extends AnnotationFS>
      extends AbstractCollection<T>
      implements AnnotationIndex<T>

  Implementation of annotation indexes. Implements AnnotationIndex replaces AnnotationIndexImpl in v2

- - ### Field Summary

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

      `BAG_INDEX, DEFAULT_BAG_INDEX, SET_INDEX, SORTED_INDEX`

    - ### Fields inherited from interface org.apache.uima.cas.impl.LowLevelIndex

      `FS_ID_COMPARATOR, IS_ORDERED, IS_TYPE_ORDER`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `FsIndex_annotation(FsIndex_singletype<T> fsIndex_singletype)`

  - ### 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.
    `int` | `compareTo(org.apache.uima.cas.impl.FsIndex_iicp<? extends FeatureStructure> cp)` Maybe not used 3/2015 Compares two instances of FsIndex_iicp, for ordering.
    `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.
    `boolean` | `equals(Object o)` Two iicps are equal if and only if: - the types they index are the same, and - the comparators are equal, and - the indexing stragtegy (bag/set/sorted) are the same Used when creating the index iterator cache to select from the set of all instances of these the one that goes with the same index definition Used by CasComplete serialization to merge multiple index names referring to the same index
    `T` | `find(FeatureStructure fs)` Find an entry in the index "equal to" the given feature structure according to the comparators specified for this index.
    `CASImpl` | `getCasImpl()`
    `Comparator<TOP>` | `getComparator()`
    `FSIndexComparator` | `getComparatorForIndexSpecs()` This is **NOT** a comparator for Feature Structures, but rather something that compares two comparator specifications
    `FSIndexComparatorImpl` | `getComparatorImplForIndexSpecs()`
    `FSIndexRepositoryImpl` | `getFsRepositoryImpl()`
    `int` | `getIndexingStrategy()` Return the indexing strategy.
    `Type` | `getType()` Return the type of feature structures this index contains.
    `int` | `hashCode()`
    `boolean` | `isEmpty()`
    `boolean` | `isSorted()`
    `LowLevelIterator<T>` | `iterator()` Iterator varieties All iterators are over a Type + subtypes (because that's the purpose of this class) - ambiguous / unambiguous (for AnnotationIndex) - not strict / strict (for AnnotationIndex) - ignoring type priorities or not (for any index) - "unordered" - no need to preserve order These may be combined.
    `LowLevelIterator<T>` | `iterator(boolean ambiguous)` Return an iterator over annotations that can be constrained to be unambiguous.
    `LowLevelIterator<T>` | `iterator(boolean orderNotNeeded, boolean ignoreType)` Internal use, used by select framework.
    `LowLevelIterator<T>` | `iterator(boolean ambiguous, boolean strict, boolean orderNotNeeded, boolean ignoreType)`
    `int` | `ll_compare(int ref1, int ref2)` Compare two Feature structures, referred to by IDs
    `LowLevelIterator<T>` | `ll_iterator(boolean ambiguous)` Iterator over arbitrary Feature Structures, but also filters out non-AnnotationFS FeatureStructures
    `int` | `ll_maxAnnotSpan()`
    `int` | `size()` Return the number of feature structures in this index.
    `Stream<FsIndex_singletype<TOP>>` | `streamNonEmptyIndexes()`
    `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`.
    `String` | `toString()`
    `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.util.AbstractCollection

      `add, addAll, clear, contains, containsAll, remove, removeAll, retainAll, toArray, toArray`

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

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

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

      `compare, contains, find, getIndexingStrategy, getType, iterator, iterator, select, select, select, select, select, size, stream, subType, subType`

    - ### Methods inherited from interface java.util.Collection

      `add, addAll, clear, contains, containsAll, equals, hashCode, isEmpty, parallelStream, remove, removeAll, removeIf, retainAll, spliterator, toArray, toArray`

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

      `forEach`

    - ### Methods inherited from interface java.util.Comparator

      `comparing, comparing, comparingDouble, comparingInt, comparingLong, naturalOrder, nullsFirst, nullsLast, reversed, reverseOrder, thenComparing, thenComparing, thenComparing, thenComparingDouble, thenComparingInt, thenComparingLong`

    - ### Methods inherited from interface org.apache.uima.cas.impl.LowLevelIndex

      `flush, getIntIterator, getSubIndex, getSubIndex, ll_iterator, select, select, select, select, select`

- - ### Constructor Detail

    - #### FsIndex_annotation

          public FsIndex_annotation(FsIndex_singletype<T> fsIndex_singletype)

  - ### Method Detail

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

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

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `AbstractCollection<T extends FeatureStructure>`

    - #### equals

          public boolean equals(Object o)

      Two iicps are equal if and only if: - the types they index are the same, and - the comparators are equal, and - the indexing stragtegy (bag/set/sorted) are the same Used when creating the index iterator cache to select from the set of all instances of these the one that goes with the same index definition Used by CasComplete serialization to merge multiple index names referring to the same index
      Specified by:
        `equals` in interface `Collection<T extends FeatureStructure>`
      Specified by:
        `equals` in interface `Comparator<FeatureStructure>`
      Overrides:
        `equals` in class `Object`

    - #### hashCode

          public int hashCode()

      Specified by:
        `hashCode` in interface `Collection<T extends FeatureStructure>`
      Overrides:
        `hashCode` in class `Object`

    - #### compareTo

          public int compareTo(org.apache.uima.cas.impl.FsIndex_iicp<? extends FeatureStructure> cp)

      Maybe not used 3/2015 Compares two instances of FsIndex_iicp, for ordering. Compares first using the type code of the main types If those are equal, Compares using the comparatorForIndexSpecs objects
      Specified by:
        `compareTo` in interface `Comparable<org.apache.uima.cas.impl.FsIndex_iicp<? extends FeatureStructure>>`
      See Also:
        `Comparable.compareTo(Object)`

    - #### size

          public int size()

      Description copied from interface: `FSIndex`
      Return the number of feature structures in this index.
      Specified by:
        `size` in interface `Collection<T extends FeatureStructure>`
      Specified by:
        `size` in interface `FSIndex<T extends FeatureStructure>`
      Specified by:
        `size` in class `AbstractCollection<T extends FeatureStructure>`
      Returns:
        the sum of the sizes of the indexes of the type + all subtypes

    - #### ll_maxAnnotSpan

          public int ll_maxAnnotSpan()

      Specified by:
        `ll_maxAnnotSpan` in interface `LowLevelIndex<T extends FeatureStructure>`
      Returns:
        for annotation indexes, an conservative estimate the maximum span between begin and end The value may be larger than actual.

    - #### isEmpty

          public boolean isEmpty()

      Specified by:
        `isEmpty` in interface `Collection<T extends FeatureStructure>`
      Overrides:
        `isEmpty` in class `AbstractCollection<T extends FeatureStructure>`

    - #### ll_compare

          public int ll_compare(int ref1,
                                int ref2)

      Description copied from interface: `LowLevelIndex`
      Compare two Feature structures, referred to by IDs
      Specified by:
        `ll_compare` in interface `LowLevelIndex<T extends FeatureStructure>`
      Parameters:
        `ref1` - -
        `ref2` - -
      Returns:
        -

    - #### getIndexingStrategy

          public int getIndexingStrategy()

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

    - #### getComparator

          public Comparator<TOP> getComparator()

      Specified by:
        `getComparator` in interface `LowLevelIndex<T extends FeatureStructure>`
      Returns:
        a comparator used by this index to compare Feature Structures For sets, the equal is used to determine set membership For sorted, the comparator is the sort order (this comparator is without the ID)

    - #### getComparatorForIndexSpecs

          public FSIndexComparator getComparatorForIndexSpecs()

      Description copied from interface: `LowLevelIndex`
      This is **NOT** a comparator for Feature Structures, but rather something that compares two comparator specifications
      Specified by:
        `getComparatorForIndexSpecs` in interface `LowLevelIndex<T extends FeatureStructure>`
      Returns:
        -

    - #### getComparatorImplForIndexSpecs

          public FSIndexComparatorImpl getComparatorImplForIndexSpecs()

    - #### 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 or a supertype, the result is undefined. Because the indexes compare might use only features defined in supertypes, the arguments being compared could be supertypes of the indexed type.
      Specified by:
        `compare` in interface `Comparator<FeatureStructure>`
      Specified by:
        `compare` in interface `FSIndex<T extends FeatureStructure>`
      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.

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

      The element is used as a template, and may be a supertype of the type of the index, as long as the keys specified for this index can be accessed.

      Specified by:
        `contains` in interface `FSIndex<T extends FeatureStructure>`
      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 T 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. If there are multiple different FSs in the index which compare equal with the given feature structure, an arbitrary one is returned. This differs from the moveTo(fs) operation which guarantees to move to the first feature structure occurring in the index in this case.
      Specified by:
        `find` in interface `FSIndex<T extends FeatureStructure>`
      Parameters:
        `fs` - A Feature Structure used a template to match with the Feature Structures in the index. It must have the keys needed to do the compare as specified for the index that it's in.
      Returns:
        A FS equal to the template argument, or `null` if no such FS exists.
      See Also:
        `FSIterator.moveTo(FeatureStructure)`

    - #### 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 FeatureStructure>`
      Returns:
        The type of feature structures in this index.

    - #### getCasImpl

          public CASImpl getCasImpl()

      Specified by:
        `getCasImpl` in interface `LowLevelIndex<T extends FeatureStructure>`
      Returns:
        a CAS View associated with this iterator

    - #### isSorted

          public boolean isSorted()

      Specified by:
        `isSorted` in interface `LowLevelIndex<T extends FeatureStructure>`
      Returns:
        true if the index is sorted

    - #### iterator

          public LowLevelIterator<T> iterator()

      Iterator varieties All iterators are over a Type + subtypes (because that's the purpose of this class) - ambiguous / unambiguous (for AnnotationIndex) - not strict / strict (for AnnotationIndex) - ignoring type priorities or not (for any index) - "unordered" - no need to preserve order These may be combined.
      Specified by:
        `iterator` in interface `Iterable<T extends FeatureStructure>`
      Specified by:
        `iterator` in interface `Collection<T extends FeatureStructure>`
      Specified by:
        `iterator` in interface `FSIndex<T extends FeatureStructure>`
      Specified by:
        `iterator` in interface `LowLevelIndex<T extends FeatureStructure>`
      Specified by:
        `iterator` in class `AbstractCollection<T extends FeatureStructure>`
      Returns:
        An FSIterator positioned at the beginning, or an invalid iterator.

    - #### iterator

          public LowLevelIterator<T> iterator(boolean orderNotNeeded,
                                              boolean ignoreType)

      Description copied from interface: `LowLevelIndex`
      Internal use, used by select framework. Return an iterator over the index. The position of the iterator will be set to return the first item in the index. If the index is empty, the iterator position will be marked as invalid.
      Specified by:
        `iterator` in interface `LowLevelIndex<T extends FeatureStructure>`
      Parameters:
        `orderNotNeeded` - if true, skips work while iterating to keep iterators over multiple types in sync.
        `ignoreType` - if true, the comparator used for moveTo leftmost operations will ignore typeOrder keys, if the index happens to define these
      Returns:
        An FSIterator positioned at the beginning, or an invalid iterator.

    - #### ll_iterator

          public LowLevelIterator<T> ll_iterator(boolean ambiguous)

      Iterator over arbitrary Feature Structures, but also filters out non-AnnotationFS FeatureStructures
      Specified by:
        `ll_iterator` in interface `LowLevelIndex<T extends FeatureStructure>`
      Parameters:
        `ambiguous` - true for normal iteration, false to do unambiguous iteration
      Returns:
        the iterator

    - #### getFsRepositoryImpl

          public FSIndexRepositoryImpl getFsRepositoryImpl()

    - #### streamNonEmptyIndexes

          public Stream<FsIndex_singletype<TOP>> streamNonEmptyIndexes()

      Returns:
        a stream of FSIndex_singletype, for all non-empty indexes

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