Package org.apache.uima.cas

# Interface FSIndex<T extends FeatureStructure>

Type Parameters:
  `T` - the topmost type in this Index

All Superinterfaces:
  `Collection<T>`, `Iterable<T>`

All Known Subinterfaces:
  `AnnotationIndex<T>`, `LowLevelIndex<T>`

All Known Implementing Classes:
  `FsIndex_annotation`, `FsIndex_bag`, `FsIndex_flat`, `FsIndex_set_sorted`, `FsIndex_singletype`, `FsIndex_snapshot`

public interface FSIndex<T extends FeatureStructure> extends Collection<T>
Feature structure index access interface.

Notice that each feature structure index uses its own ordering relation that will usually be different from index to index. In particular, equality with respect to the index ordering will in general not imply object identity for the feature structures.

We currently support three different kinds of indexes: sorted, set and bag indexes. The default index is a sorted index. In a sorted index, FSs that are committed (added to the indexes) are added, unless they are duplicates of already existing FSs in the index. Multiple different instances of FSs which compare equal may all be in the index, individually.

The index is sorted in the sense that iterators will output FSs in sorted order according to the comparator for that index. The order of FSs that are equal with respect to the comparator is arbitrary but fixed. That is, if you iterate over the same index several times, you will see the same relative order of FSs every time. We also guarantee that reverse iterators will produce exactly the reverse sequence of forward iteration.

A set index will contain no duplicates of the same type, where a duplicate is defined by the indexing comparator. That is, if you commit two feature structures of the same type that are equal with respect to the indexing comparator, only the first one will be entered into the index. Note that you can still have duplicates with respect to the indexing order if they are of a different type; different types are never "equal". A set index is not in any particular sort order.

A bag index finally simply stores everything, without any guaranteed order. Operations that depend on comparison, such as find(FeatureStructure fs) or FSIterator.moveTo(FeatureStructure fs) only compare for equality using FeatureStructure identity, since no ordering relationship is possible with bag indexes.

Indexes have a top-most type; let's call it T. They store only instances of that type or its subtypes. A given index definition specifies this top-most type. The APIs for obtaining an index include the ability to specify, in addition, a type T2 which is a subtype of T; indexes obtained using this will have only instances of type T2 or its subtypes.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `BAG_INDEX`
  Indexing strategy: bag index.
  `static final int`
  `DEFAULT_BAG_INDEX`
  Special indexes used by the framework to implement `FSIndexRepository.getAllIndexedFS(Type)`.
  `static final int`
  `SET_INDEX`
  Indexing strategy: set index.
  `static final int`
  `SORTED_INDEX`
  Indexing strategy: sorted index.

- ## Method Summary

  Modifier and Type
  Method
  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.
  `T`
  `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.
  `default FSIterator<T>`
  `iterator(FeatureStructure fs)`
  Return an iterator over the index.
  `SelectFSs<T>`
  `select()`
  `<N extends T>
  SelectFSs<N>`
  `select(int jcasType)`
  `<N extends T>
  SelectFSs<N>`
  `select(Class<N> clazz)`
  `<N extends T>
  SelectFSs<N>`
  `select(String fullyQualifiedTypeName)`
  `<N extends T>
  SelectFSs<N>`
  `select(Type type)`
  `int`
  `size()`
  Return the number of feature structures in this index.
  `default Stream<T>`
  `stream()`
  `default <U extends T>
  FSIndex<U>`
  `subType(Class<? extends TOP> clazz)`
  `default <U extends T>
  FSIndex<U>`
  `subType(Type type)`
  `FSIndex<T>`
  `withSnapshotIterators()`
  Creates a shared copy of this FSIndex configured to produce snapshot iterators that don't throw ConcurrentModificationExceptions.

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

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

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

  `forEach`

- ## Field Details

  - ### SORTED_INDEX

    static final int SORTED_INDEX
    Indexing strategy: sorted index. A sorted index contains all elements, including duplicates. Iterators over sorted indexes will return elements in sorted order.
    See Also:
      - Constant Field Values

  - ### SET_INDEX

    static final int SET_INDEX
    Indexing strategy: set index. A set index contains no duplicates of the same type, where a duplicate is defined by the indexing comparator. A set index is not guaranteed to be sorted.
    See Also:
      - Constant Field Values

  - ### BAG_INDEX

    static final int BAG_INDEX
    Indexing strategy: bag index. A bag index contains all elements, in no particular order.
    See Also:
      - Constant Field Values

  - ### DEFAULT_BAG_INDEX

    static final int DEFAULT_BAG_INDEX
    Special indexes used by the framework to implement `FSIndexRepository.getAllIndexedFS(Type)`. Not user-definable.
    See Also:
      - Constant Field Values

- ## Method Details

  - ### size

    int size()
    Return the number of feature structures in this index.
    Specified by:
      `size` in interface `Collection<T extends FeatureStructure>`
    Returns:
      The number of FSs in this index.

  - ### getType

    Type getType()
    Return the type of feature structures this index contains.
    Returns:
      The type of feature structures in this index.

  - ### contains

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

    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

    T find(FeatureStructure fs)
    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.
    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)`

  - ### compare

    int compare(FeatureStructure fs1, FeatureStructure fs2)
    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.
    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

    default FSIterator<T> iterator(FeatureStructure fs)
    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.
    Parameters:
      `fs` - A feature structure template (may be a supertype of T) having keys used in the index compare function, specifying where to initially position the iterator.
    Returns:
      An iterator positioned at `fs`, if it exists; else, an invalid iterator.

  - ### iterator

    FSIterator<T> iterator()
    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 `Collection<T extends FeatureStructure>`
    Specified by:
      `iterator` in interface `Iterable<T extends FeatureStructure>`
    Returns:
      An FSIterator positioned at the beginning, or an invalid iterator.

  - ### getIndexingStrategy

    int getIndexingStrategy()
    Return the indexing strategy.
    Returns:
      One of `SORTED_INDEX`, `BAG_INDEX` or `SET_INDEX`.

  - ### withSnapshotIterators

    FSIndex<T> withSnapshotIterators()
    Creates a shared copy of this FSIndex configured to produce snapshot iterators that don't throw ConcurrentModificationExceptions.
    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.

  - ### select

    SelectFSs<T> select()
    Returns:
      a newly created selection object for accessing feature structures

  - ### select

    <N extends T> SelectFSs<N> select(Type type)
    Type Parameters:
      `N` - the Type of the elements being accessed
    Parameters:
      `type` - specifies the type (and subtypes of that type) to access
    Returns:
      a newly created selection object for accessing feature structures of that type and its subtypes
    Throws:
      `IllegalArgumentException` - if no type is specified.

  - ### select

    <N extends T> SelectFSs<N> select(Class<N> clazz)
    Type Parameters:
      `N` - the Type of the elements being accessed
    Parameters:
      `clazz` - a JCas class corresponding to the type (and subtypes of that type) to access
    Returns:
      a newly created selection object for accessing feature structures of that type and its subtypes
    Throws:
      `IllegalArgumentException` - if no type is specified.

  - ### select

    <N extends T> SelectFSs<N> select(int jcasType)
    Type Parameters:
      `N` - the Type of the elements being accessed
    Parameters:
      `jcasType` - the "type" field from the JCas class corresponding to the type (and subtypes of that type) to access
    Returns:
      a newly created selection object for accessing feature structures of that type and its subtypes

  - ### select

    <N extends T> SelectFSs<N> select(String fullyQualifiedTypeName)
    Type Parameters:
      `N` - the Type of the elements being accessed
    Parameters:
      `fullyQualifiedTypeName` - the string name of the type to access
    Returns:
      a newly created selection object for accessing feature structures of that type and its subtypes
    Throws:
      `IllegalArgumentException` - if no type is specified.

  - ### stream

    default Stream<T> stream()
    Specified by:
      `stream` in interface `Collection<T extends FeatureStructure>`
    Returns:
      a Stream over all the elements in the index (including subtypes)

  - ### subType

    default <U extends T> FSIndex<U> subType(Class<? extends TOP> clazz)
    Type Parameters:
      `U` - the subtype
    Parameters:
      `clazz` - - the subtype
    Returns:
      an instance of this index specialized to a subtype

  - ### subType

    default <U extends T> FSIndex<U> subType(Type type)
    Type Parameters:
      `U` - the subtype
    Parameters:
      `type` - - the subtype
    Returns:
      an instance of this index specialized to a subtype