1   /*
2    *  AnnotationSet.java
3    *
4    *  Copyright (c) 1998-2001, 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.22 2002/03/14 16:40:11 hamish Exp $
14   */
15  
16  package gate;
17  
18  import java.util.*;
19  import java.io.*;
20  import gate.util.*;
21  import gate.event.*;
22  
23  /** Annotation sets */
24  public interface AnnotationSet extends Set, Cloneable, Serializable
25  {
26    /** Create and add an annotation with pre-existing nodes,
27      * and return its id
28      */
29    public Integer add(Node start, Node end, String type, FeatureMap features);
30  
31    /** Create and add an annotation with a pre-existing ID */
32    public void add(
33      Integer id, Long start, Long end, String type, FeatureMap features
34    ) throws InvalidOffsetException;
35  
36    /** Create and add an annotation and return its id */
37    public Integer add(Long start, Long end, String type, FeatureMap features)
38      throws InvalidOffsetException;
39  
40    /** Add an existing annotation. Returns true when the set is modified. */
41    public boolean add(Object o);
42  
43    /** Get an iterator for this set */
44    public Iterator iterator();
45  
46    /** The size of this set */
47    public int size();
48  
49    /** Remove an element from this set. */
50    public boolean remove(Object o);
51  
52    /** Find annotations by id */
53    public Annotation    get(Integer id);
54  
55    /** Get all annotations */
56    public AnnotationSet get();
57  
58    /** Select annotations by type */
59    public AnnotationSet get(String type);
60  
61    /** Select annotations by a set of types. Expects a Set of String. */
62    public AnnotationSet get(Set types);
63  
64    /** Select annotations by type and features */
65    public AnnotationSet get(String type, FeatureMap constraints);
66  
67    /** Select annotations by type and feature names
68     *  It returns all annotations of the given type that
69     *  have the given set of features, regardless of their
70     *  concrete values
71     *  If the type == null, then select regardless of type
72     *  */
73    public AnnotationSet get(String type, Set featureNames);
74  
75    /** Select annotations by type, features and offset */
76    public AnnotationSet get(String type, FeatureMap constraints, Long offset);
77  
78    /** Select annotations by offset. This returns the set of annotations
79      * whose start node is the least such that it is greater than or equal
80      * to offset. If a positional index doesn't exist it is created.
81      */
82    public AnnotationSet get(Long offset);
83  
84    /** Select annotations by offset. This returns the set of annotations
85      * that overlap totaly or partially the interval defined by the two
86      * provided offsets
87      */
88    public AnnotationSet get(Long startOffset, Long endOffset);
89  
90    /** Select annotations by offset and type. This returns the set of annotations
91      * that overlap totaly or partially the interval defined by the two
92      * provided offsets and are of the given type
93      */
94    public AnnotationSet get(String type, Long startOffset, Long endOffset);
95  
96    /** Select annotations by offset. This returns the set of annotations
97      * that are contained in the interval defined by the two
98      * provided offsets. The difference with get(startOffset, endOffset) is
99      * that the latter also provides annotations that have a span which
100     * covers completely and is bigger than the given one. Here we only get
101     * the annotations between the two offsets.
102     */
103   public AnnotationSet getContained(Long startOffset, Long endOffset);
104 
105 
106   /** Get the node with the smallest offset */
107   public Node firstNode();
108 
109   /** Get the node with the largest offset */
110   public Node lastNode();
111 
112   /** Get the first node that is relevant for this annotation set and which has
113     * the offset larger than the one of the node provided.
114     */
115   public Node nextNode(Node node);
116 
117   /** Get the name of this set. */
118   public String getName();
119 
120   /** Get a set of java.lang.String objects representing all the annotation
121     * types present in this annotation set.
122     */
123   public Set getAllTypes();
124 
125   /** Get the document this set is attached to. */
126   public Document getDocument();
127 
128   public void addAnnotationSetListener(AnnotationSetListener l);
129 
130   public void removeAnnotationSetListener(AnnotationSetListener l);
131 
132   public void addGateListener(GateListener l);
133 
134   public void removeGateListener(GateListener l);
135 
136 } // interface AnnotationSet
137