org.biojava.bio.symbol
Class AlphabetManager

java.lang.Object
  |
  +--org.biojava.bio.symbol.AlphabetManager

public final class AlphabetManager
extends java.lang.Object

The first port of call for retrieving standard alphabets.

The alphabet interfaces themselves don't give you a lot of help in actualy getting an alphabet instance. This is where the AlphabetManager comes in handy. It helps out in serialization, generating derived alphabets and building CrossProductAlphabet instances. It also contains limited support for parsing complex alphabet names back into the alphabets.

Author:
Matthew Pocock, Thomas Down

Inner Class Summary
static class AlphabetManager.ListWrapper
          Simple wrapper to assist in list-comparisons.
 
Constructor Summary
AlphabetManager()
           
 
Method Summary
static Alphabet alphabetForName(java.lang.String name)
          Retrieve the alphabet for a specific name.
static java.util.Iterator alphabets()
          Get an iterator over all alphabets known.
static CrossProductAlphabet generateCrossProductAlphaFromName(java.lang.String name)
          Generates a new CrossProductAlphabet from the give name.
static Symbol getAmbiguitySymbol(char token, java.lang.String name, Annotation ann, java.util.Collection syms)
          Create a specific ambiguity symbol for a collection of symbols.
static Symbol getAmbiguitySymbol(java.util.Collection syms)
          Obtain the default ambiguity symbol to represent the symbols passed in as parameters e.g.
static CrossProductAlphabet getCrossProductAlphabet(java.util.List aList)
          Retrieve a CrossProductAlphabet instance over the alphabets in aList.
static CrossProductAlphabet getCrossProductAlphabet(java.util.List aList, CrossProductAlphabet parent)
          Retrieve a CrossProductAlphabet instance over the alphabets in aList.
static CrossProductSymbol getCrossProductSymbol(char token, java.util.List symList)
          Generates a new CrossProductSymbol instance.
static CrossProductSymbol getCrossProductSymbol(char token, java.util.List symList, CrossProductAlphabet parent)
          Generates a new CrossProductSymbol instance.
static CrossProductSymbol getGapSymbol()
          Get the special `gap' Symbol.
static AlphabetManager instance()
          Deprecated. all AlphabetManager methods have become static
static void registerAlphabet(java.lang.String name, Alphabet alphabet)
          Register an alphabet by name.
static Symbol symbolForName(java.lang.String name)
          Retrieve the symbol represented a String object
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

AlphabetManager

public AlphabetManager()
Method Detail

instance

public static AlphabetManager instance()
Deprecated. all AlphabetManager methods have become static

Retrieve the singleton instance.
Returns:
the AlphabetManager instance

alphabetForName

public static Alphabet alphabetForName(java.lang.String name)
                                throws java.util.NoSuchElementException
Retrieve the alphabet for a specific name.
Parameters:
name - the name of the alphabet
Returns:
the alphabet object
Throws:
java.util.NoSuchElementException - if there is no alphabet by that name

symbolForName

public static Symbol symbolForName(java.lang.String name)
                            throws java.util.NoSuchElementException
Retrieve the symbol represented a String object
Parameters:
name - of the string whose symbol you want to get
Throws:
java.util.NoSuchElementException - if the string name is invalid.

registerAlphabet

public static void registerAlphabet(java.lang.String name,
                                    Alphabet alphabet)
Register an alphabet by name.
Parameters:
name - the name by which it can be retrieved
alphabet - the Alphabet to store

alphabets

public static java.util.Iterator alphabets()
Get an iterator over all alphabets known.
Returns:
an Iterator over Alphabet objects

getGapSymbol

public static CrossProductSymbol getGapSymbol()
Get the special `gap' Symbol.

Returns:
the system-wide symbol that represents a gap

getCrossProductSymbol

public static CrossProductSymbol getCrossProductSymbol(char token,
                                                       java.util.List symList)
Generates a new CrossProductSymbol instance.

This factory method hides some complexity about exactly what to make. If symList contains only gaps, then the gap symbol is returned. If it contains only AtomicSymbol instances, then a CrossProductSymbol implementing AtomicSymbol will be returned. Otherwise, a plain-old CrossProductSymbol will be returned.

This method makes no attempt to force singleton-ness upon the returned symbol. This method will normaly be invoked by methods within alphabet implementations, not by client code.

Parameters:
symList - a list of Symbol objects
Returns:
a CrossProductSymbol that encapsulates that list

getCrossProductSymbol

public static CrossProductSymbol getCrossProductSymbol(char token,
                                                       java.util.List symList,
                                                       CrossProductAlphabet parent)
Generates a new CrossProductSymbol instance.

This factory method hides some complexity about exactly what to make. If symList contains only gaps, then the gap symbol is returned. If it contains only AtomicSymbol instances, then a CrossProductSymbol implementing AtomicSymbol will be returned. Otherwise, a plain-old CrossProductSymbol will be returned.

This method makes no attempt to force singleton-ness upon the returned symbol. This method will normaly be invoked by methods within alphabet implementations, not by client code.

Parameters:
symList - a list of Symbol objects
parent - a parental CrossProductAlphabet instance
Returns:
a CrossProductSymbol that encapsulates that list

generateCrossProductAlphaFromName

public static CrossProductAlphabet generateCrossProductAlphaFromName(java.lang.String name)
Generates a new CrossProductAlphabet from the give name.
Parameters:
name - the name to parse
Returns:
the associated Alphabet

getCrossProductAlphabet

public static CrossProductAlphabet getCrossProductAlphabet(java.util.List aList)
Retrieve a CrossProductAlphabet instance over the alphabets in aList.

If all of the alphabets in aList implements FiniteAlphabet then the method will return a FiniteAlphabet. Otherwise, it returns a non-finite alphabet.

If you call this method twice with a list containing the same alphabets, it will return the same alphabet. This promotes the re-use of alphabets and helps to maintain the 'flyweight' principal for finite alphabet symbols.

The resulting alphabet cpa will be retrievable via AlphabetManager.alphabetForName(cpa.getName())

Parameters:
aList - a list of Alphabet objects
Returns:
a CrossProductAlphabet that is over the alphabets in aList

getCrossProductAlphabet

public static CrossProductAlphabet getCrossProductAlphabet(java.util.List aList,
                                                           CrossProductAlphabet parent)
Retrieve a CrossProductAlphabet instance over the alphabets in aList.

If all of the alphabets in aList implements FiniteAlphabet then the method will return a FiniteAlphabet. Otherwise, it returns a non-finite alphabet.

If you call this method twice with a list containing the same alphabets, it will return the same alphabet. This promotes the re-use of alphabets and helps to maintain the 'flyweight' principal for finite alphabet symbols.

The resulting alphabet cpa will be retrievable via AlphabetManager.alphabetForName(cpa.getName())

Parameters:
aList - a list of Alphabet objects
parent - a parent alphabet
Returns:
a CrossProductAlphabet that is over the alphabets in aList

getAmbiguitySymbol

public static Symbol getAmbiguitySymbol(java.util.Collection syms)
                                 throws IllegalSymbolException
Obtain the default ambiguity symbol to represent the symbols passed in as parameters e.g. using the IUPAC ambiguity code, the symbol W will be returned for the collection [AT].
Parameters:
syms - the collection of symbols
Throws:
IllegalSymbolException - if the symbols are not recognized.

getAmbiguitySymbol

public static Symbol getAmbiguitySymbol(char token,
                                        java.lang.String name,
                                        Annotation ann,
                                        java.util.Collection syms)
                                 throws IllegalSymbolException
Create a specific ambiguity symbol for a collection of symbols.
Parameters:
token - the ambiguity character's designated token
name - a name for this ambiguity symbol.
ann - Annotation to associate with the ambiguity symbol
syms - the collection of symbols which will be represented by this ambiguity symbol
Throws:
IllegalSymbolException - if the symbols are not recognized.