001package org.biojava.bio.annodb;
002
003import java.util.Iterator;
004
005import org.biojava.bio.AnnotationType;
006
007/**
008 * <p>A database of Annotation instances.</p>
009 *
010 * <p>It is often a pain to provide explicit API for a particular file format,
011 * but it is still necisary to present it as some collection of structured
012 * objects. Annotation, together with AnnotationType are capable of representing
013 * structured data and the tag-value parser API is uniquely suited to creating
014 * these from structured text files. AnnotationDB is provided as a way to wrap
015 * up a whole collection of Annotation instances so that they can be queried and
016 * handled as a unit.</p>
017 *
018 * @author Matthew Pocock
019 * @since 1.3
020 */
021public interface AnnotationDB {
022  /**
023   * An AnnotationDB that is always empty.
024   */
025  public static AnnotationDB EMPTY = new EmptyAnnotationDB();
026  
027  /**
028   * <p>The name of this AnnotationDB.</p>
029   *
030   * @return the name of this AnnotationDB
031   */
032  public String getName();
033  
034  /**
035   * <p>
036   * Get an AnnotationType that accepts all Annotation instances in this DB.
037   * </p>
038   *
039   * <p>
040   * The schema should accept all Annotations in the DB. However, it may hit
041   * other Annotations. So, AnnotationType.ALL is always a valid schema.
042   * Obviously, the more retrictive it is, the more usefull it becomes for
043   * introspection.
044   * </p>
045   *
046   * @return  the schema AnnotationType
047   */
048  public AnnotationType getSchema();
049
050  /**
051   * Loop over each Annotation in this db.
052   *
053   * @return an Iterator over each item in the DB
054   */
055  public Iterator iterator();
056  
057  /**
058   * The number of Annotation instances in the DB.
059   *
060   * @return the size of this DB
061   */
062  public int size();
063  
064  /**
065   * Find all Annotation instances in this DB that are of a particular type.
066   *
067   * @param at  the AnnotationType to match
068   * @return an AnnotationDB with all matching Annotation instances
069   */
070  public AnnotationDB filter(AnnotationType at);
071  
072  /**
073   * Find all Annotation instances in this DB and any Annotations that are child
074   * properties of these that match an AnnotationType.
075   *
076   * @param at  the AnnotationType to search with
077   * @return an AnnotationDB with all matching Annotation instances,
078   *         irregardless of how deep in the hieracy they are
079   */
080  public AnnotationDB search(AnnotationType at);
081}
082