1   /*
2    *  AnnotationSetImpl.java
3    *
4    *  Copyright (c) 1998-2004, 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   *  Developer notes:
14   *  ---
15   *
16   *  the addToIndex... and indexBy... methods could be refactored as I'm
17   *  sure they can be made simpler
18   *
19   *  every set to which annotation will be added has to have positional
20   *  indexing, so that we can find or create the nodes on the new annotations
21   *
22   *  note that annotations added anywhere other than sets that are
23   *  stored on the document will not get stored anywhere...
24   *
25   *  nodes aren't doing anything useful now. needs some interface that allows
26   *  their creation, defaulting to no coterminous duplicates, but allowing such
27   *  if required
28   *
29   *  $Id: AnnotationSetImpl.java,v 1.93 2004/09/27 16:55:37 mike Exp $
30   */
31  
32  package gate.annotation;
33  
34  import java.util.*;
35  
36  import gate.*;
37  import gate.corpora.DocumentImpl;
38  import gate.event.*;
39  import gate.util.InvalidOffsetException;
40  import gate.util.RBTreeMap;
41  
42  /** Implementation of AnnotationSet. Has a number of indices, all bar one
43   * of which are null by default and are only constructed when asked
44   * for. Has lots of get methods with various selection criteria; these
45   * return views into the set, which are nonetheless valid sets in
46   * their own right (but will not necesarily be fully indexed).
47   * Has a name, which is null by default; clients of Document can
48   * request named AnnotationSets if they so desire. Has a reference to the
49   * Document it is attached to. Contrary to Collections convention,
50   * there is no no-arg constructor, as this would leave the set in
51   * an inconsistent state.
52   * <P>
53   * There are five indices: annotation by id, annotations by type, annotations
54   * by start/end node and nodes by offset. The last three jointly provide
55   * positional indexing; construction of these is triggered by
56   * indexByStart/EndOffset(),
57   * or by calling a get method that selects on offset. The type
58   * index is triggered by indexByType(), or calling a get method that selects
59   * on type. The id index is always present.
60   */
61  public class AnnotationSetImpl
62      extends AbstractSet
63      implements AnnotationSet {
64    /** Debug flag */
65    private static final boolean DEBUG = false;
66  
67    /** Construction from Document. */
68    public AnnotationSetImpl(Document doc) {
69  //    annotsById = new VerboseHashMap();
70      annotsById = new HashMap();
71      this.doc = (DocumentImpl) doc;
72    } // construction from document
73  
74    /** Construction from Document and name. */
75    public AnnotationSetImpl(Document doc, String name) {
76      this(doc);
77      this.name = name;
78    } // construction from document and name
79  
80    /** Construction from Collection (which must be an AnnotationSet) */
81  //<<<dam: speedup constructor
82    /*
83      public AnnotationSetImpl(Collection c) throws ClassCastException {
84        this(((AnnotationSet) c).getDocument());
85        addAll(c);
86      } // construction from collection
87     */
88  //===dam: now
89    /** Construction from Collection (which must be an AnnotationSet) */
90    public AnnotationSetImpl(Collection c) throws ClassCastException {
91      this( ( (AnnotationSet) c).getDocument(), ( (AnnotationSet) c).getName());
92      if (c instanceof AnnotationSetImpl) {
93        AnnotationSetImpl theC = (AnnotationSetImpl) c;
94        annotsById = (HashMap) theC.annotsById.clone();
95        if (theC.annotsByEndNode != null) {
96          annotsByEndNode = (Map) ( (HashMap) theC.annotsByEndNode).clone();
97          annotsByStartNode = (Map) ( (HashMap) theC.annotsByStartNode).clone();
98        }
99        if (theC.annotsByType != null)
100         annotsByType = (Map) ( (HashMap) theC.annotsByType).clone();
101       if (theC.nodesByOffset != null) {
102         nodesByOffset = (RBTreeMap) theC.nodesByOffset.clone();
103       }
104     }
105     else
106       addAll(c);
107   } // construction from collection
108 
109 //>>>dam: end
110 
111   /** This inner class serves as the return value from the iterator()
112    * method.
113    */
114   class AnnotationSetIterator
115       implements Iterator {
116     private Iterator iter;
117     protected Annotation lastNext = null;
118     AnnotationSetIterator() {
119       iter = annotsById.values().iterator();
120     }
121 
122     public boolean hasNext() {
123       return iter.hasNext();
124     }
125 
126     public Object next() {
127       return (lastNext = (Annotation) iter.next());
128     }
129 
130     public void remove() {
131       // this takes care of the ID index
132       iter.remove();
133       // remove from type index
134       removeFromTypeIndex(lastNext);
135       // remove from offset indices
136       removeFromOffsetIndex(lastNext);
137       //that's the second way of removing annotations from a set
138       //apart from calling remove() on the set itself
139       fireAnnotationRemoved(new AnnotationSetEvent(
140           AnnotationSetImpl.this,
141           AnnotationSetEvent.ANNOTATION_REMOVED,
142           getDocument(), (Annotation) lastNext));      
143     } // remove()
144   }; // AnnotationSetIterator
145 
146   /**
147    *  This is a {@link java.util.HashMap}
148    * that fires events when elements are removed.
149    * 
150    * This class has been used in a previous version for the indexById structure 
151    * which now uses a simple HashMap.
152    * 
153    * This class is kept here for backwards compatibility of old serial 
154    * datastores.
155    *  
156    */
157   public class VerboseHashMap
158       extends HashMap {
159     VerboseHashMap() {
160       super(Gate.HASH_STH_SIZE);
161     } //contructor
162 
163     public Object remove(Object key) {
164       Object res = super.remove(key);
165       if (res != null) {
166         if (owner == null) {
167           fireAnnotationRemoved(new AnnotationSetEvent(
168               AnnotationSetImpl.this,
169               AnnotationSetEvent.ANNOTATION_REMOVED,
170               getDocument(), (Annotation) res));
171         }
172         else {
173           owner.fireAnnotationRemoved(new AnnotationSetEvent(
174               AnnotationSetImpl.this,
175               AnnotationSetEvent.ANNOTATION_REMOVED,
176               getDocument(), (Annotation) res));
177         }
178       }
179       return res;
180     } //public Object remove(Object key)
181 
182     static final long serialVersionUID = -4832487354063073511L;
183 
184     /**
185      * The annotation set this maps is part of.
186      * This is an ugly hack in order to fix a bug: database annotation sets
187      * didn't fire annotation removed events.
188      */
189     private transient AnnotationSetImpl owner;
190 
191     /**
192      * Sets the annotation set this maps is part of.
193      * This is an ugly hack in order to fix a bug: database annotation sets
194      * didn't fire annotation removed events.
195      */
196     public void setOwner(AnnotationSetImpl newOwner) {
197       this.owner = newOwner;
198     }
199   } //protected class VerboseHashMap extends HashMap
200 
201   /** Get an iterator for this set */
202   public Iterator iterator() {
203     return new AnnotationSetIterator();
204   }
205 
206   /** Remove an element from this set. */
207   public boolean remove(Object o) throws ClassCastException {
208     Annotation a = (Annotation) o;
209     boolean wasPresent = removeFromIdIndex(a);
210     if (wasPresent) {
211       removeFromTypeIndex(a);
212       removeFromOffsetIndex(a);
213     }
214     //fire the event
215     fireAnnotationRemoved(new AnnotationSetEvent(
216         AnnotationSetImpl.this,
217         AnnotationSetEvent.ANNOTATION_REMOVED,
218         getDocument(), a));
219     
220     return wasPresent;
221   } // remove(o)
222   
223 
224   /** Remove from the ID index. */
225   protected boolean removeFromIdIndex(Annotation a) {
226     if (annotsById.remove(a.getId()) == null)
227       return false;
228     return true;
229   } // removeFromIdIndex(a)
230 
231   /** Remove from the type index. */
232   protected void removeFromTypeIndex(Annotation a) {
233     if (annotsByType != null) {
234       AnnotationSet sameType = (AnnotationSet) annotsByType.get(a.getType());
235       if (sameType != null)
236         sameType.remove(a);
237       if (sameType.isEmpty()) // none left of this type
238         annotsByType.remove(a.getType());
239     }
240   } // removeFromTypeIndex(a)
241 
242   /** Remove from the offset indices. */
243   protected void removeFromOffsetIndex(Annotation a) {
244     if (nodesByOffset != null) {
245       // knowing when a node is no longer needed would require keeping a reference
246       // count on annotations, or using a weak reference to the nodes in
247       // nodesByOffset
248     }
249     if (annotsByStartNode != null) {
250       Integer id = a.getStartNode().getId();
251       AnnotationSet starterAnnots = (AnnotationSet) annotsByStartNode.get(id);
252       starterAnnots.remove(a);
253       if (starterAnnots.isEmpty()) // no annotations start here any more
254         annotsByStartNode.remove(id);
255     }
256     if (annotsByEndNode != null) {
257       Integer id = a.getEndNode().getId();
258       AnnotationSet endingAnnots = (AnnotationSet) annotsByEndNode.get(id);
259       endingAnnots.remove(a);
260       if (endingAnnots.isEmpty()) // no annotations start here any more
261         annotsByEndNode.remove(id);
262     }
263   } // removeFromOffsetIndex(a)
264 
265   /** The size of this set */
266   public int size() {
267     return annotsById.size();
268   }
269 
270   /** Find annotations by id */
271   public Annotation get(Integer id) {
272     return (Annotation) annotsById.get(id);
273   } // get(id)
274 
275   /** Get all annotations */
276   public AnnotationSet get() {
277     AnnotationSetImpl resultSet = new AnnotationSetImpl(doc);
278     resultSet.addAllKeepIDs(annotsById.values());
279     if (resultSet.isEmpty())
280       return null;
281     return resultSet;
282   } // get()
283 
284   /** Select annotations by type */
285   public AnnotationSet get(String type) {
286     if (annotsByType == null)
287       indexByType();
288       // the aliasing that happens when returning a set directly from the
289       // types index can cause concurrent access problems; but the fix below
290       // breaks the tests....
291       //AnnotationSet newSet =
292       //  new AnnotationSetImpl((Collection) annotsByType.get(type));
293       //return newSet;
294     return (AnnotationSet) annotsByType.get(type);
295   } // get(type)
296 
297   /** Select annotations by a set of types. Expects a Set of String. */
298   public AnnotationSet get(Set types) throws ClassCastException {
299     if (annotsByType == null)
300       indexByType();
301     Iterator iter = types.iterator();
302     AnnotationSetImpl resultSet = new AnnotationSetImpl(doc);
303     while (iter.hasNext()) {
304       String type = (String) iter.next();
305       AnnotationSet as = (AnnotationSet) annotsByType.get(type);
306       if (as != null)
307         resultSet.addAllKeepIDs(as);
308         // need an addAllOfOneType method
309     } // while
310     if (resultSet.isEmpty())
311       return null;
312     return resultSet;
313   } // get(types)
314 
315   /** 
316    * Select annotations by type and features 
317    * 
318    * This will return an annotation set containing just those annotations of a
319    * particular type (i.e. with a particular name) and which have features with 
320    * specific names and values. (It will also return annotations that have features
321    * besides those specified, but it will not return any annotations that do not
322    * have all the specified feature-value pairs.)
323    * 
324    * However, if constraints contains a feature whose value is equal to 
325    * gate.creole.ANNIEConstants.LOOKUP_CLASS_FEATURE_NAME (which is normally 
326    * "class"), then GATE will attempt to match that feature using an ontology
327    * which it will try to retreive from a feature on the both the annotation
328    * and in constraints. If these do not return identical ontologies, or if
329    * either the annotation or constraints does not contain an ontology, then 
330    * matching will fail, and the annotation will not be added. In summary, 
331    * this method will not work normally for features with the name "class".
332    * 
333    * @param type The name of the annotations to return.
334    * @param constraints A feature map containing all of the feature value pairs
335    * that the annotation must have in order for them to be returned.
336    * @return An annotation set containing only those annotations with the given
337    * name and which have the specified set of feature-value pairs.
338    */
339   public AnnotationSet get(String type, FeatureMap constraints) {
340     if (annotsByType == null)
341       indexByType();
342     AnnotationSet typeSet = get(type);
343     if (typeSet == null)
344       return null;
345     AnnotationSet resultSet = new AnnotationSetImpl(doc);
346     Iterator iter = typeSet.iterator();
347     while (iter.hasNext()) {
348       Annotation a = (Annotation) iter.next();
349       // we check for matching constraints by simple equality. a
350       // feature map satisfies the constraints if it contains all the
351       // key/value pairs from the constraints map
352 
353 //      if (a.getFeatures().entrySet().containsAll(constraints.entrySet()))
354       if( a.getFeatures().subsumes(constraints))
355         resultSet.add(a);
356     } // while
357     if (resultSet.isEmpty())
358       return null;
359     return resultSet;
360   } // get(type, constraints)
361 
362   /** Select annotations by type and feature names */
363   public AnnotationSet get(String type, Set featureNames) {
364     if (annotsByType == null)
365       indexByType();
366     AnnotationSet typeSet = null;
367     if (type != null) {
368       //if a type is provided, try finding annotations of this type
369       typeSet = get(type);
370       //if none exist, then return coz nothing left to do
371       if (typeSet == null)
372         return null;
373     }
374     AnnotationSet resultSet = new AnnotationSetImpl(doc);
375     Iterator iter = null;
376     if (type != null)
377       iter = typeSet.iterator();
378     else
379       iter = annotsById.values().iterator();
380     while (iter.hasNext()) {
381       Annotation a = (Annotation) iter.next();
382       // we check for matching constraints by simple equality. a
383       // feature map satisfies the constraints if it contains all the
384       // key/value pairs from the constraints map
385       if (a.getFeatures().keySet().containsAll(featureNames))
386         resultSet.add(a);
387     } // while
388     if (resultSet.isEmpty())
389       return null;
390     return resultSet;
391   } // get(type, featureNames)
392 
393   /** Select annotations by offset. This returns the set of annotations
394    * whose start node is the least such that it is less than or equal
395    * to offset. If a positional index doesn't exist it is created.
396    * If there are no nodes at or beyond the offset param then it will return
397    * null.
398    */
399   public AnnotationSet get(Long offset) {
400     if (annotsByStartNode == null)
401       indexByStartOffset();
402       // find the next node at or after offset; get the annots starting there
403     Node nextNode = (Node) nodesByOffset.getNextOf(offset);
404     if (nextNode == null) // no nodes at or beyond this offset
405       return null;
406     AnnotationSet res = (AnnotationSet) annotsByStartNode.get(nextNode.getId());
407     //get ready for next test
408     nextNode = (Node) nodesByOffset.getNextOf(new Long(offset.longValue() + 1));
409     //skip all the nodes that have no starting annotations
410     while (res == null && nextNode != null) {
411       res = (AnnotationSet) annotsByStartNode.get(nextNode.getId());
412       //get ready for next test
413       nextNode = (Node) nodesByOffset.getNextOf(
414           new Long(nextNode.getOffset().longValue() + 1)
415           );
416     }
417     //res it either null (no suitable node found) or the correct result
418     return res;
419   } // get(offset)
420 
421   /**
422    * Select annotations by offset. This returns the set of annotations
423    * that overlap totaly or partially with the interval defined by the two
424    * provided offsets.The result will include all the annotations that either:
425    * <ul>
426    * <li>start before the start offset and end strictly after it</li>
427    * <li>OR</li>
428    * <li>start at a position between the start and the end offsets</li>
429    */
430   public AnnotationSet get(Long startOffset, Long endOffset) {
431     //the result will include all the annotations that either:
432     //-start before the start offset and end strictly after it
433     //or
434     //-start at a position between the start and the end offsets
435     if (annotsByStartNode == null)
436       indexByStartOffset();
437     AnnotationSetImpl resultSet = new AnnotationSetImpl(doc);
438     Iterator nodesIter;
439     Iterator annotsIter;
440     Node currentNode;
441     Annotation currentAnnot;
442     //find all the annots that start strictly before the start offset and end
443     //strictly after it
444     nodesIter = nodesByOffset.headMap(startOffset).values().iterator();
445     while (nodesIter.hasNext()) {
446       currentNode = (Node) nodesIter.next();
447       Set fromPoint = (Set) annotsByStartNode.get(currentNode.getId());
448       if (fromPoint != null) {
449         annotsIter = (fromPoint).iterator();
450         while (annotsIter.hasNext()) {
451           currentAnnot = (Annotation) annotsIter.next();
452           if (currentAnnot.getEndNode().getOffset().compareTo(startOffset) > 0) {
453             resultSet.add(currentAnnot);
454           }
455         }
456       }
457     }
458     //find all the annots that start at or after the start offset but strictly
459     //before the end offset
460     nodesIter = nodesByOffset.subMap(startOffset, endOffset).values().iterator();
461     while (nodesIter.hasNext()) {
462       currentNode = (Node) nodesIter.next();
463       Set fromPoint = (Set) annotsByStartNode.get(currentNode.getId());
464       if (fromPoint != null)
465         resultSet.addAllKeepIDs(fromPoint);
466     }
467     return resultSet;
468   } //get(startOfset, endOffset)
469 
470   /**
471    * Select annotations by offset. This returns the set of annotations
472    * that overlap strictly with the interval defined by the two
473    * provided offsets.The result will include all the annotations that
474    * start at the start offset and end strictly at the end offset
475    */
476   public AnnotationSet getStrict(Long startOffset, Long endOffset) {
477     //the result will include all the annotations that
478     //start at the start offset and end strictly at the end offset
479     if (annotsByStartNode == null)
480       indexByStartOffset();
481     AnnotationSet resultSet = new AnnotationSetImpl(doc);
482     Iterator nodesIter;
483     Iterator annotsIter;
484     Node currentNode;
485     Annotation currentAnnot;
486     //find all the annots that start at the start offset
487     currentNode = (Node) nodesByOffset.get(startOffset);
488     if (currentNode != null) {
489       Set fromPoint = (Set) annotsByStartNode.get(currentNode.getId());
490       if (fromPoint != null) {
491         annotsIter = fromPoint.iterator();
492         while (annotsIter.hasNext()) {
493           currentAnnot = (Annotation) annotsIter.next();
494           if (currentAnnot.getEndNode().getOffset().compareTo(endOffset) == 0) {
495             resultSet.add(currentAnnot);
496           } // if
497         } // while
498       } // if
499     } // if
500     return resultSet;
501   } //getStrict(startOfset, endOffset)
502 
503   /**
504    * Select annotations by offset. This returns the set of annotations
505    * of the given type
506    * that overlap totaly or partially with the interval defined by the two
507    * provided offsets.The result will include all the annotations that either:
508    * <ul>
509    * <li>start before the start offset and end strictly after it</li>
510    * <li>OR</li>
511    * <li>start at a position between the start and the end offsets</li>
512    */
513   public AnnotationSet get(String neededType, Long startOffset, Long endOffset) {
514     //the result will include all the annotations that either:
515     //-start before the start offset and end strictly after it
516     //or
517     //-start at a position between the start and the end offsets
518     if (annotsByStartNode == null)
519       indexByStartOffset();
520     AnnotationSet resultSet = new AnnotationSetImpl(doc);
521     Iterator nodesIter;
522     Iterator annotsIter;
523     Node currentNode;
524     Annotation currentAnnot;
525     //find all the annots that start strictly before the start offset and end
526     //strictly after it
527     nodesIter = nodesByOffset.headMap(startOffset).values().iterator();
528     while (nodesIter.hasNext()) {
529       currentNode = (Node) nodesIter.next();
530       Set fromPoint = (Set) annotsByStartNode.get(currentNode.getId());
531       if (fromPoint != null) {
532         annotsIter = (fromPoint).iterator();
533         while (annotsIter.hasNext()) {
534           currentAnnot = (Annotation) annotsIter.next();
535           if (currentAnnot.getType().equals(neededType) &&
536               currentAnnot.getEndNode().getOffset().compareTo(startOffset) > 0
537               ) {
538             resultSet.add(currentAnnot);
539           } //if
540         } //while
541       }
542     }
543     //find all the annots that start at or after the start offset but strictly
544     //before the end offset
545     nodesIter = nodesByOffset.subMap(startOffset, endOffset).values().iterator();
546     while (nodesIter.hasNext()) {
547       currentNode = (Node) nodesIter.next();
548       Set fromPoint = (Set) annotsByStartNode.get(currentNode.getId());
549       if (fromPoint != null) {
550         annotsIter = (fromPoint).iterator();
551         while (annotsIter.hasNext()) {
552           currentAnnot = (Annotation) annotsIter.next();
553           if (currentAnnot.getType().equals(neededType)) {
554             resultSet.add(currentAnnot);
555           } //if
556         } //while
557       } //if
558     }
559     return resultSet;
560   } //get(type, startOfset, endOffset)
561 
562   /** Select annotations by type, features and offset */
563   public AnnotationSet get(String type, FeatureMap constraints, Long offset) {
564     // select by offset
565     AnnotationSet nextAnnots = (AnnotationSet) get(offset);
566     if (nextAnnots == null)
567       return null;
568     // select by type and constraints from the next annots
569     return nextAnnots.get(type, constraints);
570   } // get(type, constraints, offset)
571 
572   /**
573    * Select annotations by offset that
574    * start at a position between the start and end before the end offset
575    */
576   public AnnotationSet getContained(Long startOffset, Long endOffset) {
577     //the result will include all the annotations that either:
578     //start at a position between the start and end before the end offsets
579     if (annotsByStartNode == null)
580       indexByStartOffset();
581     AnnotationSet resultSet = new AnnotationSetImpl(doc);
582     Iterator nodesIter;
583     Iterator annotsIter;
584     Node currentNode;
585     Annotation currentAnnot;
586     //find all the annots that start at or after the start offset but strictly
587     //before the end offset
588     nodesIter = nodesByOffset.subMap(startOffset, endOffset).values().iterator();
589     while (nodesIter.hasNext()) {
590       currentNode = (Node) nodesIter.next();
591       Set fromPoint = (Set) annotsByStartNode.get(currentNode.getId());
592       if (fromPoint == null)
593         continue;
594       //loop through the annotations and find only those that
595       //also end before endOffset
596       Iterator annotIter = fromPoint.iterator();
597       while (annotIter.hasNext()) {
598         Annotation annot = (Annotation) annotIter.next();
599         if (annot.getEndNode().getOffset().compareTo(endOffset) <= 0)
600           resultSet.add(annot);
601       }
602     }
603     return resultSet;
604   } //get(startOfset, endOffset)
605 
606   /** Get the node with the smallest offset */
607   public Node firstNode() {
608     indexByStartOffset();
609     if (nodesByOffset.isEmpty())
610       return null;
611     else
612       return (Node) nodesByOffset.get(nodesByOffset.firstKey());
613   } // firstNode
614 
615   /** Get the node with the largest offset */
616   public Node lastNode() {
617     indexByStartOffset();
618     indexByEndOffset();
619     if (nodesByOffset.isEmpty())
620       return null;
621     else
622       return (Node) nodesByOffset.get(nodesByOffset.lastKey());
623   } // lastNode
624 
625   /**
626    * Get the first node that is relevant for this annotation set and which has
627    * the offset larger than the one of the node provided.
628    */
629   public Node nextNode(Node node) {
630     indexByStartOffset();
631     indexByEndOffset();
632     return (Node) nodesByOffset.getNextOf(
633         new Long(node.getOffset().longValue() + 1)
634         );
635   }
636 
637   /** Create and add an annotation with pre-existing nodes,
638    * and return its id
639    */
640   public Integer add(Node start, Node end, String type, FeatureMap features) {
641     // the id of the new annotation
642     Integer id = doc.getNextAnnotationId();
643     // construct an annotation
644     Annotation a = new AnnotationImpl(id, start, end, type, features);
645     // delegate to the method that adds existing annotations
646     add(a);
647     return id;
648   } // add(Node, Node, String, FeatureMap)
649 
650   /** Add an existing annotation. Returns true when the set is modified. */
651   public boolean add(Object o) throws ClassCastException {
652     Annotation a = (Annotation) o;
653     Object oldValue = annotsById.put(a.getId(), a);
654     if (annotsByType != null)
655       addToTypeIndex(a);
656     if (annotsByStartNode != null || annotsByEndNode != null)
657       addToOffsetIndex(a);
658     AnnotationSetEvent evt = new AnnotationSetEvent(
659         this,
660         AnnotationSetEvent.ANNOTATION_ADDED,
661         doc, a);
662     fireAnnotationAdded(evt);
663     fireGateEvent(evt);
664     return oldValue != a;
665   } // add(o)
666 
667   /**
668    * Adds multiple annotations to this set in one go.
669    * All the objects in the provided collection should be of
670    * {@link gate.Annotation} type, otherwise a ClassCastException will be
671    * thrown.
672    * The provided annotations will be used to create new annotations using the
673    * appropriate add() methods from this set. The new annotations will have
674        * different IDs from the old ones (which is required in order to preserve the
675    * uniqueness of IDs inside an annotation set).
676    * @param c a collection of annotations
677    * @return <tt>true</tt> if the set has been modified as a result of this
678    * call.
679    */
680   public boolean addAll(Collection c) {
681     Iterator annIter = c.iterator();
682     boolean changed = false;
683     while (annIter.hasNext()) {
684       Annotation a = (Annotation) annIter.next();
685       try {
686         add(a.getStartNode().getOffset(),
687             a.getEndNode().getOffset(),
688             a.getType(),
689             a.getFeatures());
690         changed = true;
691       }
692       catch (InvalidOffsetException ioe) {
693         throw new IllegalArgumentException(ioe.toString());
694       }
695     }
696     return changed;
697   }
698 
699   /**
700    * Adds multiple annotations to this set in one go.
701    * All the objects in the provided collection should be of
702    * {@link gate.Annotation} type, otherwise a ClassCastException will be
703    * thrown.
704    * This method does not create copies of the annotations like addAll() does
705    * but simply adds the new annotations to the set.
706    * It is intended to be used solely by annotation sets in order to construct
707    * the results for various get(...) methods.
708    * @param c a collection of annotations
709    * @return <tt>true</tt> if the set has been modified as a result of this
710    * call.
711    */
712   protected boolean addAllKeepIDs(Collection c) {
713     Iterator annIter = c.iterator();
714     boolean changed = false;
715     while (annIter.hasNext()) {
716       Annotation a = (Annotation) annIter.next();
717       changed |= add(a);
718     }
719     return changed;
720   }
721 
722   /** Create and add an annotation and return its id */
723   public Integer add(
724       Long start, Long end, String type, FeatureMap features
725       ) throws InvalidOffsetException {
726     // are the offsets valid?
727     if (!doc.isValidOffsetRange(start, end))
728       throw new InvalidOffsetException();
729     // the set has to be indexed by position in order to add, as we need
730     // to find out if nodes need creating or if they exist already
731     if (nodesByOffset == null) {
732       indexByStartOffset();
733       indexByEndOffset();
734     }
735     // find existing nodes if appropriate nodes don't already exist, create them
736     Node startNode = (Node) nodesByOffset.getNextOf(start);
737     if (startNode == null || !startNode.getOffset().equals(start))
738       startNode = new NodeImpl(doc.getNextNodeId(), start);
739     Node endNode = null;
740     if (start.equals(end))
741       endNode = startNode;
742     else
743       endNode = (Node) nodesByOffset.getNextOf(end);
744     if (endNode == null || !endNode.getOffset().equals(end))
745       endNode = new NodeImpl(doc.getNextNodeId(), end);
746       // delegate to the method that adds annotations with existing nodes
747     return add(startNode, endNode, type, features);
748   } // add(start, end, type, features)
749 
750   /** Create and add an annotation from database read data
751    * In this case the id is already known being previously fetched from the
752    * database
753    */
754   public void add(
755       Integer id, Long start, Long end, String type, FeatureMap features
756       ) throws InvalidOffsetException {
757     // are the offsets valid?
758     if (!doc.isValidOffsetRange(start, end))
759       throw new InvalidOffsetException();
760     // the set has to be indexed by position in order to add, as we need
761     // to find out if nodes need creating or if they exist already
762     if (nodesByOffset == null) {
763       indexByStartOffset();
764       indexByEndOffset();
765     }
766     // find existing nodes if appropriate nodes don't already exist, create them
767     Node startNode = (Node) nodesByOffset.getNextOf(start);
768     if (startNode == null || !startNode.getOffset().equals(start))
769       startNode = new NodeImpl(doc.getNextNodeId(), start);
770     Node endNode = null;
771     if (start.equals(end))
772       endNode = startNode;
773     else
774       endNode = (Node) nodesByOffset.getNextOf(end);
775     if (endNode == null || !endNode.getOffset().equals(end))
776       endNode = new NodeImpl(doc.getNextNodeId(), end);
777       // construct an annotation
778     Annotation a = new AnnotationImpl(id, startNode, endNode, type, features);
779     add(a);
780   } // add(id, start, end, type, features)
781 
782   /** Construct the positional index. */
783   protected void indexByType() {
784     if (annotsByType != null)
785       return;
786     annotsByType = new HashMap(Gate.HASH_STH_SIZE);
787     Annotation a;
788     Iterator annotIter = annotsById.values().iterator();
789     while (annotIter.hasNext())
790       addToTypeIndex( (Annotation) annotIter.next());
791   } // indexByType()
792 
793   /** Construct the positional indices for annotation start */
794   protected void indexByStartOffset() {
795     if (annotsByStartNode != null) return;
796     if (nodesByOffset == null) nodesByOffset = new RBTreeMap();
797     annotsByStartNode = new HashMap(Gate.HASH_STH_SIZE);
798     Iterator annotIter = annotsById.values().iterator();
799     while (annotIter.hasNext())
800       addToStartOffsetIndex( (Annotation) annotIter.next());
801   } // indexByStartOffset()
802 
803   /** Construct the positional indices for annotation end */
804   protected void indexByEndOffset() {
805     if (annotsByEndNode != null)
806       return;
807     if (nodesByOffset == null)
808       nodesByOffset = new RBTreeMap();
809     annotsByEndNode = new HashMap(Gate.HASH_STH_SIZE);
810     Annotation a;
811     Iterator annotIter = annotsById.values().iterator();
812     while (annotIter.hasNext())
813       addToEndOffsetIndex( (Annotation) annotIter.next());
814   } // indexByEndOffset()
815 
816   /** Add an annotation to the type index. Does nothing if the index
817    * doesn't exist.
818    */
819   void addToTypeIndex(Annotation a) {
820     if (annotsByType == null)
821       return;
822     String type = a.getType();
823     AnnotationSet sameType = (AnnotationSet) annotsByType.get(type);
824     if (sameType == null) {
825       sameType = new AnnotationSetImpl(doc);
826       annotsByType.put(type, sameType);
827     }
828     sameType.add(a);
829   } // addToTypeIndex(a)
830 
831   /** Add an annotation to the offset indices. Does nothing if they
832    * don't exist.
833    */
834   void addToOffsetIndex(Annotation a) {
835     addToStartOffsetIndex(a);
836     addToEndOffsetIndex(a);
837   } // addToOffsetIndex(a)
838 
839   /** Add an annotation to the start offset index. Does nothing if the
840    * index doesn't exist.
841    */
842   void addToStartOffsetIndex(Annotation a) {
843     Node startNode = a.getStartNode();
844     Node endNode = a.getEndNode();
845     Long start = startNode.getOffset();
846     Long end = endNode.getOffset();
847     // add a's nodes to the offset index
848     if (nodesByOffset != null)
849       nodesByOffset.put(start, startNode);
850       // if there's no appropriate index give up
851     if (annotsByStartNode == null)
852       return;
853     // get the annotations that start at the same node, or create new set
854     AnnotationSet thisNodeAnnots =
855         (AnnotationSet) annotsByStartNode.get(startNode.getId());
856     if (thisNodeAnnots == null) {
857       thisNodeAnnots = new AnnotationSetImpl(doc);
858       annotsByStartNode.put(startNode.getId(), thisNodeAnnots);
859     }
860     // add to the annots listed for a's start node
861     thisNodeAnnots.add(a);
862   } // addToStartOffsetIndex(a)
863 
864   /** Add an annotation to the end offset index. Does nothing if the
865    * index doesn't exist.
866    */
867   void addToEndOffsetIndex(Annotation a) {
868     Node startNode = a.getStartNode();
869     Node endNode = a.getEndNode();
870     Long start = startNode.getOffset();
871     Long end = endNode.getOffset();
872     // add a's nodes to the offset index
873     if (nodesByOffset != null)
874       nodesByOffset.put(end, endNode);
875       // if there's no appropriate index give up
876     if (annotsByEndNode == null)
877       return;
878     // get the annotations that start at the same node, or create new set
879     AnnotationSet thisNodeAnnots =
880         (AnnotationSet) annotsByEndNode.get(endNode.getId());
881     if (thisNodeAnnots == null) {
882       thisNodeAnnots = new AnnotationSetImpl(doc);
883       annotsByEndNode.put(endNode.getId(), thisNodeAnnots);
884     }
885     // add to the annots listed for a's start node
886     thisNodeAnnots.add(a);
887   } // addToEndOffsetIndex(a)
888 
889   /** Propagate changes to the document content. Has, unfortunately,
890    * to be public, to allow DocumentImpls to get at it. Oh for a
891    * "friend" declaration. Doesn't throw InvalidOffsetException as
892    * DocumentImpl is the only client, and that checks the offsets
893    * before calling this method.
894    */
895   public void edit(Long start, Long end, DocumentContent replacement) {
896     //make sure we have the indices computed
897     indexByStartOffset();
898     indexByEndOffset();
899     if(end.compareTo(start) > 0){
900       //get the nodes that need to be processed (the nodes internal to the
901       //removed section plus the marginal ones
902       List affectedNodes = new ArrayList(nodesByOffset.subMap(start,
903           new Long(end.longValue() + 1)).values());
904       //if we have more than 1 node we need to delete all apart from the first
905       //and move the annotations so that they refer to the one we keep (the first)
906       NodeImpl firstNode = null;
907       if (!affectedNodes.isEmpty()) {
908         firstNode = (NodeImpl) affectedNodes.get(0);
909         List startingAnnotations = new ArrayList();
910         List endingAnnotations = new ArrayList();
911         for (int i = 1; i < affectedNodes.size(); i++) {
912           Node aNode = (Node) affectedNodes.get(i);
913           //save the annotations
914           AnnotationSet annSet = (AnnotationSet) annotsByStartNode.get(aNode.
915               getId());
916           if (annSet != null)
917             startingAnnotations.addAll(annSet);
918           annSet = (AnnotationSet) annotsByEndNode.get(aNode.getId());
919           if (annSet != null)
920             endingAnnotations.addAll(annSet);
921             //remove the node
922             nodesByOffset.remove(aNode.getOffset());
923             annotsByStartNode.remove(aNode);
924             annotsByEndNode.remove(aNode);
925         }
926         //modify the annotations so they point to the saved node
927         Iterator annIter = startingAnnotations.iterator();
928         while (annIter.hasNext()) {
929           AnnotationImpl anAnnot = (AnnotationImpl) annIter.next();
930           anAnnot.start = firstNode;
931           addToStartOffsetIndex(anAnnot);
932         }
933         annIter = endingAnnotations.iterator();
934         while (annIter.hasNext()) {
935           AnnotationImpl anAnnot = (AnnotationImpl) annIter.next();
936           anAnnot.end = firstNode;
937           addToEndOffsetIndex(anAnnot);
938         }
939         //repair the first node
940         //remove from offset index
941         nodesByOffset.remove(firstNode.getOffset());
942         //change the offset for the saved node
943         firstNode.setOffset(start);
944         //add back to the offset index
945         nodesByOffset.put(firstNode.getOffset(), firstNode);
946       }
947     }
948 
949     //now handle the insert and/or update the rest of the nodes' position
950     //get the user selected behaviour (defaults to append)
951     boolean shouldPrepend = Gate.getUserConfig().
952         getBoolean(GateConstants.DOCEDIT_INSERT_PREPEND).booleanValue();
953 
954     long s = start.longValue(), e = end.longValue();
955     long rlen = // length of the replacement value
956         ( (replacement == null) ? 0 : replacement.size().longValue());
957 
958     // update the offsets and the index by offset for the rest of the nodes
959     List nodesAfterReplacement = new ArrayList(
960         nodesByOffset.tailMap(start).values());
961 
962     //remove from the index by offset
963     Iterator nodesAfterReplacementIter = nodesAfterReplacement.iterator();
964     while (nodesAfterReplacementIter.hasNext()) {
965       NodeImpl n = (NodeImpl) nodesAfterReplacementIter.next();
966       nodesByOffset.remove(n.getOffset());
967     }
968     //change the offsets
969     nodesAfterReplacementIter = nodesAfterReplacement.iterator();
970     while (nodesAfterReplacementIter.hasNext()) {
971       NodeImpl n = (NodeImpl) nodesAfterReplacementIter.next();
972       long oldOffset = n.getOffset().longValue();
973       //by default we move all nodes back
974       long newOffset = oldOffset - (e - s) + rlen;
975       //for the first node we need behave differently
976       if (oldOffset == s){
977         //the first offset never moves back
978         if(newOffset < s) newOffset = s;
979         //if we're prepending we don't move forward
980         if(shouldPrepend) newOffset = s;
981       }
982       n.setOffset(new Long(newOffset));
983     }
984     //add back to the index by offset with the new offsets
985     nodesAfterReplacementIter = nodesAfterReplacement.iterator();
986     while (nodesAfterReplacementIter.hasNext()) {
987       NodeImpl n = (NodeImpl) nodesAfterReplacementIter.next();
988       nodesByOffset.put(n.getOffset(), n);
989     }
990 
991 //    //rebuild the indices with the new offsets
992 //    nodesByOffset = null;
993 //    annotsByStartNode = null;
994 //    annotsByEndNode = null;
995 //    indexByStartOffset();
996 //    indexByEndOffset();
997   } // edit(start,end,replacement)
998 
999   /** Get the name of this set. */
1000  public String getName() {
1001    return name;
1002  }
1003
1004  /** Get the document this set is attached to. */
1005  public Document getDocument() {
1006    return doc;
1007  }
1008
1009  /** Get a set of java.lang.String objects representing all the annotation
1010   * types present in this annotation set.
1011   */
1012  public Set getAllTypes() {
1013    indexByType();
1014    return annotsByType.keySet();
1015  }
1016
1017  /**
1018   *
1019   * @return a clone of this set.
1020   * @throws CloneNotSupportedException
1021   */
1022  public Object clone() throws CloneNotSupportedException {
1023    return super.clone();
1024  }
1025
1026  /**
1027   *
1028   * @param l
1029   */
1030  public synchronized void removeAnnotationSetListener(AnnotationSetListener l) {
1031    if (annotationSetListeners != null && annotationSetListeners.contains(l)) {
1032      Vector v = (Vector) annotationSetListeners.clone();
1033      v.removeElement(l);
1034      annotationSetListeners = v;
1035    }
1036  }
1037
1038  /**
1039   *
1040   * @param l
1041   */
1042  public synchronized void addAnnotationSetListener(AnnotationSetListener l) {
1043    Vector v = annotationSetListeners == null ? new Vector(2) :
1044        (Vector) annotationSetListeners.clone();
1045    if (!v.contains(l)) {
1046      v.addElement(l);
1047      annotationSetListeners = v;
1048    }
1049  }
1050
1051  /** String representation of the set */
1052  /*public String toString() {
1053    // annotsById
1054    SortedSet sortedAnnots = new TreeSet();
1055    sortedAnnots.addAll(annotsById.values());
1056    String aBI = sortedAnnots.toString();
1057    // annotsByType
1058    StringBuffer buf = new StringBuffer();
1059    Iterator iter = annotsByType.iterator();
1060    while(iter.hasNext()) {
1061      HashMap thisType = iter.next().entrySet();
1062      sortedAnnots.clear();
1063      sortedAnnots.addAll(thisType.);
1064      buf.append("[type: " +
1065    }
1066    return
1067      "AnnotationSetImpl: " +
1068      "name=" + name +
1069    //  "; doc.getURL()=" + doc +
1070      "; annotsById=" + aBI +
1071    //  "; annotsByType=" + aBT +
1072      "; "
1073      ;
1074     } // toString()
1075   */
1076//  public int hashCode() {
1077//    int hash = 0;
1078//    Iterator i = this.iterator();
1079//    while (i.hasNext()) {
1080//        Annotation annot = (Annotation)i.next();
1081//        if ( annot != null)
1082//            hash += annot.hashCode();
1083//    }
1084//    int nameHash = (name == null ? 0 : name.hashCode());
1085//    //int docHash = (doc == null ? 0 : doc.hashCode());
1086//
1087//    return hash ^ nameHash;// ^ docHash;
1088//  }
1089  /** The name of this set */
1090  String name = null;
1091  /** The document this set belongs to */
1092  DocumentImpl doc;
1093  /** Maps annotation ids (Integers) to Annotations */
1094  protected HashMap annotsById;
1095  /** Maps annotation types (Strings) to AnnotationSets */
1096  Map annotsByType = null;
1097  /** Maps offsets (Longs) to nodes */
1098  RBTreeMap nodesByOffset = null;
1099  /** Maps node ids (Integers) to AnnotationSets representing those
1100   * annotations that start from that node
1101   */
1102  Map annotsByStartNode;
1103  /** Maps node ids (Integers) to AnnotationSets representing those
1104   * annotations that end at that node
1105   */
1106  Map annotsByEndNode;
1107  protected transient Vector annotationSetListeners;
1108  private transient Vector gateListeners;
1109  /**
1110   *
1111   * @param e
1112   */
1113  protected void fireAnnotationAdded(AnnotationSetEvent e) {
1114    if (annotationSetListeners != null) {
1115      Vector listeners = annotationSetListeners;
1116      int count = listeners.size();
1117      for (int i = 0; i < count; i++) {
1118        ( (AnnotationSetListener) listeners.elementAt(i)).annotationAdded(e);
1119      }
1120    }
1121  }
1122
1123  /**
1124   *
1125   * @param e
1126   */
1127  protected void fireAnnotationRemoved(AnnotationSetEvent e) {
1128    if (annotationSetListeners != null) {
1129      Vector listeners = annotationSetListeners;
1130      int count = listeners.size();
1131      for (int i = 0; i < count; i++) {
1132        ( (AnnotationSetListener) listeners.elementAt(i)).annotationRemoved(e);
1133      }
1134    }
1135  }
1136
1137  /**
1138   *
1139   * @param l
1140   */
1141  public synchronized void removeGateListener(GateListener l) {
1142    if (gateListeners != null && gateListeners.contains(l)) {
1143      Vector v = (Vector) gateListeners.clone();
1144      v.removeElement(l);
1145      gateListeners = v;
1146    }
1147  }
1148
1149  /**
1150   *
1151   * @param l
1152   */
1153  public synchronized void addGateListener(GateListener l) {
1154    Vector v = gateListeners == null ? new Vector(2) :
1155        (Vector) gateListeners.clone();
1156    if (!v.contains(l)) {
1157      v.addElement(l);
1158      gateListeners = v;
1159    }
1160  }
1161
1162  /**
1163   *
1164   * @param e
1165   */
1166  protected void fireGateEvent(GateEvent e) {
1167    if (gateListeners != null) {
1168      Vector listeners = gateListeners;
1169      int count = listeners.size();
1170      for (int i = 0; i < count; i++) {
1171        ( (GateListener) listeners.elementAt(i)).processGateEvent(e);
1172      }
1173    }
1174  }
1175
1176  /** Freeze the serialization UID. */
1177  static final long serialVersionUID = 1479426765310434166L;
1178} // AnnotationSetImpl