001/*
002 *                    BioJava development code
003 *
004 * This code may be freely distributed and modified under the
005 * terms of the GNU Lesser General Public Licence.  This should
006 * be distributed with the code.  If you do not have a copy,
007 * see:
008 *
009 *      http://www.gnu.org/copyleft/lesser.html
010 *
011 * Copyright for this code is held jointly by the individual
012 * authors.  These should be listed in @author doc comments.
013 *
014 * For more information on the BioJava project and its aims,
015 * or to join the biojava-l mailing list, visit the home page
016 * at:
017 *
018 *      http://www.biojava.org/
019 *
020 */
021
022package org.biojavax;
023import java.util.NoSuchElementException;
024import java.util.Set;
025
026import org.biojava.bio.Annotation;
027import org.biojava.utils.ChangeVetoException;
028
029/**
030 * An annotation collection which stores annotations as Note objects.
031 * @author Richard Holland
032 * @author Mark Schreiber
033 * @see Note
034 * @see RichAnnotatable
035 * @since 1.5
036 */
037public interface RichAnnotation extends Annotation {
038        
039    public static final RichAnnotation EMPTY_ANNOTATION = new EmptyRichAnnotation();
040    
041    /**
042     * Removes all notes from this annotation object.
043     * @throws ChangeVetoException if it couldn't do it.
044     */
045    public void clear() throws ChangeVetoException;
046    
047    /**
048     * Adds a note to this annotation. Must not be null.
049     * If the note is already in the annotation, nothing happens.
050     * @param note note to add
051     * @throws ChangeVetoException if it doesn't like this.
052     */
053    public void addNote(Note note) throws ChangeVetoException;
054    
055    /**
056     * Removes a note from this annotation. Must not be null.
057     * If the note wasn't in the annotation, nothing happens.
058     * @param note note to remove
059     * @throws ChangeVetoException if it doesn't like this.
060     */
061    public void removeNote(Note note) throws ChangeVetoException;
062    
063    /**
064     * Uses the term and rank to lookup a note in this annotation.
065     * @param note note to lookup, using term and rank.
066     * @return the matching note.
067     * @throws ChangeVetoException if it doesn't like this.
068     * @throws NoSuchElementException if it couldn't be found.
069     */
070    public Note getNote(Note note) throws NoSuchElementException;
071    
072    /**
073     * Returns true if the given note exists in this annotation.
074     * The lookup is done using the term and rank of the note.
075     * @param note note to lookup
076     * @return true if it is in this annotation, false if not.
077     */
078    public boolean contains(Note note);
079    
080    /**
081     * Returns an immutable set of all notes in this annotation.
082     * @return a set of notes.
083     * @see Note
084     */
085    public Set<Note> getNoteSet();
086    
087    /**
088     * Clears the notes from this annotation and replaces them with
089     * those from the given set. The set cannot be null.
090     * @param notes a set of Note objects to use from now on.
091     * @throws ChangeVetoException if it doesn't like any of them.
092     * @see Note
093     */
094    public void setNoteSet(Set<Note> notes) throws ChangeVetoException;
095    
096    /**
097     * Find all the <code>Note</code>s with any rank that match the key.
098     * @param key either a <code>String</code> identifier of a term from the
099     * default ontology or a <code>ComparableTerm</code>
100     * @return an array of matching <code>Notes</code> in order of rank or an
101     * empty array if there are no matches. No implementation should ever 
102     * return null!
103     * @see Note
104     * @see org.biojavax.ontology.ComparableTerm
105     */
106    public Note[] getProperties(Object key);
107    
108}