001 /*
002 * SimpleAnnotationSet.java
003 *
004 * Copyright (c) 1995-2010, 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 * Kalina Bontcheva, 23/Jul/2004
013 *
014 * $Id: SimpleAnnotationSet.java 12006 2009-12-01 17:24:28Z thomas_heitz $
015 */
016
017 package gate;
018
019 import java.io.Serializable;
020 import java.util.Iterator;
021 import java.util.Set;
022
023 import gate.util.InvalidOffsetException;
024
025 /**
026 * <p>
027 * A set of annotations on a document. Simple annotation sets support
028 * creation of new annotations and access to subsets of the annotations
029 * in the set by annotation type. Annotation sets are attached to
030 * documents - they cannot be constructed directly, but are obtained via
031 * the <code>getAnnotations</code> methods of {@link Document}.
032 * </p>
033 *
034 * <p>
035 * This interface provides methods to get all annotations of a
036 * particular type or set of types from the current set. Note that the
037 * annotation sets returned by these <code>get</code> methods are
038 * immutable snapshots of the set as it was at the time the method was
039 * called. Subsequent changes to the underlying set are not reflected in
040 * the subset view.
041 * </p>
042 *
043 * <p>
044 * This interface extends {@link java.util.Set}<Annotation>, so
045 * can be used anywhere a Java Collections Framework <code>Set</code>
046 * or <code>Collection</code> is required.
047 * </p>
048 */
049 public interface SimpleAnnotationSet extends Set<Annotation>, Cloneable,
050 Serializable {
051 /**
052 * Create and add an annotation with pre-existing nodes, and return
053 * its id. The nodes provided must already exist in this set, i.e.
054 * they must have been obtained from an existing annotation which is
055 * in this set.
056 *
057 * @param start the start node for the new annotation
058 * @param end the end node for the new annotation
059 * @param type the annotation type
060 * @param features the features for the new annotation
061 * @return the newly generated annotation ID, which will be distinct
062 * from all other annotations in this set.
063 */
064 public Integer add(Node start, Node end, String type, FeatureMap features);
065
066 /**
067 * Create and add an annotation and return its id.
068 *
069 * @param start the start offset for the new annotation
070 * @param end the end offset for the new annotation
071 * @param type the annotation type
072 * @param features the features for the new annotation
073 * @return the newly generated annotation ID, which will be distinct
074 * from all other annotations in this set.
075 * @throws InvalidOffsetException if the start or end offsets are
076 * <code>null</code>, or if the start offset is less than
077 * 0 or the end offset is greater than the length of the
078 * document.
079 */
080 public Integer add(Long start, Long end, String type, FeatureMap features)
081 throws InvalidOffsetException;
082
083 /**
084 * Add an existing annotation, which should be an annotation on this
085 * set's document.
086 *
087 * @param a the annotation to add
088 * @return <code>true</code> if the set was modified by this
089 * operation, <code>false</code> otherwise.
090 */
091 public boolean add(Annotation a);
092
093 /**
094 * Get an iterator for this set
095 */
096 public Iterator<Annotation> iterator();
097
098 /**
099 * Get the size of (i.e. number of annotations in) this set.
100 */
101 public int size();
102
103 /**
104 * Remove an element from this set.
105 *
106 * @param o the element to remove
107 * @return <code>true</code> if the set was modified by this
108 * operation, <code>false</code> otherwise.
109 */
110 public boolean remove(Object o);
111
112 /**
113 * Find annotations by id
114 *
115 * @param id the ID to search for
116 * @return the annotation from this set with this ID, or
117 * <code>null</code> if there is no annotation with this ID
118 * in this set.
119 */
120 public Annotation get(Integer id);
121
122 /**
123 * Get a copy of this annotation set.
124 *
125 * @return a snapshot copy of all annotations in this set. The
126 * returned annotation set is immutable.
127 */
128 public AnnotationSet get();
129
130 /**
131 * Select annotations by type.
132 *
133 * @param type the annotation type to search for.
134 * @return a snapshot copy of all annotations in this set that have
135 * the requested type. If there are no annotations of the
136 * requested type in this set, an empty set is returned. The
137 * returned set is immutable.
138 */
139 public AnnotationSet get(String type);
140
141 /**
142 * Select annotations by a set of types.
143 *
144 * @param types the set of annotation types to search for.
145 * @return a snapshot copy of all annotations in this set that have
146 * one of the requested types. If there are no annotations of
147 * the requested types in this set, an empty set is returned.
148 * The returned set is immutable.
149 */
150 public AnnotationSet get(Set<String> types);
151
152 /**
153 * Get the name of this set.
154 *
155 * @return the name of this annotation set, or <code>null</code> if
156 * this set does not have a name (i.e. it is the default
157 * annotation set for a document, or it is a subset view of
158 * another annotation set).
159 */
160 public String getName();
161
162 /**
163 * Get a set of java.lang.String objects representing all the
164 * annotation types present in this annotation set.
165 */
166 public Set<String> getAllTypes();
167
168 /**
169 * Get the document this set is attached to. Every annotation set must
170 * be attached to a document.
171 */
172 public Document getDocument();
173
174 } // interface SimpleAnnotationSet
|