Package org.codehaus.plexus.util.cli

Class Commandline

java.lang.Object

org.codehaus.plexus.util.cli.Commandline

All Implemented Interfaces:

Cloneable

public class Commandline
extends Object
implements Cloneable

Commandline objects help handling command lines specifying processes to execute.

The class can be used to define a command line as nested elements or as a helper to define a command line by an application.

<someelement>
<acommandline executable="/executable/to/run">
<argument value="argument 1" />
<argument line="argument_1 argument_2 argument_3" />
<argument value="argument 4" />
</acommandline>
</someelement>


The element someelement must provide a method createAcommandline which returns an instance of this class.

Author:

thomas.haas@softwired-inc.com, Stefan Bodewig

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	Commandline.Argument
class	Commandline.Marker	Class to keep track of the position of an Argument.

Field Summary

Fields

Modifier and Type	Field	Description
protected Vector<Arg>	arguments
protected Map<String,String>	envVars
protected String	executable	Deprecated. Use setExecutable(String) instead.
protected static final String	OS_NAME	Deprecated. Use Os class instead.
protected static final String	WINDOWS	Deprecated. Use Os class instead.

Constructor Summary

Constructors

Constructor	Description
Commandline()	Create a new command line object.
Commandline(String toProcess)	Create a new command line object, given a command following POSIX sh quoting rules
Commandline(String toProcess, Shell shell)	Create a new command line object.
Commandline(Shell shell)	Create a new command line object.

Method Summary

Modifier and Type	Method	Description
void	addArg(Arg argument)
void	addArg(Arg argument, boolean insertAtStart)	Adds an argument object to our list of args.
void	addArguments(String[] line)
void	addEnvironment(String name, String value)	Add an environment variable
void	addSystemEnvironment()	Add system environment variables
void	clear()	Clear out the whole command line.
void	clearArgs()	Clear out the arguments but leave the executable in place for another operation.
Object	clone()
Arg	createArg()	Creates an argument object.
Arg	createArg(boolean insertAtStart)
Commandline.Argument	createArgument()	Deprecated. Use createArg() instead
Commandline.Argument	createArgument(boolean insertAtStart)	Deprecated. Use createArg(boolean) instead
Commandline.Marker	createMarker()	This marker can be used to locate a position on the commandline - to insert something for example - when all parameters have been set.
Process	execute()	Executes the command.
String[]	getArguments()
String[]	getCommandline()
String[]	getEnvironmentVariables()
String	getExecutable()	Return an executable name, quoted for shell use.
String	getLiteralExecutable()
long	getPid()
String[]	getRawCommandline()	Returns the executable and all defined arguments.
Shell	getShell()	Get the shell to be used in this command line.
String[]	getShellCommandline()	Returns the shell, executable and all defined arguments.
Properties	getSystemEnvVars()
File	getWorkingDirectory()
static String	quoteArgument(String argument)	Deprecated. Use CommandLineUtils.quote(String) instead.
void	setExecutable(String executable)	Sets the executable to run.
void	setPid(long pid)
void	setShell(Shell shell)	Allows to set the shell to be used in this command line.
void	setWorkingDirectory(File workingDirectory)	Sets execution directory.
void	setWorkingDirectory(String path)	Sets execution directory.
int	size()
String	toString()
static String	toString(String[] line)	Deprecated. Use CommandLineUtils.toString(String[]) instead.
static String[]	translateCommandline(String toProcess)	Deprecated. Use CommandLineUtils.translateCommandline(String) instead.

Methods inherited from class java.lang.Object

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

Field Details

OS_NAME

@Deprecated
protected static final String OS_NAME

Deprecated.

Use Os class instead.

See Also:

• Constant Field Values

WINDOWS

@Deprecated
protected static final String WINDOWS

Deprecated.

Use Os class instead.

See Also:

• Constant Field Values

arguments

protected Vector<Arg> arguments

envVars

protected Map<String,String> envVars

executable

@Deprecated
protected String executable

Deprecated.

Use setExecutable(String) instead.

Constructor Details

Commandline

public Commandline(String toProcess,
 Shell shell)

Create a new command line object. Shell is autodetected from operating system Shell usage is only desirable when generating code for remote execution.

Parameters:

toProcess - sh to process

shell - Shell to use

Commandline

public Commandline(Shell shell)

Create a new command line object. Shell is autodetected from operating system Shell usage is only desirable when generating code for remote execution.

Parameters:

shell - the Shell

Commandline

public Commandline(String toProcess)

Create a new command line object, given a command following POSIX sh quoting rules

Parameters:

toProcess - the process

Commandline

public Commandline()

Create a new command line object.

Method Details

getPid

public long getPid()

setPid

public void setPid(long pid)

createArgument

@Deprecated
public Commandline.Argument createArgument()

Deprecated.

Use createArg() instead

Creates an argument object.

Each commandline object has at most one instance of the argument class. This method calls this.createArgument(false).

Returns:

the argument object.

See Also:

• createArgument(boolean)

createArgument

@Deprecated
public Commandline.Argument createArgument(boolean insertAtStart)

Deprecated.

Use createArg(boolean) instead

Creates an argument object and adds it to our list of args.

Each commandline object has at most one instance of the argument class.

Parameters:

insertAtStart - if true, the argument is inserted at the beginning of the list of args, otherwise it is appended.

Returns:

Argument the argument Object

createArg

public Arg createArg()

Creates an argument object.

Each commandline object has at most one instance of the argument class. This method calls this.createArgument(false).

Returns:

the argument object.

See Also:

• createArgument(boolean)

createArg

public Arg createArg(boolean insertAtStart)

Parameters:

insertAtStart - if true, the argument is inserted at the beginning of the list of args, otherwise it is appended.

Returns:

Creates an argument object and adds it to our list of args.

Each commandline object has at most one instance of the argument class.

addArg

public void addArg(Arg argument)

Parameters:

argument - the argument

See Also:

• addArg(Arg,boolean)

addArg

public void addArg(Arg argument,
 boolean insertAtStart)

Adds an argument object to our list of args.

Parameters:

argument - the argument

insertAtStart - if true, the argument is inserted at the beginning of the list of args, otherwise it is appended.

setExecutable

public void setExecutable(String executable)

Sets the executable to run.

Parameters:

executable - the executable

getLiteralExecutable

public String getLiteralExecutable()

Returns:

Executable to be run, as a literal string (no shell quoting/munging)

getExecutable

public String getExecutable()

Return an executable name, quoted for shell use. Shell usage is only desirable when generating code for remote execution.

Returns:

Executable to be run, quoted for shell interpretation

addArguments

public void addArguments(String[] line)

addEnvironment

public void addEnvironment(String name,
 String value)

Add an environment variable

Parameters:

name - name

value - value

addSystemEnvironment

public void addSystemEnvironment()
                          throws Exception

Add system environment variables

Throws:

Exception - if error

getEnvironmentVariables

public String[] getEnvironmentVariables()
                                 throws CommandLineException

Returns:

String[] Return the list of environment variables

Throws:

CommandLineException - if error

getCommandline

public String[] getCommandline()

Returns:

Returns the executable and all defined arguments. For Windows Family, getShellCommandline() is returned

getRawCommandline

public String[] getRawCommandline()

Returns the executable and all defined arguments.

Returns:

the command line as array not escaped neither quoted

getShellCommandline

public String[] getShellCommandline()

Returns the shell, executable and all defined arguments. Shell usage is only desirable when generating code for remote execution.

Returns:

the command line as array

getArguments

public String[] getArguments()

Returns:

Returns all arguments defined by addLine, addValue or the argument object.

toString

public String toString()

Overrides:

toString in class Object

size

public int size()

clone

public Object clone()

Overrides:

clone in class Object

clear

public void clear()

Clear out the whole command line.

clearArgs

public void clearArgs()

Clear out the arguments but leave the executable in place for another operation.

createMarker

public Commandline.Marker createMarker()

This marker can be used to locate a position on the commandline - to insert something for example - when all parameters have been set.

Returns:

Return a marker.

setWorkingDirectory

public void setWorkingDirectory(String path)

Sets execution directory.

Parameters:

path - the working directory as String

setWorkingDirectory

public void setWorkingDirectory(File workingDirectory)

Sets execution directory.

Parameters:

workingDirectory - the File used as working directory

getWorkingDirectory

public File getWorkingDirectory()

execute

public Process execute()
                throws CommandLineException

Executes the command.

Returns:

the Process

Throws:

CommandLineException - if error

getSystemEnvVars

public Properties getSystemEnvVars()
                            throws Exception

Throws:

Exception

setShell

public void setShell(Shell shell)

Allows to set the shell to be used in this command line. Shell usage is only desirable when generating code for remote execution.

Parameters:

shell - Shell to use

Since:

1.2

getShell

public Shell getShell()

Get the shell to be used in this command line. Shell usage is only desirable when generating code for remote execution.

Returns:

the Shell

Since:

1.2

translateCommandline

@Deprecated
public static String[] translateCommandline(String toProcess)
                                     throws Exception

Deprecated.

Use CommandLineUtils.translateCommandline(String) instead.

Parameters:

toProcess - the process

Returns:

the command line arguments

Throws:

Exception - if error happen

quoteArgument

@Deprecated
public static String quoteArgument(String argument)
                            throws CommandLineException

Deprecated.

Use CommandLineUtils.quote(String) instead.

Parameters:

argument - the argument

Returns:

the quote arg

Throws:

CommandLineException - if error happen

toString

@Deprecated
public static String toString(String[] line)

Deprecated.

Use CommandLineUtils.toString(String[]) instead.

Parameters:

line - the lines

Returns:

lines as single String