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.symbol;
023
024import org.biojava.utils.ChangeType;
025import org.biojava.utils.Changeable;
026
027/**
028 * <p>
029 * Map between Symbols and index numbers.
030 * </p>
031 *
032 * <p>
033 * The Symbols will all come from a single finite alphabet. The indices will
034 * range from 0 to getAlphabet().size()-1 inclusive with each symbol having a
035 * unique index. The resulting table can be used to look up array indices by
036 * symbol, which in many cases will be more efficient than performing a Map
037 * operation on, for example, a HashMap.
038 * </p>
039 *
040 * <p>
041 * An index should do whatever is necessary to stay synchronized with its
042 * alphabet. It may chose to modify the index table with the alphabet, or to
043 * veto all changes to the alphabet that would invalidate the indexing
044 * scheme.
045 * </p>
046 *
047 * @author Thomas Down
048 * @author Matthew pocock
049 * @since 1.1
050 */
051
052public interface AlphabetIndex extends Changeable {
053  /**
054   * <p>
055   * Indicates that the index is changing, probably due to the underlying
056   * alphabet changing.
057   * </p>
058   *
059   * <p>
060   * The previous & changed fields should be arrays of symbols in the order they
061   * are indexed in the unmodified and modified indices respectively.
062   * </p>
063   */
064  public static ChangeType INDEX = new ChangeType(
065    "The alphabet being indexed has changed.",
066    "org.biojava.bio.symbol.AlphabetIndex",
067    "INDEX"
068  );
069
070  /**
071   * Retrieve the alphabet that this indexes.
072   *
073   * @return the FiniteAlphabet that is indexed by this object
074   */
075  FiniteAlphabet getAlphabet();
076
077  /**
078   * Return the unique index for a symbol.
079   *
080   * @param s  the Symbol to index
081   * @return   the unique index for the symbol
082   * @throws   IllegalSymbolException if s is not a member of the indexed
083   *           alphabet, or if the indexer only indexes the AtomicSymbols
084   *           within an alphabet and s was not attomic.
085   */
086  int indexForSymbol(Symbol s) throws IllegalSymbolException;
087  
088  /**
089   * Retrieve the symbol for an index.
090   *
091   * @param i  the index of the symbol
092   * @return   the symbol at that index
093   * @throws   IndexOutOfBoundsException if i is negative or >=
094   *           getAlphabet().size()
095   */
096  Symbol symbolForIndex(int i) throws IndexOutOfBoundsException;
097}