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.biojava.bio.program.indexdb;
023
024import java.util.List;
025import java.util.Map;
026
027import org.biojava.bio.Annotation;
028import org.biojava.bio.BioException;
029import org.biojava.utils.io.RAF;
030
031/**
032 * <code>IndexStore</code> is an interface for indexing flatfiles
033 * according to the OBDA specification. It represents a map of Record instances
034 * by a primary ID and any number of Records associated with an ID in some
035 * seccondary namespace.
036 *
037 * @author Matthew Pocock
038 * @author Keith James
039 */
040public interface IndexStore {
041
042    /**
043     * <code>get</code> returns a record specified by a primary
044     * identifier.
045     *
046     * @param id a <code>String</code> primary ID.
047     *
048     * @return a <code>Record</code>.
049     *
050     * @exception BioException if an error occurs or if there is no Record
051     *            associated with the id
052     */
053    public Record get(String id) throws BioException;
054
055    /**
056     * <code>get</code> returns a list of <code>Record</code>s by
057     * searching against the primary identifiers if the namespace
058     * argument is equal to the primary namespace or otherwise by
059     * searching the secondary namespaces. The list of Record instances retuned
060     * may be empty, but is never null.
061     *
062     * @param id a <code>String</code> primary ID.
063     * @param namespace a <code>String</code>.
064     *
065     * @return a <code>List</code> of <code>Record</code>s.
066     *
067     * @exception BioException if an error occurs.
068     */
069    public List get(String id, String namespace) throws BioException;
070
071    /**
072     * <code>getMetaData</code> returns a data structure which
073     * represents an OBDA "config.dat" flatfile indexing configuration
074     * file.
075     *
076     * @return an <code>Annotation</code>.
077     */
078    public Annotation getMetaData();
079
080    /**
081     * <code>writeRecord</code> creates and writes a new
082     * <code>Record</code>
083     *
084     * @param file a <code>RAF</code> file.
085     * @param offset a <code>long</code> byte offset.
086     * @param length an <code>int</code> byte record length.
087     * @param id a <code>String</code> primary ID.
088     * @param secIDs a <code>Map</code> of primary ID to a
089     * <code>List</code> of secondary IDs.
090     */
091    public void writeRecord(RAF file,
092                            long offset,
093                            int length,
094                            String id,
095                            Map secIDs);
096}