com.cosylab.jcosyne.client
Class JMXClient

java.lang.Object
  extended bycom.cosylab.jcosyne.client.JMXClient
Direct Known Subclasses:
DirectAccess, JMXAdministratorEngine

public class JMXClient
extends java.lang.Object

This is root class for writing JMX Clients. This class contains the functionality that allows straightforward (automatic) connection to the server, a simple way to obtain a reference to the remote task and methods for controlling the remote task. Use this class to extend it and create your own JMX clients. If you want to use the client without modifying it, we suggest using DirectAccess that has the functionality of running both the local and remote JMX servers simultaneously. This class initializes the client configuration file when it is instantiated. All property keys needed by the client are enumerated in the Constants interface, see javadoc. Initialization is performed in the following sequence:

  1. If the property needed is in Java System properties, it is looked up and returned.
  2. If not found in system properties, system properties are checked if they contain the Constants.CLIENT_PROPS_FILE. If so, properties are loaded from there. If the requested property is found in this file, it is returned.
  3. If still not found, the client tries to load the property from the client property file located in the user.home + Constants.CONFIG_HOME + Constants.CLIENT_PROPS_LOCATION. If found there, the property value is returned.
  4. If not found there, the property is loaded from the JAR client property file.
  5. If not found, null is returned for the property value.
This mechanism is very flexible and allows configuration at many different levels. You should probably pick the most suitable one and stick to it - putting configuration into home directory is usually preferred, because it needs no additional switches to be set. After instantiation, you may call loadRemoteTask() and provide the full string name of the class that you wish to install on the server. After the method returns, the targetRef member variable which you can access will hold the reference to the remote MBean proxy (see JMX Documentation); this is of type Object. You may cast it to the specific MBean interface that your loaded MBean implements, and invoke methods directly on it. In addition, the target member variable will contain the ObjectName of the entity you connect to. If you need to access the server or executor, do so always by calling getServer() or getExecutor() methods, not by accessing the references directly. Use startRemoteTask() and stopRemoteTask() for basic operations on the task that you loaded. For more advanced features (suspend, resume, etc), obtain the reference to executor and invoke methods on it. This class automatically registers as a listener to the LogCollector remote task and will publish all logs, locally generated as well as collected from remote, thorugh the default handler. You are free to modify this behavior. Note that many JMXClients can be run in parallel with no conflicts, and they may each connect to a different remote task.

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

Field Summary
protected  java.util.logging.Logger log
          Reference to logger, instantiated after constructor completes.
protected  java.util.Properties props
          Client configuration file loaded as a set of name-value pairs upon construction of JMXClient instance.
protected  javax.management.ObjectName target
          After you call loadRemoteTask() this variable contains the name of the remote task that you will operate on.
protected  java.lang.Object targetRef
          After you call loadRemoteTask() this variable contains the reference to the remote task that you will operate on.
 
Constructor Summary
JMXClient()
          Creates a new instance of the client.
 
Method Summary
protected  ExecutorMBean getExecutor()
          A convenience method returning the executor field.
protected  javax.management.MBeanServerConnection getServer()
          Returns a reference to the JMX server.
protected  javax.management.MBeanServerConnection getServer(boolean quiet)
          Internal method for accessing the server.
protected  boolean isRecording()
          Returns true if result repository will be set to record all remote task executions, when connection to server is made.
 void loadRemoteTask(java.lang.String className, boolean isTarget)
          Loads remote task in the server and (optionally) sets the target--- fields.
protected  void setRecording(boolean flag)
          Changes the value of the flag on result repository, making it start or stop recording result data from the execution of remote tasks.
 void shutdown(boolean onlyLocalCleanup)
          Deregisters from the server and closes the client RMI connector.
 void startRemoteTask()
          Delegates to the executor and starts the remote task that was loaded as a target using loadRemoteTask().
 void stopRemoteTask()
          Delegates to the executor and stops the running remote task.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

props

protected java.util.Properties props
Client configuration file loaded as a set of name-value pairs upon construction of JMXClient instance. The keys and values are described in Constants interface.

See Also:
Constants

log

protected java.util.logging.Logger log
Reference to logger, instantiated after constructor completes. Use this log to create your log messages. This log will also process the log notifications received from the remote log collector task.


target

protected javax.management.ObjectName target
After you call loadRemoteTask() this variable contains the name of the remote task that you will operate on.


targetRef

protected java.lang.Object targetRef
After you call loadRemoteTask() this variable contains the reference to the remote task that you will operate on. Cast to appropriate RemoteTaskMBean subinterface to gain access to all features.

Constructor Detail

JMXClient

public JMXClient()
Creates a new instance of the client. Initializes the logger, opens the client configuration file.

Method Detail

getServer

protected javax.management.MBeanServerConnection getServer()
Returns a reference to the JMX server. If not connected, this method forces connect.

Returns:
a reference to the JMX server

getServer

protected javax.management.MBeanServerConnection getServer(boolean quiet)
Internal method for accessing the server. This method actually verifies that the server is still alive each time it is invoked, by requesting the number of live MBeans as a sort of ping functionality. If it detects an error, it tries to reconnect.

Parameters:
quiet - do not produce exception reports; used internally; if set to true this is usually to prevent expected exceptions from being printed (reconnect and similar tasks)
Returns:
a reference to the server

loadRemoteTask

public void loadRemoteTask(java.lang.String className,
                           boolean isTarget)
Loads remote task in the server and (optionally) sets the target--- fields. If not connected to the server, this method also does connection.

Parameters:
className - the name of the class to load. This class must implement RemoteTaskMBean or its subclass
isTarget - iff true, this method also sets the target and targetRef fields to contain the name and reference to the new remote task, respectively

startRemoteTask

public void startRemoteTask()
Delegates to the executor and starts the remote task that was loaded as a target using loadRemoteTask().

See Also:
Executor

stopRemoteTask

public void stopRemoteTask()
Delegates to the executor and stops the running remote task.

See Also:
Executor

shutdown

public void shutdown(boolean onlyLocalCleanup)
Deregisters from the server and closes the client RMI connector.

Parameters:
onlyLocalCleanup - used internally; if false, this method also deregisters from the server and perform other communication with the server; otherwise this method ONLY clears local state of this client

isRecording

protected boolean isRecording()
Returns true if result repository will be set to record all remote task executions, when connection to server is made.

Returns:
true iff result repository is recording results

setRecording

protected void setRecording(boolean flag)
Changes the value of the flag on result repository, making it start or stop recording result data from the execution of remote tasks. Note that there is ONE result repository running of the server. If multiple JMX clients are launched, they will modify THE SAME remote result repository through this method.

Parameters:
flag - true iff the remote result repository should record all task executions

getExecutor

protected ExecutorMBean getExecutor()
A convenience method returning the executor field. This is set once the connection to the server completes, which is at the time of first remote operation.

Returns:
a reference to executor MBean delegate