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