Interface FSIndex<T extends FeatureStructure>
-
- All Superinterfaces:
Iterable<T>
- All Known Subinterfaces:
AnnotationIndex<T>
- All Known Implementing Classes:
AnnotationIndexImpl
public interface FSIndex<T extends FeatureStructure> extends Iterable<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 index) are added, unless they are duplicates of already existing FSs in the index. This behavior is new as of version 2.7.0; the old behavior can be restored by specifying the JVM property "uima.allow_duplicate_add_to_indexes". Even without this flag, multiple different instances of FSs which compare equal will still be added in the index.
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 wrt 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 wrt the indexing comparator, only the first one will be entered into the index. Note that you can still have duplicates wrt the indexing order if they are of a different type. A set index is not guaranteed to be sorted.
A bag index finally simply stores everything, without any guaranteed order. Note that any operation like find() or FSIterator.moveTo() will not produce useful results on bag indexes, since bag indexes do not honor comparators (except that find is useful for indicating if the FS is in the index). Only use a bag index if you want very fast adding and will have to iterate over the whole index anyway.
Indexes have a top-most type, either the top of the type hierarchy, or some subtype of that. The top-most type in an index is represented by the generic T.
-
-
Field Summary
Fields Modifier and Type Field Description static int
BAG_INDEX
Indexing strategy: bag index.static int
DEFAULT_BAG_INDEX
Special indexes used by the framework to implementFSIndexRepository.getAllIndexedFS(Type)
.static int
SET_INDEX
Indexing strategy: set index.static int
SORTED_INDEX
Indexing strategy: sorted index.
-
Method Summary
All Methods Instance Methods Abstract Methods 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.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(FeatureStructure fs)
Return an iterator over the index.int
size()
Return the number of feature structures in this index.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.lang.Iterable
forEach, spliterator
-
-
-
-
Field Detail
-
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 implementFSIndexRepository.getAllIndexedFS(Type)
. Not user-definable.- See Also:
- Constant Field Values
-
-
Method Detail
-
size
int size()
Return the number of feature structures in this index.- 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.- 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
FeatureStructure 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.- 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
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, the result is undefined.- Parameters:
fs1
- the first Feature Structure to comparefs2
- the second Feature Structure to compare- Returns:
-1
iffs1 < fs2
;0
iffs1 = fs2
;1
else.
-
iterator
FSIterator<T> iterator()
Return an iterator over the index. The iterator will be set to the start position of the index.- Specified by:
iterator
in interfaceIterable<T extends FeatureStructure>
- Returns:
- An iterator over the index.
-
iterator
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'sget()
method is greater than or equal tofs
, and any previous FS is less thanFS
(the iterator is positioned at the earliest of equal values). If no such position exists, the iterator will be invalid.- 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
int getIndexingStrategy()
Return the indexing strategy.- Returns:
- One of
SORTED_INDEX
,BAG_INDEX
orSET_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.
-
-