gate.annotation

Class AnnotationSetImpl

java.lang.Object

java.util.AbstractCollection<E>

java.util.AbstractSet<Annotation>

gate.annotation.AnnotationSetImpl

All Implemented Interfaces:

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

Direct Known Subclasses:

ImmutableAnnotationSetImpl

public class AnnotationSetImpl
extends AbstractSet<Annotation>
implements AnnotationSet

Implementation of AnnotationSet. Has a number of indices, all bar one of which are null by default and are only constructed when asked for. Has lots of get methods with various selection criteria; these return views into the set, which are nonetheless valid sets in their own right (but will not necesarily be fully indexed). Has a name, which is null by default; clients of Document can request named AnnotationSets if they so desire. Has a reference to the Document it is attached to. Contrary to Collections convention, there is no no-arg constructor, as this would leave the set in an inconsistent state.

There are four indices: annotation by id, annotations by type, annotations by start node and nodes by offset. The last two jointly provide positional indexing; construction of these is triggered by indexByStart(), or by calling a get method that selects on offset. The type index is triggered by indexByType(), or calling a get method that selects on type. The id index is always present.

NOTE: equality and hashCode of this implementation is exclusively based on the annotations which appear in the set (if any). The document the set comes from, the name of the set or the relations stored in that set are not taken into account for equality or hashSet!!

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
protected static AnnotationFactory	annFactory
protected Vector<AnnotationSetListener>	annotationSetListeners
protected HashMap<Integer,Annotation>	annotsById Maps annotation ids (Integers) to Annotations
protected Long	longestAnnot A caching value that greatly improves the performance of get methods that have a defined beginning and end.
protected RelationSet	relations

Constructor Summary

Constructors

Constructor and Description
AnnotationSetImpl(AnnotationSet c) Construction from an existing AnnotationSet
AnnotationSetImpl(Document doc) Construction from Document.
AnnotationSetImpl(Document doc, String name) Construction from Document and name.

Method Summary

Methods

Modifier and Type	Method and Description
boolean	add(Annotation a) Add an existing annotation.
void	add(Integer id, Long start, Long end, String type, FeatureMap features) Create and add an annotation from database read data In this case the id is already known being previously fetched from the database
Integer	add(Long start, Long end, String type, FeatureMap features) Create and add an annotation and return its id
Integer	add(Node start, Node end, String type, FeatureMap features) Create and add an annotation with pre-existing nodes, and return its id.
boolean	addAll(Collection<? extends Annotation> c) Adds multiple annotations to this set in one go.
protected boolean	addAllKeepIDs(Collection<? extends Annotation> c) Adds multiple annotations to this set in one go.
void	addAnnotationSetListener(AnnotationSetListener l)
void	addGateListener(GateListener l)
void	clear()
Object	clone()
void	edit(Long start, Long end, DocumentContent replacement) Propagate document content changes to this AnnotationSet.
protected AnnotationSet	emptyAS()
protected void	fireAnnotationAdded(AnnotationSetEvent e)
protected void	fireAnnotationRemoved(AnnotationSetEvent e)
protected void	fireGateEvent(GateEvent e)
Node	firstNode() Get the node with the smallest offset
AnnotationSet	get() Get all annotations.
Annotation	get(Integer id) Find annotations by id
AnnotationSet	get(Long offset) Select annotations by offset.
AnnotationSet	get(Long startOffset, Long endOffset) Select annotations by offset.
AnnotationSet	get(Set<String> types) Select annotations by a set of types.
AnnotationSet	get(String type) Select annotations by type
AnnotationSet	get(String type, FeatureMap constraints) Select annotations by type and features This will return an annotation set containing just those annotations of a particular type (i.e. with a particular name) and which have features with specific names and values.
AnnotationSet	get(String type, FeatureMap constraints, Long offset) Select annotations by type, features and offset
AnnotationSet	get(String neededType, Long startOffset, Long endOffset) Select annotations by offset.
AnnotationSet	get(String type, Set<? extends Object> featureNames) Select annotations by type and feature names
Set<String>	getAllTypes() Get a set of java.lang.String objects representing all the annotation types present in this annotation set.
AnnotationSet	getContained(Long startOffset, Long endOffset) Select annotations contained within an interval, i.e.
AnnotationSet	getCovering(String neededType, Long startOffset, Long endOffset) Select annotations of the given type that completely span the range.
Document	getDocument() Get the document this set is attached to.
String	getName() Get the name of this set.
RelationSet	getRelations()
AnnotationSet	getStartingAt(long offset) Select annotations by offset.
AnnotationSet	getStrict(Long startOffset, Long endOffset) Select annotations by offset.
protected void	indexByStartOffset() Construct the positional indices for annotation start
protected void	indexByType() Construct the positional index.
List<Annotation>	inDocumentOrder() Return a list of annotations sorted by increasing start offset, i.e. in the order they appear in the document.
Iterator<Annotation>	iterator() Get an iterator for this set
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.
boolean	remove(Object o) Remove an element from this set.
void	removeAnnotationSetListener(AnnotationSetListener l)
protected boolean	removeFromIdIndex(Annotation a) Remove from the ID index.
protected void	removeFromOffsetIndex(Annotation a) Remove from the offset indices.
protected void	removeFromTypeIndex(Annotation a) Remove from the type index.
void	removeGateListener(GateListener l)
static void	setAnnotationFactory(AnnotationFactory newFactory) Set the annotation factory used to create annotation objects.
int	size() The size of this set

Methods inherited from class java.util.AbstractSet

equals, hashCode, removeAll

Methods inherited from class java.util.AbstractCollection

contains, containsAll, isEmpty, retainAll, toArray, toArray, toString

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.Set

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

Field Detail

annotsById

protected transient HashMap<Integer,Annotation> annotsById

Maps annotation ids (Integers) to Annotations

annotationSetListeners

protected transient Vector<AnnotationSetListener> annotationSetListeners

longestAnnot

protected transient Long longestAnnot

A caching value that greatly improves the performance of get methods that have a defined beginning and end. By tracking the maximum length that an annotation can be, we know the maximum amount of nodes outside of a specified range that must be checked to see if an annotation starting at one of those nodes crosses into the range. This mechanism is not perfect because we do not check if we have to decrease it if an annotation is removed from the set. However, usually annotations are removed because they are about to be replaced with another one that is >= to the length of the one being replaced, so this isn't a big deal. At worst, it means that the get methods simply checks a few more start positions than it needs to.

relations

protected RelationSet relations

annFactory

protected static AnnotationFactory annFactory

Constructor Detail

AnnotationSetImpl

public AnnotationSetImpl(Document doc)

Construction from Document.

AnnotationSetImpl

public AnnotationSetImpl(Document doc,
                 String name)

Construction from Document and name.

AnnotationSetImpl

public AnnotationSetImpl(AnnotationSet c)
                  throws ClassCastException

Construction from an existing AnnotationSet

Throws:

ClassCastException

Method Detail

clear

public void clear()

Specified by:

clear in interface Collection<Annotation>

Specified by:

clear in interface Set<Annotation>

Overrides:

clear in class AbstractCollection<Annotation>

iterator

public Iterator<Annotation> iterator()

Get an iterator for this set

Specified by:

iterator in interface SimpleAnnotationSet

Specified by:

iterator in interface Iterable<Annotation>

Specified by:

iterator in interface Collection<Annotation>

Specified by:

iterator in interface Set<Annotation>

Specified by:

iterator in class AbstractCollection<Annotation>

remove

public boolean remove(Object o)
               throws ClassCastException

Remove an element from this set.

Specified by:

remove in interface SimpleAnnotationSet

Specified by:

remove in interface Collection<Annotation>

Specified by:

remove in interface Set<Annotation>

Overrides:

remove in class AbstractCollection<Annotation>

Parameters:

o - the element to remove

Returns:

true if the set was modified by this operation, false otherwise.

Throws:

ClassCastException

removeFromIdIndex

protected boolean removeFromIdIndex(Annotation a)

Remove from the ID index.

removeFromTypeIndex

protected void removeFromTypeIndex(Annotation a)

Remove from the type index.

removeFromOffsetIndex

protected void removeFromOffsetIndex(Annotation a)

Remove from the offset indices.

size

public int size()

The size of this set

Specified by:

size in interface SimpleAnnotationSet

Specified by:

size in interface Collection<Annotation>

Specified by:

size in interface Set<Annotation>

Specified by:

size in class AbstractCollection<Annotation>

get

public Annotation get(Integer id)

Find annotations by id

Specified by:

get in interface SimpleAnnotationSet

Parameters:

id - the ID to search for

Returns:

the annotation from this set with this ID, or null if there is no annotation with this ID in this set.

get

public AnnotationSet get()

Get all annotations.

Specified by:

get in interface SimpleAnnotationSet

Returns:

an ImmutableAnnotationSet, empty or not

get

public AnnotationSet get(String type)

Select annotations by type

Specified by:

get in interface SimpleAnnotationSet

Parameters:

type - the annotation type to search for.

Returns:

an ImmutableAnnotationSet

get

public AnnotationSet get(Set<String> types)
                  throws ClassCastException

Select annotations by a set of types. Expects a Set of String.

Specified by:

get in interface SimpleAnnotationSet

Parameters:

types - the set of annotation types to search for.

Returns:

an ImmutableAnnotationSet

Throws:

ClassCastException

get

public AnnotationSet get(String type,
                FeatureMap constraints)

Select annotations by type and features This will return an annotation set containing just those annotations of a particular type (i.e. with a particular name) and 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 gate.creole.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 on the 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".

Specified by:

get in interface AnnotationSet

Parameters:

type - The name 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.

get

public AnnotationSet get(String type,
                Set<? extends Object> featureNames)

Select annotations by type and feature names

Specified by:

get in interface AnnotationSet

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

public AnnotationSet get(Long offset)

Select annotations by offset. This returns the set of annotations whose start node is the least such that it is less than or equal to offset. If a positional index doesn't exist it is created. If there are no nodes at or beyond the offset param then it will return an empty annotationset.

Specified by:

get in interface AnnotationSet

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.

getStartingAt

public AnnotationSet getStartingAt(long offset)

Select annotations by offset. This returns the set of annotations that start exactly at the given offset. If a positional index doesn't exist it is created. If there are no annotations at the given offset then an empty annotation set is returned.

Parameters:

offset - The starting offset for which to return annotations

Returns:

a ImmutableAnnotationSetImpl containing all annotations starting at the given offset (possibly empty).

inDocumentOrder

public List<Annotation> inDocumentOrder()

Return a list of annotations sorted by increasing start offset, i.e. in the order they appear in the document. If more than one annotation starts at a specific offset the order of these annotations is unspecified.

Specified by:

inDocumentOrder in interface AnnotationSet

Returns:

a list of annotations ordered by increasing start offset. If a positional index does not exist, it is created.

get

public AnnotationSet get(Long startOffset,
                Long endOffset)

Select annotations by offset. This returns the set of annotations that overlap totaly or partially with the interval defined by the two provided offsets.The result will include all the annotations that either:

• start before the start offset and end strictly after it
• OR
• start at a position between the start and the end offsets

Specified by:

get in interface AnnotationSet

Parameters:

startOffset - the start of the interval

endOffset - the end of the interval

Returns:

an ImmutableAnnotationSet

getStrict

public AnnotationSet getStrict(Long startOffset,
                      Long endOffset)

Select annotations by offset. This returns the set of annotations that overlap strictly with the interval defined by the two provided offsets.The result will include all the annotations that start at the start offset and end strictly at the end offset

get

public AnnotationSet get(String neededType,
                Long startOffset,
                Long endOffset)

Select annotations by offset. This returns the set of annotations of the given type that overlap totaly or partially with the interval defined by the two provided offsets.The result will include all the annotations that either:

• start before the start offset and end strictly after it
• OR
• start at a position between the start and the end offsets

Specified by:

get in interface AnnotationSet

Parameters:

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

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

Select annotations of the given type that completely 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

Specified by:

getCovering in interface AnnotationSet

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:

annotations of the given type that completely span the range.

get

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

Select annotations by type, features and offset

Specified by:

get in interface AnnotationSet

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.

getContained

public AnnotationSet getContained(Long startOffset,
                         Long endOffset)

Select annotations contained within an interval, i.e. those annotations whose start position is >= startOffset and whose end position is <= endOffset.

Specified by:

getContained in interface AnnotationSet

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

public Node firstNode()

Get the node with the smallest offset

Specified by:

firstNode in interface AnnotationSet

lastNode

public Node lastNode()

Get the node with the largest offset

Specified by:

lastNode in interface AnnotationSet

nextNode

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

Specified by:

nextNode in interface AnnotationSet

setAnnotationFactory

public static void setAnnotationFactory(AnnotationFactory newFactory)

Set the annotation factory used to create annotation objects. The default factory is DefaultAnnotationFactory.

add

public Integer add(Node start,
          Node end,
          String type,
          FeatureMap features)

Create and add an annotation with pre-existing nodes, and return its id. Note that only Nodes retrieved from the same annotation set should be used to create a new annotation using this method. Using Nodes from other annotation sets may lead to undefined behaviour. If in any doubt use the Long based add method instead of this one.

Specified by:

add in interface SimpleAnnotationSet

Parameters:

start - the start node for the new annotation

end - the end node for the new annotation

type - the annotation type

features - the features for the new annotation

Returns:

the newly generated annotation ID, which will be distinct from all other annotations in this set.

add

public boolean add(Annotation a)
            throws ClassCastException

Add an existing annotation. Returns true when the set is modified.

Specified by:

add in interface SimpleAnnotationSet

Specified by:

add in interface Collection<Annotation>

Specified by:

add in interface Set<Annotation>

Overrides:

add in class AbstractCollection<Annotation>

Parameters:

a - the annotation to add

Returns:

true if the set was modified by this operation, false otherwise.

Throws:

ClassCastException

addAll

public boolean addAll(Collection<? extends Annotation> c)

Adds multiple annotations to this set in one go. All the objects in the provided collection should be of Annotation type, otherwise a ClassCastException will be thrown. The provided annotations will be used to create new annotations using the appropriate add() methods from this set. The new annotations will have different IDs from the old ones (which is required in order to preserve the uniqueness of IDs inside an annotation set).

Specified by:

addAll in interface Collection<Annotation>

Specified by:

addAll in interface Set<Annotation>

Overrides:

addAll in class AbstractCollection<Annotation>

Parameters:

c - a collection of annotations

Returns:

true if the set has been modified as a result of this call.

addAllKeepIDs

protected boolean addAllKeepIDs(Collection<? extends Annotation> c)

Adds multiple annotations to this set in one go. All the objects in the provided collection should be of Annotation type, otherwise a ClassCastException will be thrown. This method does not create copies of the annotations like addAll() does but simply adds the new annotations to the set. It is intended to be used solely by annotation sets in order to construct the results for various get(...) methods.

Parameters:

c - a collection of annotations

Returns:

true if the set has been modified as a result of this call.

add

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

Create and add an annotation and return its id

Specified by:

add in interface SimpleAnnotationSet

Parameters:

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

Returns:

the newly generated annotation ID, which will be distinct from all other annotations in this set.

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.

add

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

Create and add an annotation from database read data In this case the id is already known being previously fetched from the database

Specified by:

add in interface AnnotationSet

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.

indexByType

protected void indexByType()

Construct the positional index.

indexByStartOffset

protected void indexByStartOffset()

Construct the positional indices for annotation start

edit

public void edit(Long start,
        Long end,
        DocumentContent replacement)

Propagate document content changes to this AnnotationSet. This method is called for all annotation sets of a document from DocumentImpl.edit to adapt the annotations to the text changes made through the edit. The behaviour of this method is influenced by the configuration setting GateConstants.DOCEDIT_INSERT_PREPEND : annotations immediately ending before or starting after the point of insertion will either become part of the inserted text or not. Currently it works like this:

• PREPEND=true: annotation before will become part, annotation after not
• PREPEND=false: annotation before will not become part, annotation after will become part

NOTE 1 (JP): There is another setting GateConstants.DOCEDIT_INSERT_APPEND but this setting does currently not influence the behaviour of this method. The behaviour of this method may change in the future so that DOCEDIT_INSERT_APPEND is considered separately and in addition to DOCEDIT_INSERT_PREPEND so that it can be controlled independently if the annotation before and/or after an insertion point gets expanded or not.

NOTE 2: This method has, unfortunately, to be public, to allow DocumentImpls to get at it. Oh for a "friend" declaration. Doesn't throw InvalidOffsetException as DocumentImpl is the only client, and that checks the offsets before calling this method.

getName

public String getName()

Get the name of this set.

Specified by:

getName in interface SimpleAnnotationSet

Returns:

the name of this annotation set, or null if this set does not have a name (i.e. it is the default annotation set for a document, or it is a subset view of another annotation set).

getDocument

public Document getDocument()

Get the document this set is attached to.

Specified by:

getDocument in interface SimpleAnnotationSet

getAllTypes

public Set<String> getAllTypes()

Get a set of java.lang.String objects representing all the annotation types present in this annotation set.

Specified by:

getAllTypes in interface SimpleAnnotationSet

clone

public Object clone()
             throws CloneNotSupportedException

Overrides:

clone in class Object

Returns:

a clone of this set.

Throws:

CloneNotSupportedException

removeAnnotationSetListener

public void removeAnnotationSetListener(AnnotationSetListener l)

Specified by:

removeAnnotationSetListener in interface AnnotationSet

addAnnotationSetListener

public void addAnnotationSetListener(AnnotationSetListener l)

Specified by:

addAnnotationSetListener in interface AnnotationSet

fireAnnotationAdded

protected void fireAnnotationAdded(AnnotationSetEvent e)

fireAnnotationRemoved

protected void fireAnnotationRemoved(AnnotationSetEvent e)

removeGateListener

public void removeGateListener(GateListener l)

Specified by:

removeGateListener in interface AnnotationSet

addGateListener

public void addGateListener(GateListener l)

Specified by:

addGateListener in interface AnnotationSet

fireGateEvent

protected void fireGateEvent(GateEvent e)

getRelations

public RelationSet getRelations()

Specified by:

getRelations in interface SimpleAnnotationSet

emptyAS

protected AnnotationSet emptyAS()