org.codehaus.plexus.util.cli

Class CommandLineUtils

java.lang.Object

org.codehaus.plexus.util.cli.CommandLineUtils

public abstract class CommandLineUtils
extends Object

Version:

$Id$

Author:

Trygve Laugstøl

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
private static class	CommandLineUtils.ProcessHook
static class	CommandLineUtils.StringStreamConsumer

Constructor Summary

Constructors

Constructor and Description
CommandLineUtils()

Method Summary

Modifier and Type	Method and Description
static int	executeCommandLine(Commandline cl, InputStream systemIn, StreamConsumer systemOut, StreamConsumer systemErr, int timeoutInSeconds)
static int	executeCommandLine(Commandline cl, StreamConsumer systemOut, StreamConsumer systemErr)
static CommandLineCallable	executeCommandLineAsCallable(Commandline cl, InputStream systemIn, StreamConsumer systemOut, StreamConsumer systemErr, int timeoutInSeconds) Immediately forks a process, returns a callable that will block until process is complete.
static Properties	getSystemEnvVars() Gets the shell environment variables for this process.
static Properties	getSystemEnvVars(boolean caseSensitive) Return the shell environment variables.
static boolean	isAlive(Process p)
static String	quote(String argument) Deprecated. Use StringUtils.quoteAndEscape(String, char, char[], char[], char, boolean), StringUtils.quoteAndEscape(String, char, char[], char, boolean) or StringUtils.quoteAndEscape(String, char) instead.
static String	quote(String argument, boolean wrapExistingQuotes) Deprecated. Use StringUtils.quoteAndEscape(String, char, char[], char[], char, boolean), StringUtils.quoteAndEscape(String, char, char[], char, boolean) or StringUtils.quoteAndEscape(String, char) instead.
static String	quote(String argument, boolean escapeSingleQuotes, boolean escapeDoubleQuotes, boolean wrapExistingQuotes) Deprecated. Use StringUtils.quoteAndEscape(String, char, char[], char[], char, boolean), StringUtils.quoteAndEscape(String, char, char[], char, boolean) or StringUtils.quoteAndEscape(String, char) instead.
static String	toString(String[] line)
static String[]	translateCommandline(String toProcess)
private static void	waitForAllPumpers(StreamFeeder inputFeeder, StreamPumper outputPumper, StreamPumper errorPumper)

Methods inherited from class java.lang.Object

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

Constructor Detail

CommandLineUtils

public CommandLineUtils()

Method Detail

executeCommandLine

public static int executeCommandLine(Commandline cl,
                                     StreamConsumer systemOut,
                                     StreamConsumer systemErr)
                              throws CommandLineException

Throws:

CommandLineException - (without CommandLineTimeOutException) if

• the file expected to be the working directory does not exist or is not a directory.
• Runtime.exec(String, String[], File) fails throwing an IOException.
• an error inside systemOut parser occurs
• an error inside systemErr parser occurs

CommandLineTimeOutException - Wrapping an InterruptedException on the process to be executed thrown by Process.waitFor().

executeCommandLine

public static int executeCommandLine(Commandline cl,
                                     InputStream systemIn,
                                     StreamConsumer systemOut,
                                     StreamConsumer systemErr,
                                     int timeoutInSeconds)
                              throws CommandLineException

Parameters:

cl - The command line to execute

systemIn - The input to read from, must be thread safe

systemOut - A consumer that receives output, must be thread safe

systemErr - A consumer that receives system error stream output, must be thread safe

timeoutInSeconds - Positive integer to specify timeout, zero and negative integers for no timeout.

Returns:

A return value, see Process.exitValue()

Throws:

CommandLineException - (without CommandLineTimeOutException) if

• the file expected to be the working directory does not exist or is not a directory.
• Runtime.exec(String, String[], File) fails throwing an IOException.
• an error inside systemOut parser occurs
• an error inside systemErr parser occurs

CommandLineTimeOutException - Wrapping an InterruptedException on the process to be executed: If timeoutInSeconds<=0 thrown by Process.waitFor(). If timeoutInSeconds > 0 thrown

• by Thread.sleep(long)
• if after sleep isAlive(Process) holds.
• by waitForAllPumpers(StreamFeeder, StreamPumper, StreamPumper)

executeCommandLineAsCallable

public static CommandLineCallable executeCommandLineAsCallable(Commandline cl,
                                                               InputStream systemIn,
                                                               StreamConsumer systemOut,
                                                               StreamConsumer systemErr,
                                                               int timeoutInSeconds)
                                                        throws CommandLineException

Immediately forks a process, returns a callable that will block until process is complete.

Parameters:

cl - The command line to execute

systemIn - The input to read from, must be thread safe

systemOut - A consumer that receives output, must be thread safe

systemErr - A consumer that receives system error stream output, must be thread safe

timeoutInSeconds - Positive integer to specify timeout, zero and negative integers for no timeout.

Returns:

A CommandLineCallable that provides the process return value, see Process.exitValue(). "call" must be called on this to be sure the forked process has terminated, no guarantees is made about any internal state before after the completion of the call statements

It is documented in which cases the return value throws exceptions if CommandLineCallable.call() is executed.

Throws:

CommandLineException - or CommandLineTimeOutException: see Commandline.execute().

waitForAllPumpers

private static void waitForAllPumpers(StreamFeeder inputFeeder,
                                      StreamPumper outputPumper,
                                      StreamPumper errorPumper)
                               throws InterruptedException

Throws:

InterruptedException - if one of the parameters waitUntilDone throws such an exception.

getSystemEnvVars

public static Properties getSystemEnvVars()

Gets the shell environment variables for this process. Note that the returned mapping from variable names to values will always be case-sensitive regardless of the platform, i.e. getSystemEnvVars().get("path") and getSystemEnvVars().get("PATH") will in general return different values. However, on platforms with case-insensitive environment variables like Windows, all variable names will be normalized to upper case.

Returns:

The shell environment variables, can be empty but never null.

See Also:

System.getenv() API, new in JDK 5.0, to get the same result since 2.0.2 System#getenv() will be used if available in the current running jvm.

getSystemEnvVars

public static Properties getSystemEnvVars(boolean caseSensitive)

Return the shell environment variables. If caseSensitive == true, then envar keys will all be upper-case.

Parameters:

caseSensitive - Whether environment variable keys should be treated case-sensitively.

Returns:

Properties object of (possibly modified) envar keys mapped to their values.

See Also:

System.getenv() API, new in JDK 5.0, to get the same result since 2.0.2 System#getenv() will be used if available in the current running jvm.

isAlive

public static boolean isAlive(Process p)

translateCommandline

public static String[] translateCommandline(String toProcess)
                                     throws CommandLineException

Throws:

CommandLineException - If the quotes are not ballanced

quote

public static String quote(String argument)
                    throws CommandLineException

Deprecated. Use StringUtils.quoteAndEscape(String, char, char[], char[], char, boolean), StringUtils.quoteAndEscape(String, char, char[], char, boolean) or StringUtils.quoteAndEscape(String, char) instead.

Put quotes around the given String if necessary.

If the argument doesn't include spaces or quotes, return it as is. If it contains double quotes, use single quotes - else surround the argument by double quotes.

Throws:

CommandLineException - if the argument contains both, single and double quotes.

quote

public static String quote(String argument,
                           boolean wrapExistingQuotes)
                    throws CommandLineException

Deprecated. Use StringUtils.quoteAndEscape(String, char, char[], char[], char, boolean), StringUtils.quoteAndEscape(String, char, char[], char, boolean) or StringUtils.quoteAndEscape(String, char) instead.

Put quotes around the given String if necessary.

If the argument doesn't include spaces or quotes, return it as is. If it contains double quotes, use single quotes - else surround the argument by double quotes.

Throws:

CommandLineException - if the argument contains both, single and double quotes.

quote

public static String quote(String argument,
                           boolean escapeSingleQuotes,
                           boolean escapeDoubleQuotes,
                           boolean wrapExistingQuotes)
                    throws CommandLineException

Deprecated. Use StringUtils.quoteAndEscape(String, char, char[], char[], char, boolean), StringUtils.quoteAndEscape(String, char, char[], char, boolean) or StringUtils.quoteAndEscape(String, char) instead.

Throws:

CommandLineException

toString

public static String toString(String[] line)