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
022
023package org.biojava.bio.symbol;
024
025import java.util.Iterator;
026
027import org.biojava.utils.ChangeVetoException;
028
029/**
030 * An alphabet over a finite set of Symbols.
031 * <p>
032 * This interface makes the distinction between an alphabet over a finite (and
033 * possibly small) number of symbols and an Alphabet over an infinite
034 * (or extremely large) set of symbols. Within a FiniteAlphabet, the == operator
035 * should be sufficient to decide upon equality for all AtomicSymbol instances.
036 * <p>
037 * The alphabet functions as the repository of objects in the fly-weight design
038 * pattern. Only symbols within an alphabet should appear in object that claim
039 * to use the alphabet - otherwise something is in error.
040 *
041 * @author Matthew Pocock
042 */
043public interface FiniteAlphabet extends Alphabet {
044  /**
045   * The number of symbols in the alphabet.
046   *
047   * @return the size of the alphabet
048   */
049  int size();
050
051  /**
052   * Retrieve an Iterator over the AtomicSymbols in this FiniteAlphabet.
053   * <p>
054   * Each AtomicSymbol as for which this.contains(as) is true will be returned
055   * exactly once by this iterator in no specified order.
056   *
057   * @return an Iterator over the contained AtomicSymbol objects
058   */
059  Iterator<Symbol> iterator();
060
061
062  /**
063   * Adds a symbol to this alphabet.
064   * <p>
065   * If the symbol matches more than one AtomicSymbol, then each symbol matching
066   * it will be added.
067   *
068   * @param s the Symbol to add
069   * @throws IllegalSymbolException if the symbol is null, or if for any reason
070   *         it can't be added
071   * @throws ChangeVetoException  if either the alphabet doesn't allow symbols
072   *         to be added, or the change was vetoed
073   */
074  public void addSymbol(Symbol s)
075  throws IllegalSymbolException, ChangeVetoException;
076
077
078  /**
079   * Remove a symbol from this alphabet.
080   * <p>
081   * If the symbol matches multiple AtomicSymbols, then each matching symbol it
082   * will be removed.
083   *
084   * @param s the Symbol to removeintGot
085   * @throws IllegalSymbolException if the symbol is null, or if for any reason
086   *         it can't be removed
087   * @throws ChangeVetoException  if either the alphabet doesn't allow symbols
088   *         to be added, or the change was vetoed
089   */
090  public void removeSymbol(Symbol s)
091  throws IllegalSymbolException, ChangeVetoException;
092}