/*
* BioJava development code
*
* This code may be freely distributed and modified under the
* terms of the GNU Lesser General Public Licence. This should
* be distributed with the code. If you do not have a copy,
* see:
*
* http://www.gnu.org/copyleft/lesser.html
*
* Copyright for this code is held jointly by the individual
* authors. These should be listed in @author doc comments.
*
* For more information on the BioJava project and its aims,
* or to join the biojava-l mailing list, visit the home page
* at:
*
* http://www.biojava.org/
*
*/
package org.biojavax;
import java.util.NoSuchElementException;
import java.util.Set;
import org.biojava.bio.Annotation;
import org.biojava.utils.ChangeVetoException;
/**
* An annotation collection which stores annotations as Note objects.
* @author Richard Holland
* @author Mark Schreiber
* @see Note
* @see RichAnnotatable
* @since 1.5
*/
public interface RichAnnotation extends Annotation {
public static final RichAnnotation EMPTY_ANNOTATION = new EmptyRichAnnotation();
/**
* Removes all notes from this annotation object.
* @throws ChangeVetoException if it couldn't do it.
*/
public void clear() throws ChangeVetoException;
/**
* Adds a note to this annotation. Must not be null.
* If the note is already in the annotation, nothing happens.
* @param note note to add
* @throws ChangeVetoException if it doesn't like this.
*/
public void addNote(Note note) throws ChangeVetoException;
/**
* Removes a note from this annotation. Must not be null.
* If the note wasn't in the annotation, nothing happens.
* @param note note to remove
* @throws ChangeVetoException if it doesn't like this.
*/
public void removeNote(Note note) throws ChangeVetoException;
/**
* Uses the term and rank to lookup a note in this annotation.
* @param note note to lookup, using term and rank.
* @return the matching note.
* @throws ChangeVetoException if it doesn't like this.
* @throws NoSuchElementException if it couldn't be found.
*/
public Note getNote(Note note) throws NoSuchElementException;
/**
* Returns true if the given note exists in this annotation.
* The lookup is done using the term and rank of the note.
* @param note note to lookup
* @return true if it is in this annotation, false if not.
*/
public boolean contains(Note note);
/**
* Returns an immutable set of all notes in this annotation.
* @return a set of notes.
* @see Note
*/
public Set getNoteSet();
/**
* Clears the notes from this annotation and replaces them with
* those from the given set. The set cannot be null.
* @param notes a set of Note objects to use from now on.
* @throws ChangeVetoException if it doesn't like any of them.
* @see Note
*/
public void setNoteSet(Set notes) throws ChangeVetoException;
/**
* Find all the Note
s with any rank that match the key.
* @param key either a String
identifier of a term from the
* default onltology or a ComparableTerm
* @return an array of matching Notes
in order of rank or an
* empty array if there are no matches. No implementation should ever
* return null!
* @see Note
* @see org.biojavax.ontology.ComparableTerm
*/
public Note[] getProperties(Object key);
}