toolbus.tool
Class ToolInstance

java.lang.Object
  toolbus.tool.ToolInstance

All Implemented Interfaces:

IDataHandler, IOperations

public class ToolInstance
extends java.lang.Object
implements IDataHandler, IOperations

Provides the interface to a tool instance.

Author:

Arnold Lankamp

Field Summary

private static int	BLOCKED
private static int	DISCONNECTED
private java.util.List<aterm.ATerm>	eventsFromTool
private IIOHandler	ioHandler
private static int	KILLED
private aterm.ATerm	lastDebugPerformanceStats
private java.util.List<aterm.ATerm>	performanceStats
private static int	READY
private java.util.List<aterm.ATerm>	requestsFromTool
private int	state
private java.lang.Object	stateLock
private StreamHandler	streamHandler
private TBTermFactory	tbfactory
private static int	TERMINATED
private ToolBus	toolbus
private ToolDefinition	toolDef
private int	toolID
private aterm.ATermAppl	toolKey
private static int	toolNr
private static int	UNCONNECTED
private static int	UNREACHABLE
private java.util.List<aterm.ATerm>	valuesFromTool

Fields inherited from interface toolbus.IOperations

ACKDO, ACKEVENT, CONNECT, DEBUGPERFORMANCESTATS, DISCONNECT, DO, END, EVAL, EVENT, PERFORMANCESTATS, REQUEST, RESPONSE, TERMINATE, UNDEFINED, VALUE

Constructor Summary

ToolInstance(ToolDefinition toolDef, ToolBus toolbus)
Constructor.

Method Summary

void	exceptionOccured() Notifies the data handler that an exception has occured so it can take the necessary steps.
void	executeTool() Executes the tool that should be associated with this tool instance.
boolean	getEventFromTool(aterm.ATerm pattern, Environment env) Attempts to find a event that matches the given signature.
aterm.ATerm	getLastDebugPerformanceStats() Returns the last received batch of debug performance statistics.
boolean	getPerformanceStats(aterm.ATerm aTerm, Environment env) Attempts to find performance statistics that match the given signature.
aterm.ATerm[]	getQueuedEvents() Returns an array of all queued rec-event terms for this tool instance.
aterm.ATerm[]	getQueuedRequests() Returns an array of all queued rec-request terms for this tool instance.
aterm.ATerm[]	getQueuedValues() Returns an array of all queued rec-value terms for this tool instance.
boolean	getRequestFromTool(aterm.ATerm pattern, Environment env) Attempts to find a request that matches the given signature.
int	getToolID() Returns the id of the tool that is associated with this tool instance.
aterm.ATermAppl	getToolKey() Returns the key of the tool that is associated with this tool instance.
java.lang.String	getToolName() Returns the name of the tool that is associated with this tool instance.
boolean	getValueFromTool(aterm.ATerm pattern, Environment env) Attempts to find a value that matches the given signature.
private void	goConnected() Notifies this tool instance that the tool connected.
private void	goDisconnected() Notifies this tool instance that the tool has disconnected.
private void	goKilled() Notifies this tool instance that the tool has been killed.
void	goReady() Notifies this tool instance that the tool is ready to receive a new DO or EVAL request.
private void	goTerminated() Notifies this tool instance that the tool has terminated.
private void	goUnreachable() Notifies this tool instance that the tool has become unreachable.
boolean	isConnected() Checks if the tool is connected.
boolean	isDisconnected() Checks if the tool has disconnected.
boolean	isExecutedTool() Checks if the tool that is associated with this tool instance was executed or connected on it's own initiative.
boolean	isKilled() Checks if the tool has been killed.
boolean	isReady() Checks if the tool is ready.
boolean	isTerminated() Checks if the tool has been terminated.
boolean	isUnreachable() Checks if the tool has become unreachable.
void	kill() Forcefully terminates the with this tool instance associated tool.
void	receive(byte operation, aterm.ATerm aTerm) Receives a term from the associated ioHandler.
void	send(byte operation, aterm.ATerm aTerm) Forwards a term to the associated ioHandler.
void	sendAckEvent(aterm.ATerm aTerm) Sends an ack event to the with this tool instance associated tool.
void	sendDebugPerformanceStatsRequest() Sends a debug performance statistics request to the with this tool instance associated tool.
void	sendDo(aterm.ATerm aTerm) Sends a do request to the with this tool instance associated tool.
void	sendEval(aterm.ATerm aTerm) Sends an evaluation request to the with this tool instance associated tool.
void	sendPerformanceStatsRequest(aterm.ATerm aTerm) Sends a performance statistics request to the with this tool instance associated tool.
void	sendResponse(aterm.ATerm aTerm) Sends an response to the with this tool instance associated tool.
void	sendTerminate(aterm.ATerm aTerm) Sends a termination request to the with this tool instance associated tool.
void	setIOHandler(IIOHandler ioHandler) Associates an ioHandler with the data handler.
void	setStreamHandler(StreamHandler streamHandler) Sets the stream handler for this tool instance.
java.lang.String	showStatus() Returns the status of this tool instance in string format.
void	shutDown() Shuts down this dataHandler.
void	terminate() Requests the termination of this dataHandler.
boolean	tryDoEval() Notifies the tool instance that you want to send a DO or EVAL request to the tool and checks if this is possible.

Methods inherited from class java.lang.Object

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

Field Detail

toolDef

private final ToolDefinition toolDef

toolbus

private final ToolBus toolbus

tbfactory

private final TBTermFactory tbfactory

ioHandler

private volatile IIOHandler ioHandler

streamHandler

private volatile StreamHandler streamHandler

toolNr

private static int toolNr

toolKey

private final aterm.ATermAppl toolKey

toolID

private final int toolID

valuesFromTool

private final java.util.List<aterm.ATerm> valuesFromTool

eventsFromTool

private final java.util.List<aterm.ATerm> eventsFromTool

requestsFromTool

private final java.util.List<aterm.ATerm> requestsFromTool

performanceStats

private final java.util.List<aterm.ATerm> performanceStats

lastDebugPerformanceStats

private volatile aterm.ATerm lastDebugPerformanceStats

UNCONNECTED

private static final int UNCONNECTED

See Also:

Constant Field Values

READY

private static final int READY

See Also:

Constant Field Values

BLOCKED

private static final int BLOCKED

See Also:

Constant Field Values

DISCONNECTED

private static final int DISCONNECTED

See Also:

Constant Field Values

KILLED

private static final int KILLED

See Also:

Constant Field Values

UNREACHABLE

private static final int UNREACHABLE

See Also:

Constant Field Values

TERMINATED

private static final int TERMINATED

See Also:

Constant Field Values

state

private volatile int state

stateLock

private final java.lang.Object stateLock

Constructor Detail

ToolInstance

public ToolInstance(ToolDefinition toolDef,
                    ToolBus toolbus)

Constructor.

Parameters:

toolDef - The definition of the tool.

toolbus - A reference to the toolbus associated with this tool instance.

Method Detail

executeTool

public void executeTool()
                 throws ToolBusException

Executes the tool that should be associated with this tool instance.

Throws:

ToolBusException - Thrown when the tool could not be executed.

getToolKey

public aterm.ATermAppl getToolKey()

Returns the key of the tool that is associated with this tool instance.

Returns:

The key of the tool that is associated with this tool instance.

getToolID

public int getToolID()

Returns the id of the tool that is associated with this tool instance.

Returns:

The id of the tool that is associated with this tool instance.

getToolName

public java.lang.String getToolName()

Returns the name of the tool that is associated with this tool instance.

Returns:

The name of the tool that is associated with this tool instance.

setStreamHandler

public void setStreamHandler(StreamHandler streamHandler)

Sets the stream handler for this tool instance.

Parameters:

streamHandler - The stream handler to use.

setIOHandler

public void setIOHandler(IIOHandler ioHandler)

Description copied from interface: IDataHandler

Associates an ioHandler with the data handler. Every data handler needs one to operate and it must NOT be changed during it's operation.

Specified by:

setIOHandler in interface IDataHandler

Parameters:

ioHandler - The I/O handler we need to associate with the data handler.

See Also:

IDataHandler.setIOHandler(IIOHandler)

receive

public void receive(byte operation,
                    aterm.ATerm aTerm)

Description copied from interface: IDataHandler

Receives a term from the associated ioHandler.

Specified by:

receive in interface IDataHandler

Parameters:

operation - The operation associate with the term we received.

aTerm - The term that was received.

See Also:

IDataHandler.receive(byte, ATerm)

sendAckEvent

public void sendAckEvent(aterm.ATerm aTerm)

Sends an ack event to the with this tool instance associated tool.

Parameters:

aTerm - The ack event.

sendResponse

public void sendResponse(aterm.ATerm aTerm)

Sends an response to the with this tool instance associated tool.

Parameters:

aTerm - The response.

sendDo

public void sendDo(aterm.ATerm aTerm)

Sends a do request to the with this tool instance associated tool.

Parameters:

aTerm - The do request.

sendEval

public void sendEval(aterm.ATerm aTerm)

Sends an evaluation request to the with this tool instance associated tool.

Parameters:

aTerm - The evaluation request.

sendTerminate

public void sendTerminate(aterm.ATerm aTerm)

Sends a termination request to the with this tool instance associated tool.

Parameters:

aTerm - The termination request.

sendPerformanceStatsRequest

public void sendPerformanceStatsRequest(aterm.ATerm aTerm)

Sends a performance statistics request to the with this tool instance associated tool.

Parameters:

aTerm - The performance statistics request.

sendDebugPerformanceStatsRequest

public void sendDebugPerformanceStatsRequest()

Sends a debug performance statistics request to the with this tool instance associated tool.

send

public void send(byte operation,
                 aterm.ATerm aTerm)

Description copied from interface: IDataHandler

Forwards a term to the associated ioHandler.

Specified by:

send in interface IDataHandler

Parameters:

operation - The operation associated with the term we need to send.

aTerm - The term that needs to be transmitted.

See Also:

IDataHandler.send(byte, ATerm)

terminate

public void terminate()

Description copied from interface: IDataHandler

Requests the termination of this dataHandler.

Specified by:

terminate in interface IDataHandler

See Also:

IDataHandler.terminate()

shutDown

public void shutDown()

Description copied from interface: IDataHandler

Shuts down this dataHandler. IMPORTANT: this method may only be called by the associated ioHandler. Manual invokation will lead to undefined behaviour.

Specified by:

shutDown in interface IDataHandler

See Also:

IDataHandler.shutDown()

isExecutedTool

public boolean isExecutedTool()

Checks if the tool that is associated with this tool instance was executed or connected on it's own initiative.

Returns:

True if the tool was executed; false otherwise.

kill

public void kill()

Forcefully terminates the with this tool instance associated tool. NOTE: This only works for executed tools. Tools that connected on their own initiative won't be killed by the invocation of this method; however they will become unreachable and their state will be set to 'killed'.

exceptionOccured

public void exceptionOccured()

Description copied from interface: IDataHandler

Notifies the data handler that an exception has occured so it can take the necessary steps.

Specified by:

exceptionOccured in interface IDataHandler

See Also:

IDataHandler.exceptionOccured()

getValueFromTool

public boolean getValueFromTool(aterm.ATerm pattern,
                                Environment env)

Attempts to find a value that matches the given signature. If this is the case the environment will be updated.

Parameters:

pattern - The signature we need to match on.

env - The enviroment in which we need to make updates, when a match have been made.

Returns:

Indicates if the matches was successful.

getEventFromTool

public boolean getEventFromTool(aterm.ATerm pattern,
                                Environment env)

Attempts to find a event that matches the given signature. If one is found the environment will be updated.

Parameters:

pattern - The signature we need to match on.

env - The enviroment in which we need to make updates, when a match have been made.

Returns:

Indicates if the matches was successful.

getRequestFromTool

public boolean getRequestFromTool(aterm.ATerm pattern,
                                  Environment env)

Attempts to find a request that matches the given signature. If one is found the environment will be updated.

Parameters:

pattern - The signature we need to match on.

env - The enviroment in which we need to make updates, when a match have been made.

Returns:

Indicates if the matches was successful.

getPerformanceStats

public boolean getPerformanceStats(aterm.ATerm aTerm,
                                   Environment env)

Attempts to find performance statistics that match the given signature. If one is found the environment will be updated.

Parameters:

aTerm - The signature we need to match on.

env - The enviroment in which we need to make updates, when a match have been made.

Returns:

Indicates if the matches was successful.

getLastDebugPerformanceStats

public aterm.ATerm getLastDebugPerformanceStats()

Returns the last received batch of debug performance statistics. NOTE: This method will only be used in debug mode, by the debug ToolBus.

Returns:

The last received batch of debug performance statistics.

goConnected

private void goConnected()

Notifies this tool instance that the tool connected.

goReady

public void goReady()

Notifies this tool instance that the tool is ready to receive a new DO or EVAL request.

goDisconnected

private void goDisconnected()

Notifies this tool instance that the tool has disconnected.

goTerminated

private void goTerminated()

Notifies this tool instance that the tool has terminated.

goKilled

private void goKilled()

Notifies this tool instance that the tool has been killed.

goUnreachable

private void goUnreachable()

Notifies this tool instance that the tool has become unreachable.

isConnected

public boolean isConnected()

Checks if the tool is connected.

Returns:

True if the tool is connected; false otherwise.

isReady

public boolean isReady()

Checks if the tool is ready.

Returns:

True if the tool is ready; false otherwise.

isDisconnected

public boolean isDisconnected()

Checks if the tool has disconnected.

Returns:

True if the tool has disconnected; false otherwise.

isTerminated

public boolean isTerminated()

Checks if the tool has been terminated.

Returns:

True if the tool has been terminated.

isKilled

public boolean isKilled()

Checks if the tool has been killed.

Returns:

True if the tool has been killed; false otherwise.

isUnreachable

public boolean isUnreachable()

Checks if the tool has become unreachable.

Returns:

True if the tool has become unreachable.

tryDoEval

public boolean tryDoEval()

Notifies the tool instance that you want to send a DO or EVAL request to the tool and checks if this is possible.

Returns:

True if it is possible to send a DO or EVAL request; false otherwise.

getQueuedValues

public aterm.ATerm[] getQueuedValues()

Returns an array of all queued rec-value terms for this tool instance.

Returns:

An array of all queued rec-value terms for this tool instance.

getQueuedEvents

public aterm.ATerm[] getQueuedEvents()

Returns an array of all queued rec-event terms for this tool instance.

Returns:

An array of all queued rec-event terms for this tool instance.

getQueuedRequests

public aterm.ATerm[] getQueuedRequests()

Returns an array of all queued rec-request terms for this tool instance.

Returns:

An array of all queued rec-request terms for this tool instance.

showStatus

public java.lang.String showStatus()

Returns the status of this tool instance in string format.

Returns:

The status of this tool instance in string format.