com.cosylab.jcosyne.client
Class DirectAccess

java.lang.Object
  extended bycom.cosylab.jcosyne.client.JMXClient
      extended bycom.cosylab.jcosyne.client.DirectAccess

public class DirectAccess
extends JMXClient

This is a convenience extension of JMXClient that is ready for final use. DirectAccess offers parallel and consistent access to both a remotely running JMX Server and locally running JMX server. Remote server is contacted when this instance initializes, and its location is obtained from the client configuration file (hostname, port and server process name). Local server is instantiated as soon as it is needed (i.e. any method with local in its name is invoked). This class uses LocalSetup as a helper to manage the local process. The user can access one target task running remotely and one (possibly different) target task running locally. This class also offers a convenience feature to monitor the value of the remotely running attributes periodically, even if they do not support attribute change notifications, by polling. Access instances of this class through J/Link from Mathematica, if you want to import data. Due to some security restrictions, you will probably have to start the local server outside the Mathematica, for example by starting JMXAdministrator, which will create one. Note that this class is a realization of a singleton pattern. This is for convenience, but it also means that there is only one instance per JVM (in contrast to JMXClient). Watch out if you expect independent behavior of different DirectAccess "instances" - they all share the same local server, local target task and remote task. In practice, however, this is sufficient. Use this class by first calling DirectAccess.getInstance(), then install a local or remote task by calling getRemoteTask(taskName) and then you are free to operate on the remote task directly, by casting the return value into the appropriate subtype of RemoteTaskMBean interface. In parallel, you can repeat the same steps for local server, and this is completely independent from the remote part. As far as the implementation goes, this class is just a passthrough to either JMXClient, which connects to the remote server and which this class extends, or to the embedded LocalSetup that manages the local server. Note that this class is not safe against concurrent access - synchronize on your own if you need this functionality.

Author:
Gasper Tkacik (gasper.tkacik@cosylab.com)

Field Summary
 
Fields inherited from class com.cosylab.jcosyne.client.JMXClient
log, props, target, targetRef
 
Method Summary
 void addRemoteListener(java.lang.String name)
          Starts monitoring named attribute.
 void cloneIntoLocal()
          Take the current remote task and replicate it locally by transferring state.
static DirectAccess getInstance()
          Singleton accessor for the direct access instance.
 java.lang.Object getLocalTask()
          Returns a local task, parallels the getRemoteTask() method.
 java.lang.Object getLocalTask(java.lang.String className)
          Returns a local task, parallel method to getRemoteTask().
 java.lang.Object getRemoteAttribute(java.lang.String name)
          Returns the value of the attribute running on the remote task that has been loaded as target.
 java.lang.Object[] getRemoteHistory(java.lang.String name)
          Returns the remote history array collected by monitoring the remote attribute.
 java.lang.Object getRemoteTask()
          Returns the reference to the remote task.
 java.lang.Object getRemoteTask(java.lang.String className)
          If necessary, loads the named remote task, and returns a reference to it.
 void removeRemoteListener(java.lang.String name)
          Removes a monitor on a remote task attribute.
 void startLocalTask()
          Starts a local task that has been loaded with getLocalTask().
 void stopLocalTask()
          Stops the running local task or does NOP if no local task is running.
 
Methods inherited from class com.cosylab.jcosyne.client.JMXClient
getExecutor, getServer, getServer, isRecording, loadRemoteTask, setRecording, shutdown, startRemoteTask, stopRemoteTask
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

getRemoteAttribute

public java.lang.Object getRemoteAttribute(java.lang.String name)
Returns the value of the attribute running on the remote task that has been loaded as target.

Parameters:
name - the attribute name to query
Returns:
the attribute value

getRemoteTask

public java.lang.Object getRemoteTask()
Returns the reference to the remote task. You can cast this to the appropriate RemoteTaskMBean subinterface (but not to the RemoteTask subclass!).

Returns:
remote task that this access is operating on, null iff no remote task has been loaded using getRemoteTask(String)

getRemoteTask

public java.lang.Object getRemoteTask(java.lang.String className)
If necessary, loads the named remote task, and returns a reference to it. If the remote task with this name already runs on the remote server, simply obtain and return the reference. The user can cast the reference to the appropriate subinterface of RemoteTaskMBean.

Parameters:
className - the name of the remote task implementation class
Returns:
a proxy to the remote task

addRemoteListener

public void addRemoteListener(java.lang.String name)
Starts monitoring named attribute. The monitored data can be accessed through getRemoteHistory() method. This method can be invoked multiple times given different attribute names for monitoring.

Parameters:
name - the attribute name to monitor
See Also:
getRemoteHistory(java.lang.String), removeRemoteListener(java.lang.String)

removeRemoteListener

public void removeRemoteListener(java.lang.String name)
Removes a monitor on a remote task attribute. Quietly ignores if this attribute is not monitored anyway.

Parameters:
name - the attribute that will no longer be monitored

getRemoteHistory

public java.lang.Object[] getRemoteHistory(java.lang.String name)
Returns the remote history array collected by monitoring the remote attribute.

Parameters:
name - the name of the attribute for which the data will be returned; this attribute must have an active monitor, started with addRemoteListener()
Returns:
the array of history data or null iff no attribute with name is being monitored

cloneIntoLocal

public void cloneIntoLocal()
Take the current remote task and replicate it locally by transferring state.


getLocalTask

public java.lang.Object getLocalTask(java.lang.String className)
Returns a local task, parallel method to getRemoteTask(). If local server is not running, this method will start one. If requested local task is already running in the local server, a reference to it is returned; otherwise a local task is loaded into the local server.

Parameters:
className - the name of the local task to install
Returns:
a reference to the local class; the user may cast this to a subinterface of RemoteTaskMBean

getLocalTask

public java.lang.Object getLocalTask()
Returns a local task, parallels the getRemoteTask() method. The task must have been installed previously with getLocalTask(taskname).

Returns:
a proxy reference to the local task or null if the local task has not been installed yet

getInstance

public static DirectAccess getInstance()
Singleton accessor for the direct access instance. Use this to start using the DirectAccess

Returns:
instance of this class

startLocalTask

public void startLocalTask()
Starts a local task that has been loaded with getLocalTask(). Delegates to the executor.

See Also:
Executor

stopLocalTask

public void stopLocalTask()
Stops the running local task or does NOP if no local task is running. Delegates to the local executor.

See Also:
Executor