com.palantir.giraffe.command

Class Commands

java.lang.Object

com.palantir.giraffe.command.Commands

public final class Commands
extends Object

Static utility methods to create and execute commands.

In most cases, the methods defined here delegate to the associated execution system provider to perform the operations.

Method Summary

Modifier and Type	Method and Description
static CommandResult	execute(Command command) Synchronously executes a command with the default context.
static CommandResult	execute(Command command, CommandContext context) Synchronously executes a command with the specified context.
static CommandResult	execute(Command command, CommandContext context, long timeout, TimeUnit unit) Synchronously executes a command with the given context and timeout.
static CommandResult	execute(Command command, long timeout, TimeUnit timeUnit) Synchronously executes a command with the default context and the given timeout.
static CommandFuture	executeAsync(Command command) Executes a command asynchronously with the default context.
static CommandFuture	executeAsync(Command command, CommandContext context) Executes a command asynchronously with the specified context.
static Command	get(Path executable, Object... args) Gets a command for the default execution system.
static Command	get(String command, Object... args) Gets a command for the default execution system.
static Command.Builder	getBuilder(Path executable) Gets a command builder for the default execution system.
static Command.Builder	getBuilder(String command) Gets a command builder for the default execution system.
static boolean	isLocal(Command command) Determines if the given command is associated with the default (local) execution system.
static CommandResult	toResult(CommandFuture future) Creates a CommandResult from the given CommandFuture.
static CommandResult	toResult(CommandFuture future, int exitStatus) Creates a CommandResult from the given CommandFuture.
static CommandResult	waitFor(CommandFuture future) Waits for the command associated with a CommandFuture to terminate.
static CommandResult	waitFor(CommandFuture future, long timeout, TimeUnit unit) Waits for the command associated with a CommandFuture to terminate or the timeout to be reached.

Methods inherited from class java.lang.Object

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

Method Detail

get

public static Command get(String command,
                          Object... args)

Gets a command for the default execution system.

Parameters:

command - the command name

args - the optional arguments

get

public static Command get(Path executable,
                          Object... args)

Gets a command for the default execution system.

Parameters:

executable - the path to the executable

args - the optional arguments

Throws:

IllegalArgumentException - if executable is not associated with the default file system

getBuilder

public static Command.Builder getBuilder(Path executable)

Gets a command builder for the default execution system.

Parameters:

executable - the path to the executable

Throws:

IllegalArgumentException - if executable is not associated with the default file system

getBuilder

public static Command.Builder getBuilder(String command)

Gets a command builder for the default execution system.

Parameters:

command - the command name

execute

public static CommandResult execute(Command command)
                             throws IOException

Synchronously executes a command with the default context.

Parameters:

command - the command to execute

Returns:

the result of executing the command

Throws:

CommandException - if the command exits with non-zero status

IOException - if an I/O error occurs while executing the command

See Also:

execute(Command, CommandContext)

execute

public static CommandResult execute(Command command,
                                    CommandContext context)
                             throws IOException

Synchronously executes a command with the specified context.

This method blocks until the command terminates.

Parameters:

command - the command to execute

context - the CommandContext

Returns:

the result of executing the command

Throws:

CommandException - if the command exits with a status other than that specified by the CommandContext

IOException - if an I/O error occurs while executing the command

execute

public static CommandResult execute(Command command,
                                    long timeout,
                                    TimeUnit timeUnit)
                             throws IOException,
                                    CommandTimeoutException

Synchronously executes a command with the default context and the given timeout.

Parameters:

command - the command to execute

timeout - the maximum time to wait for the command to terminate

timeUnit - the unit of the timeout argument

Returns:

the result of executing the command

Throws:

CommandException - if the command exits with a non-zero status

IOException - if an I/O error occurs while executing the command

CommandTimeoutException - if the timeout is reached before the command terminates

See Also:

execute(Command, CommandContext, long, TimeUnit)

execute

public static CommandResult execute(Command command,
                                    CommandContext context,
                                    long timeout,
                                    TimeUnit unit)
                             throws IOException,
                                    CommandTimeoutException

Synchronously executes a command with the given context and timeout.

This method blocks until the command terminates or the timeout is reached. When the timeout is reached, a best-effort attempt is made to cancel the command before throwing a TimeoutException.

Parameters:

command - the command to execute

context - the CommandContext

timeout - the maximum time to wait for the command to terminate

unit - the unit of the timeout argument

Returns:

the result of executing the command

Throws:

CommandException - if the command exits with a status other than that specified by the CommandContext

IOException - if an I/O error occurs while executing the command

CommandTimeoutException - if the timeout is reached before the command terminates

executeAsync

public static CommandFuture executeAsync(Command command)

Executes a command asynchronously with the default context.

Parameters:

command - the command to execute

Returns:

a CommandFuture for the executing command

See Also:

executeAsync(Command, CommandContext)

executeAsync

public static CommandFuture executeAsync(Command command,
                                         CommandContext context)

Executes a command asynchronously with the specified context. Returns a CommandFuture that allows clients to wait for the command to finish and access input and output streams while the command is in progress.

Any errors encountered during execution are reported through the returned future. This includes CommandExceptions caused by the context's exit status check.

If a command's execution system is closed while it is executing, a best-effort attempt is made to terminate the command. If this occurs, the future reports that the command was cancelled. Clients may also cancel the command explicitly using CommandFuture.cancel(true).

Parameters:

command - the command to execute

context - the CommandContext

Returns:

a CommandFuture for the executing command

waitFor

public static CommandResult waitFor(CommandFuture future)
                             throws IOException

Waits for the command associated with a CommandFuture to terminate.

This method is uninterruptible; to allow interruption, use Future.get().

Parameters:

future - the CommandFuture to block on

Returns:

the result of executing the command

Throws:

CommandException - if the command fails by throwing a CommandException

IOException - if an I/O error occurs while executing the command or the command fails for any other reason.

waitFor

public static CommandResult waitFor(CommandFuture future,
                                    long timeout,
                                    TimeUnit unit)
                             throws IOException,
                                    TimeoutException

Waits for the command associated with a CommandFuture to terminate or the timeout to be reached. If the timeout is reached, a best-effort attempt is made to cancel the command before throwing a TimeoutException.

This method is uninterruptible; to allow interruption, use Future.get(long, TimeUnit).

Parameters:

future - the CommandFuture to block on

Returns:

the result of executing the command

Throws:

TimeoutException - if the timeout is reached before the command terminates

CommandException - if the command fails by throwing a CommandException

IOException - if an I/O error occurs while executing the command or the command fails for any other reason.

toResult

public static CommandResult toResult(CommandFuture future)
                              throws IOException

Creates a CommandResult from the given CommandFuture.

If the future is resolved, this method returns the resolved CommandResult. Otherwise, a new CommandFuture is created using the default exit status and any available output. This method never blocks.

Parameters:

future - the CommandFuture to create a result from

Returns:

a CommandResult

Throws:

IOException - if an error occurs while reading output

toResult

public static CommandResult toResult(CommandFuture future,
                                     int exitStatus)
                              throws IOException

Creates a CommandResult from the given CommandFuture.

If the future is resolved, this method returns the resolved CommandResult. Otherwise, a new CommandFuture is created using the given exit status and any available output. This method never blocks.

Parameters:

future - the CommandFuture to create a result from

exitStatus - the exit status to use if the future is unresolved

Returns:

a CommandResult

Throws:

IOException - if an error occurs while reading output

isLocal

public static boolean isLocal(Command command)

Determines if the given command is associated with the default (local) execution system.