You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by gg...@apache.org on 2023/12/29 18:24:45 UTC
(commons-exec) 01/03: Javadoc and comments
This is an automated email from the ASF dual-hosted git repository.
ggregory pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-exec.git
commit b20c476df3623e4562151a13a8333a549b5587c4
Author: Gary Gregory <ga...@gmail.com>
AuthorDate: Fri Dec 29 13:10:21 2023 -0500
Javadoc and comments
---
.../java/org/apache/commons/exec/CommandLine.java | 78 +++++++++++-----------
.../org/apache/commons/exec/DaemonExecutor.java | 6 +-
.../commons/exec/DefaultExecuteResultHandler.java | 20 +++---
.../org/apache/commons/exec/DefaultExecutor.java | 54 +++++++--------
.../org/apache/commons/exec/ExecuteException.java | 16 ++---
.../apache/commons/exec/ExecuteResultHandler.java | 4 +-
.../apache/commons/exec/ExecuteStreamHandler.java | 6 +-
.../org/apache/commons/exec/ExecuteWatchdog.java | 12 ++--
.../java/org/apache/commons/exec/Executor.java | 48 ++++++-------
.../org/apache/commons/exec/InputStreamPumper.java | 8 +--
.../org/apache/commons/exec/LogOutputStream.java | 20 +++---
src/main/java/org/apache/commons/exec/OS.java | 28 ++++----
.../org/apache/commons/exec/ProcessDestroyer.java | 10 +--
.../org/apache/commons/exec/PumpStreamHandler.java | 28 ++++----
.../commons/exec/ShutdownHookProcessDestroyer.java | 28 ++++----
.../java/org/apache/commons/exec/StreamPumper.java | 20 +++---
.../java/org/apache/commons/exec/Watchdog.java | 2 +-
.../environment/DefaultProcessingEnvironment.java | 18 ++---
.../commons/exec/environment/EnvironmentUtils.java | 16 ++---
.../environment/OpenVmsProcessingEnvironment.java | 2 +-
.../commons/exec/launcher/CommandLauncher.java | 28 ++++----
.../exec/launcher/CommandLauncherFactory.java | 2 +-
.../exec/launcher/CommandLauncherProxy.java | 8 +--
.../exec/launcher/Java13CommandLauncher.java | 12 ++--
.../commons/exec/launcher/OS2CommandLauncher.java | 12 ++--
.../commons/exec/launcher/VmsCommandLauncher.java | 2 +-
.../exec/launcher/WinNTCommandLauncher.java | 11 ++-
.../org/apache/commons/exec/util/DebugUtils.java | 9 +--
.../org/apache/commons/exec/util/MapUtils.java | 28 ++++----
.../org/apache/commons/exec/util/StringUtils.java | 24 +++----
.../org/apache/commons/exec/CommandLineTest.java | 2 -
31 files changed, 278 insertions(+), 284 deletions(-)
diff --git a/src/main/java/org/apache/commons/exec/CommandLine.java b/src/main/java/org/apache/commons/exec/CommandLine.java
index 4eb8d251..2289c61f 100644
--- a/src/main/java/org/apache/commons/exec/CommandLine.java
+++ b/src/main/java/org/apache/commons/exec/CommandLine.java
@@ -57,9 +57,9 @@ public class CommandLine {
/**
* Create a command line from a string.
*
- * @param line the first element becomes the executable, the rest the arguments
- * @return the parsed command line
- * @throws IllegalArgumentException If line is null or all whitespace
+ * @param line the first element becomes the executable, the rest the arguments.
+ * @return the parsed command line.
+ * @throws IllegalArgumentException If line is null or all whitespace.
*/
public static CommandLine parse(final String line) {
return parse(line, null);
@@ -68,10 +68,10 @@ public class CommandLine {
/**
* Create a command line from a string.
*
- * @param line the first element becomes the executable, the rest the arguments
- * @param substitutionMap the name/value pairs used for substitution
- * @return the parsed command line
- * @throws IllegalArgumentException If line is null or all whitespace
+ * @param line the first element becomes the executable, the rest the arguments.
+ * @param substitutionMap the name/value pairs used for substitution.
+ * @return the parsed command line.
+ * @throws IllegalArgumentException If line is null or all whitespace.
*/
public static CommandLine parse(final String line, final Map<String, ?> substitutionMap) {
@@ -95,8 +95,8 @@ public class CommandLine {
/**
* Crack a command line.
*
- * @param toProcess the command line to process
- * @return the command line broken into strings. An empty or null toProcess parameter results in a zero sized array
+ * @param toProcess the command line to process.
+ * @return the command line broken into strings. An empty or null toProcess parameter results in a zero sized array.
*/
private static String[] translateCommandline(final String toProcess) {
if (toProcess == null || toProcess.trim().isEmpty()) {
@@ -104,7 +104,7 @@ public class CommandLine {
return new String[0];
}
- // parse with a simple finite state machine
+ // parse with a simple finite state machine.
final int normal = 0;
final int inQuote = 1;
@@ -175,19 +175,19 @@ public class CommandLine {
private final String executable;
/**
- * A map of name value pairs used to expand command line arguments
+ * A map of name value pairs used to expand command line arguments.
*/
- private Map<String, ?> substitutionMap; // N.B. This can contain values other than Strings
+ private Map<String, ?> substitutionMap; // N.B. This can contain values other than Strings.
/**
- * Was a file being used to set the executable?
+ * Tests whether a file was used to set the executable.
*/
private final boolean isFile;
/**
* Copy constructor.
*
- * @param other the instance to copy
+ * @param other the instance to copy.
*/
public CommandLine(final CommandLine other) {
this.executable = other.getExecutable();
@@ -202,7 +202,7 @@ public class CommandLine {
/**
* Create a command line without any arguments.
*
- * @param executable the executable file
+ * @param executable the executable file.
*/
public CommandLine(final File executable) {
this.isFile = true;
@@ -224,9 +224,9 @@ public class CommandLine {
/**
* Add a single argument. Handles quoting.
*
- * @param argument The argument to add
- * @return The command line itself
- * @throws IllegalArgumentException If argument contains both single and double quotes
+ * @param argument The argument to add.
+ * @return The command line itself.
+ * @throws IllegalArgumentException If argument contains both single and double quotes.
*/
public CommandLine addArgument(final String argument) {
return addArgument(argument, true);
@@ -235,9 +235,9 @@ public class CommandLine {
/**
* Add a single argument.
*
- * @param argument The argument to add
- * @param handleQuoting Add the argument with/without handling quoting
- * @return The command line itself
+ * @param argument The argument to add.
+ * @param handleQuoting Add the argument with/without handling quoting.
+ * @return The command line itself.
*/
public CommandLine addArgument(final String argument, final boolean handleQuoting) {
@@ -260,7 +260,7 @@ public class CommandLine {
* recommended to build the command line incrementally.
*
* @param addArguments An string containing multiple arguments.
- * @return The command line itself
+ * @return The command line itself.
*/
public CommandLine addArguments(final String addArguments) {
return addArguments(addArguments, true);
@@ -271,8 +271,8 @@ public class CommandLine {
* recommended to build the command line incrementally.
*
* @param addArguments An string containing multiple arguments.
- * @param handleQuoting Add the argument with/without handling quoting
- * @return The command line itself
+ * @param handleQuoting Add the argument with/without handling quoting.
+ * @return The command line itself.
*/
public CommandLine addArguments(final String addArguments, final boolean handleQuoting) {
if (addArguments != null) {
@@ -286,8 +286,8 @@ public class CommandLine {
/**
* Add multiple arguments. Handles parsing of quotes and whitespace.
*
- * @param addArguments An array of arguments
- * @return The command line itself
+ * @param addArguments An array of arguments.
+ * @return The command line itself.
*/
public CommandLine addArguments(final String[] addArguments) {
return addArguments(addArguments, true);
@@ -296,9 +296,9 @@ public class CommandLine {
/**
* Add multiple arguments.
*
- * @param addArguments An array of arguments
- * @param handleQuoting Add the argument with/without handling quoting
- * @return The command line itself
+ * @param addArguments An array of arguments.
+ * @param handleQuoting Add the argument with/without handling quoting.
+ * @return The command line itself.
*/
public CommandLine addArguments(final String[] addArguments, final boolean handleQuoting) {
if (addArguments != null) {
@@ -312,8 +312,8 @@ public class CommandLine {
/**
* Expand variables in a command line argument.
*
- * @param argument the argument
- * @return the expanded string
+ * @param argument the argument.
+ * @return the expanded string.
*/
private String expandArgument(final String argument) {
final StringBuffer stringBuffer = StringUtils.stringSubstitution(argument, getSubstitutionMap(), true);
@@ -323,7 +323,7 @@ public class CommandLine {
/**
* Returns the expanded and quoted command line arguments.
*
- * @return The quoted arguments
+ * @return The quoted arguments.
*/
public String[] getArguments() {
@@ -343,7 +343,7 @@ public class CommandLine {
/**
* Returns the executable.
*
- * @return The executable
+ * @return The executable.
*/
public String getExecutable() {
// Expand the executable and replace '/' and '\\' with the platform
@@ -353,23 +353,21 @@ public class CommandLine {
}
/**
- * @return the substitution map
+ * @return the substitution map.
*/
public Map<String, ?> getSubstitutionMap() {
return substitutionMap;
}
/**
- * Was a file being used to set the executable?
+ * Tests whether a file was used to set the executable.
*
- * @return true if a file was used for setting the executable
+ * @return true whether a file was used for setting the executable.
*/
public boolean isFile() {
return isFile;
}
- // --- Implementation ---------------------------------------------------
-
/**
* Sets the substitutionMap to expand variables in the command line.
*
@@ -399,7 +397,7 @@ public class CommandLine {
* Stringify operator returns the command line as a string. Parameters are correctly quoted when containing a space or left untouched if the are already
* quoted.
*
- * @return the command line as single string
+ * @return the command line as single string.
*/
@Override
public String toString() {
@@ -409,7 +407,7 @@ public class CommandLine {
/**
* Returns the command line as an array of strings.
*
- * @return The command line as an string array
+ * @return The command line as an string array.
*/
public String[] toStrings() {
final String[] result = new String[arguments.size() + 1];
diff --git a/src/main/java/org/apache/commons/exec/DaemonExecutor.java b/src/main/java/org/apache/commons/exec/DaemonExecutor.java
index 3d9aaced..a5217f06 100644
--- a/src/main/java/org/apache/commons/exec/DaemonExecutor.java
+++ b/src/main/java/org/apache/commons/exec/DaemonExecutor.java
@@ -26,9 +26,9 @@ public class DaemonExecutor extends DefaultExecutor {
/**
* Factory method to create a thread waiting for the result of an asynchronous execution.
*
- * @param runnable the runnable passed to the thread
- * @param name the name of the thread
- * @return the thread
+ * @param runnable the runnable passed to the thread.
+ * @param name the name of the thread.
+ * @return the thread.
*/
@Override
protected Thread createThread(final Runnable runnable, final String name) {
diff --git a/src/main/java/org/apache/commons/exec/DefaultExecuteResultHandler.java b/src/main/java/org/apache/commons/exec/DefaultExecuteResultHandler.java
index ccc3a7fc..5a1f5905 100644
--- a/src/main/java/org/apache/commons/exec/DefaultExecuteResultHandler.java
+++ b/src/main/java/org/apache/commons/exec/DefaultExecuteResultHandler.java
@@ -25,16 +25,16 @@ import java.time.Instant;
*/
public class DefaultExecuteResultHandler implements ExecuteResultHandler {
- /** The interval polling the result */
+ /** The interval polling the result. */
private static final int SLEEP_TIME_MS = 50;
- /** Keep track if the process is still running */
+ /** Keep track if the process is still running. */
private volatile boolean hasResult;
- /** The exit value of the finished process */
+ /** The exit value of the finished process. */
private volatile int exitValue;
- /** Any offending exception */
+ /** Any offending exception. */
private volatile ExecuteException exception;
/**
@@ -49,7 +49,7 @@ public class DefaultExecuteResultHandler implements ExecuteResultHandler {
* Gets the {@code exception} causing the process execution to fail.
*
* @return Returns the exception.
- * @throws IllegalStateException if the process has not exited yet
+ * @throws IllegalStateException if the process has not exited yet.
*/
public ExecuteException getException() {
if (!hasResult) {
@@ -62,7 +62,7 @@ public class DefaultExecuteResultHandler implements ExecuteResultHandler {
* Gets the {@code exitValue} of the process.
*
* @return Returns the exitValue.
- * @throws IllegalStateException if the process has not exited yet
+ * @throws IllegalStateException if the process has not exited yet.
*/
public int getExitValue() {
if (!hasResult) {
@@ -72,9 +72,9 @@ public class DefaultExecuteResultHandler implements ExecuteResultHandler {
}
/**
- * Has the process exited and a result is available, i.e. exitCode or exception?
+ * Tests whether the process exited and a result is available, i.e. exitCode or exception?
*
- * @return true if a result of the execution is available
+ * @return true whether a result of the execution is available.
*/
public boolean hasResult() {
return hasResult;
@@ -117,7 +117,7 @@ public class DefaultExecuteResultHandler implements ExecuteResultHandler {
* Causes the current thread to wait, if necessary, until the process has terminated. This method returns immediately if the process has already terminated.
* If the process has not yet terminated, the calling thread will be blocked until the process exits.
*
- * @param timeout the maximum time to wait
+ * @param timeout the maximum time to wait.
* @throws InterruptedException if the current thread is {@linkplain Thread#interrupt() interrupted} by another thread while it is waiting, then the wait is
* ended and an {@link InterruptedException} is thrown.
* @since 1.4.0
@@ -133,7 +133,7 @@ public class DefaultExecuteResultHandler implements ExecuteResultHandler {
* Causes the current thread to wait, if necessary, until the process has terminated. This method returns immediately if the process has already terminated.
* If the process has not yet terminated, the calling thread will be blocked until the process exits.
*
- * @param timeoutMillis the maximum time to wait in milliseconds
+ * @param timeoutMillis the maximum time to wait in milliseconds.
* @throws InterruptedException if the current thread is {@linkplain Thread#interrupt() interrupted} by another thread while it is waiting, then the wait is
* ended and an {@link InterruptedException} is thrown.
* @deprecated Use {@link #waitFor(Duration)}.
diff --git a/src/main/java/org/apache/commons/exec/DefaultExecutor.java b/src/main/java/org/apache/commons/exec/DefaultExecutor.java
index 11353e4e..752783d1 100644
--- a/src/main/java/org/apache/commons/exec/DefaultExecutor.java
+++ b/src/main/java/org/apache/commons/exec/DefaultExecutor.java
@@ -44,32 +44,32 @@ import java.util.Map;
*/
public class DefaultExecutor implements Executor {
- /** Taking care of output and error stream */
+ /** Taking care of output and error stream. */
private ExecuteStreamHandler streamHandler;
- /** The working directory of the process */
+ /** The working directory of the process. */
private File workingDirectory;
- /** Monitoring of long running processes */
+ /** Monitoring of long running processes. */
private ExecuteWatchdog watchdog;
- /** The exit values considered to be successful */
+ /** The exit values considered to be successful. */
private int[] exitValues;
- /** Launches the command in a new process */
+ /** Launches the command in a new process. */
private final CommandLauncher launcher;
- /** Optional cleanup of started processes */
+ /** Optional cleanup of started processes. */
private ProcessDestroyer processDestroyer;
- /** Worker thread for asynchronous execution */
+ /** Worker thread for asynchronous execution. */
private Thread executorThread;
- /** The first exception being caught to be thrown to the caller */
+ /** The first exception being caught to be thrown to the caller. */
private IOException exceptionCaught;
/**
- * Default constructor creating a default {@code PumpStreamHandler} and sets the working directory of the subprocess to the current working directory.
+ * Constructs a default {@code PumpStreamHandler} and sets the working directory of the subprocess to the current working directory.
*
* The {@code PumpStreamHandler} pumps the output of the subprocess into our {@code System.out} and {@code System.err} to avoid into our {@code System.out}
* and {@code System.err} to avoid a blocked or deadlocked subprocess (see {@link Process Process}).
@@ -83,7 +83,7 @@ public class DefaultExecutor implements Executor {
}
/**
- * Close the streams belonging to the given Process.
+ * Closes the streams belonging to the given Process.
*
* @param process the {@link Process}.
*/
@@ -109,10 +109,10 @@ public class DefaultExecutor implements Executor {
}
/**
- * Factory method to create a thread waiting for the result of an asynchronous execution.
+ * Creates a thread waiting for the result of an asynchronous execution.
*
- * @param runnable the runnable passed to the thread
- * @param name the name of the thread
+ * @param runnable the runnable passed to the thread.
+ * @param name the name of the thread.
* @return the thread
*/
protected Thread createThread(final Runnable runnable, final String name) {
@@ -181,12 +181,12 @@ public class DefaultExecutor implements Executor {
/**
* Execute an internal process. If the executing thread is interrupted while waiting for the child process to return the child process will be killed.
*
- * @param command the command to execute
- * @param environment the execution environment
- * @param dir the working directory
- * @param streams process the streams (in, out, err) of the process
- * @return the exit code of the process
- * @throws IOException executing the process failed
+ * @param command the command to execute.
+ * @param environment the execution environment.
+ * @param dir the working directory.
+ * @param streams process the streams (in, out, err) of the process.
+ * @return the exit code of the process.
+ * @throws IOException executing the process failed.
*/
private int executeInternal(final CommandLine command, final Map<String, String> environment, final File dir, final ExecuteStreamHandler streams)
throws IOException {
@@ -288,7 +288,7 @@ public class DefaultExecutor implements Executor {
/**
* Gets the first IOException being thrown.
*
- * @return the first IOException being caught
+ * @return the first IOException being caught.
*/
private IOException getExceptionCaught() {
return this.exceptionCaught;
@@ -297,7 +297,7 @@ public class DefaultExecutor implements Executor {
/**
* Gets the worker thread being used for asynchronous execution.
*
- * @return the worker thread
+ * @return the worker thread.
*/
protected Thread getExecutorThread() {
return executorThread;
@@ -356,11 +356,11 @@ public class DefaultExecutor implements Executor {
/**
* Creates a process that runs a command.
*
- * @param command the command to run
- * @param env the environment for the command
- * @param dir the working directory for the command
- * @return the process started
- * @throws IOException forwarded from the particular launcher used
+ * @param command the command to run.
+ * @param env the environment for the command.
+ * @param dir the working directory for the command.
+ * @return the process started.
+ * @throws IOException forwarded from the particular launcher used.
*/
protected Process launch(final CommandLine command, final Map<String, String> env, final File dir) throws IOException {
@@ -377,7 +377,7 @@ public class DefaultExecutor implements Executor {
/**
* Keep track of the first IOException being thrown.
*
- * @param e the IOException
+ * @param e the IOException.
*/
private void setExceptionCaught(final IOException e) {
if (this.exceptionCaught == null) {
diff --git a/src/main/java/org/apache/commons/exec/ExecuteException.java b/src/main/java/org/apache/commons/exec/ExecuteException.java
index 68331818..a0350175 100644
--- a/src/main/java/org/apache/commons/exec/ExecuteException.java
+++ b/src/main/java/org/apache/commons/exec/ExecuteException.java
@@ -30,15 +30,15 @@ public class ExecuteException extends IOException {
private static final long serialVersionUID = 3256443620654331699L;
/**
- * The exit value returned by the failed process
+ * The exit value returned by the failed process.
*/
private final int exitValue;
/**
* Constructs a new exception with the specified detail message.
*
- * @param message The detail message
- * @param exitValue The exit value
+ * @param message The detail message.
+ * @param exitValue The exit value.
*/
public ExecuteException(final String message, final int exitValue) {
super(message + " (Exit value: " + exitValue + ")");
@@ -48,9 +48,9 @@ public class ExecuteException extends IOException {
/**
* Constructs a new exception with the specified detail message and cause.
*
- * @param message The detail message
- * @param exitValue The exit value
- * @param cause The underlying cause
+ * @param message The detail message.
+ * @param exitValue The exit value.
+ * @param cause The underlying cause.
*/
public ExecuteException(final String message, final int exitValue, final Throwable cause) {
super(message + " (Exit value: " + exitValue + ")", cause);
@@ -58,9 +58,9 @@ public class ExecuteException extends IOException {
}
/**
- * Gets the exit value returned by the failed process
+ * Gets the exit value returned by the failed process.
*
- * @return The exit value
+ * @return The exit value.
*/
public int getExitValue() {
return exitValue;
diff --git a/src/main/java/org/apache/commons/exec/ExecuteResultHandler.java b/src/main/java/org/apache/commons/exec/ExecuteResultHandler.java
index 381810c1..7f790322 100644
--- a/src/main/java/org/apache/commons/exec/ExecuteResultHandler.java
+++ b/src/main/java/org/apache/commons/exec/ExecuteResultHandler.java
@@ -28,14 +28,14 @@ public interface ExecuteResultHandler {
/**
* The asynchronous execution completed.
*
- * @param exitValue the exit value of the sub-process
+ * @param exitValue the exit value of the sub-process.
*/
void onProcessComplete(int exitValue);
/**
* The asynchronous execution failed.
*
- * @param e the {@code ExecuteException} containing the root cause
+ * @param e the {@code ExecuteException} containing the root cause.
*/
void onProcessFailed(ExecuteException e);
}
diff --git a/src/main/java/org/apache/commons/exec/ExecuteStreamHandler.java b/src/main/java/org/apache/commons/exec/ExecuteStreamHandler.java
index dfff18d5..00334cd2 100644
--- a/src/main/java/org/apache/commons/exec/ExecuteStreamHandler.java
+++ b/src/main/java/org/apache/commons/exec/ExecuteStreamHandler.java
@@ -29,7 +29,7 @@ public interface ExecuteStreamHandler {
/**
* Install a handler for the error stream of the subprocess.
*
- * @param is input stream to read from the error stream from the subprocess
+ * @param is input stream to read from the error stream from the subprocess.
* @throws IOException thrown when an I/O exception occurs.
*/
void setProcessErrorStream(InputStream is) throws IOException;
@@ -37,7 +37,7 @@ public interface ExecuteStreamHandler {
/**
* Install a handler for the input stream of the subprocess.
*
- * @param os output stream to write to the standard input stream of the subprocess
+ * @param os output stream to write to the standard input stream of the subprocess.
* @throws IOException thrown when an I/O exception occurs.
*/
void setProcessInputStream(OutputStream os) throws IOException;
@@ -45,7 +45,7 @@ public interface ExecuteStreamHandler {
/**
* Install a handler for the output stream of the subprocess.
*
- * @param is input stream to read from the error stream from the subprocess
+ * @param is input stream to read from the error stream from the subprocess.
* @throws IOException thrown when an I/O exception occurs.
*/
void setProcessOutputStream(InputStream is) throws IOException;
diff --git a/src/main/java/org/apache/commons/exec/ExecuteWatchdog.java b/src/main/java/org/apache/commons/exec/ExecuteWatchdog.java
index 9792b872..a6968952 100644
--- a/src/main/java/org/apache/commons/exec/ExecuteWatchdog.java
+++ b/src/main/java/org/apache/commons/exec/ExecuteWatchdog.java
@@ -47,16 +47,16 @@ import org.apache.commons.exec.util.DebugUtils;
*/
public class ExecuteWatchdog implements TimeoutObserver {
- /** The marker for an infinite timeout */
+ /** The marker for an infinite timeout. */
public static final long INFINITE_TIMEOUT = -1;
- /** The marker for an infinite timeout */
+ /** The marker for an infinite timeout. */
public static final Duration INFINITE_TIMEOUT_DURATION = Duration.ofMillis(INFINITE_TIMEOUT);
/** The process to execute and watch for duration. */
private Process process;
- /** Is a user-supplied timeout in use */
+ /** Is a user-supplied timeout in use. */
private final boolean hasWatchdog;
/** Say whether or not the watchdog is currently monitoring a process. */
@@ -135,7 +135,7 @@ public class ExecuteWatchdog implements TimeoutObserver {
/**
* Ensures that the process is started or not already terminated so we do not race with asynch executionor hang forever. The caller of this method must be
- * holding the lock on this
+ * holding the lock on this.
*/
private void ensureStarted() {
while (!processStarted && caught == null) {
@@ -150,7 +150,7 @@ public class ExecuteWatchdog implements TimeoutObserver {
/**
* Notification that starting the process failed.
*
- * @param e the offending exception
+ * @param e the offending exception.
*
*/
public synchronized void failedToStart(final Exception e) {
@@ -185,7 +185,7 @@ public class ExecuteWatchdog implements TimeoutObserver {
/**
* Watches the given process and terminates it, if it runs for too long. All information from the previous run are reset.
*
- * @param processToMonitor the process to monitor. It cannot be {@code null}
+ * @param processToMonitor the process to monitor. It cannot be {@code null}.
* @throws IllegalStateException if a process is still being monitored.
*/
public synchronized void start(final Process processToMonitor) {
diff --git a/src/main/java/org/apache/commons/exec/Executor.java b/src/main/java/org/apache/commons/exec/Executor.java
index 42cdaa00..c84c3ddd 100644
--- a/src/main/java/org/apache/commons/exec/Executor.java
+++ b/src/main/java/org/apache/commons/exec/Executor.java
@@ -51,8 +51,8 @@ public interface Executor {
/**
* Executes a command synchronously. The child process inherits all environment variables of the parent process.
*
- * @param command the command to execute
- * @return process exit value
+ * @param command the command to execute.
+ * @return process exit value.
* @throws ExecuteException execution of subprocess failed or the subprocess returned a exit value indicating a failure {@link Executor#setExitValue(int)}.
* @throws IOException If an I/O error occurs.
*/
@@ -62,9 +62,9 @@ public interface Executor {
* Executes a command asynchronously. The child process inherits all environment variables of the parent process. Result provided to callback
* handler.
*
- * @param command the command to execute
- * @param handler capture process termination and exit code
- * @throws ExecuteException execution of subprocess failed
+ * @param command the command to execute.
+ * @param handler capture process termination and exit code.
+ * @throws ExecuteException execution of subprocess failed.
* @throws IOException If an I/O error occurs.
*/
void execute(CommandLine command, ExecuteResultHandler handler) throws ExecuteException, IOException;
@@ -72,9 +72,9 @@ public interface Executor {
/**
* Executes a command synchronously.
*
- * @param command the command to execute
+ * @param command the command to execute.
* @param environment The environment for the new process. If null, the environment of the current process is used.
- * @return process exit value
+ * @return process exit value.
* @throws ExecuteException execution of subprocess failed or the subprocess returned a exit value indicating a failure {@link Executor#setExitValue(int)}.
* @throws IOException If an I/O error occurs.
*/
@@ -84,10 +84,10 @@ public interface Executor {
* Executes a command asynchronously. The child process inherits all environment variables of the parent process. Result provided to callback
* handler.
*
- * @param command the command to execute
+ * @param command the command to execute.
* @param environment The environment for the new process. If null, the environment of the current process is used.
- * @param handler capture process termination and exit code
- * @throws ExecuteException execution of subprocess failed
+ * @param handler capture process termination and exit code.
+ * @throws ExecuteException execution of subprocess failed.
* @throws IOException If an I/O error occurs.
*/
void execute(CommandLine command, Map<String, String> environment, ExecuteResultHandler handler) throws ExecuteException, IOException;
@@ -95,28 +95,28 @@ public interface Executor {
/**
* Sets the handler for cleanup of started processes if the main process is going to terminate.
*
- * @return the ProcessDestroyer
+ * @return the ProcessDestroyer.
*/
ProcessDestroyer getProcessDestroyer();
/**
* Gets the StreamHandler used for providing input and retrieving the output.
*
- * @return the StreamHandler
+ * @return the StreamHandler.
*/
ExecuteStreamHandler getStreamHandler();
/**
* Gets the watchdog used to kill of processes running, typically, too long time.
*
- * @return the watchdog
+ * @return the watchdog.
*/
ExecuteWatchdog getWatchdog();
/**
* Gets the working directory of the created process.
*
- * @return the working directory
+ * @return the working directory.
*/
File getWorkingDirectory();
@@ -124,21 +124,21 @@ public interface Executor {
* Tests whether {@code exitValue} signals a failure. If no exit values are set than the default conventions of the OS is used. e.g. most OS regard an exit
* code of '0' as successful execution and everything else as failure.
*
- * @param exitValue the exit value (return code) to be checked
- * @return {@code true} if {@code exitValue} signals a failure
+ * @param exitValue the exit value (return code) to be checked.
+ * @return {@code true} if {@code exitValue} signals a failure.
*/
boolean isFailure(final int exitValue);
/**
* Sets the {@code exitValue} of the process to be considered successful. If a different exit value is returned by the process then
- * {@link org.apache.commons.exec.Executor#execute(CommandLine)} will throw an {@link org.apache.commons.exec.ExecuteException}
+ * {@link org.apache.commons.exec.Executor#execute(CommandLine)} will throw an {@link org.apache.commons.exec.ExecuteException}.
*
- * @param value the exit code representing successful execution
+ * @param value the exit code representing successful execution.
*/
void setExitValue(final int value);
/**
- * Sets a list of {@code exitValue} of the process to be considered successful. The caller can pass one of the following values
+ * Sets a list of {@code exitValue} of the process to be considered successful. The caller can pass one of the following values.
* <ul>
* <li>an array of exit values to be considered successful</li>
* <li>an empty array for auto-detect of successful exit codes relying on {@link org.apache.commons.exec.Executor#isFailure(int)}</li>
@@ -148,14 +148,14 @@ public interface Executor {
* If an undefined exit value is returned by the process then {@link org.apache.commons.exec.Executor#execute(CommandLine)} will throw an
* {@link org.apache.commons.exec.ExecuteException}.
*
- * @param values a list of the exit codes
+ * @param values a list of the exit codes.
*/
void setExitValues(final int[] values);
/**
* Sets the handler for cleanup of started processes if the main process is going to terminate.
*
- * @param processDestroyer the ProcessDestroyer
+ * @param processDestroyer the ProcessDestroyer.
*/
void setProcessDestroyer(ProcessDestroyer processDestroyer);
@@ -163,21 +163,21 @@ public interface Executor {
* Sets a custom the StreamHandler used for providing input and retrieving the output. If you don't provide a proper stream handler the executed process
* might block when writing to stdout and/or stderr (see {@link Process Process}).
*
- * @param streamHandler the stream handler
+ * @param streamHandler the stream handler.
*/
void setStreamHandler(ExecuteStreamHandler streamHandler);
/**
* Sets the watchdog used to kill of processes running, typically, too long time.
*
- * @param watchDog the watchdog
+ * @param watchDog the watchdog.
*/
void setWatchdog(ExecuteWatchdog watchDog);
/**
* Sets the working directory of the created process. The working directory must exist when you start the process.
*
- * @param dir the working directory
+ * @param dir the working directory.
*/
void setWorkingDirectory(File dir);
}
diff --git a/src/main/java/org/apache/commons/exec/InputStreamPumper.java b/src/main/java/org/apache/commons/exec/InputStreamPumper.java
index 94a81af1..011924ce 100644
--- a/src/main/java/org/apache/commons/exec/InputStreamPumper.java
+++ b/src/main/java/org/apache/commons/exec/InputStreamPumper.java
@@ -29,19 +29,19 @@ public class InputStreamPumper implements Runnable {
public static final int SLEEPING_TIME = 100;
- /** The input stream to pump from */
+ /** The input stream to pump from. */
private final InputStream is;
- /** The output stream to pmp into */
+ /** The output stream to pmp into. */
private final OutputStream os;
- /** Flag to stop the stream pumping */
+ /** Flag to stop the stream pumping. */
private volatile boolean stop;
/**
* Create a new stream pumper.
*
- * @param is input stream to read data from
+ * @param is input stream to read data from.
* @param os output stream to write data to.
*/
public InputStreamPumper(final InputStream is, final OutputStream os) {
diff --git a/src/main/java/org/apache/commons/exec/LogOutputStream.java b/src/main/java/org/apache/commons/exec/LogOutputStream.java
index 58c09724..0a9f0009 100644
--- a/src/main/java/org/apache/commons/exec/LogOutputStream.java
+++ b/src/main/java/org/apache/commons/exec/LogOutputStream.java
@@ -41,13 +41,13 @@ public abstract class LogOutputStream extends OutputStream {
/** Initial buffer size. */
private static final int INTIAL_SIZE = 132;
- /** Carriage return */
+ /** Carriage return. */
private static final int CR = 0x0d;
- /** Linefeed */
+ /** Line-feed. */
private static final int LF = 0x0a;
- /** The internal buffer */
+ /** The internal buffer. */
private final ByteArrayOutputStreamX buffer = new ByteArrayOutputStreamX(INTIAL_SIZE);
private boolean skip;
@@ -75,8 +75,8 @@ public abstract class LogOutputStream extends OutputStream {
/**
* Creates a new instance of this class, specifying the character set that should be used for outputting the string for each line
*
- * @param level level used to log data written to this stream
- * @param charset Character Set to use when processing lines
+ * @param level level used to log data written to this stream.
+ * @param charset Character Set to use when processing lines.
*/
public LogOutputStream(final int level, final Charset charset) {
this.level = level;
@@ -109,7 +109,7 @@ public abstract class LogOutputStream extends OutputStream {
}
/**
- * @return the trace level of the log system
+ * @return the trace level of the log system.
*/
public int getMessageLevel() {
return level;
@@ -141,11 +141,11 @@ public abstract class LogOutputStream extends OutputStream {
protected abstract void processLine(final String line, final int logLevel);
/**
- * Write a block of characters to the output stream
+ * Write a block of characters to the output stream.
*
- * @param b the array containing the data
- * @param off the offset into the array where data starts
- * @param len the length of block
+ * @param b the array containing the data.
+ * @param off the offset into the array where data starts.
+ * @param len the length of block.
* @throws IOException if the data cannot be written into the stream.
* @see java.io.OutputStream#write(byte[], int, int)
*/
diff --git a/src/main/java/org/apache/commons/exec/OS.java b/src/main/java/org/apache/commons/exec/OS.java
index f288999b..f0196c11 100644
--- a/src/main/java/org/apache/commons/exec/OS.java
+++ b/src/main/java/org/apache/commons/exec/OS.java
@@ -85,8 +85,8 @@ public final class OS {
/**
* Determines if the OS on which commons-exec is executing matches the given OS architecture.
*
- * @param arch the OS architecture to check for
- * @return true if the OS matches
+ * @param arch the OS architecture to check for.
+ * @return true if the OS matches.
*/
public static boolean isArch(final String arch) {
return isOs(null, null, arch, null);
@@ -95,8 +95,8 @@ public final class OS {
/**
* Determines if the OS on which commons-exec is executing matches the given OS family.
*
- * @param family the family to check for
- * @return true if the OS matches
+ * @param family the family to check for.
+ * @return true if the OS matches.
*/
private static boolean isFamily(final String family) {
return isOs(family, null, null, null);
@@ -153,8 +153,8 @@ public final class OS {
/**
* Determines if the OS on which commons-exec is executing matches the given OS name.
*
- * @param name the OS name to check for
- * @return true if the OS matches
+ * @param name the OS name to check for.
+ * @return true if the OS matches.
*/
public static boolean isName(final String name) {
return isOs(null, name, null, null);
@@ -163,11 +163,11 @@ public final class OS {
/**
* Determines if the OS on which commons-exec is executing matches the given OS family, name, architecture and version.
*
- * @param family The OS family
- * @param name The OS name
- * @param arch The OS architecture
- * @param version The OS version
- * @return true if the OS matches
+ * @param family The OS family.
+ * @param name The OS name.
+ * @param arch The OS architecture.
+ * @param version The OS version.
+ * @return true if the OS matches.
*/
public static boolean isOs(final String family, final String name, final String arch, final String version) {
boolean retValue = false;
@@ -238,15 +238,15 @@ public final class OS {
/**
* Determines if the OS on which commonss-exec is executing matches the given OS version.
*
- * @param version the OS version to check for
- * @return true if the OS matches
+ * @param version the OS version to check for.
+ * @return true if the OS matches.
*/
public static boolean isVersion(final String version) {
return isOs(null, null, null, version);
}
/**
- * Default constructor
+ * Avoids instances.
*/
private OS() {
}
diff --git a/src/main/java/org/apache/commons/exec/ProcessDestroyer.java b/src/main/java/org/apache/commons/exec/ProcessDestroyer.java
index 1277bf92..87ae9f92 100644
--- a/src/main/java/org/apache/commons/exec/ProcessDestroyer.java
+++ b/src/main/java/org/apache/commons/exec/ProcessDestroyer.java
@@ -27,23 +27,23 @@ public interface ProcessDestroyer {
/**
* Returns {@code true} if the specified {@link Process} was successfully added to the list of processes to be destroy.
*
- * @param process the process to add
- * @return {@code true} if the specified {@link Process} was successfully added
+ * @param process the process to add.
+ * @return {@code true} if the specified {@link Process} was successfully added.
*/
boolean add(Process process);
/**
* Returns {@code true} if the specified {@link Process} was successfully removed from the list of processes to be destroy.
*
- * @param process the process to remove
- * @return {@code true} if the specified {@link Process} was successfully removed
+ * @param process the process to remove.
+ * @return {@code true} if the specified {@link Process} was successfully removed.
*/
boolean remove(Process process);
/**
* Returns the number of registered processes.
*
- * @return the number of register process
+ * @return the number of register process.
*/
int size();
}
diff --git a/src/main/java/org/apache/commons/exec/PumpStreamHandler.java b/src/main/java/org/apache/commons/exec/PumpStreamHandler.java
index 4e97d82c..3141e3d5 100644
--- a/src/main/java/org/apache/commons/exec/PumpStreamHandler.java
+++ b/src/main/java/org/apache/commons/exec/PumpStreamHandler.java
@@ -46,10 +46,10 @@ public class PumpStreamHandler implements ExecuteStreamHandler {
private InputStreamPumper inputStreamPumper;
- /** The timeout in milliseconds the implementation waits when stopping the pumper threads */
+ /** The timeout in milliseconds the implementation waits when stopping the pumper threads. */
private long stopTimeout;
- /** The last exception being caught */
+ /** The last exception being caught. */
private IOException caught;
/**
@@ -115,9 +115,9 @@ public class PumpStreamHandler implements ExecuteStreamHandler {
* Creates a stream pumper to copy the given input stream to the given output stream. When the 'os' is an PipedOutputStream we are closing 'os' afterwards
* to avoid an IOException ("Write end dead").
*
- * @param is the input stream to copy from
- * @param os the output stream to copy into
- * @return the stream pumper thread
+ * @param is the input stream to copy from.
+ * @param os the output stream to copy into.
+ * @return the stream pumper thread.
*/
protected Thread createPump(final InputStream is, final OutputStream os) {
return createPump(is, os, os instanceof PipedOutputStream);
@@ -126,10 +126,10 @@ public class PumpStreamHandler implements ExecuteStreamHandler {
/**
* Creates a stream pumper to copy the given input stream to the given output stream.
*
- * @param is the input stream to copy from
- * @param os the output stream to copy into
- * @param closeWhenExhausted close the output stream when the input stream is exhausted
- * @return the stream pumper thread
+ * @param is the input stream to copy from.
+ * @param os the output stream to copy into.
+ * @param closeWhenExhausted close the output stream when the input stream is exhausted.
+ * @return the stream pumper thread.
*/
protected Thread createPump(final InputStream is, final OutputStream os, final boolean closeWhenExhausted) {
final Thread result = new Thread(new StreamPumper(is, os, closeWhenExhausted), "Exec Stream Pumper");
@@ -140,9 +140,9 @@ public class PumpStreamHandler implements ExecuteStreamHandler {
/**
* Creates a stream pumper to copy the given input stream to the given output stream.
*
- * @param is the System.in input stream to copy from
- * @param os the output stream to copy into
- * @return the stream pumper thread
+ * @param is the System.in input stream to copy from.
+ * @param os the output stream to copy into.
+ * @return the stream pumper thread.
*/
private Thread createSystemInPump(final InputStream is, final OutputStream os) {
inputStreamPumper = new InputStreamPumper(is, os);
@@ -282,8 +282,8 @@ public class PumpStreamHandler implements ExecuteStreamHandler {
* Stops a pumper thread. The implementation actually waits longer than specified in 'timeout' to detect if the timeout was indeed exceeded. If the
* timeout was exceeded an IOException is created to be thrown to the caller.
*
- * @param thread the thread to be stopped
- * @param timeoutMillis the time in ms to wait to join
+ * @param thread the thread to be stopped.
+ * @param timeoutMillis the time in ms to wait to join.
*/
protected void stopThread(final Thread thread, final long timeoutMillis) {
diff --git a/src/main/java/org/apache/commons/exec/ShutdownHookProcessDestroyer.java b/src/main/java/org/apache/commons/exec/ShutdownHookProcessDestroyer.java
index 05fb929a..db432140 100644
--- a/src/main/java/org/apache/commons/exec/ShutdownHookProcessDestroyer.java
+++ b/src/main/java/org/apache/commons/exec/ShutdownHookProcessDestroyer.java
@@ -45,17 +45,17 @@ public class ShutdownHookProcessDestroyer implements ProcessDestroyer, Runnable
}
}
- /** The list of currently running processes */
+ /** The list of currently running processes. */
private final Vector<Process> processes = new Vector<>();
- /** The thread registered at the JVM to execute the shutdown handler */
+ /** The thread registered at the JVM to execute the shutdown handler. */
private ProcessDestroyerImpl destroyProcessThread;
- /** Whether or not this ProcessDestroyer has been registered as a shutdown hook */
+ /** Whether or not this ProcessDestroyer has been registered as a shutdown hook. */
private boolean added;
/**
- * Whether or not this ProcessDestroyer is currently running as shutdown hook
+ * Whether or not this ProcessDestroyer is currently running as shutdown hook.
*/
private volatile boolean running = false;
@@ -71,8 +71,8 @@ public class ShutdownHookProcessDestroyer implements ProcessDestroyer, Runnable
/**
* Returns {@code true} if the specified {@code Process} was successfully added to the list of processes to destroy upon VM exit.
*
- * @param process the process to add
- * @return {@code true} if the specified {@code Process} was successfully added
+ * @param process the process to add.
+ * @return {@code true} if the specified {@code Process} was successfully added.
*/
@Override
public boolean add(final Process process) {
@@ -98,9 +98,9 @@ public class ShutdownHookProcessDestroyer implements ProcessDestroyer, Runnable
}
/**
- * Tests whether or not the ProcessDestroyer is registered as shutdown hook
+ * Tests whether or not the ProcessDestroyer is registered as shutdown hook.
*
- * @return true if this is currently added as shutdown hook
+ * @return true if this is currently added as shutdown hook.
*/
public boolean isAddedAsShutdownHook() {
return added;
@@ -119,8 +119,8 @@ public class ShutdownHookProcessDestroyer implements ProcessDestroyer, Runnable
/**
* Returns {@code true} if the specified {@code Process} was successfully removed from the list of processes to destroy upon VM exit.
*
- * @param process the process to remove
- * @return {@code true} if the specified {@code Process} was successfully removed
+ * @param process the process to remove.
+ * @return {@code true} if the specified {@code Process} was successfully removed.
*/
@Override
public boolean remove(final Process process) {
@@ -142,10 +142,8 @@ public class ShutdownHookProcessDestroyer implements ProcessDestroyer, Runnable
if (!removed) {
System.err.println("Could not remove shutdown hook");
}
- /*
- * start the hook thread, a unstarted thread may not be eligible for garbage collection Cf.: http://developer.java.sun.com/developer/
- * bugParade/bugs/4533087.html
- */
+ // start the hook thread, a unstarted thread may not be eligible for garbage collection Cf.: http://developer.java.sun.com/developer/
+ // bugParade/bugs/4533087.html
destroyProcessThread.setShouldDestroy(false);
destroyProcessThread.start();
@@ -183,7 +181,7 @@ public class ShutdownHookProcessDestroyer implements ProcessDestroyer, Runnable
/**
* Returns the number of registered processes.
*
- * @return the number of register process
+ * @return the number of register process.
*/
@Override
public int size() {
diff --git a/src/main/java/org/apache/commons/exec/StreamPumper.java b/src/main/java/org/apache/commons/exec/StreamPumper.java
index 880794a3..ef553721 100644
--- a/src/main/java/org/apache/commons/exec/StreamPumper.java
+++ b/src/main/java/org/apache/commons/exec/StreamPumper.java
@@ -28,28 +28,28 @@ import org.apache.commons.exec.util.DebugUtils;
*/
public class StreamPumper implements Runnable {
- /** The default size of the internal buffer for copying the streams */
+ /** The default size of the internal buffer for copying the streams. */
private static final int DEFAULT_SIZE = 1024;
- /** The input stream to pump from */
+ /** The input stream to pump from. */
private final InputStream is;
- /** The output stream to pmp into */
+ /** The output stream to pmp into. */
private final OutputStream os;
- /** The size of the internal buffer for copying the streams */
+ /** The size of the internal buffer for copying the streams. */
private final int size;
- /** Was the end of the stream reached */
+ /** Was the end of the stream reached. */
private boolean finished;
- /** Close the output stream when exhausted */
+ /** Close the output stream when exhausted. */
private final boolean closeWhenExhausted;
/**
* Constructs a new stream pumper.
*
- * @param is input stream to read data from
+ * @param is input stream to read data from.
* @param os output stream to write data to.
*/
public StreamPumper(final InputStream is, final OutputStream os) {
@@ -59,7 +59,7 @@ public class StreamPumper implements Runnable {
/**
* Constructs a new stream pumper.
*
- * @param is input stream to read data from
+ * @param is input stream to read data from.
* @param os output stream to write data to.
* @param closeWhenExhausted if true, the output stream will be closed when the input is exhausted.
*/
@@ -73,10 +73,10 @@ public class StreamPumper implements Runnable {
/**
* Constructs a new stream pumper.
*
- * @param is input stream to read data from
+ * @param is input stream to read data from.
* @param os output stream to write data to.
* @param closeWhenExhausted if true, the output stream will be closed when the input is exhausted.
- * @param size the size of the internal buffer for copying the streams
+ * @param size the size of the internal buffer for copying the streams.
*/
public StreamPumper(final InputStream is, final OutputStream os, final boolean closeWhenExhausted, final int size) {
this.is = is;
diff --git a/src/main/java/org/apache/commons/exec/Watchdog.java b/src/main/java/org/apache/commons/exec/Watchdog.java
index 92fb5988..c278752a 100644
--- a/src/main/java/org/apache/commons/exec/Watchdog.java
+++ b/src/main/java/org/apache/commons/exec/Watchdog.java
@@ -22,7 +22,7 @@ import java.util.Enumeration;
import java.util.Vector;
/**
- * Generalization of {@code ExecuteWatchdog}
+ * Generalization of {@code ExecuteWatchdog}.
*
* @see org.apache.commons.exec.ExecuteWatchdog
*/
diff --git a/src/main/java/org/apache/commons/exec/environment/DefaultProcessingEnvironment.java b/src/main/java/org/apache/commons/exec/environment/DefaultProcessingEnvironment.java
index c0110532..2a809e0e 100644
--- a/src/main/java/org/apache/commons/exec/environment/DefaultProcessingEnvironment.java
+++ b/src/main/java/org/apache/commons/exec/environment/DefaultProcessingEnvironment.java
@@ -53,8 +53,8 @@ public class DefaultProcessingEnvironment {
/**
* Find the list of environment variables for this process.
*
- * @return a amp containing the environment variables
- * @throws IOException the operation failed
+ * @return a amp containing the environment variables.
+ * @throws IOException the operation failed.
*/
protected Map<String, String> createProcEnvironment() throws IOException {
if (procEnvironment == null) {
@@ -98,8 +98,8 @@ public class DefaultProcessingEnvironment {
/**
* Determine the OS specific command line to get a list of environment variables.
*
- * @return the command line
- * @deprecated No longer needed
+ * @return the command line.
+ * @deprecated No longer needed.
*/
@Deprecated
protected CommandLine getProcEnvCommand() {
@@ -151,8 +151,8 @@ public class DefaultProcessingEnvironment {
/**
* Find the list of environment variables for this process.
*
- * @return a map containing the environment variables
- * @throws IOException obtaining the environment variables failed
+ * @return a map containing the environment variables.
+ * @throws IOException obtaining the environment variables failed.
*/
public synchronized Map<String, String> getProcEnvironment() throws IOException {
@@ -197,9 +197,9 @@ public class DefaultProcessingEnvironment {
/**
* Start a process to list the environment variables.
*
- * @return a reader containing the output of the process
- * @throws IOException starting the process failed
- * @deprecated No longer needed
+ * @return a reader containing the output of the process.
+ * @throws IOException starting the process failed.
+ * @deprecated No longer needed.
*/
@Deprecated
protected BufferedReader runProcEnvCommand() throws IOException {
diff --git a/src/main/java/org/apache/commons/exec/environment/EnvironmentUtils.java b/src/main/java/org/apache/commons/exec/environment/EnvironmentUtils.java
index f19d62c9..8b9a04f9 100644
--- a/src/main/java/org/apache/commons/exec/environment/EnvironmentUtils.java
+++ b/src/main/java/org/apache/commons/exec/environment/EnvironmentUtils.java
@@ -41,8 +41,8 @@ public class EnvironmentUtils {
/**
* Add a key/value pair to the given environment. If the key matches an existing key, the previous setting is replaced.
*
- * @param environment the current environment
- * @param keyAndValue the key/value pair
+ * @param environment the current environment.
+ * @param keyAndValue the key/value pair.
*/
public static void addVariableToEnvironment(final Map<String, String> environment, final String keyAndValue) {
final String[] parsedVariable = parseEnvironmentVariable(keyAndValue);
@@ -53,8 +53,8 @@ public class EnvironmentUtils {
* Find the list of environment variables for this process. The returned map preserves the casing of a variable's name on all platforms but obeys the casing
* rules of the current platform during lookup, e.g. key names will be case-insensitive on Windows platforms.
*
- * @return a map containing the environment variables, may be empty but never {@code null}
- * @throws IOException the operation failed
+ * @return a map containing the environment variables, may be empty but never {@code null}.
+ * @throws IOException the operation failed.
*/
public static Map<String, String> getProcEnvironment() throws IOException {
return PROCESSING_ENVIRONMENT_IMPLEMENTATION.getProcEnvironment();
@@ -63,8 +63,8 @@ public class EnvironmentUtils {
/**
* Split a key/value pair into a String[]. It is assumed that the ky/value pair contains a '=' character.
*
- * @param keyAndValue the key/value pair
- * @return a String[] containing the key and value
+ * @param keyAndValue the key/value pair.
+ * @return a String[] containing the key and value.
*/
private static String[] parseEnvironmentVariable(final String keyAndValue) {
final int index = keyAndValue.indexOf('=');
@@ -82,8 +82,8 @@ public class EnvironmentUtils {
/**
* Gets the variable list as an array.
*
- * @param environment the environment to use, may be {@code null}
- * @return array of key=value assignment strings or {@code null} if and only if the input map was {@code null}
+ * @param environment the environment to use, may be {@code null}.
+ * @return array of key=value assignment strings or {@code null} if and only if the input map was {@code null}.
*/
public static String[] toStrings(final Map<String, String> environment) {
if (environment == null) {
diff --git a/src/main/java/org/apache/commons/exec/environment/OpenVmsProcessingEnvironment.java b/src/main/java/org/apache/commons/exec/environment/OpenVmsProcessingEnvironment.java
index 8656c728..72e04bda 100644
--- a/src/main/java/org/apache/commons/exec/environment/OpenVmsProcessingEnvironment.java
+++ b/src/main/java/org/apache/commons/exec/environment/OpenVmsProcessingEnvironment.java
@@ -27,7 +27,7 @@ package org.apache.commons.exec.environment;
/**
* Helper class to determine the environment variable for VMS.
*
- * @deprecated No longer needed
+ * @deprecated No longer needed.
*/
@Deprecated
public class OpenVmsProcessingEnvironment extends DefaultProcessingEnvironment {
diff --git a/src/main/java/org/apache/commons/exec/launcher/CommandLauncher.java b/src/main/java/org/apache/commons/exec/launcher/CommandLauncher.java
index 082df0a3..98c4258f 100644
--- a/src/main/java/org/apache/commons/exec/launcher/CommandLauncher.java
+++ b/src/main/java/org/apache/commons/exec/launcher/CommandLauncher.java
@@ -24,43 +24,41 @@ import java.util.Map;
import org.apache.commons.exec.CommandLine;
/**
- * Interface to shield the caller from the various platform-dependent implementations.
+ * Abstracts the various platform-dependent implementations.
*/
public interface CommandLauncher {
/**
- * Launches the given command in a new process.
+ * Executes the given command in a new process.
*
- * @param cmd The command to execute
+ * @param cmd The command to execute.
* @param env The environment for the new process. If null, the environment of the current process is used.
- *
- * @return the newly created process
- * @throws IOException if attempting to run a command in a specific directory
+ * @return the newly created process.
+ * @throws IOException if attempting to run a command in a specific directory.
*/
Process exec(final CommandLine cmd, final Map<String, String> env) throws IOException;
/**
- * Launches the given command in a new process, in the given working directory.
+ * Executes the given command in a new process, in the given working directory.
*
- * @param cmd The command to execute
+ * @param cmd The command to execute.
* @param env The environment for the new process. If null, the environment of the current process is used.
- * @param workingDir The directory to start the command in. If null, the current directory is used
- *
- * @return the newly created process
- * @throws IOException if trying to change directory
+ * @param workingDir The directory to start the command in. If null, the current directory is used.
+ * @return the newly created process.
+ * @throws IOException if trying to change directory.
*/
Process exec(final CommandLine cmd, final Map<String, String> env, final File workingDir) throws IOException;
/**
- * Checks whether {@code exitValue} signals a failure on the current system (OS specific).
+ * Tests whether {@code exitValue} signals a failure on the current system (OS specific).
* <p>
* <b>Note</b> that this method relies on the conventions of the OS, it will return false results if the application you are running doesn't follow these
* conventions. One notable exception is the Java VM provided by HP for OpenVMS - it will return 0 if successful (like on any other platform), but this
* signals a failure on OpenVMS. So if you execute a new Java VM on OpenVMS, you cannot trust this method.
* </p>
*
- * @param exitValue the exit value (return code) to be checked
- * @return {@code true} if {@code exitValue} signals a failure
+ * @param exitValue the exit value (return code) to be checked.
+ * @return {@code true} if {@code exitValue} signals a failure.
*/
boolean isFailure(final int exitValue);
}
diff --git a/src/main/java/org/apache/commons/exec/launcher/CommandLauncherFactory.java b/src/main/java/org/apache/commons/exec/launcher/CommandLauncherFactory.java
index f8e885bc..1e0e6110 100644
--- a/src/main/java/org/apache/commons/exec/launcher/CommandLauncherFactory.java
+++ b/src/main/java/org/apache/commons/exec/launcher/CommandLauncherFactory.java
@@ -27,7 +27,7 @@ public final class CommandLauncherFactory {
/**
* Factory method to create an appropriate launcher.
*
- * @return the command launcher
+ * @return the command launcher.
*/
public static CommandLauncher createVMLauncher() {
// Try using a JDK 1.3 launcher
diff --git a/src/main/java/org/apache/commons/exec/launcher/CommandLauncherProxy.java b/src/main/java/org/apache/commons/exec/launcher/CommandLauncherProxy.java
index 3793ac9d..92941de7 100644
--- a/src/main/java/org/apache/commons/exec/launcher/CommandLauncherProxy.java
+++ b/src/main/java/org/apache/commons/exec/launcher/CommandLauncherProxy.java
@@ -34,11 +34,11 @@ public abstract class CommandLauncherProxy extends CommandLauncherImpl {
}
/**
- * Launches the given command in a new process. Delegates this method to the proxied launcher
+ * Launches the given command in a new process. Delegates this method to the proxied launcher.
*
- * @param cmd the command line to execute as an array of strings
- * @param env the environment to set as an array of strings
- * @throws IOException forwarded from the exec method of the command launcher
+ * @param cmd the command line to execute as an array of strings.
+ * @param env the environment to set as an array of strings.
+ * @throws IOException forwarded from the exec method of the command launcher.
*/
@Override
public Process exec(final CommandLine cmd, final Map<String, String> env) throws IOException {
diff --git a/src/main/java/org/apache/commons/exec/launcher/Java13CommandLauncher.java b/src/main/java/org/apache/commons/exec/launcher/Java13CommandLauncher.java
index 91e57453..6a40bf15 100644
--- a/src/main/java/org/apache/commons/exec/launcher/Java13CommandLauncher.java
+++ b/src/main/java/org/apache/commons/exec/launcher/Java13CommandLauncher.java
@@ -25,7 +25,7 @@ import org.apache.commons.exec.CommandLine;
import org.apache.commons.exec.environment.EnvironmentUtils;
/**
- * A command launcher for JDK/JRE 1.3 (and higher). Uses the built-in Runtime.exec() command
+ * A command launcher for JDK/JRE 1.3 (and higher). Uses the built-in Runtime.exec() command.
*/
public class Java13CommandLauncher extends CommandLauncherImpl {
@@ -36,12 +36,12 @@ public class Java13CommandLauncher extends CommandLauncherImpl {
}
/**
- * Launches the given command in a new process, in the given working directory
+ * Launches the given command in a new process, in the given working directory.
*
- * @param cmd the command line to execute as an array of strings
- * @param env the environment to set as an array of strings
- * @param workingDir the working directory where the command should run
- * @throws IOException probably forwarded from Runtime#exec
+ * @param cmd the command line to execute as an array of strings.
+ * @param env the environment to set as an array of strings.
+ * @param workingDir the working directory where the command should run.
+ * @throws IOException probably forwarded from {@link Runtime#exec(String[], String[], File)}.
*/
@Override
public Process exec(final CommandLine cmd, final Map<String, String> env, final File workingDir) throws IOException {
diff --git a/src/main/java/org/apache/commons/exec/launcher/OS2CommandLauncher.java b/src/main/java/org/apache/commons/exec/launcher/OS2CommandLauncher.java
index c13f20b8..ee1c82ef 100644
--- a/src/main/java/org/apache/commons/exec/launcher/OS2CommandLauncher.java
+++ b/src/main/java/org/apache/commons/exec/launcher/OS2CommandLauncher.java
@@ -28,7 +28,9 @@ import org.apache.commons.exec.CommandLine;
* <p>
* Unlike Windows NT and friends, OS/2's cd doesn't support the /d switch to change drives and directories in one go.
* </p>
- * Please not that this class is currently unused because the Java13CommandLauncher is used for 0S/2
+ * <p>
+ * Note that this class is currently unused because the Java13CommandLauncher is used for 0S/2.
+ * </p>
*/
public class OS2CommandLauncher extends CommandLauncherProxy {
@@ -39,10 +41,10 @@ public class OS2CommandLauncher extends CommandLauncherProxy {
/**
* Launches the given command in a new process, in the given working directory.
*
- * @param cmd the command line to execute as an array of strings
- * @param env the environment to set as an array of strings
- * @param workingDir working directory where the command should run
- * @throws IOException forwarded from the exec method of the command launcher
+ * @param cmd the command line to execute as an array of strings.
+ * @param env the environment to set as an array of strings.
+ * @param workingDir working directory where the command should run.
+ * @throws IOException forwarded from the exec method of the command launcher.
*/
@Override
public Process exec(final CommandLine cmd, final Map<String, String> env, final File workingDir) throws IOException {
diff --git a/src/main/java/org/apache/commons/exec/launcher/VmsCommandLauncher.java b/src/main/java/org/apache/commons/exec/launcher/VmsCommandLauncher.java
index a761a028..32106c33 100644
--- a/src/main/java/org/apache/commons/exec/launcher/VmsCommandLauncher.java
+++ b/src/main/java/org/apache/commons/exec/launcher/VmsCommandLauncher.java
@@ -36,7 +36,7 @@ import org.apache.commons.exec.util.StringUtils;
*/
public class VmsCommandLauncher extends Java13CommandLauncher {
- /*
+ /**
* Writes the command into a temporary DCL script and returns the corresponding File object. The script will be deleted on exit.
*/
private File createCommandFile(final CommandLine cmd, final Map<String, String> env) throws IOException {
diff --git a/src/main/java/org/apache/commons/exec/launcher/WinNTCommandLauncher.java b/src/main/java/org/apache/commons/exec/launcher/WinNTCommandLauncher.java
index 13eb2170..880ca54d 100644
--- a/src/main/java/org/apache/commons/exec/launcher/WinNTCommandLauncher.java
+++ b/src/main/java/org/apache/commons/exec/launcher/WinNTCommandLauncher.java
@@ -34,10 +34,10 @@ public class WinNTCommandLauncher extends CommandLauncherProxy {
/**
* Launches the given command in a new process, in the given working directory.
*
- * @param cmd the command line to execute as an array of strings
- * @param env the environment to set as an array of strings
- * @param workingDir working directory where the command should run
- * @throws IOException forwarded from the exec method of the command launcher
+ * @param cmd the command line to execute as an array of strings.
+ * @param env the environment to set as an array of strings.
+ * @param workingDir working directory where the command should run.
+ * @throws IOException forwarded from the exec method of the command launcher.
*/
@Override
public Process exec(final CommandLine cmd, final Map<String, String> env, final File workingDir) throws IOException {
@@ -45,8 +45,7 @@ public class WinNTCommandLauncher extends CommandLauncherProxy {
return exec(cmd, env);
}
- // Use cmd.exe to change to the specified directory before running
- // the command
+ // Use cmd.exe to change to the specified directory before running the command.
// @formatter:off
return exec(new CommandLine("cmd")
.addArgument("/c")
diff --git a/src/main/java/org/apache/commons/exec/util/DebugUtils.java b/src/main/java/org/apache/commons/exec/util/DebugUtils.java
index cb8fbee8..90b7051c 100644
--- a/src/main/java/org/apache/commons/exec/util/DebugUtils.java
+++ b/src/main/java/org/apache/commons/exec/util/DebugUtils.java
@@ -21,6 +21,7 @@ package org.apache.commons.exec.util;
* Provides debugging support.
*/
public class DebugUtils {
+
/**
* System property to determine how to handle exceptions. When set to "false" we rethrow the otherwise silently catched exceptions found in the original
* code. The default value is "true"
@@ -35,8 +36,8 @@ public class DebugUtils {
/**
* Handles an exception based on the system properties.
*
- * @param msg message describing the problem
- * @param e an exception being handled
+ * @param msg message describing the problem.
+ * @param e an exception being handled.
*/
public static void handleException(final String msg, final Exception e) {
if (isDebugEnabled()) {
@@ -54,7 +55,7 @@ public class DebugUtils {
/**
* Determines if debugging is enabled based on the system property "COMMONS_EXEC_DEBUG".
*
- * @return true if debug mode is enabled
+ * @return true if debug mode is enabled.
*/
public static boolean isDebugEnabled() {
final String debug = System.getProperty(COMMONS_EXEC_DEBUG, Boolean.FALSE.toString());
@@ -64,7 +65,7 @@ public class DebugUtils {
/**
* Determines if lenient mode is enabled.
*
- * @return true if lenient mode is enabled
+ * @return true if lenient mode is enabled.
*/
public static boolean isLenientEnabled() {
final String lenient = System.getProperty(COMMONS_EXEC_LENIENT, Boolean.TRUE.toString());
diff --git a/src/main/java/org/apache/commons/exec/util/MapUtils.java b/src/main/java/org/apache/commons/exec/util/MapUtils.java
index 7be47e34..76048fba 100644
--- a/src/main/java/org/apache/commons/exec/util/MapUtils.java
+++ b/src/main/java/org/apache/commons/exec/util/MapUtils.java
@@ -27,10 +27,10 @@ public class MapUtils {
/**
* Clones a map.
*
- * @param source the Map to clone
- * @param <K> the map key type
- * @param <V> the map value type
- * @return the cloned map
+ * @param source the Map to clone.
+ * @param <K> the map key type.
+ * @param <V> the map value type.
+ * @return the cloned map.
*/
public static <K, V> Map<K, V> copy(final Map<K, V> source) {
return source == null ? null : new HashMap<>(source);
@@ -39,11 +39,11 @@ public class MapUtils {
/**
* Clones the lhs map and add all things from the rhs map.
*
- * @param lhs the first map
- * @param rhs the second map
- * @param <K> the map key type
- * @param <V> the map value type
- * @return the merged map
+ * @param lhs the first map.
+ * @param rhs the second map.
+ * @param <K> the map key type.
+ * @param <V> the map value type.
+ * @return the merged map.
*/
public static <K, V> Map<K, V> merge(final Map<K, V> lhs, final Map<K, V> rhs) {
Map<K, V> result = null;
@@ -61,11 +61,11 @@ public class MapUtils {
/**
* Clones a map and prefixes the keys in the clone, e.g. for mapping "JAVA_HOME" to "env.JAVA_HOME" to simulate the behavior of Ant.
*
- * @param source the source map
- * @param prefix the prefix used for all names
- * @param <K> the map key type
- * @param <V> the map value type
- * @return the clone of the source map
+ * @param source the source map.
+ * @param prefix the prefix used for all names.
+ * @param <K> the map key type.
+ * @param <V> the map value type.
+ * @return the clone of the source map.
*/
public static <K, V> Map<String, V> prefix(final Map<K, V> source, final String prefix) {
if (source == null) {
diff --git a/src/main/java/org/apache/commons/exec/util/StringUtils.java b/src/main/java/org/apache/commons/exec/util/StringUtils.java
index 0b38e52d..dea88bc3 100644
--- a/src/main/java/org/apache/commons/exec/util/StringUtils.java
+++ b/src/main/java/org/apache/commons/exec/util/StringUtils.java
@@ -44,8 +44,8 @@ public class StringUtils {
* <li>'\\' → File.separatorChar</li>
* </ul>
*
- * @param arg the argument to fix
- * @return the transformed argument
+ * @param arg the argument to fix.
+ * @return the transformed argument.
*/
public static String fixFileSeparatorChar(final String arg) {
return arg.replace(SLASH_CHAR, File.separatorChar).replace(BACKSLASH_CHAR, File.separatorChar);
@@ -54,8 +54,8 @@ public class StringUtils {
/**
* Determines if this is a quoted argument - either single or double quoted.
*
- * @param argument the argument to check
- * @return true when the argument is quoted
+ * @param argument the argument to check.
+ * @return true when the argument is quoted.
*/
public static boolean isQuoted(final String argument) {
return argument.startsWith(SINGLE_QUOTE) && argument.endsWith(SINGLE_QUOTE) || argument.startsWith(DOUBLE_QUOTE) && argument.endsWith(DOUBLE_QUOTE);
@@ -68,9 +68,9 @@ public class StringUtils {
* quotes.
* </p>
*
- * @param argument the argument to be quoted
- * @return the quoted argument
- * @throws IllegalArgumentException If argument contains both types of quotes
+ * @param argument the argument to be quoted.
+ * @return the quoted argument.
+ * @throws IllegalArgumentException If argument contains both types of quotes.
*/
public static String quoteArgument(final String argument) {
@@ -101,9 +101,9 @@ public class StringUtils {
/**
* Split a string into an array of strings based on a separator.
*
- * @param input what to split
- * @param splitChar what to split on
- * @return the array of strings
+ * @param input what to split.
+ * @param splitChar what to split on.
+ * @return the array of strings.
*/
public static String[] split(final String input, final String splitChar) {
final StringTokenizer tokens = new StringTokenizer(input, splitChar);
@@ -132,8 +132,8 @@ public class StringUtils {
* <li>underscore character
* </ul>
*
- * @param argStr the argument string to be processed
- * @param vars name/value pairs used for substitution
+ * @param argStr the argument string to be processed.
+ * @param vars name/value pairs used for substitution.
* @param isLenient ignore a key not found in vars or throw a RuntimeException?
* @return String target string with replacements.
*/
diff --git a/src/test/java/org/apache/commons/exec/CommandLineTest.java b/src/test/java/org/apache/commons/exec/CommandLineTest.java
index 3ace703e..2bb9b597 100644
--- a/src/test/java/org/apache/commons/exec/CommandLineTest.java
+++ b/src/test/java/org/apache/commons/exec/CommandLineTest.java
@@ -21,8 +21,6 @@ import static org.junit.jupiter.api.Assertions.assertArrayEquals;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.junit.jupiter.api.Assertions.assertTrue;
-import static org.junit.jupiter.api.Assertions.fail;
-
import java.io.File;
import java.util.HashMap;
import java.util.Map;