laser.alphabet
Class IndexedAlphabetFactory

java.lang.Object
  extended by laser.alphabet.IndexedAlphabetFactory
All Implemented Interfaces:
AlphabetFactoryInterface<IndexedLabel>

public class IndexedAlphabetFactory
extends java.lang.Object
implements AlphabetFactoryInterface<IndexedLabel>

This Alphabet factory, as in the factory design pattern, (Design Patterns, Gamma, Helm, Johnson, and Vlissides, p87, 1995) is used to create IndexedLabels and Alphabets of IndexedLabels.

This class uses the singleton design pattern, (Design Patterns, Gamma, Helm, Johnson, and Vlissides, p127, 1995) and thus there is only one instance of this class, and that single instance is referenced through a static point of access.

Note that this class is not synchronized, and attempts to use it with non-sequential code may result in unexpected behavior.

Author:
Nathan A. Jokel (laser-software@cs.umass.edu)
See Also:
IndexedLabel, IndexedAlphabet

Nested Class Summary
 class IndexedAlphabetFactory.TestProbe
          Provides, for testing purposes only, methods necessary for testing the IndexedAlphabetFactory class that should not under any circumstances be invoked during normal operation.
 
Constructor Summary
protected IndexedAlphabetFactory()
          Create an instance of IndexedAlphabetFactory.
 
Method Summary
 AlphabetInterface<IndexedLabel> createAlphabetInterface(java.lang.Object... args)
          Creates a new Alphabet of IndexedLabels with the specified value for N (the maximum index of IndexedLabels in this Alphabet.
 IndexedLabel createLabelInterface(java.lang.Integer index)
          Gets an IndexedLabel specified by index.
 IndexedLabel createLabelInterface(java.lang.String inputString)
          Gets an IndexedLabel specified by the inputString.
 java.lang.Object[] getCreateAlphabetArgs(AlphabetInterface<IndexedLabel> alphabet)
          Gets any required arguments for the create alphabet method from the given alphabet.
static IndexedAlphabetFactory getInstance()
          Return a reference to the single instance of this class.
 int getLargestIndex()
          Returns the index of the largest existing IndexedLabel, or -1 if there are none in existence.
 IndexedAlphabetFactory.TestProbe getTestProbe()
          Returns a TestProbe that provides for testing purposes only, methods necessary for testing the IndexedAlphabetFactory class that should not under any circumstances be invoked during normal operation.
 boolean isValidLabel(java.lang.String s)
          Returns true if the specified String specifies a valid IndexedLabel, false otherwise.
 AlphabetInterface<IndexedLabel> unmodifiableAlphabet(AlphabetInterface<IndexedLabel> alphabet)
          Returns an unmodifiable view of the specified IndexedAlphabet.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

IndexedAlphabetFactory

protected IndexedAlphabetFactory()
Create an instance of IndexedAlphabetFactory.

Method Detail

getInstance

public static IndexedAlphabetFactory getInstance()
Return a reference to the single instance of this class.

Returns:
The reference.

createLabelInterface

public IndexedLabel createLabelInterface(java.lang.String inputString)
                                  throws AlphabetInterfaceException
Gets an IndexedLabel specified by the inputString. Like all Labels, IndexedLabels participate in flyweighting, (Design Patterns, Gamma, Helm, Johnson, and Vlissides, p195, 1995) thus IndexedAlphabetFactory maintains a repository of IndexedLabels. If the IndexedLabel specified by the inputString already exists, a reference to it is returned. Otherwise, a new IndexedLabel is constructed from the inputString, added to the repository, and returned.

The input String must represent an integer value that is >= 0 and <= the index of the largest existing IndexedLabel + 1.

Specified by:
createLabelInterface in interface AlphabetFactoryInterface<IndexedLabel>
Parameters:
inputString - The String from which the IndexedLabel is constructed.
Returns:
The IndexedLabel.
Throws:
AlphabetInterfaceException - When the specified input String does not represent an integer value >= 0.
java.lang.NullPointerException - When the specified input String is null.
java.lang.UnsupportedOperationException - When the input String represents and integer that is > the index of the largest existing IndexedLabel + 1.

createLabelInterface

public IndexedLabel createLabelInterface(java.lang.Integer index)
                                  throws AlphabetInterfaceException
Gets an IndexedLabel specified by index.

Index must be >= 0, and <= the index of the largest existing IndexedLabel + 1.

Parameters:
index - The Integer from which the IndexedLabel is constructed.
Returns:
The IndexedLabel.
Throws:
AlphabetInterfaceException - When the input Integer is not >= 0.
java.lang.NullPointerException - When the input Integer is null.
java.lang.UnsupportedOperationException - When the input Integer is > the index of the largest existing IndexedLabel + 1.
See Also:
createLabelInterface(String), getLargestIndex()

createAlphabetInterface

public AlphabetInterface<IndexedLabel> createAlphabetInterface(java.lang.Object... args)
                                                        throws AlphabetInterfaceException
Creates a new Alphabet of IndexedLabels with the specified value for N (the maximum index of IndexedLabels in this Alphabet.

args must contain exactly 1 argument, an integer > 0.

Specified by:
createAlphabetInterface in interface AlphabetFactoryInterface<IndexedLabel>
Parameters:
args - A single integer argument specifying the value of N for the Alphabet of IndexedLabels being created.
Returns:
The Alphabet of IndexedLabels.
Throws:
AlphabetInterfaceException - When the Alphabet of IndexedLabels cannot be created from the specified input arguments.

getCreateAlphabetArgs

public java.lang.Object[] getCreateAlphabetArgs(AlphabetInterface<IndexedLabel> alphabet)
Gets any required arguments for the create alphabet method from the given alphabet.

PRECONDITIONS:

Specified by:
getCreateAlphabetArgs in interface AlphabetFactoryInterface<IndexedLabel>
Parameters:
alphabet - The alphabet to use as a prototype
Returns:
Any required arguments for the create alphabet method

isValidLabel

public boolean isValidLabel(java.lang.String s)
Returns true if the specified String specifies a valid IndexedLabel, false otherwise.

Specified by:
isValidLabel in interface AlphabetFactoryInterface<IndexedLabel>
Parameters:
s - The String.
Returns:
true if the specified String specifies a valid IndexedLabel, false otherwise.
Throws:
java.lang.NullPointerException - The specified String is null.
See Also:
createLabelInterface(String)

getLargestIndex

public int getLargestIndex()
Returns the index of the largest existing IndexedLabel, or -1 if there are none in existence.

Returns:
the index of the largest existing IndexedLabel, or -1 if there are none in existence.

unmodifiableAlphabet

public AlphabetInterface<IndexedLabel> unmodifiableAlphabet(AlphabetInterface<IndexedLabel> alphabet)
Returns an unmodifiable view of the specified IndexedAlphabet. Any attempt to modify the returned Alphabet will result in an UnsupportedOperationException being thrown.

Specified by:
unmodifiableAlphabet in interface AlphabetFactoryInterface<IndexedLabel>
Parameters:
alphabet - The IndexedAlphabet.
Returns:
An unmodifiable view of the specified IndexedAlphabet.
Throws:
java.lang.ClassCastException - alphabet is not an IndexedAlphabet.
java.lang.NullPointerException - the specified Alphabet is null.

getTestProbe

public IndexedAlphabetFactory.TestProbe getTestProbe()
Returns a TestProbe that provides for testing purposes only, methods necessary for testing the IndexedAlphabetFactory class that should not under any circumstances be invoked during normal operation.

Returns:
The TestProbe.