AnnotationSet.java
001 /*
002  *  AnnotationSet.java
003  *
004  *  Copyright (c) 1995-2012, The University of Sheffield. See the file
005  *  COPYRIGHT.txt in the software or at http://gate.ac.uk/gate/COPYRIGHT.txt
006  *
007  *  This file is part of GATE (see http://gate.ac.uk/), and is free
008  *  software, licenced under the GNU Library General Public License,
009  *  Version 2, June 1991 (in the distribution as file licence.html,
010  *  and also available at http://gate.ac.uk/gate/licence.html).
011  *
012  *  Hamish Cunningham, 7/Feb/2000
013  *
014  *  $Id: AnnotationSet.java 18392 2014-10-17 13:32:18Z ian_roberts $
015  */
016 
017 package gate;
018 
019 import gate.event.AnnotationSetListener;
020 import gate.event.GateListener;
021 import gate.util.InvalidOffsetException;
022 
023 import java.io.Serializable;
024 import java.util.List;
025 import java.util.Set;
026 
027 /**
028  <p>
029  * A set of annotations on a document. In addition to the methods
030  * provided by {@link SimpleAnnotationSet}, Annotation sets support
031  * access to subsets of the annotations in the set by various more
032  * complex criteria. Annotation sets are attached to documents - they
033  * cannot be constructed directly, but are obtained via the
034  <code>getAnnotations</code> methods of {@link Document}.
035  </p>
036  *
037  <p>
038  * This interface provides methods to extract subsets of annotations
039  * from the current set given various constraints. Note that the
040  * annotation sets returned by these <code>get</code> methods are
041  * immutable snapshots of the set as it was at the time the method was
042  * called. Subsequent changes to the underlying set are not reflected in
043  * the subset view.
044  </p>
045  *
046  <p>
047  * This interface extends {@link java.util.Set}&lt;Annotation&gt;, so
048  * can be used anywhere a Java Collections Framework <code>Set</code>
049  * or <code>Collection</code> is required.
050  </p>
051  */
052 public interface AnnotationSet extends SimpleAnnotationSet, Serializable {
053   /**
054    * Create and add an annotation with a pre-existing ID. This method
055    * should only be used when you have existing annotations with unique
056    * IDs, for example when reading the full contents of an annotation
057    * set from some saved representation. In normal use you should use
058    * the method
059    {@link SimpleAnnotationSet#add(Long, Long, String, FeatureMap)},
060    * which allows the set to assign a unique ID.
061    *
062    @param id the ID for the new annotation
063    @param start the start offset for the new annotation
064    @param end the end offset for the new annotation
065    @param type the annotation type
066    @param features the features for the new annotation
067    @throws InvalidOffsetException if the start or end offsets are
068    *           <code>null</code>, or if the start offset is less than
069    *           0 or the end offset is greater than the length of the
070    *           document.
071    */
072   public void add(Integer id, Long start, Long end, String type,
073           FeatureMap featuresthrows InvalidOffsetException;
074 
075   /**
076    <p>
077    * Select annotations by type and feature values. This will return an
078    * annotation set containing just those annotations of a particular
079    * type which have features with specific names and values. (It will
080    * also return annotations that have features besides those specified,
081    * but it will not return any annotations that do not have all the
082    * specified feature-value pairs.)
083    </p>
084    *
085    <p>
086    * However, if constraints contains a feature whose value is equal to
087    {@link gate.creole.ANNIEConstants#LOOKUP_CLASS_FEATURE_NAME} (which
088    * is normally "class"), then GATE will attempt to match that feature
089    * using an ontology which it will try to retreive from a feature
090    {@link gate.creole.ANNIEConstants#LOOKUP_ONTOLOGY_FEATURE_NAME} on
091    * both the annotation and in <code>constraints</code>. If these do
092    * not return identical ontologies, or if either the annotation or
093    * constraints does not contain an ontology, then matching will fail,
094    * and the annotation will not be added. In summary, this method will
095    * not work normally for features with the name "class".
096    </p>
097    *
098    @param type The type of the annotations to return.
099    @param constraints A feature map containing all of the feature
100    *          value pairs that the annotation must have in order for
101    *          them to be returned.
102    @return An annotation set containing only those annotations with
103    *         the given name and which have the specified set of
104    *         feature-value pairs. If no annotations match the
105    *         constraints, an empty set is returned. The returned set is
106    *         immutable.
107    */
108   public AnnotationSet get(String type, FeatureMap constraints);
109 
110   /**
111    * Select annotations by type and feature names It returns all
112    * annotations of the given type that have the given set of features,
113    * regardless of their concrete values If the type == null, then
114    * select regardless of type
115    *
116    @param type the annotation type to return. If <code>null</code>
117    *          then all annotation types are searched.
118    @param featureNames the feature names which an annotation must have
119    *          to be matched.
120    @return An annotation set containing only those annotations with
121    *         the given type and at least the given features. If no
122    *         annotations match these constraints, an empty set is
123    *         returned. The returned set is immutable.
124    */
125   public AnnotationSet get(String type, Set<? extends Object> featureNames);
126 
127   /**
128    * Select annotations by type, features and offset. This method is a
129    * combination of {@link #get(Long)} and
130    {@link #get(String, FeatureMap)}, in that it matches annotations
131    * by type and feature constraints but considers only those
132    * annotations that start as close as possible to the right of the
133    * given offset.
134    *
135    @param type the annotation type to search for
136    @param constraints the set of features an annotation must have to
137    *          be matched
138    @param offset the offset at which to anchor the search.
139    @return An annotation set containing those annotations that match
140    *         the constraints, or an empty set if there are no such
141    *         annotations. The returned set is immutable.
142    */
143   public AnnotationSet get(String type, FeatureMap constraints, Long offset);
144 
145   /**
146    * Select annotations by offset. This returns the set of annotations
147    * whose start node is the least such that it is greater than or equal
148    * to <code>offset</code>. In other words it finds the first
149    * annotation that starts at or after the given offset and returns all
150    * annotations which start at the same place.
151    *
152    @param offset the offset at which to start the search.
153    @return a set of annotations, all of which start at the same offset
154    *         &gt;= <code>offset</code>. The returned set is
155    *         immutable.
156    */
157   public AnnotationSet get(Long offset);
158 
159   /**
160    * Select annotations by offset. This returns the set of annotations
161    * that overlap totaly or partially the interval defined by the two
162    * provided offsets, i.e. that start strictly before
163    <code>endOffset</code> and end strictly after
164    <code>startOffset</code>.
165    *
166    @param startOffset the start of the interval
167    @param endOffset the end of the interval
168    @return the set of annotations that overlap the given interval, or
169    *         an empty set if there are no such annotations. The returned
170    *         set is immutable.
171    */
172   public AnnotationSet get(Long startOffset, Long endOffset);
173 
174   /**
175    * Select annotations by offset and type. This returns the set of
176    * annotations that overlap totally or partially the interval defined
177    * by the two provided offsets and are of the given type. This method
178    * is effectively a combination of {@link #get(Long, Long)} and
179    {@link SimpleAnnotationSet#get(String)} but may admit more
180    * efficient implementation.
181    *
182    @param type the annotation type to search for
183    @param startOffset the start of the interval
184    @param endOffset the end of the interval
185    @return the set of annotations of the given type that overlap the
186    *         given interval, or an empty set if no such annotations
187    *         exist. The returned set is immutable.
188    */
189   public AnnotationSet get(String type, Long startOffset, Long endOffset);
190 
191   /**
192    * Select annotations of the given type that completely span the range.
193    * Formally, for any annotation a, a will be included in the return
194    * set if:
195    <ul>
196    <li>a.getStartNode().getOffset() <= startOffset</li>
197    <li>and</li>
198    <li>a.getEndNode().getOffset() >= endOffset</li>
199    *
200    @param neededType Type of annotation to return. If empty, all
201    *          annotation types will be returned.
202    @param startOffset the start of the interval
203    @param endOffset the end of the interval
204    @return the set of annotations matching the parameters, or an empty
205    *         set if no such annotations exist. The returned set is
206    *         immutable.
207    */
208   public AnnotationSet getCovering(String neededType, Long startOffset, Long endOffset);
209 
210   /**
211    * Select annotations by offset. This returns the set of annotations
212    * that are contained in the interval defined by the two provided
213    * offsets. The difference with get(startOffset, endOffset) is that
214    * the latter also provides annotations that have a span which covers
215    * completely and is bigger than the given one. Here we only get the
216    * annotations between the two offsets.  Formally, all annotations
217    * are returned whose start position is >= <code>startOffset</code>
218    * and whose end position is &lt;= <code>endOffset</code>.
219    *
220    @param startOffset the start of the interval, inclusive
221    @param endOffset the end of the interval, inclusive
222    @return the set of annotations from this set contained completely
223    *         inside the interval, or an empty set if no such annotations
224    *         exist. The returned set is immutable.
225    */
226   public AnnotationSet getContained(Long startOffset, Long endOffset);
227 
228   /**
229    * Return a list of annotations sorted by increasing start offset, i.e. in the order
230    * they appear in the document. If more than one annotation starts at a specific offset
231    * the order of these annotations is unspecified.
232    
233    @return a list of annotations ordered by increasing start offset.
234    */
235   public List<Annotation> inDocumentOrder();
236   
237   
238   /**
239    * Get the node with the smallest offset
240    */
241   public Node firstNode();
242 
243   /**
244    * Get the node with the largest offset
245    */
246   public Node lastNode();
247 
248   /**
249    * Get the first node that is relevant for this annotation set and
250    * which has the offset larger than the one of the node provided.
251    */
252   public Node nextNode(Node node);
253 
254   public void addAnnotationSetListener(AnnotationSetListener l);
255 
256   public void removeAnnotationSetListener(AnnotationSetListener l);
257 
258   public void addGateListener(GateListener l);
259 
260   public void removeGateListener(GateListener l);
261 
262 // interface AnnotationSet