com.sun.faban.common
Class Command

java.lang.Object
  extended by com.sun.faban.common.Command
All Implemented Interfaces:
Serializable

public class Command
extends Object
implements Serializable

Represents a command that can be sent to execute on any machine. It allows setting the command behavior before executing the command.

Author:
Akara Sucharitakul
See Also:
Serialized Form

Field Summary
static int BULK_LOG
          Bulk logging of the stdout or stderr.
static int CAPTURE
          Captures the stream in a buffer for later retrieval.
static int STDERR
          Stream identifier for standard error output.
static int STDOUT
          Stream identifier for standard output.
static String[] STREAM_NAME
          String array representing the stream names stdout and stderr.
static int TRICKLE_LOG
          Trickle logging logs the stream whenever something is read from the corresponding stream.
 
Constructor Summary
Command(List<String> command)
          Constructs a command from a pre-prepared list of command and arguments.
Command(String... command)
          Constructs a command from a string array passed in as a variable argument list.
Command(String command)
          Constructs a command from a command string with default settings.
 
Method Summary
 CommandHandle execute()
          Executes the command locally on this system.
 CommandHandle execute(CommandChecker checker, Map<String,List<String>> extMap)
          Called from the command agent allowing the agent to ensure the command will work in the agent environment.
 CommandHandle executeJava(CommandChecker checker, List<String> extClassPath)
          Called from the command agent to execute java allowing the agent to ensure the java command will work in the agent environment.
 String[] getEnvironment()
          Obtains the current environment this command is set to run.
 byte[] getInput()
          Obtains the data for the stdin of the command, if set.
 String getInputFile()
          Obtains the file name to be used as input file to the command.
 Level getLogLevel(int streamId)
          Obtains the current log level for a certain stream.
 String getOutputFile(int streamId)
          Obtains the output file name, if set.
 int getStreamHandling(int streamId)
          Obtains the stream handling mode for a certain stream associated with this command.
 String getWorkingDirectory()
          Obtains the current working directory this command is set to run.
 boolean isDaemon()
          Checks whether this command is set to be a daemon or not.
 boolean isSynchronous()
          Checks whether the command is synchronous, i.e.
static void main(String[] args)
          Main is used for testing the command facility.
static List<String> parseArgs(String command)
          Parses the command and/or arguments from a command string and puts into a list.
 void register(List<CommandHandle> handleList)
          Registers the command handle resulting from this command into a list of command handles.
 void setDaemon(boolean daemon)
          The daemon property determines whether the process spawned from this command will again spawn children that keep outputting to stdout or stderr.
 void setEnvironment(String[] env)
          Sets the environment variables in which this command should run in the form of name=value.
 void setInput(byte[] input)
          Sets the data to be sent to stdin of the command.
 void setInputFile(String filePath)
          Sets the input file for the command.
 void setLogLevel(int streamId, Level level)
          Sets the log level to log a certain stream.
 void setOutputFile(int streamId, String fileName)
          Directs the command to save the output from the stream to an output file, overwriting the output file if it already exists.
 void setOutputFile(int streamId, String fileName, boolean append)
          Directs the command to save the output from the stream to an output file.
 void setStreamHandling(int streamId, int mode)
          Sets the stream handling mode for a certain stream associated with this command.
 void setSynchronous(boolean synchronous)
          Sets this command to be synchronous.
 void setWorkingDirectory(String dir)
          Sets the working directory to run this command.
 String toString()
          Returns a string representation of this command.
 void waitMatch(int streamId, String match)
          Waits for the match string to match all or part of the corresponding stream before execute() returns.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

STDOUT

public static final int STDOUT
Stream identifier for standard output.

See Also:
Constant Field Values

STDERR

public static final int STDERR
Stream identifier for standard error output.

See Also:
Constant Field Values

STREAM_NAME

public static final String[] STREAM_NAME
String array representing the stream names stdout and stderr.


BULK_LOG

public static final int BULK_LOG
Bulk logging of the stdout or stderr. All output is saved and logged at once when the corresponding stream closes or reaches EOF.

See Also:
Constant Field Values

TRICKLE_LOG

public static final int TRICKLE_LOG
Trickle logging logs the stream whenever something is read from the corresponding stream. This causes multiple log messages to be created and is useful for detecting the timing of the message as well as correlating stdout and stderr.

See Also:
Constant Field Values

CAPTURE

public static final int CAPTURE
Captures the stream in a buffer for later retrieval. If the size of the stream output is more than 8KB, the output will automatically be written to a temporary file for later retrieval. Small output within 8KB will not cause any file I/O.

See Also:
Constant Field Values
Constructor Detail

Command

public Command(String command)
Constructs a command from a command string with default settings. Using this constructor, the command will get parsed into command and arguments, honoring double quotes and backslash escapes. While we try our best at the parsing, it may not be as accurate as constructing the command from the constructor Command(List command). Please use the accessor methods to set non-default command behavior.

Parameters:
command - The command string

Command

public Command(String... command)
Constructs a command from a string array passed in as a variable argument list.

Parameters:
command - The command and arguments

Command

public Command(List<String> command)
Constructs a command from a pre-prepared list of command and arguments.

Parameters:
command - List containing the command and arguments
Method Detail

parseArgs

public static List<String> parseArgs(String command)
Parses the command and/or arguments from a command string and puts into a list.

Parameters:
command - The command string.
Returns:
The list of commands and arguments.

toString

public String toString()
Returns a string representation of this command.

Overrides:
toString in class Object
Returns:
a string representation of the command.

execute

public CommandHandle execute(CommandChecker checker,
                             Map<String,List<String>> extMap)
                      throws IOException,
                             InterruptedException
Called from the command agent allowing the agent to ensure the command will work in the agent environment.

Parameters:
checker - The command checker
extMap - The extended command map for the service/tool, if any
Returns:
A handle to the executing command
Throws:
IOException - Error dealing with the stdin, stdout, or stderr
InterruptedException - The execute thread got interrupted.

executeJava

public CommandHandle executeJava(CommandChecker checker,
                                 List<String> extClassPath)
                          throws IOException,
                                 InterruptedException
Called from the command agent to execute java allowing the agent to ensure the java command will work in the agent environment.

Parameters:
checker - The command checker
extClassPath - The extended classpath for the service/tool, if any
Returns:
A handle to the executing command
Throws:
IOException - Error dealing with the stdin, stdout, or stderr
InterruptedException - The execute thread got interrupted.

execute

public CommandHandle execute()
                      throws IOException,
                             InterruptedException
Executes the command locally on this system. Please use CmdAgent.execute instead to execute this command in a remote location.

Returns:
A handle to the executing command
Throws:
IOException - Error dealing with the stdin, stdout, or stderr
InterruptedException - The execute thread got interrupted

setEnvironment

public void setEnvironment(String[] env)
Sets the environment variables in which this command should run in the form of name=value. Names and values are typically case sensitive. The environment set here will be combined with the environment inherited from the system in the following ways:

Parameters:
env - The shell environment relevant to this command

getEnvironment

public String[] getEnvironment()
Obtains the current environment this command is set to run. This does not return the inherited environment for this command. It may return null if the default process' environment is used.

Returns:
The current set environment, or null if not set

setWorkingDirectory

public void setWorkingDirectory(String dir)
Sets the working directory to run this command.

Parameters:
dir - The command's working directory.

getWorkingDirectory

public String getWorkingDirectory()
Obtains the current working directory this command is set to run. May return null if the parent process' working directory is used.

Returns:
The set working directory, or null if not set

setSynchronous

public void setSynchronous(boolean synchronous)
Sets this command to be synchronous. The execute() call will only return after the command has terminated. By default, a command is synchronous.

Parameters:
synchronous - True if the command shall be synchronous

isSynchronous

public boolean isSynchronous()
Checks whether the command is synchronous, i.e. the execute() call will only return after the command has terminated. By default, a command is synchronous.

Returns:
True if the command shall be synchronous, false otherwise

waitMatch

public void waitMatch(int streamId,
                      String match)
Waits for the match string to match all or part of the corresponding stream before execute() returns. If waitMatch is set, the command is implicitly set to asynchronous as we are only interested in the match.

Parameters:
streamId - The stream identifier, STDOUT or STDERR
match - The match string, null if execute shall not wait

setLogLevel

public void setLogLevel(int streamId,
                        Level level)
Sets the log level to log a certain stream. Note that the default log level is INFO for the STDOUT stream and WARNING for the STDERR stream.

Parameters:
streamId - The stream identifier, STDOUT or STDERR
level - The log level

getLogLevel

public Level getLogLevel(int streamId)
Obtains the current log level for a certain stream.

Parameters:
streamId - The stream identifier, STDOUT or STDERR
Returns:
The current log level

setStreamHandling

public void setStreamHandling(int streamId,
                              int mode)
Sets the stream handling mode for a certain stream associated with this command.

Parameters:
streamId - The stream identifier, STDOUT or STDERR
mode - The stream handling mode, BULK_LOG, TRICKLE_LOG, or CAPTURE

getStreamHandling

public int getStreamHandling(int streamId)
Obtains the stream handling mode for a certain stream associated with this command.

Parameters:
streamId - The stream identifier, STDOUT or STDERR
Returns:
The stream handling mode, BULK_LOG, TRICKLE_LOG, or CAPTURE

setOutputFile

public void setOutputFile(int streamId,
                          String fileName)
Directs the command to save the output from the stream to an output file, overwriting the output file if it already exists. Note that this option will implicitly set the stream handling mode to CAPTURE.

Parameters:
streamId - The stream identifier, STDOUT or STDERR
fileName - The target file name on the target machine

setOutputFile

public void setOutputFile(int streamId,
                          String fileName,
                          boolean append)
Directs the command to save the output from the stream to an output file. Note that this option will implicitly set the stream handling mode to CAPTURE.

Parameters:
streamId - The stream identifier, STDOUT or STDERR
fileName - The target file name on the target machine
append - Whether to append to the file or overwrite the file

getOutputFile

public String getOutputFile(int streamId)
Obtains the output file name, if set. Otherwise returns null.

Parameters:
streamId - The stream identifier, STDOUT or STDERR
Returns:
A file name, if set, or null

setInput

public void setInput(byte[] input)
Sets the data to be sent to stdin of the command.

Parameters:
input - The data buffer

getInput

public byte[] getInput()
Obtains the data for the stdin of the command, if set.

Returns:
The data buffer

setInputFile

public void setInputFile(String filePath)
Sets the input file for the command. The content of the file is sent to stdin of the process. Note that the file path pertains to the path of the file on the system the command is executed.

Parameters:
filePath - The full path of the input file.

getInputFile

public String getInputFile()
Obtains the file name to be used as input file to the command.

Returns:
The file name, if set.

register

public void register(List<CommandHandle> handleList)
Registers the command handle resulting from this command into a list of command handles. The handle list can be used to track down running commands in case they need to be terminated. This is used by Faban's CmdAgent to ensure we kill off all the commands at the end of the run.

Parameters:
handleList - The list of command handles

setDaemon

public void setDaemon(boolean daemon)
The daemon property determines whether the process spawned from this command will again spawn children that keep outputting to stdout or stderr. Such spawning behavior is common for daemons. However, daemons will unlikely keep writing to stdout or stderr. They usually manage their logging. This property is false by default and shall be falls for 99.9% of the cases. Use extreme care when changing.

Parameters:
daemon - True for spawning daemons that write to stdout/stderr

isDaemon

public boolean isDaemon()
Checks whether this command is set to be a daemon or not.

Returns:
True if this is set to be a daemon, false otherwise

main

public static void main(String[] args)
Main is used for testing the command facility. This should be moved to JUnit soon.

Parameters:
args - The command line arguments