com.sun.faban.common
Class Command

java.lang.Object
  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:

• If the variable is not already set, it will be set.
• If the variable is set, it will be replaced with these settings.
• If the value of the variable is empty, the environment will be removed if it is set. Otherwise it will not be set.

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