public final class Commands extends Object
In most cases, the methods defined here delegate to the associated execution system provider to perform the operations.
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. |
public static Command get(String command, Object... args)
command
- the command nameargs
- the optional argumentspublic static Command get(Path executable, Object... args)
executable
- the path to the executableargs
- the optional argumentsIllegalArgumentException
- if executable
is not associated
with the default file systempublic static Command.Builder getBuilder(Path executable)
executable
- the path to the executableIllegalArgumentException
- if executable
is not associated
with the default file systempublic static Command.Builder getBuilder(String command)
command
- the command namepublic static CommandResult execute(Command command) throws IOException
command
- the command to executeCommandException
- if the command exits with non-zero statusIOException
- if an I/O error occurs while executing the commandexecute(Command, CommandContext)
public static CommandResult execute(Command command, CommandContext context) throws IOException
This method blocks until the command terminates.
command
- the command to executecontext
- the CommandContext
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 commandpublic static CommandResult execute(Command command, long timeout, TimeUnit timeUnit) throws IOException, CommandTimeoutException
command
- the command to executetimeout
- the maximum time to wait for the command to terminatetimeUnit
- the unit of the timeout argumentCommandException
- if the command exits with a non-zero statusIOException
- if an I/O error occurs while executing the commandCommandTimeoutException
- if the timeout is reached before the
command terminatesexecute(Command, CommandContext, long, TimeUnit)
public static CommandResult execute(Command command, CommandContext context, long timeout, TimeUnit unit) throws IOException, CommandTimeoutException
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
.
command
- the command to executecontext
- the CommandContext
timeout
- the maximum time to wait for the command to terminateunit
- the unit of the timeout argumentCommandException
- if the command exits with a status other than
that specified by the CommandContext
IOException
- if an I/O error occurs while executing the commandCommandTimeoutException
- if the timeout is reached before the
command terminatespublic static CommandFuture executeAsync(Command command)
command
- the command to executeCommandFuture
for the executing commandexecuteAsync(Command, CommandContext)
public static CommandFuture executeAsync(Command command, CommandContext context)
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 CommandException
s 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)
.
command
- the command to executecontext
- the CommandContext
CommandFuture
for the executing commandpublic static CommandResult waitFor(CommandFuture future) throws IOException
CommandFuture
to
terminate.
This method is uninterruptible; to allow interruption, use
Future.get()
.
future
- the CommandFuture
to block onCommandException
- 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.public static CommandResult waitFor(CommandFuture future, long timeout, TimeUnit unit) throws IOException, TimeoutException
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)
.
future
- the CommandFuture
to block onTimeoutException
- if the timeout is reached before the command
terminatesCommandException
- 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.public static CommandResult toResult(CommandFuture future) throws IOException
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.
future
- the CommandFuture
to create a result fromCommandResult
IOException
- if an error occurs while reading outputpublic static CommandResult toResult(CommandFuture future, int exitStatus) throws IOException
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.
future
- the CommandFuture
to create a result fromexitStatus
- the exit status to use if the future is unresolvedCommandResult
IOException
- if an error occurs while reading outputpublic static boolean isLocal(Command command)