marytts.modules

Class ExternalModule

java.lang.Object

marytts.modules.ExternalModule

All Implemented Interfaces:

MaryModule

public class ExternalModule
extends Object
implements MaryModule

A base class for all external Mary modules. Provides non-specific input/output functionality for communication with an external module.

Any external module extending this class will need to implement a constructor calling this class's constructor. If data input/output requires additional processing, the subclass may override externalIO(), open() and/or close().

Example for a subclass:

Default case (external module reads from stdin and writes to stdout without requiring any particular triggers):

 public class Intonation extends ExternalModule {
        public Intonation() {
                super("Intonation", System.getProperty("mary.base") + File.separator + "src" + File.separator + "modules"
                                + File.separator + "intonation" + File.separator + "intonation_tts", MaryDataType.INTONISED);
        }
 }
 

Non-standard case (external module needs special trigger, data needs to be post-processed):

 public class Tokeniser extends ExternalModule {
        public Tokeniser()
     {
         super(...);
     }
 
        protected MaryData externalIO(MaryData d) throws TransformerConfigurationException, TransformerException,
                        FileNotFoundException, IOException, ParserConfigurationException, SAXException, Exception {
                MaryData result;
                // Write to and read from external module similarly to super class,
                // but write e.g. an empty line after writing the data,
                // to mark end of input.
 
                // Modify the result tree
                myModifications(result);
 
                return result;
        }
 }
 

Author:

Marc Schröder

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	ExternalModule.ProcessingThread
class	ExternalModule.RestarterThread

Field Summary

Fields

Modifier and Type	Field and Description
protected StreamLogger	errorLogger
protected InputStream	from
protected String	ignorePattern A regular expression describing what to be ignored in the external module's standard error output.
protected org.apache.log4j.Logger	logger The logger instance to be used by this module.
protected Process	process
protected ExternalModule.ProcessingThread	processingThread
protected ExternalModule.RestarterThread	restarterThread
protected boolean	retrying Remember if a retry attempt is undertaken in process().
protected int	state
protected long	timeLimit The duration given to the module before timeout occurs (in milliseconds).
protected OutputStream	to

Fields inherited from interface marytts.modules.MaryModule

MODULE_OFFLINE, MODULE_RUNNING

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	ExternalModule(String name, String cmd, MaryDataType inputType, MaryDataType outputType, Locale locale)

Method Summary

Methods

Modifier and Type	Method and Description
protected void	addRequest(Object r)
protected void	close() Closes the external process's input and output streams, and destroys the process.
protected String	cmd() The command line to execute as an external process.
protected void	doNotifyAll()
protected void	doWait()
protected void	doWait(long millis)
protected boolean	exitRequested()
protected MaryData	externalIO(MaryData d) The actual external input and output.
protected InputStream	from() The stream on which data is read from the external process.
MaryDataType	getInputType()
Locale	getLocale() The locale of this module, i.e.
protected ExternalModuleRequest	getNextRequest()
MaryDataType	getOutputType()
protected Process	getProcess() Get the process object representing the external module program.
int	getState() Inform about the state of this module.
protected boolean	haveWaitingRequests()
MaryDataType	inputType() Deprecated.
String	name() This module's name, as free text, for example "Tokeniser"
protected boolean	needToRestart()
protected void	open() Execute the command cmd as an external process.
MaryDataType	outputType() Deprecated.
void	powerOnSelfTest() Perform a power-on self test by processing some example input data.
MaryData	process(MaryData d) Feed the input data into the external module, and return the result.
protected void	removeRequest(ExternalModuleRequest r)
protected void	setCmd(String cmd) Sets the command line to execute.
protected void	setExitRequested(boolean b) Tell all helper threads to exit.
protected void	setNeedToRestart(boolean needToRestart)
void	shutdown() Allow the module to shut down cleanly.
void	startup() Allow the module to start up, performing whatever is necessary to become operational.
protected OutputStream	to() The stream on which data is written to the external process.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

state

protected int state

process

protected Process process

to

protected OutputStream to

from

protected InputStream from

errorLogger

protected StreamLogger errorLogger

processingThread

protected ExternalModule.ProcessingThread processingThread

restarterThread

protected ExternalModule.RestarterThread restarterThread

logger

protected org.apache.log4j.Logger logger

The logger instance to be used by this module. It will identify the origin of the log message in the log file.

timeLimit

protected long timeLimit

The duration given to the module before timeout occurs (in milliseconds).

retrying

protected boolean retrying

Remember if a retry attempt is undertaken in process().

See Also:

process

ignorePattern

protected String ignorePattern

A regular expression describing what to be ignored in the external module's standard error output. Default is null.

Constructor Detail

ExternalModule

protected ExternalModule(String name,
              String cmd,
              MaryDataType inputType,
              MaryDataType outputType,
              Locale locale)
                  throws NoSuchPropertyException

Throws:

NoSuchPropertyException

Method Detail

getProcess

protected Process getProcess()

Get the process object representing the external module program.

Returns:

process

open

protected void open()
             throws IOException

Execute the command cmd as an external process. The process's input and output streams are accessible from then on via the from() and to() methods; the process's error stream is logged by a separate StreamLogger thread.

Throws:

IOException - IOException

See Also:

to(), from(), StreamLogger

close

protected void close()

Closes the external process's input and output streams, and destroys the process.

to

protected OutputStream to()

The stream on which data is written to the external process.

Returns:

to

from

protected InputStream from()

The stream on which data is read from the external process.

Returns:

from

cmd

protected String cmd()

The command line to execute as an external process.

Returns:

cmd

setCmd

protected void setCmd(String cmd)

Sets the command line to execute.

Parameters:

cmd - cmd

name

public String name()

Description copied from interface: MaryModule

This module's name, as free text, for example "Tokeniser"

Specified by:

name in interface MaryModule

Returns:

name

inputType

@Deprecated
public MaryDataType inputType()

Deprecated.

Description copied from interface: MaryModule

The type of input data needed by this module.

Specified by:

inputType in interface MaryModule

Returns:

input type

getInputType

public MaryDataType getInputType()

Specified by:

getInputType in interface MaryModule

outputType

@Deprecated
public MaryDataType outputType()

Deprecated.

Description copied from interface: MaryModule

The type of output data produced by this module.

Specified by:

outputType in interface MaryModule

Returns:

outputType

getOutputType

public MaryDataType getOutputType()

Specified by:

getOutputType in interface MaryModule

getLocale

public Locale getLocale()

Description copied from interface: MaryModule

The locale of this module, i.e. the locale of data that this module can process. If null, indicates that the module can use data of any locale (i.e., the module is language-independent.)

Specified by:

getLocale in interface MaryModule

Returns:

the locale of this module, if any, or null

getState

public int getState()

Description copied from interface: MaryModule

Inform about the state of this module.

Specified by:

getState in interface MaryModule

Returns:

an int identifying the state of this module, either MODULE_OFFLINE or MODULE_RUNNING.

startup

public void startup()
             throws Exception

Description copied from interface: MaryModule

Allow the module to start up, performing whatever is necessary to become operational. After successful completion, getState() should return MODULE_RUNNING.

Specified by:

startup in interface MaryModule

Throws:

Exception - Exception

powerOnSelfTest

public void powerOnSelfTest()
                     throws Error

Perform a power-on self test by processing some example input data.

Specified by:

powerOnSelfTest in interface MaryModule

Throws:

Error - if the module does not work properly.

shutdown

public void shutdown()

Description copied from interface: MaryModule

Allow the module to shut down cleanly. After this has successfully completed, getState() should return MODULE_OFFLINE.

Specified by:

shutdown in interface MaryModule

externalIO

protected MaryData externalIO(MaryData d)
                       throws TransformerConfigurationException,
                              TransformerException,
                              FileNotFoundException,
                              IOException,
                              ParserConfigurationException,
                              SAXException,
                              Exception

The actual external input and output. Write to the module and read from the module in the appropriate ways as determined by input and output data types.

Parameters:

d - d

Returns:

result

Throws:

TransformerConfigurationException - TransformerConfigurationException

TransformerException - TransformerException

FileNotFoundException - FileNotFoundException

IOException - IOException

ParserConfigurationException - ParserConfigurationException

SAXException - SAXException

Exception - Exception

process

public final MaryData process(MaryData d)
                       throws TransformerConfigurationException,
                              TransformerException,
                              FileNotFoundException,
                              IOException,
                              ParserConfigurationException,
                              SAXException,
                              Exception

Feed the input data into the external module, and return the result. This method is responsible for the timer and timeout handling and is regarded as generic for all external modules, thus final. The actual input and output is performed by externalIO() and may be overridden by subclasses to account for module-specifics.

If timeout occurs, the external module is restarted, and a second attempt is made. If it fails again, an IOException is thrown. Even in case of the second failure, the external process is restarted, because failure may have been provoked by this particular input.

For the time being, external modules are thread-safe simply by this method being synchronized.

Specified by:

process in interface MaryModule

Parameters:

d - d

Returns:

A MaryData object of type outputType() encapsulating the processing result.

Throws:

Exception - Exception

TransformerConfigurationException

TransformerException

FileNotFoundException

IOException

ParserConfigurationException

SAXException

addRequest

protected void addRequest(Object r)

getNextRequest

protected ExternalModuleRequest getNextRequest()

removeRequest

protected void removeRequest(ExternalModuleRequest r)

haveWaitingRequests

protected boolean haveWaitingRequests()

setNeedToRestart

protected void setNeedToRestart(boolean needToRestart)

needToRestart

protected boolean needToRestart()

doNotifyAll

protected void doNotifyAll()

doWait

protected void doWait()

doWait

protected void doWait(long millis)

setExitRequested

protected void setExitRequested(boolean b)

Tell all helper threads to exit.

Parameters:

b - b

exitRequested

protected boolean exitRequested()