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.seq.db;
023
024import java.util.Set;
025
026import org.biojava.bio.BioException;
027import org.biojava.bio.seq.io.SequenceBuilderFactory;
028import org.biojava.bio.seq.io.SequenceFormat;
029import org.biojava.bio.seq.io.SymbolTokenization;
030
031/**
032 * This defines the objects that IndexedSequenceDB uses to store all of the
033 * database state, such as name, format, sequence builder and the actual file
034 * offsets.
035 *
036 * You should only ever have to instantiate an implementation of this. Don't
037 * call any of the inerface methods directly. They are intended for
038 * IndexedSequenceDB, not you.
039 *
040 * In general, these objects should be transactional. Calls to store should add
041 * the index to temporary storage. When commit is invoked, these indices should
042 * all be added to the permanent storage. When rollback is invoked, these
043 * indexes should be discarded. If commit fails for any reason, it should leave
044 * the permanent storage in the pre-commit status.
045
046 * @author Matthew Pocock
047 */
048public interface IndexStore {
049  /**
050   * Add the Index to the store.
051   * <p>
052   * This method should be transactional. If the store fails, the IndexStore
053   * should be left in its original state.
054   * <p>
055   * If the file of the Index is not known yet, it is the
056   * responsibility of the IndexStore to add it to the set returned by
057   * getFiles.
058   *
059   * @param indx the Index to add
060   * @throws IllegalIDException if the index has an invalid ID field
061   * @throws BioException if the store failed
062   */
063  void store(Index indx) throws IllegalIDException, BioException;
064  
065  /**
066   * Commit the stored indices to permanent storage.
067   *
068   * @throws BioException if for any reason the commit fails
069   */
070  void commit() throws BioException;
071  
072  /**
073   * Discard all uncommited changes.
074   */
075  void rollback();
076  
077  /**
078   * Fetch an Index based upon an ID.
079   *
080   * @param id  The ID of the sequence Index to retrieve
081   * @throws IllegalIDException if the ID couldn't be found
082   * @throws BioException if the fetch fails in the underlying storage mechanism
083   */
084  Index fetch(String id) throws IllegalIDException, BioException;
085  
086  /**
087   * Retrieve the name of this store. This will be reflected as the name of the
088   * IndexedSequenceDB.
089   *
090   * @return the String name of the index
091   */
092  String getName();
093  
094  /**
095   * Retrieve the set of all current IDs.
096   * <p>
097   * This set should either be immutable, or modifiable totally
098   * separately from the IndexStore.
099   *
100   * @return a Set of all legal IDs
101   */
102  Set getIDs();
103  
104  /**
105   * Retrieve the Set of files that are currently indexed.
106   */
107  Set getFiles();
108  
109  /**
110   * Retrieve the format of the index file.
111   * <p>
112   * This set should either be immutable, or modifiable totally
113   * separately from the IndexStore.
114   *
115   * @return a Set of all indexed files
116   */
117  SequenceFormat getFormat();
118  
119  /**
120   * Retrieve the SequenceBuilderFactory used to build Sequence instances.
121   *
122   * @return the associated SequenceBuilderFactory
123   */
124  SequenceBuilderFactory getSBFactory();
125  
126  /**
127   * Retrieve the symbol parser used to turn the sequence characters
128   * into Symobl objects.
129   *
130   * @return the associated SymbolParser
131   */
132  SymbolTokenization getSymbolParser();
133}