1   /*
2    *  AnnotationSet.java
3    *
4    *  Copyright (c) 1998-2005, The University of Sheffield.
5    *
6    *  This file is part of GATE (see http://gate.ac.uk/), and is free
7    *  software, licenced under the GNU Library General Public License,
8    *  Version 2, June 1991 (in the distribution as file licence.html,
9    *  and also available at http://gate.ac.uk/gate/licence.html).
10   *
11   *  Hamish Cunningham, 7/Feb/2000
12   *
13   *  $Id: AnnotationSet.java,v 1.26 2005/01/11 13:51:30 ian Exp $
14   */
15  
16  package gate;
17  
18  import java.io.Serializable;
19  import java.util.Iterator;
20  import java.util.Set;
21  
22  import gate.event.AnnotationSetListener;
23  import gate.event.GateListener;
24  import gate.util.InvalidOffsetException;
25  
26  /** Annotation sets */
27  public interface AnnotationSet extends SimpleAnnotationSet, Serializable
28  {
29    /** Create and add an annotation with a pre-existing ID */
30    public void add(
31      Integer id, Long start, Long end, String type, FeatureMap features
32    ) throws InvalidOffsetException;
33  
34    /** Select annotations by type and features */
35    public AnnotationSet get(String type, FeatureMap constraints);
36  
37    /** Select annotations by type and feature names
38     *  It returns all annotations of the given type that
39     *  have the given set of features, regardless of their
40     *  concrete values
41     *  If the type == null, then select regardless of type
42     *  */
43    public AnnotationSet get(String type, Set featureNames);
44  
45    /** Select annotations by type, features and offset */
46    public AnnotationSet get(String type, FeatureMap constraints, Long offset);
47  
48    /** Select annotations by offset. This returns the set of annotations
49      * whose start node is the least such that it is greater than or equal
50      * to offset. If a positional index doesn't exist it is created.
51      */
52    public AnnotationSet get(Long offset);
53  
54    /** Select annotations by offset. This returns the set of annotations
55      * that overlap totaly or partially the interval defined by the two
56      * provided offsets
57      */
58    public AnnotationSet get(Long startOffset, Long endOffset);
59  
60    /** Select annotations by offset and type. This returns the set of annotations
61      * that overlap totaly or partially the interval defined by the two
62      * provided offsets and are of the given type
63      */
64    public AnnotationSet get(String type, Long startOffset, Long endOffset);
65  
66    /** Select annotations by offset. This returns the set of annotations
67      * that are contained in the interval defined by the two
68      * provided offsets. The difference with get(startOffset, endOffset) is
69      * that the latter also provides annotations that have a span which
70      * covers completely and is bigger than the given one. Here we only get
71      * the annotations between the two offsets.
72      */
73    public AnnotationSet getContained(Long startOffset, Long endOffset);
74  
75  
76    /** Get the node with the smallest offset */
77    public Node firstNode();
78  
79    /** Get the node with the largest offset */
80    public Node lastNode();
81  
82    /** Get the first node that is relevant for this annotation set and which has
83      * the offset larger than the one of the node provided.
84      */
85    public Node nextNode(Node node);
86  
87    public void addAnnotationSetListener(AnnotationSetListener l);
88  
89    public void removeAnnotationSetListener(AnnotationSetListener l);
90  
91    public void addGateListener(GateListener l);
92  
93    public void removeGateListener(GateListener l);
94  
95  } // interface AnnotationSet
96