org.jscience.linguistics.braille
Class BrailleLanguageUnicode

java.lang.Object
  extended by org.jscience.linguistics.braille.BrailleLanguageUnicode
All Implemented Interfaces:
java.io.Serializable, BrailleLanguage, Named

public class BrailleLanguageUnicode
extends java.lang.Object
implements BrailleLanguage, java.io.Serializable, Named

An implementation of BrailleLanguage that works with Unicode strings and Unicode language tables.

Copyright 1999, 2004 Alasdair King. This program is free software under the terms of the GNU General Public License.

See Also:
Serialized Form

Field Summary
static java.lang.String DATAFILE_EXTENSION
          The filename extension for the unprocessed BrailleLanguage rules tables for this implementation of language.
 char ESCAPE_CHAR_1
          The first character forming part of the escape sequence for unicode characters to be depicted in ASCII.
 char ESCAPE_CHAR_2
          The second character forming part of the escape sequence for unicode characters to be depicted in ASCII.
static java.lang.String FILENAME_EXTENSION
          Filename extension for serialized BrailleLanguageUnicode objects that can be loaded into memory by calling the constructor with their path and name and used for translation.
 
Fields inherited from interface org.jscience.linguistics.braille.BrailleLanguage
FILE_EXTENSION_DELIMITER, LEFT_FOCUS_DELIMITER, RIGHT_FOCUS_DELIMITER, RULE_BUFFER, RULE_CONTENT_DELIMITER, RULE_OUTPUT_DELIMITER, SPACE_FLAG, TABLE_DELIMITER, WILDCARD_FLAG, WILDCARD_NONE, WILDCARD_ONE, WILDCARD_SEVERAL
 
Constructor Summary
BrailleLanguageUnicode()
          Constructs a BrailleLanguageUnicode object without data ready to be filled with information for the language being created in the correct order.
BrailleLanguageUnicode(java.lang.String filename)
          Loads a BrailleLanguageUnicode object with all the language rules table information required for translation from disk.
 
Method Summary
 void addCharacterInformation(java.lang.Character from, java.lang.Character to, java.lang.Integer flagValue)
          Adds the information for one Unicode character to the language.
 void addTranslationRule(java.lang.String toProcess)
          Adds a new translation rule to the language.
 void addWildcardInformation(int wildcardNumber, int wildcardFlags, java.lang.Character wildcardChar)
          Adds one wildcard's information to the language
 BrailleLanguageUnicode getBrailleLanguageUnicodeFromDisk(java.lang.String filename)
          Loads a BrailleLanguageUnicode object from disk
static BrailleLanguageUnicode getBrailleLanguageUnicodeFromWebsite(java.lang.String languageName)
          Downloads a language file from the web.
 java.lang.String getDescription()
          Returns the free text description of the language.
 java.lang.String getInputClassDescription(int inputClass)
          Returns the language description for an input class.
 java.lang.String getName()
          Returns the name of the language.
 int getNumberCharacters()
          Returns the number of Unicode characters supported by this language.
 int getNumberInputClasses()
          Returns the number of input classes available in the language.
 int getNumberStates()
          Returns the number of states available in this language.
 int getNumberWildcards()
          Returns the number of wildcards defined in the language
 int getPermittedStates()
          DOCUMENT ME!
 int getState()
          DOCUMENT ME!
 java.lang.String getStateDescription(int state)
          Returns the language description for a state.
 int getVersionNumber()
          Returns the version of the language
 void setDecisionTableEntry(int state, int inputClass, boolean value)
          Sets a state table entry for the language.
 void setDescription(java.lang.String description)
          Allows the free text description of the language to be set.
 void setInputClassDescription(int inputClass, java.lang.String description)
          Applies a description to one of the input classes of the language.
 void setName(java.lang.String name)
          Allows the name of the language to be set.
 void setNumberCharacters(int numberCharacters)
          Sets the number of Unicode characters supported by this new language.
 void setNumberInputClasses(int numberInputClasses)
          Sets the number of input classes for the language.
 void setNumberStates(int numberStates)
          Sets the number of states possible for the finite state machine of the language.
 void setNumberWildcards(int numberWildcards)
          Defines the number of wildcards for this language.
 boolean setState(int newState)
          Sets the state of the finite state machine performing the translation, and therefore controls the type of translation performed, depending on the translation language selected.
 void setStateDescription(int state, java.lang.String description)
          Applies a description to one of the finite state machine states.
 void setVersionNumber(int versionNumber)
          Sets the version number of a BrailleLanguageUnicode object.
 int[] translate(int[] toConvert)
          DOCUMENT ME!
 java.lang.String translate(java.lang.String toConvert)
          DOCUMENT ME!
 void writeBrailleLanguageUnicodeToDisk(java.lang.String filename)
          Writes the current language to disk as a serialized object.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

FILENAME_EXTENSION

public static final java.lang.String FILENAME_EXTENSION
Filename extension for serialized BrailleLanguageUnicode objects that can be loaded into memory by calling the constructor with their path and name and used for translation.

See Also:
Constant Field Values

DATAFILE_EXTENSION

public static final java.lang.String DATAFILE_EXTENSION
The filename extension for the unprocessed BrailleLanguage rules tables for this implementation of language.

See Also:
Constant Field Values

ESCAPE_CHAR_1

public final char ESCAPE_CHAR_1
The first character forming part of the escape sequence for unicode characters to be depicted in ASCII.

See Also:
Constant Field Values

ESCAPE_CHAR_2

public final char ESCAPE_CHAR_2
The second character forming part of the escape sequence for unicode characters to be depicted in ASCII.

See Also:
Constant Field Values
Constructor Detail

BrailleLanguageUnicode

public BrailleLanguageUnicode()
Constructs a BrailleLanguageUnicode object without data ready to be filled with information for the language being created in the correct order.


BrailleLanguageUnicode

public BrailleLanguageUnicode(java.lang.String filename)
                       throws java.io.IOException,
                              java.lang.ClassNotFoundException,
                              java.io.FileNotFoundException
Loads a BrailleLanguageUnicode object with all the language rules table information required for translation from disk. It should have previously been constructed with the parameter-less constructor, then populated with language data by the various set methods, then serialized to disk with writeBrailleLanguageUnicodeToDisk, before it can be loaded in by this constructor. If a supplied BrailleLanguageUnicode object is provided, this can be interrogated for its translation abilities with the get methods.

Parameters:
filename - Full path and name of serialized Java object as file to load, excluding the filename extension. For example, language file "english.dat" in "\languages" should be instantiated with BrailleLanguageUnicode myBrailleLanguage = new BrailleLanguageUnicode("\languages\english");
Throws:
java.io.IOException
java.lang.ClassNotFoundException
java.io.FileNotFoundException
Method Detail

getBrailleLanguageUnicodeFromDisk

public BrailleLanguageUnicode getBrailleLanguageUnicodeFromDisk(java.lang.String filename)
                                                         throws java.io.IOException,
                                                                java.io.FileNotFoundException,
                                                                java.io.StreamCorruptedException,
                                                                java.lang.ClassNotFoundException
Loads a BrailleLanguageUnicode object from disk

Parameters:
filename - Full path and name of serialized Java object as file to load.
Throws:
java.io.IOException
java.io.FileNotFoundException
java.io.StreamCorruptedException
java.lang.ClassNotFoundException

setState

public boolean setState(int newState)
Description copied from interface: BrailleLanguage
Sets the state of the finite state machine performing the translation, and therefore controls the type of translation performed, depending on the translation language selected.

Specified by:
setState in interface BrailleLanguage
Parameters:
newState - An int containing the new state for the machine to take.
Returns:
A boolean indicating whether setting the state was successful. It will fail if the new state requested is outside the limits of states for the language being used.

getPermittedStates

public int getPermittedStates()
DOCUMENT ME!

Specified by:
getPermittedStates in interface BrailleLanguage
Returns:
DOCUMENT ME!

getState

public int getState()
DOCUMENT ME!

Specified by:
getState in interface BrailleLanguage
Returns:
DOCUMENT ME!

translate

public java.lang.String translate(java.lang.String toConvert)
DOCUMENT ME!

Specified by:
translate in interface BrailleLanguage
Parameters:
toConvert - DOCUMENT ME!
Returns:
DOCUMENT ME!

translate

public int[] translate(int[] toConvert)
DOCUMENT ME!

Specified by:
translate in interface BrailleLanguage
Parameters:
toConvert - DOCUMENT ME!
Returns:
DOCUMENT ME!

setNumberWildcards

public void setNumberWildcards(int numberWildcards)
                        throws BrailleLanguageDefinitionException
Defines the number of wildcards for this language. Can only be called once for any one new language.

Parameters:
numberWildcards - int number of wildcards.
Throws:
BrailleLanguageDefinitionException

getNumberWildcards

public int getNumberWildcards()
Returns the number of wildcards defined in the language

Returns:
numberWildcards Number of wildcards in language.

getVersionNumber

public int getVersionNumber()
Returns the version of the language

Returns:
version Version of the language.

addCharacterInformation

public void addCharacterInformation(java.lang.Character from,
                                    java.lang.Character to,
                                    java.lang.Integer flagValue)
                             throws BrailleLanguageDefinitionException
Adds the information for one Unicode character to the language.

Parameters:
from - Character object wrapping the character that will be mapped from in normalising the input text.
to - Character object wrapping the character that is produced when mapping the input text.
flagValue - The distinctive flags for the character in to.
Throws:
BrailleLanguageDefinitionException

addWildcardInformation

public void addWildcardInformation(int wildcardNumber,
                                   int wildcardFlags,
                                   java.lang.Character wildcardChar)
                            throws BrailleLanguageDefinitionException
Adds one wildcard's information to the language

Parameters:
wildcardNumber - The value indicating whether the wildcard matches zero or more characters (WILDCARD_NONE), one character (WILDCARD_ONE), or one or more characters (WILDCARD_SEVERAL).
wildcardFlags - The distinctive flags that the wildcard matches.
wildcardChar - Character object wrapping the character used for the wildcard.
Throws:
BrailleLanguageDefinitionException

addTranslationRule

public void addTranslationRule(java.lang.String toProcess)
                        throws BrailleLanguageDefinitionException
Adds a new translation rule to the language. The String argument must be in the format "inputclass [TAB] leftContext LEFT_FOCUS_DELIMITER focus RIGHT_FOCUS_DELIMITER rightContext RULE_OUTPUT_DELIMITER output RULE_CONTENT_DELIMITER [TAB] newState". The CONSTANTS are inherited from BrailleLanguage.

Parameters:
toProcess - String containing whole translation rule content, input class to new state.
Throws:
BrailleLanguageDefinitionException

setName

public void setName(java.lang.String name)
Allows the name of the language to be set.

Parameters:
name - String that will become the name of the language.

getName

public java.lang.String getName()
Returns the name of the language.

Specified by:
getName in interface Named
Returns:
name The name of the language.

setDescription

public void setDescription(java.lang.String description)
Allows the free text description of the language to be set.

Parameters:
description - String containing the description for the language.

getDescription

public java.lang.String getDescription()
Returns the free text description of the language.

Returns:
description String containing the description for the language.

setNumberCharacters

public void setNumberCharacters(int numberCharacters)
                         throws BrailleLanguageDefinitionException
Sets the number of Unicode characters supported by this new language. Can only be set once.

Parameters:
numberCharacters - int number of characters for language.
Throws:
BrailleLanguageDefinitionException

getNumberCharacters

public int getNumberCharacters()
Returns the number of Unicode characters supported by this language.

Returns:
numberCharacters The number of Unicode characters supported.

setNumberStates

public void setNumberStates(int numberStates)
                     throws BrailleLanguageDefinitionException
Sets the number of states possible for the finite state machine of the language. Can only be set once.

Parameters:
numberStates - The number of possible states.
Throws:
BrailleLanguageDefinitionException

setStateDescription

public void setStateDescription(int state,
                                java.lang.String description)
                         throws BrailleLanguageDefinitionException
Applies a description to one of the finite state machine states.

Parameters:
state - The state to have a description applied to it.
description - A String containing the description to be applied.
Throws:
BrailleLanguageDefinitionException

getStateDescription

public java.lang.String getStateDescription(int state)
                                     throws BrailleLanguageDefinitionException,
                                            java.lang.ArrayIndexOutOfBoundsException
Returns the language description for a state.

Parameters:
state - The state for which the description is required.
Returns:
stateDescription[state] The description for the state.
Throws:
BrailleLanguageDefinitionException
java.lang.ArrayIndexOutOfBoundsException

getInputClassDescription

public java.lang.String getInputClassDescription(int inputClass)
                                          throws BrailleLanguageDefinitionException,
                                                 java.lang.ArrayIndexOutOfBoundsException
Returns the language description for an input class.

Parameters:
inputClass - The input class for which the description is required.
Returns:
inputClassDescriptions[inputClass] The description for the input class.
Throws:
BrailleLanguageDefinitionException
java.lang.ArrayIndexOutOfBoundsException

setInputClassDescription

public void setInputClassDescription(int inputClass,
                                     java.lang.String description)
                              throws BrailleLanguageDefinitionException
Applies a description to one of the input classes of the language.

Parameters:
inputClass - The input class for which a description is being provided.
description - The description as a String for the input class.
Throws:
BrailleLanguageDefinitionException

setNumberInputClasses

public void setNumberInputClasses(int numberInputClasses)
                           throws BrailleLanguageDefinitionException
Sets the number of input classes for the language. Can only be set once.

Parameters:
numberInputClasses - Number of input classes for the language.
Throws:
BrailleLanguageDefinitionException

setDecisionTableEntry

public void setDecisionTableEntry(int state,
                                  int inputClass,
                                  boolean value)
                           throws BrailleLanguageDefinitionException,
                                  java.lang.ArrayIndexOutOfBoundsException
Sets a state table entry for the language. Both the number of states and and the number of input classes must be defined already. The state table is a (rules * input classes) table of true/false values.

Parameters:
state - State of table.
inputClass - Input class of table.
value - Results to be entered.
Throws:
BrailleLanguageDefinitionException
java.lang.ArrayIndexOutOfBoundsException

getNumberInputClasses

public int getNumberInputClasses()
Returns the number of input classes available in the language. A translation rule may belong to any one of the input classes.

Returns:
numberInputClasses The number of input classes in the language.

getNumberStates

public int getNumberStates()
Returns the number of states available in this language. Any state may be selected by setState. States affect the translation performed.

Returns:
The number of states in the language.

setVersionNumber

public void setVersionNumber(int versionNumber)
Sets the version number of a BrailleLanguageUnicode object. Version is not used anywhere yet, so this can be used to differentiate languages but should not be relied upon to do this.


getBrailleLanguageUnicodeFromWebsite

public static BrailleLanguageUnicode getBrailleLanguageUnicodeFromWebsite(java.lang.String languageName)
                                                                   throws java.lang.Exception
Downloads a language file from the web. This can be used as an alternative to using the constructor and passing it the name and path to a local serialized instance of BrailleLanguageUnicode. Instead, the language file name can be passed to this method, and the language file will be obtained by HTTP. As with other BrailleLanguage implementations, the filename extension should not be added. To get language "english", simply call getBrailleLanguageUnicodeFromDisk("english");

Parameters:
languageName - String name of language file to get.
Returns:
The BrailleLanguageUnicode received.
Throws:
java.lang.Exception

writeBrailleLanguageUnicodeToDisk

public void writeBrailleLanguageUnicodeToDisk(java.lang.String filename)
                                       throws java.io.IOException
Writes the current language to disk as a serialized object. The filename extension should not be provided - the correct extension will be appended for this implementation of BrailleLanguage

Parameters:
filename - String showing full path and filename for object as file.
Throws:
java.io.IOException