com.jstatcom.engine
Class PCall

java.lang.Object
  java.lang.Thread
      com.jstatcom.engine.PCall

All Implemented Interfaces:

java.lang.Runnable

public abstract class PCall
extends java.lang.Thread

This class encapsulates procedure calls to carry out computational tasks in an extra thread. It can optionally be executed in a single worker thread by invoking the thread with execute. Concrete subclasses must implement runCode with the respective algorithm for the computation. Subclasses can also overwrite finalCode for output formatting or other tasks that should be carried out if runCode finished successfully. All relevant data should be given as arguments in the constructor.

A procedure call object can be invoked with the respective arguments from a GUI or a non GUI object. It helps to separate the program logic from the user interface part.

All events that are fired are synchronized with the Swing EvenDispatchingThread if isGui()==true.

Author:

Markus Kraetzig

Nested Class Summary

Nested classes/interfaces inherited from class java.lang.Thread

java.lang.Thread.State, java.lang.Thread.UncaughtExceptionHandler

Field Summary

Fields inherited from class java.lang.Thread

MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY

Constructor Summary

PCall()

Method Summary

void	add(PCall pCall) Adds another call object that will be executed if this call finished successfully.
void	addPCallListener(PCallListener l) Registers listener l such that it will receive notifications.
void	call(java.lang.String procName, JSCData[] args, JSCData[] retData) Adapter to Engine.call that uses engine().
void	cancel() Interrupts this call and calls the stop method of the engine.
abstract Engine	engine() Gets the Engine instance that is used by this call for the convenience implementations of the adapter methods to the engine interface.
boolean	equals(java.lang.Object o) Overwrite protection method calls super method.
void	execute() Puts this call object in the worker thread queue.
EDU.oswego.cs.dl.util.concurrent.Executor	getExecutor() Gets the executor that is used by the execute method.
OutHolder	getOutHolder() Gets the output holder component.
long	getStartTime() Gets the system time at thread start.
SymbolTable	getSymbolTable() Gets the currently used symbol table.
int	hashCode() Overwrite protection method calls super method.
boolean	isGui() Gets whether GUI mode is set.
boolean	isPrintDate() Gets whether date is printed in output.
boolean	isSuccess() Gets whether the call finished successfully.
void	load(java.lang.String module, LoadTypes loadType, JSCData[] args) Adapter to Engine.load that uses engine().
void	remove(PCall pCall) Removes an element from the list of calls that are executed if this call finishes ok.
void	removePCallListener(PCallListener l) Unregisters listener l so that it will no longer be notified.
void	run() Template method that calls preCode,runCode and finalCode in this order.
void	setGui(boolean gui) Sets GUI mode, if true/false the following features are enabled/disabled: event synchronization with Swing Swing dialogs are used to display error messages Default is true.
void	setOutHolder(OutHolder outputHolder) Sets the output component that the results and other output should be written to.
void	setPrintDate(boolean b) Sets whether date is printed in output, the default is true.
void	setSymbolTable(SymbolTable newSymbolTable) Sets the symbol table to access data objects.

Methods inherited from class java.lang.Thread

activeCount, checkAccess, countStackFrames, currentThread, destroy, dumpStack, enumerate, getAllStackTraces, getContextClassLoader, getDefaultUncaughtExceptionHandler, getId, getName, getPriority, getStackTrace, getState, getThreadGroup, getUncaughtExceptionHandler, holdsLock, interrupt, interrupted, isAlive, isDaemon, isInterrupted, join, join, join, resume, setContextClassLoader, setDaemon, setDefaultUncaughtExceptionHandler, setName, setPriority, setUncaughtExceptionHandler, sleep, sleep, start, stop, stop, suspend, toString, yield

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

PCall

public PCall()

Method Detail

addPCallListener

public final void addPCallListener(PCallListener l)

Registers listener l such that it will receive notifications.

Parameters:

l - listener to be added

getOutHolder

public OutHolder getOutHolder()

Gets the output holder component. The default is SystemOutHolder.

Returns:

a component used to assemble output from this call

getStartTime

public long getStartTime()

Gets the system time at thread start.

Returns:

System.currentTimeMillis() when the call was started

getSymbolTable

public SymbolTable getSymbolTable()

Gets the currently used symbol table.

Returns:

a symbol table

isSuccess

public boolean isSuccess()

Gets whether the call finished successfully.

Returns:

true if runCode was successful

removePCallListener

public void removePCallListener(PCallListener l)

Unregisters listener l so that it will no longer be notified.

Parameters:

l - listener to be removed

run

public final void run()

Template method that calls preCode,runCode and finalCode in this order. It handles any exceptions that occur in these methods. The method has the following structure:

1. calls started of all registered PCallListener objects
2. clears getOutput buffer
3. calls runCode
4. calls finalCode if no exception was thrown and no interruption occured
5. output buffer is appended to outHolder if no error occured (optional)
6. if an error occured, messages are written to a log4j logger and outHolder and a dialog is shown (optional)
7. if interrupted, messages are written to a logger and outHolder
8. if successfull and not interrupted, then success and finished methods of PCallListener objects are called, otherwise only finished

The behaviour of this function can be adjusted by overwriting runCode and finalCode as well as by setting:

• setShowMessage
• setPrintDate
• setOutHolder

The output should be assembled in the finalCode method of subclasses by using the getOutput buffer.

Specified by:

run in interface java.lang.Runnable

Overrides:

run in class java.lang.Thread

setOutHolder

public void setOutHolder(OutHolder outputHolder)

Sets the output component that the results and other output should be written to. The default is SystemOutHolder.

Parameters:

outputHolder - write output to

setSymbolTable

public void setSymbolTable(SymbolTable newSymbolTable)

Sets the symbol table to access data objects. Subclasses must implement and document themselves which variables should be written or read to and from the symbol table. It is not used in the abstract implementation.

Parameters:

newSymbolTable - a new symbol table

Throws:

java.lang.IllegalArgumentException - if (newSymbolTable == null)

execute

public void execute()

Puts this call object in the worker thread queue. The call will be executed after every other call that has been queued before has finished. The queuing strategy can be changed by overwriting getExecutor.

Implementation
Calls execute(Runnable command) from util.concurrent.QueuedExecutor.

cancel

public void cancel()

Interrupts this call and calls the stop method of the engine.

add

public void add(PCall pCall)

Adds another call object that will be executed if this call finished successfully. All added objects are stored in a list that keeps the original order. All calls are executed in the same thread as this call. If one of the added calls produces an error, the remaining calls are executed nevertheless.

The event notification is done whenever a call was finished, meaning that success and finished are called before the other elements of the list are started.

Parameters:

pCall - call object that is exectued conditional on this call to finish without error

remove

public void remove(PCall pCall)

Removes an element from the list of calls that are executed if this call finishes ok. Nothing happens if pCall was not added before.

Parameters:

pCall - the call object to remove

isPrintDate

public boolean isPrintDate()

Gets whether date is printed in output.

Returns:

true if printed

setPrintDate

public void setPrintDate(boolean b)

Sets whether date is printed in output, the default is true.

Parameters:

b - true if printed

hashCode

public final int hashCode()

Overwrite protection method calls super method.

Overrides:

hashCode in class java.lang.Object

equals

public final boolean equals(java.lang.Object o)

Overwrite protection method calls super method.

Overrides:

equals in class java.lang.Object

engine

public abstract Engine engine()

Gets the Engine instance that is used by this call for the convenience implementations of the adapter methods to the engine interface.

Returns:

a instance of Engine

call

public void call(java.lang.String procName,
                 JSCData[] args,
                 JSCData[] retData)

Adapter to Engine.call that uses engine().

Parameters:

procName - procedure to be executed by this engine

args - the data to be used as input

retData - the return types

See Also:

Engine

load

public void load(java.lang.String module,
                 LoadTypes loadType,
                 JSCData[] args)

Adapter to Engine.load that uses engine().

Parameters:

module - the name of the module to load

loadType - the type of module to load

args - module load arguments if needed

getExecutor

public EDU.oswego.cs.dl.util.concurrent.Executor getExecutor()

Gets the executor that is used by the execute method. The default implementation uses util.concurrent.QueuedExecutor. Subclasses might overwrite this method to define a different execution policy.

Returns:

instance of Executor to be used by execute

isGui

public boolean isGui()

Gets whether GUI mode is set.

Returns:

true if in GUI mode, false otherwise

setGui

public void setGui(boolean gui)

Sets GUI mode, if true/false the following features are enabled/disabled:

• event synchronization with Swing
• Swing dialogs are used to display error messages

Default is true.

Parameters:

gui -