org.jlab.coda.cMsg.remoteExec

Class Commander

java.lang.Object

org.jlab.coda.cMsg.remoteExec.Commander

public class Commander
extends java.lang.Object

This class in conjunction with an Executor running on a remote host, allow its user to run any command or java thread on that Executor.

Author:

timmer Date: Oct 13, 2010

Field Summary

Fields

Modifier and Type	Field and Description
(package private) static java.lang.String	allSubjectType cMsg message subject or type used in internal Commander/Executor communication.
(package private) static java.lang.String	remoteExecSubjectType cMsg message subject or type used in internal Commander/Executor communication.

Constructor Summary

Constructors

Constructor and Description
Commander(java.lang.String udl, java.lang.String name, java.lang.String description, java.lang.String password) Create this object given parameters needed to make a connection to the cMsg server.

Method Summary

Modifier and Type	Method and Description
void	cancelCallback(CommandReturn commandReturn) Cancel a callback previously registered by calling startProcess(ExecutorInfo, String, boolean, CommandCallback , Object).
void	connectToServer(java.lang.String udl, java.lang.String name, java.lang.String description) Connect to the specified cMsg server.
void	findExecutors(int milliseconds) Find all executors currently running.
java.util.Collection<ExecutorInfo>	getExecutors() Get the collection of known Executors.
void	kill(ExecutorInfo exec, boolean killProcesses) Kill the specified executor and, optionally, all processes it has started.
void	killAll(boolean killProcesses) Kill all executors and, optionally, all processes they have started.
static void	main(java.lang.String[] args) Take keyboard input, pass as commands to one Executor, and print results - like a simple remote terminal.
static void	main0(java.lang.String[] args) Run the command "ls" inside an xterm in all Executors.
static void	main1(java.lang.String[] args) RStart up 20 xterms in one Executor, then shut them down one-by-one.
static void	main2(java.lang.String[] args) Run the ExampleThread object as a thread in a single Executor, wait 5 sec, and then shut it down.
static void	main3(java.lang.String[] args) Run a cMsg server a thread in a single Executor, wait 5 sec, and then shut it down.
static void	main4(java.lang.String[] args) Kill all Executors and their spawned processes either 1-by-1 or all at once.
boolean	reconnectToServer() Tries to connect to the last cMsg server successfully connected to.
java.util.List<CommandReturn>	startCommandInWindows(java.util.List<ExecutorInfo> executors, java.lang.String command, int widthChars, int heightChars) This method is example of how to make a bunch of identical xterm windows fill the screen in a conveniently packed manner and run a single given command in each of the xterms.
java.util.List<CommandReturn>	startCommandsInWindows(java.util.List<ExecutorInfo> executors, java.util.List<java.lang.String> commands, int widthChars, int heightChars) This method is example of how to make a bunch of identical xterm windows fill the screen in a conveniently packed manner and run a single, different command in each of the xterms.
(package private) CommandReturn	startProcess(ExecutorInfo exec, java.lang.String cmd, boolean monitor, boolean wait, CommandCallback callback, java.lang.Object userObject, int timeout) Start an external process using the specified executor.
CommandReturn	startProcess(ExecutorInfo exec, java.lang.String cmd, boolean monitor, CommandCallback callback, java.lang.Object userObject) This method is an asynchronous means of starting an external process using the specified executor.
CommandReturn	startProcess(ExecutorInfo exec, java.lang.String cmd, boolean monitor, int timeout) This method is a synchronous means of starting an external process using the specified executor and waiting for it to finish.
(package private) CommandReturn	startThread(ExecutorInfo exec, java.lang.String className, boolean wait, CommandCallback callback, java.lang.Object userObject, int timeout, ConstructorInfo constructorArgs) Starts an internal thread in the specified executor and immediately returns.
(package private) CommandReturn	startThread(ExecutorInfo exec, java.lang.String className, CommandCallback callback, java.lang.Object userObject, ConstructorInfo constructorArgs) This method is an asynchronous means of starting an internal thread in the specified executor and immediately returns.
CommandReturn	startThread(ExecutorInfo exec, java.lang.String className, int timeout, ConstructorInfo constructorArgs) This method is a synchronous means of starting an internal thread in the specified executor and waiting for it to finish.
java.util.List<CommandReturn>	startWindows(ExecutorInfo exec, java.lang.String title, int count, int widthChars, int heightChars) This method is example of how to make a bunch of identical xterm windows fill the screen in a conveniently packed manner.
CommandReturn	startXterm(ExecutorInfo exec, java.lang.String cmd, java.lang.String geometry, java.lang.String title) Start an xterm and run the specified command in it using the specified executor.
void	stop(ExecutorInfo exec, CommandReturn commandReturn) Stop the given process or thread on the specified executor.
void	stop(ExecutorInfo exec, int commandId) Stop the given process or thread on the specified executor.
void	stopAll() Stop all processes and threads on all executors.
void	stopAll(ExecutorInfo exec) Stop all processes and threads on the specified executor.
static java.util.List<java.lang.String>	xtermGeometry(int count, int widthChars, int heightChars) This method calculates the geometry specification of a given number of identical xterm windows on the local display screen in a conveniently packed manner.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

allSubjectType

static final java.lang.String allSubjectType

cMsg message subject or type used in internal Commander/Executor communication.

See Also:

Constant Field Values

remoteExecSubjectType

static final java.lang.String remoteExecSubjectType

cMsg message subject or type used in internal Commander/Executor communication.

See Also:

Constant Field Values

Constructor Detail

Commander

public Commander(java.lang.String udl,
                 java.lang.String name,
                 java.lang.String description,
                 java.lang.String password)
          throws cMsgException

Create this object given parameters needed to make a connection to the cMsg server.

Parameters:

udl - UDL to connect to cMsg server.

name - unique name used to connect to cMsg server.

password - unique string used to connect to cMsg server. It may be null but must be <= 16 characters if not null.

description - description used to connect to cMsg server.

Throws:

cMsgException - if error connecting to cMsg server; password is > 16 characters

Method Detail

reconnectToServer

public boolean reconnectToServer()
                          throws cMsgException

Tries to connect to the last cMsg server successfully connected to.

Returns:

false (nothing done) if already connected, true if a new connection is made.

Throws:

cMsgException - if cannot connect.

connectToServer

public void connectToServer(java.lang.String udl,
                            java.lang.String name,
                            java.lang.String description)
                     throws cMsgException

Connect to the specified cMsg server.

Parameters:

udl - UDL to connect to cMsg server.

name - unique name used to connect to cMsg server.

description - description used to connect to cMsg server.

Throws:

cMsgException - if cannot connect.

findExecutors

public void findExecutors(int milliseconds)
                   throws cMsgException

Find all executors currently running. Replace existing list of executors with the new one.

Parameters:

milliseconds - number of milliseconds to wait for responses from executors.

Throws:

cMsgException - if not connected to cMsg server.

getExecutors

public java.util.Collection<ExecutorInfo> getExecutors()

Get the collection of known Executors.

Returns:

collection of known Executors.

kill

public void kill(ExecutorInfo exec,
                 boolean killProcesses)
          throws cMsgException

Kill the specified executor and, optionally, all processes it has started. The executor will destroy all started processes and shutdown all started threads before exiting.

Parameters:

exec - object specifying executor.

killProcesses - false to leave spawned processes running, else true to kill them too.

Throws:

cMsgException - if no connection to cMsg server or error sending message

killAll

public void killAll(boolean killProcesses)
             throws cMsgException

Kill all executors and, optionally, all processes they have started. Each executor will destroy all started processes and shutdown all started threads before exiting.

Parameters:

killProcesses - false to leave spawned processes running, else true to kill them too.

Throws:

cMsgException - if no connection to cMsg server or error sending message

stop

public void stop(ExecutorInfo exec,
                 CommandReturn commandReturn)
          throws cMsgException

Stop the given process or thread on the specified executor. This can only be called if startProcess or startThread has returned with a CommandReturn object.

Parameters:

exec - object specifying executor.

commandReturn - object specifying process or thread to stop

Throws:

cMsgException - if no connection to cMsg server or error sending message

stop

public void stop(ExecutorInfo exec,
                 int commandId)
          throws cMsgException

Stop the given process or thread on the specified executor. This can only be called if startProcess or startThread has returned with a CommandReturn object.

Parameters:

exec - object specifying executor.

commandId - id of process or thread to stop

Throws:

cMsgException - if no connection to cMsg server or error sending message

stopAll

public void stopAll(ExecutorInfo exec)
             throws cMsgException

Stop all processes and threads on the specified executor.

Parameters:

exec - object specifying executor.

Throws:

cMsgException - if no connection to cMsg server or error sending message.

stopAll

public void stopAll()
             throws cMsgException

Stop all processes and threads on all executors.

Throws:

cMsgException - if no connection to cMsg server or error sending message.

cancelCallback

public void cancelCallback(CommandReturn commandReturn)

Cancel a callback previously registered by calling startProcess(ExecutorInfo, String, boolean, CommandCallback , Object).

Parameters:

commandReturn - object associated with callback.

startProcess

public CommandReturn startProcess(ExecutorInfo exec,
                                  java.lang.String cmd,
                                  boolean monitor,
                                  CommandCallback callback,
                                  java.lang.Object userObject)
                           throws cMsgException

This method is an asynchronous means of starting an external process using the specified executor. The executor waits 0.1 seconds for the process to finish. If the process has terminated, any output will be immediately available in the returned object if monitor is true. If the process does not terminate in that time, then the returned object will not contain that information yet, but will when it terminates. In either case, the callback is run when the process terminates, passing userObject and the updated CommandReturn object to the callback as arguments. If an error starting the process occurs, it is returned immediately (0.1 sec after process started), is visible in the returned object, and the callback is NOT run. All other errors will be available in the returned object as well when the process terminates. All errors can be seen whether or not monitor is true. Allows 2 seconds for initial return message from executor before throwing an exception.

Parameters:

exec - Executor to start process with.

cmd - command that Executor will run.

monitor - true if output of the command should be captured and returned, else false.

callback - callback to be run when process ends.

userObject - object to be passed to callback as argument.

Returns:

object containing id number and any process output captured

Throws:

cMsgException - if arg is null, cmsg sendAndGet communication fails or takes too long, or internal protocol error

startProcess

public CommandReturn startProcess(ExecutorInfo exec,
                                  java.lang.String cmd,
                                  boolean monitor,
                                  int timeout)
                           throws cMsgException,
                                  java.util.concurrent.TimeoutException

This method is a synchronous means of starting an external process using the specified executor and waiting for it to finish. All status information is available in the returned object. All errors can be seen whether or not monitor is true. If the timeout exception is thrown, the caller will no longer be able to see any results from the process.

Parameters:

exec - Executor to start process with.

cmd - command that Executor will run.

monitor - true if output of the command should be captured and returned, else false.

timeout - milliseconds to wait for reply (coming via asynchronous messaging system), 0 means wait forever.

Returns:

object containing id number and any process output captured

Throws:

cMsgException - if arg is null, cmsg communication fails, or internal protocol error

java.util.concurrent.TimeoutException - if process/thread return time exceeds timeout time.

startProcess

CommandReturn startProcess(ExecutorInfo exec,
                           java.lang.String cmd,
                           boolean monitor,
                           boolean wait,
                           CommandCallback callback,
                           java.lang.Object userObject,
                           int timeout)
                    throws cMsgException,
                           java.util.concurrent.TimeoutException

Start an external process using the specified executor. If an error starting the process occurs, it is returned immediately (0.1 sec after process started), is visible in the returned object, and the callback is NOT run. All other errors will be available in the returned object as well when the process terminates. All errors can be seen whether or not monitor is true.

Parameters:

exec - Executor to start process with.

cmd - command that Executor will run.

monitor - true if output of the command should be captured and returned, else false.

wait - true if executor waits for the process to complete before responding, else false.

callback - callback to be run when process ends.

userObject - object to be passed to callback as argument.

timeout - milliseconds to wait for reply (coming via asynchronous messaging system), 0 means wait forever.

Returns:

object containing id number and any process output captured

Throws:

cMsgException - if arg is null, cmsg communication fails, or internal protocol error

java.util.concurrent.TimeoutException - if process/thread return time exceeds timeout time.

startThread

CommandReturn startThread(ExecutorInfo exec,
                          java.lang.String className,
                          CommandCallback callback,
                          java.lang.Object userObject,
                          ConstructorInfo constructorArgs)
                   throws cMsgException

This method is an asynchronous means of starting an internal thread in the specified executor and immediately returns. It runs callback when the thread finishes, passing userObject and the updated CommandReturn object to it as arguments. Allows 2 seconds for initial return message from executor before throwing exception. If an error starting the thread occurs, it is returned immediately, is visible in the returned object and the callback is NOT run.

Parameters:

exec - Executor to start thread in.

className - name of java class to instantiate and run as thread in executor.

callback - callback to be run when thread ends.

userObject - object to be passed to callback.

constructorArgs - object containing className constructor's arguments. May be null.

Returns:

object containing executor id number and any error output

Throws:

cMsgException - if cmsg communication fails or takes too long, or internal protocol error

startThread

public CommandReturn startThread(ExecutorInfo exec,
                                 java.lang.String className,
                                 int timeout,
                                 ConstructorInfo constructorArgs)
                          throws cMsgException,
                                 java.util.concurrent.TimeoutException

This method is a synchronous means of starting an internal thread in the specified executor and waiting for it to finish. All status information is available in the returned object. If the timeout exception is thrown, the caller will no longer be able to see any results from the thread. If an error starting the thread occurs, it is returned immediately, and is visible in the returned object.

Parameters:

exec - Executor to start thread in.

className - name of java class to instantiate and run as thread in executor.

timeout - milliseconds to wait for reply (coming via asynchronous messaging system), 0 means wait forever.

constructorArgs - object containing className constructor's arguments. May be null.

Returns:

object containing executor id number and any error output

Throws:

cMsgException - if cmsg communication fails or internal protocol error

java.util.concurrent.TimeoutException - if cmsg communication times out

startThread

CommandReturn startThread(ExecutorInfo exec,
                          java.lang.String className,
                          boolean wait,
                          CommandCallback callback,
                          java.lang.Object userObject,
                          int timeout,
                          ConstructorInfo constructorArgs)
                   throws cMsgException,
                          java.util.concurrent.TimeoutException

Starts an internal thread in the specified executor and immediately returns. Allows 2 seconds for sendAndGet return message from executor before throwing exception. If an error starting the thread occurs, it is returned immediately, is visible in the returned object and the callback is NOT run.

Parameters:

exec - Executor to start thread in.

className - name of java class to instantiate and run as thread in executor.

wait - true if executor waits for the process to complete before responding, else false.

callback - callback to be run when process ends.

userObject - object to be passed to callback.

timeout - milliseconds to wait for reply (coming via asynchronous messaging system), 0 means wait forever.

constructorArgs - object containing className constructor's arguments. May be null.

Returns:

object containing executor id number and any error output

Throws:

cMsgException - if args null, cmsg communication fails, or internal protocol error

java.util.concurrent.TimeoutException - if cmsg communication times out

xtermGeometry

public static java.util.List<java.lang.String> xtermGeometry(int count,
                                                             int widthChars,
                                                             int heightChars)

This method calculates the geometry specification of a given number of identical xterm windows on the local display screen in a conveniently packed manner. The output is list of strings in the format WxH+X+Y, which can be used directly in the command to start up an xterm.

Parameters:

count - number of xterms.

widthChars - width of each xterm in characters.

heightChars - number of lines in each xterm.

Returns:

list of strings in WxH+X+Y format specifying geometry of each xterm to be displayed.

startXterm

public CommandReturn startXterm(ExecutorInfo exec,
                                java.lang.String cmd,
                                java.lang.String geometry,
                                java.lang.String title)
                         throws cMsgException

Start an xterm and run the specified command in it using the specified executor. Do not wait for it to exit. Allows 2 seconds for return message from executor before throwing exeception. Reading from xterm output blocks for some reason so no monitoring of it.

NOTE: The command to run must not have any arguments (or white space) or it will most likely fail. If the desired command needs arguments, put it in a shell script and use the script name as the command.

Parameters:

exec - Executor to start process with.

cmd - command that Executor will run inside xterm. May be null. Must not have args.

geometry - geometry info in the form WxH+-X+-Y with W and H in chars, X and Y in pixels; for example 75x10+0+200 or 75x10-10-20. May be null.

title - window title. May be null.

Returns:

object containing id number and any process output/error captured

Throws:

cMsgException - if arg is null, cmsg communication fails or takes too long, internal protocol error, or white space in cmd

startWindows

public java.util.List<CommandReturn> startWindows(ExecutorInfo exec,
                                                  java.lang.String title,
                                                  int count,
                                                  int widthChars,
                                                  int heightChars)
                                           throws cMsgException

This method is example of how to make a bunch of identical xterm windows fill the screen in a conveniently packed manner.

Parameters:

exec - Executor to use.

title - title of xterm windows.

count - number of windows to make.

widthChars - width of each xterm in characters.

heightChars - number of lines in each xterm.

Returns:

list of CommandReturn objects.

Throws:

cMsgException - when starting the xterm, if cmsg communication fails or takes too long or internal protocol error

startCommandInWindows

public java.util.List<CommandReturn> startCommandInWindows(java.util.List<ExecutorInfo> executors,
                                                           java.lang.String command,
                                                           int widthChars,
                                                           int heightChars)
                                                    throws cMsgException

This method is example of how to make a bunch of identical xterm windows fill the screen in a conveniently packed manner and run a single given command in each of the xterms.

NOTE: The command to run must not have any arguments (or white space) or it will most likely fail. If the desired command needs arguments, put it in a shell script and use the script name as the command.

Parameters:

executors - list of Executors to use.

command - command to run in each executor which must not have args.

widthChars - width of each xterm in characters.

heightChars - number of lines in each xterm.

Returns:

list of CommandReturn objects.

Throws:

cMsgException - when starting xterm, if cmsg communication fails or takes too long, internal protocol error, or white space in cmd

startCommandsInWindows

public java.util.List<CommandReturn> startCommandsInWindows(java.util.List<ExecutorInfo> executors,
                                                            java.util.List<java.lang.String> commands,
                                                            int widthChars,
                                                            int heightChars)
                                                     throws cMsgException

This method is example of how to make a bunch of identical xterm windows fill the screen in a conveniently packed manner and run a single, different command in each of the xterms.

NOTE: The commands to run must not have any arguments (or white space) or they will most likely fail. If the desired commands need arguments, put each in its own shell script and use the script name as the command.

Parameters:

executors - list of Executors to use.

commands - list of commands to run, one in each executor. Must not have args.

widthChars - width of each xterm in characters.

heightChars - number of lines in each xterm.

Returns:

list of CommandReturn objects.

Throws:

cMsgException - when starting xterm, if cmsg communication fails or takes too long, internal protocol error, or white space in cmd

main0

public static void main0(java.lang.String[] args)

Run the command "ls" inside an xterm in all Executors.

Parameters:

args - arguments.

main1

public static void main1(java.lang.String[] args)

RStart up 20 xterms in one Executor, then shut them down one-by-one.

Parameters:

args - arguments.

main2

public static void main2(java.lang.String[] args)

Run the ExampleThread object as a thread in a single Executor, wait 5 sec, and then shut it down.

Parameters:

args - arguments.

main3

public static void main3(java.lang.String[] args)

Run a cMsg server a thread in a single Executor, wait 5 sec, and then shut it down.

Parameters:

args - arguments.

main4

public static void main4(java.lang.String[] args)

Kill all Executors and their spawned processes either 1-by-1 or all at once.

Parameters:

args - arguments.

main

public static void main(java.lang.String[] args)

Take keyboard input, pass as commands to one Executor, and print results - like a simple remote terminal.

Parameters:

args - arguments.