gate
Interface AnnotationSet

All Superinterfaces:

Cloneable, Collection<Annotation>, Iterable<Annotation>, Serializable, Set<Annotation>, SimpleAnnotationSet

All Known Subinterfaces:

EventAwareAnnotationSet

All Known Implementing Classes:

AnnotationSetImpl, ImmutableAnnotationSetImpl

public interface AnnotationSet
extends SimpleAnnotationSet, Serializable

A set of annotations on a document. In addition to the methods provided by SimpleAnnotationSet, Annotation sets support access to subsets of the annotations in the set by various more complex criteria. Annotation sets are attached to documents - they cannot be constructed directly, but are obtained via the getAnnotations methods of Document.

This interface provides methods to extract subsets of annotations from the current set given various constraints. Note that the annotation sets returned by these get methods are immutable snapshots of the set as it was at the time the method was called. Subsequent changes to the underlying set are not reflected in the subset view.

This interface extends Set<Annotation>, so can be used anywhere a Java Collections Framework Set or Collection is required.

Method Summary

void	add(Integer id, Long start, Long end, String type, FeatureMap features) Create and add an annotation with a pre-existing ID.
void	addAnnotationSetListener(AnnotationSetListener l)
void	addGateListener(GateListener l)
Node	firstNode() Get the node with the smallest offset
AnnotationSet	get(Long offset) Select annotations by offset.
AnnotationSet	get(Long startOffset, Long endOffset) Select annotations by offset.
AnnotationSet	get(String type, FeatureMap constraints) Select annotations by type and feature values.
AnnotationSet	get(String type, FeatureMap constraints, Long offset) Select annotations by type, features and offset.
AnnotationSet	get(String type, Long startOffset, Long endOffset) Select annotations by offset and type.
AnnotationSet	get(String type, Set featureNames) Select annotations by type and feature names It returns all annotations of the given type that have the given set of features, regardless of their concrete values If the type == null, then select regardless of type
AnnotationSet	getContained(Long startOffset, Long endOffset) Select annotations by offset.
AnnotationSet	getCovering(String neededType, Long startOffset, Long endOffset) Select annotations of the given type that complete span the range.
Node	lastNode() Get the node with the largest offset
Node	nextNode(Node node) Get the first node that is relevant for this annotation set and which has the offset larger than the one of the node provided.
void	removeAnnotationSetListener(AnnotationSetListener l)
void	removeGateListener(GateListener l)

Methods inherited from interface gate.SimpleAnnotationSet

add, add, add, get, get, get, get, getAllTypes, getDocument, getName, iterator, remove, size

Methods inherited from interface java.util.Set

addAll, clear, contains, containsAll, equals, hashCode, isEmpty, removeAll, retainAll, toArray, toArray

Method Detail

add

void add(Integer id,
         Long start,
         Long end,
         String type,
         FeatureMap features)
         throws InvalidOffsetException

Create and add an annotation with a pre-existing ID. This method should only be used when you have existing annotations with unique IDs, for example when reading the full contents of an annotation set from some saved representation. In normal use you should use the method SimpleAnnotationSet.add(Long, Long, String, FeatureMap), which allows the set to assign a unique ID.

Parameters:

id - the ID for the new annotation

start - the start offset for the new annotation

end - the end offset for the new annotation

type - the annotation type

features - the features for the new annotation

Throws:

InvalidOffsetException - if the start or end offsets are null, or if the start offset is less than 0 or the end offset is greater than the length of the document.

get

AnnotationSet get(String type,
                  FeatureMap constraints)

Select annotations by type and feature values. This will return an annotation set containing just those annotations of a particular type which have features with specific names and values. (It will also return annotations that have features besides those specified, but it will not return any annotations that do not have all the specified feature-value pairs.)

However, if constraints contains a feature whose value is equal to ANNIEConstants.LOOKUP_CLASS_FEATURE_NAME (which is normally "class"), then GATE will attempt to match that feature using an ontology which it will try to retreive from a feature ANNIEConstants.LOOKUP_ONTOLOGY_FEATURE_NAME on both the annotation and in constraints. If these do not return identical ontologies, or if either the annotation or constraints does not contain an ontology, then matching will fail, and the annotation will not be added. In summary, this method will not work normally for features with the name "class".

Parameters:

type - The type of the annotations to return.

constraints - A feature map containing all of the feature value pairs that the annotation must have in order for them to be returned.

Returns:

An annotation set containing only those annotations with the given name and which have the specified set of feature-value pairs. If no annotations match the constraints, an empty set is returned. The returned set is immutable.

get

AnnotationSet get(String type,
                  Set featureNames)

Select annotations by type and feature names It returns all annotations of the given type that have the given set of features, regardless of their concrete values If the type == null, then select regardless of type

Parameters:

type - the annotation type to return. If null then all annotation types are searched.

featureNames - the feature names which an annotation must have to be matched.

Returns:

An annotation set containing only those annotations with the given type and at least the given features. If no annotations match these constraints, an empty set is returned. The returned set is immutable.

get

AnnotationSet get(String type,
                  FeatureMap constraints,
                  Long offset)

Select annotations by type, features and offset. This method is a combination of get(Long) and get(String, FeatureMap), in that it matches annotations by type and feature constraints but considers only those annotations that start as close as possible to the right of the given offset.

Parameters:

type - the annotation type to search for

constraints - the set of features an annotation must have to be matched

offset - the offset at which to anchor the search.

Returns:

An annotation set containing those annotations that match the constraints, or an empty set if there are no such annotations. The returned set is immutable.

get

AnnotationSet get(Long offset)

Select annotations by offset. This returns the set of annotations whose start node is the least such that it is greater than or equal to offset. In other words it finds the first annotation that starts at or after the given offset and returns all annotations which start at the same place.

Parameters:

offset - the offset at which to start the search.

Returns:

a set of annotations, all of which start at the same offset >= offset. The returned set is immutable.

get

AnnotationSet get(Long startOffset,
                  Long endOffset)

Select annotations by offset. This returns the set of annotations that overlap totaly or partially the interval defined by the two provided offsets, i.e. that start strictly before endOffset and end strictly after startOffset.

Parameters:

startOffset - the start of the interval

endOffset - the end of the interval

Returns:

the set of annotations that overlap the given interval, or an empty set if there are no such annotations. The returned set is immutable.

get

AnnotationSet get(String type,
                  Long startOffset,
                  Long endOffset)

Select annotations by offset and type. This returns the set of annotations that overlap totaly or partially the interval defined by the two provided offsets and are of the given type. This method is effectively a combination of get(Long, Long) and SimpleAnnotationSet.get(String) but may admit more efficient implementation.

Parameters:

type - the annotation type to search for

startOffset - the start of the interval

endOffset - the end of the interval

Returns:

the set of annotations of the given type that overlap the given interval, or an empty set if no such annotations exist. The returned set is immutable.

getCovering

AnnotationSet getCovering(String neededType,
                          Long startOffset,
                          Long endOffset)

Select annotations of the given type that complete span the range. Formally, for any annotation a, a will be included in the return set if:

• a.getStartNode().getOffset() <= startOffset
• and
• a.getEndNode().getOffset() >= endOffset

Parameters:

neededType - Type of annotation to return. If empty, all annotation types will be returned.

startOffset - the start of the interval

endOffset - the end of the interval

Returns:

the set of annotations matching the parameters, or an empty set if no such annotations exist. The returned set is immutable.

getContained

AnnotationSet getContained(Long startOffset,
                           Long endOffset)

Select annotations by offset. This returns the set of annotations that are contained in the interval defined by the two provided offsets. The difference with get(startOffset, endOffset) is that the latter also provides annotations that have a span which covers completely and is bigger than the given one. Here we only get the annotations between the two offsets. Formally, all annotations are returned whose start position is >= startOffset and whose end position is <= endOffset.

Parameters:

startOffset - the start of the interval, inclusive

endOffset - the end of the interval, inclusive

Returns:

the set of annotations from this set contained completely inside the interval, or an empty set if no such annotations exist. The returned set is immutable.

firstNode

Node firstNode()

Get the node with the smallest offset

lastNode

Node lastNode()

Get the node with the largest offset

nextNode

Node nextNode(Node node)

Get the first node that is relevant for this annotation set and which has the offset larger than the one of the node provided.

addAnnotationSetListener

void addAnnotationSetListener(AnnotationSetListener l)

removeAnnotationSetListener

void removeAnnotationSetListener(AnnotationSetListener l)

addGateListener

void addGateListener(GateListener l)

removeGateListener

void removeGateListener(GateListener l)