com.cosylab.jcosyne.server
Interface RemoteTaskMBean

All Superinterfaces:
java.lang.Runnable
All Known Subinterfaces:
ExecutorMBean, FactorizationMBean, LogCollectorMBean, ResultRepositoryMBean, SentinelMBean
All Known Implementing Classes:
Executor, Factorization, LogCollector, RemoteTask, ResultRepository, Sentinel

public interface RemoteTaskMBean
extends java.lang.Runnable

JMX complient interface to a remote task. This is the parent interface of all remote tasks that the user creates, as well as predefined tasks, such as executor, result repository etc. A remote task usually represents an algorithm. Conceptually and translated into computing world, this means that the implementation of the interface will be given certain initial data, either in the form of input files or settable attributes; after this, the remote task will perform a time-consuming computation; as the result, it will either write the data to some output or it will set some of its attributes to resulting values. The view taken here is that an in a computing system tasks should be usually broken down so that each remote task parametrizes one time-consuming computation, which is coded in its run() method. After this completes and the results are safely stored in the result repository (and may later be used to reconstruct back the remote task), the remote task (with its results) can be used and queried interactively by invoking getter and other getter methods on it, that produce act on the result. For example, a task that factors numbers may have the factorization as its central, time consuming algorithm, coded in the run() method. When factorization is done, the factors are recorded somewhere. After that, the user may call, say, additional methods, that compute the number of factors, their distribution and so on. Usually, these methods will not take long to compute and will therefore not form the results that should be persisted in the result repository. If, however, that is not the case, the remote task should, as part of its time-consuming computation, compute and store all such results as well, perhaps in a different file. The interface has the following functions:


Method Summary
 boolean copyStateFrom(javax.management.AttributeList state, javax.management.AttributeList internal)
          This method is used to transfer serialized state from one running instance of a remote task to another.
 boolean copyStateFrom(RemoteTaskInvocation rti)
          Transfers state from the result repository entry.
 boolean equals(java.lang.Object o)
          Declared explicitly in accordance with JMX specification to allow this method to be called on delegates and through agent.
 java.lang.Object executeScript(java.lang.String script)
          Execute script now, can be during computation.
 java.lang.Object getLastScriptResult()
          This attribute is set by the script executed by executeScript() after it completes.
 javax.management.ObjectName getName()
          Returns the name of this remote task, which is constructed by concatenating: "MBeans:type=" with the fully scoped class name of the remote task.
 java.lang.String getPostExecutionScript()
          Returns the BeanScript, that is executed after the computation completes but before the stop execution notifications are sent.
 java.lang.String getPostInitializactionScript()
          Returns the value set by setPostInitializationScript.
 double getProgress()
          This predefined attribute returns the value from 0 to 100, which indicates the real or assessed progres of the long-term computation performed in run().
 javax.management.AttributeList getState(boolean internal)
          Returns attribute list containing all accessible read-write attributes of this remote task, or internal data.
 int hashCode()
          Declared explicitly in accordance with JMX specification to allow this method to be called on delegates and through agent.
 void initialize()
          Invoked either manually or, if not, automatically by the executor before it attempts to switch this task into running state.
 boolean isFinished()
          Returns the value of Finished attribute.
 boolean isInitialized()
          Returns true only iff the initialize() method has successfully finished.
 boolean isReadyToRun()
          This method checks if, for this remote task, all necessary RW attributes have been set and the data provided is enough to start computation.
 boolean isRunning()
          Returns the current value of the running attribute.
 boolean isSuspended()
          Returns true iff this object is suspended.
 void setPostExecutionScript(java.lang.String postExecutionScript)
          Sets the BeanScript that will be executed after the computation completes and before stop execution notifications are sent.
 void setPostInitializationScript(java.lang.String preInitializationScript)
          Sets the BeanScript that will be invoked after the initialization is done but just before the initialization state notification is sent.
 void setRunning(boolean running)
          This method can only be invoked by the Executor to force this remote task to switch into or from the running state.
 void setSuspended(boolean suspended)
          This method can only be called by the Executor in response to the user invoking suspendRemoteTask() or resumeRemoteTask() on it.
 
Methods inherited from interface java.lang.Runnable
run
 

Method Detail

getState

public javax.management.AttributeList getState(boolean internal)
Returns attribute list containing all accessible read-write attributes of this remote task, or internal data. If the MBean is in inheritance hierarchy, this includes returning the attributes of all parents.

Parameters:
internal - if false this method returns RW attributes normally recorded by the execution notifications; if true this method returns arbitrary additional data, that can be interpreted by instances of the same class when they receive it in their copyStateFrom() method. This additional data may include computation results, read-only attributes and so on, i.e. everything necessary to reconstruct the result in a cloned remote task.
Returns:
the list of either RW attributes or internal state
See Also:
copyStateFrom(AttributeList, AttributeList)

setRunning

public void setRunning(boolean running)
This method can only be invoked by the Executor to force this remote task to switch into or from the running state. This switch is flipped as a result of invocation of startRemoteTask() or stopRemoteTask() on the executor. While running, the value of the Running attribute must be periodically checked to see if it has been changed to false, if so the computing thread must terminate gracefully.

Parameters:
running - new value of the running attribute

isRunning

public boolean isRunning()
Returns the current value of the running attribute.

Returns:
true iff the remote task is currently being executed
See Also:
setRunning(boolean)

isReadyToRun

public boolean isReadyToRun()
This method checks if, for this remote task, all necessary RW attributes have been set and the data provided is enough to start computation. The result of this method is checked by the executor before it starts this remote task or attempts to initialize it.

Returns:
true iff all necessary RW attributes have been set. This does not include cross-consistency checks, which can occur in initialize()

initialize

public void initialize()
Invoked either manually or, if not, automatically by the executor before it attempts to switch this task into running state. This method is only called after the remote task is ready-to-run. This method cross-checks attribute values and prepares data structures necessary for computation. At the end, it switches Initialize flag to true and sends attribute change notifications about this. This method raises exceptions if the initialization fails, preferrably instances of IllegalArgumentException if the failure is due to inconsistent attribute values.


isInitialized

public boolean isInitialized()
Returns true only iff the initialize() method has successfully finished. After this the remote task is ready to switch to running state.

Returns:
true iff the remote task is ready to be executed

hashCode

public int hashCode()
Declared explicitly in accordance with JMX specification to allow this method to be called on delegates and through agent.

Returns:
See javadoc in java.lang.Object.

equals

public boolean equals(java.lang.Object o)
Declared explicitly in accordance with JMX specification to allow this method to be called on delegates and through agent.

Returns:
See javadoc in java.lang.Object.

isSuspended

public boolean isSuspended()
Returns true iff this object is suspended. If suspended, the execution thread that was running the run() method is blocking at a well defined point. While suspended, intermedieate results can be obtained from this remote task without the fear of disrupting the computation or causing thread issues. When transitions between suspended and resumed state occur, driven by the user's invocations of appropriate methods on the Executor, this remote task must dispatch attribute change notifications for Suspended attribute.

Returns:
true iff this task has been suspended
See Also:
Executor

setSuspended

public void setSuspended(boolean suspended)
This method can only be called by the Executor in response to the user invoking suspendRemoteTask() or resumeRemoteTask() on it. When invoked, this method should flip the state of the remote task, which should periodically observe the changes in its execution thread and modify the behavior appropriately. State transition is announced by attribute change notification as soon as this value flips. However, the remote task must also fire execution notificaitons when the suspend or resume are detected and actually executed.

Parameters:
suspended - the new value of the suspended flag, determined by the Executor
See Also:
Executor, ExecutionNotification

getName

public javax.management.ObjectName getName()
Returns the name of this remote task, which is constructed by concatenating: "MBeans:type=" with the fully scoped class name of the remote task.

Returns:
the name of this remote task

isFinished

public boolean isFinished()
Returns the value of Finished attribute. This is announced by attribute change notification, when it changes. This value is always false initially, but changes to true after the run() method completes. There is no transition available from Finished state.

Returns:
the value of finished attribute

copyStateFrom

public boolean copyStateFrom(javax.management.AttributeList state,
                             javax.management.AttributeList internal)
This method is used to transfer serialized state from one running instance of a remote task to another. Suppose that you have extracted both the state (a collection of all RW attributes) and internal data by invoking twice getState() with different parameters. The whole state of the object is now captured in two AttributeList instances. If you create a fresh instance of the remote task of the same type, perhaps on a different machine, and if that type supports state transfers, invoke this method, provide the data and the remote task will reconstruct its internal state. If state transfer is not supported, the implementor of this method must throw an exception. Note that state transfers are serializable if they are in AttributeList forms.

Parameters:
state - a collection of RW attributes of a source
internal - a collection of arbitrary internal info of a source
Returns:
true if a fresh object has successfully transferred state
Throws:
java.lang.UnsupportedOperationException - if the object does not support state transfers

copyStateFrom

public boolean copyStateFrom(RemoteTaskInvocation rti)
Transfers state from the result repository entry. This includes reconstructing the RW attribute collection from the final state stored in the invocation data, as well as optionally opening input and output files and reinitializing internal state from saved results.

Parameters:
rti - the remote invocation data for an algorithm of the same type that has finished its execution
Returns:
true iff state transfer is successful
Throws:
java.lang.UnsupportedOperationException - if the object doesnot support state transfers

getProgress

public double getProgress()
This predefined attribute returns the value from 0 to 100, which indicates the real or assessed progres of the long-term computation performed in run(). This value should be periodically updated (say with a period of 2 seconds) and the attribute change notifications should be dispatched.

Returns:
assessment of the computation progress

getPostExecutionScript

public java.lang.String getPostExecutionScript()
Returns the BeanScript, that is executed after the computation completes but before the stop execution notifications are sent. This script can do post-execution data processing. See BeanScript information for details. Scripts can bypass Java security and can access private members of remote tasks as well. The script must implement RemoteTaskScript interface.

Returns:
the script that is going to be executed in post-execution step, or null iff there is no such script

setPostExecutionScript

public void setPostExecutionScript(java.lang.String postExecutionScript)
Sets the BeanScript that will be executed after the computation completes and before stop execution notifications are sent. The script must implement RemoteTaskScript.

Parameters:
postExecutionScript - the script to execute
See Also:
RemoteTaskScript

setPostInitializationScript

public void setPostInitializationScript(java.lang.String preInitializationScript)
Sets the BeanScript that will be invoked after the initialization is done but just before the initialization state notification is sent. This script can do modification of remote task state, and so on. The script must implement RemoteTaskScript interface.

Parameters:
preInitializationScript - the script to run, can be null
See Also:
RemoteTaskScript

getPostInitializactionScript

public java.lang.String getPostInitializactionScript()
Returns the value set by setPostInitializationScript.

Returns:
the script that will be executed after the initialization, or null iff no such script exists.

executeScript

public java.lang.Object executeScript(java.lang.String script)
Execute script now, can be during computation. If so, then the computation must be first suspended and resumed after the script executes. The script must implement RemoteTaskScriptinterface. The result of the script is returned both in the return value, as well as the LastScriptResult attribute.

Parameters:
script - the script to execute, cannot be null
Returns:
the return value of the script
See Also:
RemoteTaskScript

getLastScriptResult

public java.lang.Object getLastScriptResult()
This attribute is set by the script executed by executeScript() after it completes. Attribute change notifications for LastScriptResult must be dispatched.

Returns:
the last result of custom script