hyspirit.engines
Class HyEngine

java.lang.Object
  hyspirit.engines.HyEngine

All Implemented Interfaces:

java.lang.Runnable

Direct Known Subclasses:

HyAnalysisEngine, HyFreq2MDSEngine, HyInferenceEngine, HyMDS2DirEngine, HyMDS2MDSEngine, HyMDS2PRIEngine, HyText2MDSEngine

public abstract class HyEngine
extends java.lang.Object
implements java.lang.Runnable

This class implements all required methods and communications for the HySpirit engines. There are two possible modes:

• Client/Server mode: to start an own engine process and query it
• Client mode: to connect to an existing engine process and query it

Author:

Ingo Frommholz

Created on 02-Dec-2005 10:34:51

Field Summary

protected java.lang.String	argumentString
protected org.apache.log4j.Logger	LOG
boolean	stdin
protected static java.lang.String	TIME_PREFIX The prefix that identifies a line returned by the time command

Constructor Summary

HyEngine(java.lang.String engineName)
This constructor must be used if you are going to start your own engine process (client/server mode).

HyEngine(java.lang.String engineName, HySpiritProperties hyspirit)
This constructor must be used if you are going to start your own engine process (client/server mode).

HyEngine(java.lang.String engineName, java.lang.String hostname, int port)
This constructor must be used if you want to attach to a running engine process (client mode) through a socket

Method Summary

protected java.lang.String[]	buildCommand() Builds the command from the parameters.
void	closeSTDIN() Closes the STDIN.
void	destroy() Kills a running process.
java.lang.String	echoSpecial(java.lang.String message) Returns a string which lets the engine echo the given message
int	exitValue() Returns the exit value of the process or -1 if in client mode
java.lang.String	getCommand() Returns the absolute path of the current command if in client/server mode and null if in client mode
java.lang.String	getEngineName() Returns the engine name
java.io.BufferedReader	getInputReader() Gets the input reader, which is STDOUT in client/server mode, and the socket output reader otherwise
java.io.BufferedWriter	getOutputWriter() Gets the output writer, which is STDIN in client/server mode, and the socket input writer otherwise
java.lang.String	getPercentageCPU() If we used the Unix time command, this method gets the elapsed sys mode CPU seconds
java.lang.String	getRealTime() If we used the Unix time command, this method gets the elapsed real time in [hours:]minutes:seconds.
java.io.BufferedReader	getSTDERR() Deprecated. STDERR now redirected to System.err. Returns null.
java.io.BufferedWriter	getSTDIN() Gets STDIN if not in clientmode.
java.io.BufferedReader	getSTDOUT() Gets STDOUT if not in clientmode.
protected java.lang.String	getStreamEndMessage()
java.lang.String	getSysTime() If we used the Unix time command, this method gets the elapsed sys mode CPU seconds
java.lang.String	getUserTime() If we used the Unix time command, this method gets the elapsed user mode CPU seconds
boolean	hasNext() Returns if there is a next element to read or not.
boolean	isInClientMode() Returns true if this object is in client mode, and false if it is in client/server mode.
boolean	isRunning() Returns true if the underlying process is running, false otherwise.
HyKB	kb() Get the knowledge base of this engine.
void	kb(HyKB kb) Set the knowledge base of this engine.
void	kb(java.lang.String kbName) Set the knowledge base of this engine.
java.lang.String	next() Returns the next line of output from the underlying engine or null if there's nothing more to read.
void	readFromSTDIN() Ensures that the process reads input from STDIN.
void	reset() Resets all parameters of the engine after destroying a possibly running process.
void	restart() Restarts the engine.
void	run() Run command.
protected void	send(java.io.BufferedReader input)
void	send(java.lang.String input) Send input string to engine.
java.lang.String	sendAndReceive(java.lang.String input) This is a convenience method: it sends the input given in the string to the STDIN of the engine and returns the output of the engine.
void	sendFile(java.lang.String filename) Send content of file to engine.
void	setArgumentString(java.lang.String argumentString) Additional arguments which are not supported (yet) by an engine can be set here.
void	setLogger(org.apache.log4j.Logger log) Sets a logger for the engine.
void	start() Starting this object as a thread.
void	suppressSTDERR(boolean suppress) By default, the engine process' output to STDERR is redirected to the System.err and to the engine's logger.
protected boolean	takesTime() Returns true if we use the Unix time command
void	takeTime(boolean taketime) Whether to take runtime statistics of the engine process or not.
int	waitFor() Causes the current thread to wait, if necessary, until the process has terminated.
void	waitTillRunning() This does nothing but wait until an underlying bridge process is actually running, and it return then.

Methods inherited from class java.lang.Object

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

Field Detail

stdin

public boolean stdin

argumentString

protected java.lang.String argumentString

LOG

protected org.apache.log4j.Logger LOG

TIME_PREFIX

protected static final java.lang.String TIME_PREFIX

The prefix that identifies a line returned by the time command

See Also:

Constant Field Values

Constructor Detail

HyEngine

public HyEngine(java.lang.String engineName)
         throws HySpiritException

This constructor must be used if you are going to start your own engine process (client/server mode).

Parameters:

engineName - the name of the engine (e.g., 'hy_pra')

Throws:

HySpiritException - if we can't determine the environment

HyEngine

public HyEngine(java.lang.String engineName,
                HySpiritProperties hyspirit)
         throws HySpiritException

This constructor must be used if you are going to start your own engine process (client/server mode).

Parameters:

engineName - the name of the engine (e.g., 'hy_pra')

hyspirit - the HySpirit properties containing the environment

Throws:

HySpiritException - if we can't determine the environment

HyEngine

public HyEngine(java.lang.String engineName,
                java.lang.String hostname,
                int port)
         throws HySpiritException

This constructor must be used if you want to attach to a running engine process (client mode) through a socket

Parameters:

hostname - the hostname of the engine server

port - the port of the engine server

Throws:

HySpiritException - if the connection failed

Method Detail

setLogger

public void setLogger(org.apache.log4j.Logger log)

Sets a logger for the engine. Replaces the default one.

Parameters:

log - the logger.

setArgumentString

public void setArgumentString(java.lang.String argumentString)

Additional arguments which are not supported (yet) by an engine can be set here.

Parameters:

argumentString - the argument string

start

public void start()

Starting this object as a thread.

getCommand

public java.lang.String getCommand()

Returns the absolute path of the current command if in client/server mode and null if in client mode

getEngineName

public java.lang.String getEngineName()

Returns the engine name

Returns:

the engine name

getRealTime

public java.lang.String getRealTime()

If we used the Unix time command, this method gets the elapsed real time in [hours:]minutes:seconds.

See Also:

takeTime(boolean)

getUserTime

public java.lang.String getUserTime()

If we used the Unix time command, this method gets the elapsed user mode CPU seconds

See Also:

takeTime(boolean)

getSysTime

public java.lang.String getSysTime()

If we used the Unix time command, this method gets the elapsed sys mode CPU seconds

See Also:

takeTime(boolean)

getPercentageCPU

public java.lang.String getPercentageCPU()

If we used the Unix time command, this method gets the elapsed sys mode CPU seconds

See Also:

takeTime(boolean)

readFromSTDIN

public void readFromSTDIN()

Ensures that the process reads input from STDIN. This makes sense in client/server mode only.

getSTDIN

public java.io.BufferedWriter getSTDIN()

Gets STDIN if not in clientmode. Note that the stream is null unless the actual process really started, so check this first.

Returns:

STDIN as buffered writer

getSTDOUT

public java.io.BufferedReader getSTDOUT()

Gets STDOUT if not in clientmode. Note that the stream is null unless the actual process really started, so check this first.

Returns:

STDOUT as buffered reader

getSTDERR

public java.io.BufferedReader getSTDERR()

Deprecated. STDERR now redirected to System.err. Returns null.

Gets STDERR if not in clientmode. Note that the stream is null unless the actual process really started, so check this first.

Returns:

STDERR as buffered reader

closeSTDIN

public void closeSTDIN()
                throws java.io.IOException

Closes the STDIN. Some processes (like hyp_pra) need either enough input or an EOF in STDIN before they release their buffered output. So try this if you don't receive any output from the underlying engine.

Throws:

java.io.IOException

getOutputWriter

public java.io.BufferedWriter getOutputWriter()
                                       throws java.io.IOException

Gets the output writer, which is STDIN in client/server mode, and the socket input writer otherwise

Returns:

the input writer

Throws:

java.io.IOException

getInputReader

public java.io.BufferedReader getInputReader()
                                      throws java.io.IOException

Gets the input reader, which is STDOUT in client/server mode, and the socket output reader otherwise

Returns:

the output reader

Throws:

java.io.IOException

reset

public void reset()

Resets all parameters of the engine after destroying a possibly running process. You have to restart the process with run().

run

public void run()

Run command. If in client mode, this does nothing.

Specified by:

run in interface java.lang.Runnable

destroy

public void destroy()
             throws java.lang.IllegalThreadStateException

Kills a running process. This does nothing if in client mode.

Throws:

java.lang.IllegalThreadStateException - if the process hasn't started yet.

restart

public void restart()
             throws java.lang.IllegalThreadStateException

Restarts the engine. Does nothing in client mode.

Throws:

java.lang.IllegalThreadStateException

waitFor

public int waitFor()
            throws java.lang.IllegalThreadStateException,
                   java.lang.InterruptedException

Causes the current thread to wait, if necessary, until the process has terminated. By convention, 0 indicates normal termination. If in client mode, this does nothing and returns -1.

Returns:

the exit value of the process

Throws:

java.lang.InterruptedException - - if the current thread is interrupted by another thread while it is waiting, then the wait is ended and an InterruptedException is thrown.

java.lang.IllegalThreadStateException - if the process hasn't started yet.

isRunning

public boolean isRunning()

Returns true if the underlying process is running, false otherwise. Returns always true if in client mode.

Returns:

whether the underlying process is running

isInClientMode

public boolean isInClientMode()

Returns true if this object is in client mode, and false if it is in client/server mode.

Returns:

true if in client mode, false otherwise

waitTillRunning

public void waitTillRunning()

This does nothing but wait until an underlying bridge process is actually running, and it return then. Do not invoke if you did not invoke the run() or start() method first! Returns immediately in client mode

exitValue

public int exitValue()
              throws java.lang.IllegalThreadStateException

Returns the exit value of the process or -1 if in client mode

Returns:

the exit value of the process

Throws:

java.lang.IllegalThreadStateException - - if the process has not yet terminated or started.

send

public void send(java.lang.String input)
          throws java.io.IOException

Send input string to engine. Use Use next() to read the output from the process. Be sure you read the results of a previous send() first because otherwise they will be dropped!

Parameters:

input - the string to be sent to the engine.

Throws:

java.io.IOException

sendFile

public void sendFile(java.lang.String filename)
              throws java.io.IOException

Send content of file to engine. Use next() to read the output from the process. Be sure you read the results of a previous send() first because otherwise they will be dropped!

Parameters:

filename - the content of this file will be sent to the engine

Throws:

java.io.IOException

getStreamEndMessage

protected java.lang.String getStreamEndMessage()

echoSpecial

public java.lang.String echoSpecial(java.lang.String message)

Returns a string which lets the engine echo the given message

Parameters:

message - the message to be echoed

Returns:

the echo string (null if no echoing is allowed)

sendAndReceive

public java.lang.String sendAndReceive(java.lang.String input)

This is a convenience method: it sends the input given in the string to the STDIN of the engine and returns the output of the engine. The STDIN of the engine process is closed after the string was sent. The output of the process is read and returned. STDERR is caught and redirected to System.err. This method is for engines which read something from STDIN, process it after STDIN is closed and return something to STDOUT before exiting.

Parameters:

input -

Returns:

send

protected void send(java.io.BufferedReader input)
             throws java.io.IOException

Throws:

java.io.IOException

hasNext

public boolean hasNext()

Returns if there is a next element to read or not. Might block in the situation when all received lines were read and we are waiting for the next line of the process. In this case, this method waits until the next line from the process is read.

Returns:

whether there is another element to read or not.

next

public java.lang.String next()

Returns the next line of output from the underlying engine or null if there's nothing more to read. This method might block if and as long as the output stream from the underlying process blocks.

Returns:

the next line as a string

suppressSTDERR

public void suppressSTDERR(boolean suppress)

By default, the engine process' output to STDERR is redirected to the System.err and to the engine's logger. If you do not want this, you can suppress this here. The error output of the process is still captured by the Logger on the WARN level.

Parameters:

suppress - true if the process output should not be sent to System.err, false else.

takeTime

public void takeTime(boolean taketime)

Whether to take runtime statistics of the engine process or not. If this is set to true, the engine is started using the Unix time command with the format defined in TIME_FORMAT. The output is appended to STDOUT.

Parameters:

takeTime - whether to take file or not. Default: don't take time false.

takesTime

protected boolean takesTime()

Returns true if we use the Unix time command

Returns:

true if we use the Unix time command, false else

buildCommand

protected java.lang.String[] buildCommand()

Builds the command from the parameters. If subclasses support other parameters, they have to override the buildCommand and reset methods. Be sure that you place the support for new, additional parameters somewhere. This means the block

   if (this.argumentString != null) {
     StringTokenizer strTok= new StringTokenizer(this.argumentString);
     while (strTok.hasMoreTokens()) commandVec.add(strTok.nextToken());
  }
  

should appear somewhere in your buildCommand implementation.

The output of this method is used in the run() method.

Returns:

the command string array

kb

public void kb(HyKB kb)

Set the knowledge base of this engine.

kb

public void kb(java.lang.String kbName)
        throws java.io.IOException

Set the knowledge base of this engine. This method creates a knowledge base object with the argument name.

Parameters:

kbName - the name of the knowledge base

Throws:

java.io.IOException

kb

public HyKB kb()

Get the knowledge base of this engine.