com.jstatcom.engine
Class PCall

java.lang.Object
  extended by java.lang.Thread
      extended by 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: 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: Default is true.

Parameters:
gui -