Annotation.java
001 /*
002  *  Annotation.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  *  Hamish Cunningham, 19/Jan/00
013  *
014  *  $Id: Annotation.java 17542 2014-03-05 10:36:35Z markagreenwood $
015  */
016 
017 package gate;
018 
019 import gate.event.AnnotationListener;
020 
021 import java.io.Serializable;
022 import java.util.Set;
023 
024 /** An Annotation is an arc in an AnnotationSet. It is immutable, to avoid
025   * the situation where each annotation has to point to its parent graph in
026   * order to tell it to update its indices when it changes.
027   <P> Changes from TIPSTER: no ID; single span only.
028   
029   * It inherits from SimpleAnnotation in order to allow users to add events
030   * and more methods for comparing annotations
031   *
032   * The event code is needed so a persistent annotation set can listen to
033   * its annotations and update correctly the database
034   */
035 public interface Annotation
036 extends SimpleAnnotation, Serializable {
037 
038   /** This verifies if <b>this</b> annotation is compatible with another one.
039     * Compatible means that they hit the same possition and the FeatureMap of
040     <b>this</b> is incuded into aAnnot FeatureMap.
041     @param anAnnot a gate Annotation.
042     @return <code>true</code> if aAnnot is compatible with <b>this</b> and
043     <code>false</code> otherwise.
044     */
045   public boolean isCompatible(Annotation anAnnot);
046 
047   /** This verifies if <b>this</b> annotation is compatible with another one,
048    *  given a set with certain keys.
049     * In this case, compatible means that they hit the same possition
050     * and those keys from <b>this</b>'s FeatureMap intersected with
051     * aFeatureNamesSet are incuded together with their values into the aAnnot's
052     * FeatureMap.
053     @param anAnnot a gate Annotation.
054     @param aFeatureNamesSet is a set containing certian key that will be
055     * intersected with <b>this</b>'s FeatureMap's keys.
056     @return <code>true</code> if aAnnot is compatible with <b>this</b> and
057     <code>false</code> otherwise.
058     */
059   public boolean isCompatible(Annotation anAnnot, Set<? extends Object> aFeatureNamesSet);
060 
061   /** This method verifies if two annotation and are partially compatible.
062     * Partially compatible means that they overlap and the FeatureMap of
063     <b>this</b> is incuded into FeatureMap of aAnnot.
064     @param anAnnot a gate Annotation.
065     @return <code>true</code> if <b>this</b> is partially compatible with
066     * aAnnot and <code>false</code> otherwise.
067     */
068   public boolean isPartiallyCompatible(Annotation anAnnot);
069 
070   /** This method verifies if two annotation and are partially compatible,
071     * given a set with certain keys.
072     * In this case, partially compatible means that they overlap
073     * and those keys from <b>this</b>'s FeatureMap intersected with
074     * aFeatureNamesSet are incuded together with their values into the aAnnot's
075     * FeatureMap.
076     @param anAnnot a gate Annotation.
077     @param aFeatureNamesSet is a set containing certian key that will be
078     * intersected with <b>this</b>'s FeatureMap's keys.
079     @return <code>true</code> if <b>this</b> is partially compatible with
080     * aAnnot and <code>false</code> otherwise.
081     */
082   public boolean isPartiallyCompatible(Annotation anAnnot,Set<? extends Object> aFeatureNamesSet);
083 
084   /**  Two Annotation are coestensive if their offsets are the same.
085     *  @param anAnnot A Gate annotation.
086     *  @return <code>true</code> if two annotation hit the same possition and
087     *  <code>false</code> otherwise
088     */
089   public boolean coextensive(Annotation anAnnot);
090 
091   /** 
092    * This method determines if <b>this</b> overlaps aAnnot, i.e. if either
093    * the beginning or the end (or both) of anAnnot is
094    * contained in the span of <b>this</b>.
095    
096    @param aAnnot a gate Annotation.
097    @return <code>true</code> if they overlap and <code>false</code> false if
098    * they don't or if aAnnot is null.
099    */
100   public boolean overlaps(Annotation aAnnot);
101   
102   /** This method tells if <b>this</b> annotation's text range is 
103    * fully contained within the text annotated by <code>aAnnot</code>'s
104    * annotation. 
105    @param aAnnot a gate Annotation.
106    @return <code>true</code> if this annotation is fully contained in the 
107    * other one.
108    */
109   public boolean withinSpanOf(Annotation aAnnot);
110 
111   /**
112    *
113    * Removes an annotation listener
114    */
115   public void removeAnnotationListener(AnnotationListener l);
116   /**
117    *
118    * Adds an annotation listener
119    */
120   public void addAnnotationListener(AnnotationListener l;
121 
122 // interface Annotation,