diff --git a/src/main/org/apache/tools/ant/taskdefs/ExecTask.java b/src/main/org/apache/tools/ant/taskdefs/ExecTask.java index dbd95f357..f5a0af1f4 100644 --- a/src/main/org/apache/tools/ant/taskdefs/ExecTask.java +++ b/src/main/org/apache/tools/ant/taskdefs/ExecTask.java @@ -102,6 +102,8 @@ public class ExecTask extends Task { /** * Timeout in milliseconds after which the process will be killed. * + * @param value timeout in milliseconds + * * @since Ant 1.5 */ public void setTimeout(Long value) { @@ -110,6 +112,8 @@ public class ExecTask extends Task { /** * Timeout in milliseconds after which the process will be killed. + * + * @param value timeout in milliseconds */ public void setTimeout(Integer value) { if (value == null) { @@ -120,7 +124,8 @@ public class ExecTask extends Task { } /** - * The command to execute. + * Set the name of the executable program. + * @param value the name of the executable program */ public void setExecutable(String value) { this.executable = value; @@ -128,7 +133,8 @@ public class ExecTask extends Task { } /** - * The working directory of the process. + * Set the working directory of the process. + * @param d the working directory of the process */ public void setDir(File d) { this.dir = d; @@ -136,12 +142,15 @@ public class ExecTask extends Task { /** * List of operating systems on which the command may be executed. + * @param os list of operating systems on which the command may be executed */ public void setOs(String os) { this.os = os; } /** + * Sets a command line + * @param cmdl command line * @ant.attribute ignore="true" */ public void setCommand(Commandline cmdl) { @@ -154,6 +163,8 @@ public class ExecTask extends Task { /** * File the output of the process is redirected to. If error is not * redirected, it too will appear in the output + * + * @param out name of a file to which send output to */ public void setOutput(File out) { redirector.setOutput(out); @@ -161,6 +172,8 @@ public class ExecTask extends Task { /** * Set the input to use for the task + * + * @param input name of a file to get input from */ public void setInput(File input) { redirector.setInput(input); @@ -179,6 +192,8 @@ public class ExecTask extends Task { * Controls whether error output of exec is logged. This is only useful * when output is being redirected and error output is desired in the * Ant log + * + * @param logError set to true to log error output in the normal ant log */ public void setLogError(boolean logError) { redirector.setLogError(logError); @@ -187,6 +202,8 @@ public class ExecTask extends Task { /** * File the error stream of the process is redirected to. * + * @param error a file to which send stderr to + * * @since ant 1.6 */ public void setError(File error) { @@ -194,17 +211,21 @@ public class ExecTask extends Task { } /** - * Property name whose value should be set to the output of + * Sets the property name whose value should be set to the output of * the process. + * + * @param outputProp name of property */ public void setOutputproperty(String outputProp) { redirector.setOutputProperty(outputProp); } /** - * Property name whose value should be set to the error of + * Sets the name of the property whose value should be set to the error of * the process. * + * @param errorProperty name of property + * * @since ant 1.6 */ public void setErrorProperty(String errorProperty) { @@ -213,6 +234,8 @@ public class ExecTask extends Task { /** * Fail if the command exits with a non-zero return code. + * + * @param fail if true fail the command on non-zero return code. */ public void setFailonerror(boolean fail) { failOnError = fail; @@ -220,13 +243,20 @@ public class ExecTask extends Task { /** * Do not propagate old environment when new environment variables are specified. + * + * @param newenv if true, do not propagate old environment + * when new environment variables are specified. */ public void setNewenvironment(boolean newenv) { newEnvironment = newenv; } /** - * Attempt to resolve the executable to a file + * Sets a flag indicating whether to attempt to resolve the executable + * to a file + * + * @param resolveExecutable if true, attempt to resolve the + * path of the executable */ public void setResolveExecutable(boolean resolveExecutable) { this.resolveExecutable = resolveExecutable; @@ -234,6 +264,8 @@ public class ExecTask extends Task { /** * Add an environment variable to the launched process. + * + * @param var new environment variable */ public void addEnv(Environment.Variable var) { env.addVariable(var); @@ -241,16 +273,20 @@ public class ExecTask extends Task { /** * Adds a command-line argument. + * + * @return new command line argument created */ public Commandline.Argument createArg() { return cmdl.createArgument(); } /** - * The name of a property in which the return code of the + * Sets the name of a property in which the return code of the * command should be stored. Only of interest if failonerror=false. * * @since Ant 1.5 + * + * @param resultProperty name of property */ public void setResultProperty(String resultProperty) { this.resultProperty = resultProperty; @@ -259,6 +295,8 @@ public class ExecTask extends Task { /** * helper method to set result property to the * passed in value if appropriate + * + * @param result value desired for the result property value */ protected void maybeSetResultPropertyValue(int result) { String res = Integer.toString(result); @@ -268,7 +306,10 @@ public class ExecTask extends Task { } /** - * Stop the build if program cannot be started. Defaults to true. + * Sets a flag to stop the build if program cannot be started. + * Defaults to true. + * + * @param flag stop the build if program cannot be started * * @since Ant 1.5 */ @@ -277,9 +318,11 @@ public class ExecTask extends Task { } /** - * Whether output should be appended to or overwrite an existing file. + * Sets whether output should be appended to or overwrite an existing file. * Defaults to false. * + * @param append if true append is desired + * * @since 1.30, Ant 1.5 */ public void setAppend(boolean append) { @@ -321,6 +364,13 @@ public class ExecTask extends Task { /** * Do the work. + * + * @throws BuildException in a number of circumstances : + * */ public void execute() throws BuildException { File savedDir = dir; // possibly altered in prepareExec @@ -337,6 +387,7 @@ public class ExecTask extends Task { /** * Has the user set all necessary attributes? + * @throws BuildException if there are missing required parameters */ protected void checkConfiguration() throws BuildException { if (cmdl.getExecutable() == null) { @@ -354,6 +405,14 @@ public class ExecTask extends Task { /** * Is this the OS the user wanted? + * @return boolean + * */ protected boolean isValidOs() { // test if os match @@ -370,7 +429,11 @@ public class ExecTask extends Task { } /** - * If true, launch new process with VM, otherwise use the OS's shell. + * Sets a flag indicating if we want to launch new process with VM, + * otherwise use the OS's shell. + * Default value of the flag is true. + * @param vmLauncher true if we want to launch new process with VM, + * false if we want to use the OS's shell. */ public void setVMLauncher(boolean vmLauncher) { this.vmLauncher = vmLauncher; @@ -378,6 +441,10 @@ public class ExecTask extends Task { /** * Create an Execute instance with the correct working directory set. + * + * @return an instance of the Execute class + * + * @throws BuildException under unknown circumstances. */ protected Execute prepareExec() throws BuildException { // default directory to the project's base directory @@ -403,11 +470,17 @@ public class ExecTask extends Task { /** * A Utility method for this classes and subclasses to run an * Execute instance (an external command). + * + * @param exe instance of the execute class + * + * @throws IOException in case of problem to attach to the stdin/stdout/stderr + * streams of the process */ protected final void runExecute(Execute exe) throws IOException { int returnCode = -1; // assume the worst returnCode = exe.execute(); + //test for and handle a forced process death if (exe.killedProcess()) { log("Timeout: killed the sub-process", Project.MSG_WARN); @@ -427,6 +500,11 @@ public class ExecTask extends Task { /** * Run the command using the given Execute instance. This may be * overidden by subclasses + * + * @param exe instance of Execute to run + * + * @throws BuildException if the new process could not be started + * only if failIfExecFails is set to true (the default) */ protected void runExec(Execute exe) throws BuildException { // show the command @@ -450,6 +528,10 @@ public class ExecTask extends Task { /** * Create the StreamHandler to use with our Execute instance. + * + * @return instance of ExecuteStreamHandler + * + * @throws BuildException under unknown circumstances */ protected ExecuteStreamHandler createHandler() throws BuildException { return redirector.createHandler(); @@ -457,6 +539,10 @@ public class ExecTask extends Task { /** * Create the Watchdog to kill a runaway process. + * + * @return instance of ExecuteWatchdog + * + * @throws BuildException under unknown circumstances */ protected ExecuteWatchdog createWatchdog() throws BuildException { if (timeout == null) { diff --git a/src/main/org/apache/tools/ant/taskdefs/Execute.java b/src/main/org/apache/tools/ant/taskdefs/Execute.java index 30f14082f..0e38049d4 100644 --- a/src/main/org/apache/tools/ant/taskdefs/Execute.java +++ b/src/main/org/apache/tools/ant/taskdefs/Execute.java @@ -171,8 +171,12 @@ public class Execute { } } + /** * Find the list of environment variables for this process. + * + * @return a vector containing the environment variables + * the vector elements are strings formatted like variable = value */ public static synchronized Vector getProcEnvironment() { if (procEnvironment != null) { @@ -268,7 +272,7 @@ public class Execute { return cmd; } else { // MAC OS 9 and previous - // TODO: I have no idea how to get it, someone must fix it + //TODO: I have no idea how to get it, someone must fix it String[] cmd = null; return cmd; } @@ -279,6 +283,10 @@ public class Execute { * OS/390, at least not the way we use it in the execution * context. * + * @param bos the output stream that one wants to read + * @return the output stream as a string, read with + * special encodings in the case of z/os and os/400 + * * @since Ant 1.5 */ public static String toString(ByteArrayOutputStream bos) { @@ -403,6 +411,9 @@ public class Execute { * Set the name of the antRun script using the project's value. * * @param project the current project. + * + * @throws BuildException not clear when it is going to throw an exception, but + * it is the method's signature */ public void setAntRun(Project project) throws BuildException { this.project = project; @@ -430,6 +441,8 @@ public class Execute { * @param env the environment for the command * @param dir the working directory for the command * @param useVM use the built-in exec command for JDK 1.3 if available. + * @return the process started + * @throws IOException forwarded from the particular launcher used * * @since Ant 1.5 */ @@ -493,6 +506,11 @@ public class Execute { } } + /** + * wait for a given process + * + * @param process the process one wants to wait for + */ protected void waitFor(Process process) { try { process.waitFor(); @@ -502,6 +520,11 @@ public class Execute { } } + /** + * set the exit value + * + * @param value exit value of the process + */ protected void setExitValue(int value) { exitValue = value; } @@ -596,7 +619,7 @@ public class Execute { /** * This method is VMS specific and used by getProcEnvironment(). - * + * * Parses VMS logicals from in and adds them to * environment. in is expected to be the * output of "SHOW LOGICAL". The method takes care of parsing the output @@ -608,7 +631,6 @@ public class Execute { private static Vector addVMSLogicals(Vector environment, BufferedReader in) throws IOException { HashMap logicals = new HashMap(); - String logName = null, logValue = null, newLogName; String line, lineSep = System.getProperty("line.separator"); while ((line = in.readLine()) != null) { @@ -659,6 +681,7 @@ public class Execute { * @param cmd The command to execute * @param env The environment for the new process. If null, * the environment of the current proccess is used. + * @throws IOException if attempting to run a command in a specific directory */ public Process exec(Project project, String[] cmd, String[] env) throws IOException { @@ -679,6 +702,7 @@ public class Execute { * the environment of the current proccess is used. * @param workingDir The directory to start the command in. If null, * the current directory is used + * @throws IOException if trying to change directory */ public Process exec(Project project, String[] cmd, String[] env, File workingDir) throws IOException { @@ -699,6 +723,10 @@ public class Execute { /** * Launches the given command in a new process. Needs to quote * arguments + * @param project the ant project + * @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 probably forwarded from Runtime#exec */ public Process exec(Project project, String[] cmd, String[] env) throws IOException { @@ -724,13 +752,18 @@ public class Execute { public Java13CommandLauncher() throws NoSuchMethodException { // Locate method Runtime.exec(String[] cmdarray, // String[] envp, File dir) - _execWithCWD = Runtime.class.getMethod("exec", + myExecWithCWD = Runtime.class.getMethod("exec", new Class[] {String[].class, String[].class, File.class}); } /** * Launches the given command in a new process, in the given working * directory + * @param project the ant project + * @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 */ public Process exec(Project project, String[] cmd, String[] env, File workingDir) throws IOException { @@ -740,7 +773,7 @@ public class Execute { + Commandline.describeCommand(cmd), Project.MSG_DEBUG); } Object[] arguments = {cmd, env, workingDir}; - return (Process) _execWithCWD.invoke(Runtime.getRuntime(), + return (Process) myExecWithCWD.invoke(Runtime.getRuntime(), arguments); } catch (InvocationTargetException exc) { Throwable realexc = exc.getTargetException(); @@ -758,7 +791,7 @@ public class Execute { } } - private Method _execWithCWD; + private Method myExecWithCWD; } /** @@ -768,19 +801,23 @@ public class Execute { */ private static class CommandLauncherProxy extends CommandLauncher { CommandLauncherProxy(CommandLauncher launcher) { - _launcher = launcher; + myLauncher = launcher; } /** * Launches the given command in a new process. Delegates this * method to the proxied launcher + * @param project the ant project + * @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 */ public Process exec(Project project, String[] cmd, String[] env) throws IOException { - return _launcher.exec(project, cmd, env); + return myLauncher.exec(project, cmd, env); } - private CommandLauncher _launcher; + private CommandLauncher myLauncher; } /** @@ -799,6 +836,11 @@ public class Execute { /** * Launches the given command in a new process, in the given working * directory. + * @param project the ant project + * @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 */ public Process exec(Project project, String[] cmd, String[] env, File workingDir) throws IOException { @@ -842,6 +884,11 @@ public class Execute { /** * Launches the given command in a new process, in the given working * directory. + * @param project the ant project + * @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 */ public Process exec(Project project, String[] cmd, String[] env, File workingDir) throws IOException { @@ -882,6 +929,11 @@ public class Execute { /** * Launches the given command in a new process, in the given working * directory + * @param project the ant project + * @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 */ public Process exec(Project project, String[] cmd, String[] env, File workingDir) throws IOException { @@ -905,7 +957,7 @@ public class Execute { private static class ScriptCommandLauncher extends CommandLauncherProxy { ScriptCommandLauncher(String script, CommandLauncher launcher) { super(launcher); - _script = script; + myScript = script; } /** @@ -928,7 +980,7 @@ public class Execute { throw new IOException("Cannot locate antRun script: " + "Property 'ant.home' not found"); } - String antRun = project.resolveFile(antHome + File.separator + _script).toString(); + String antRun = project.resolveFile(antHome + File.separator + myScript).toString(); // Build the command File commandDir = workingDir; @@ -944,7 +996,7 @@ public class Execute { return exec(project, newcmd, env); } - private String _script; + private String myScript; } /** @@ -955,7 +1007,7 @@ public class Execute { extends CommandLauncherProxy { PerlScriptCommandLauncher(String script, CommandLauncher launcher) { super(launcher); - _script = script; + myScript = script; } /** @@ -978,7 +1030,7 @@ public class Execute { throw new IOException("Cannot locate antRun script: " + "Property 'ant.home' not found"); } - String antRun = project.resolveFile(antHome + File.separator + _script).toString(); + String antRun = project.resolveFile(antHome + File.separator + myScript).toString(); // Build the command File commandDir = workingDir; @@ -995,9 +1047,9 @@ public class Execute { return exec(project, newcmd, env); } - private String _script; + private String myScript; } - + /** * A command launcher for VMS that writes the command to a temporary DCL * script before launching commands. This is due to limitations of both @@ -1014,7 +1066,7 @@ public class Execute { */ public Process exec(Project project, String[] cmd, String[] env) throws IOException { - String[] vmsCmd = { createCommandFile(cmd).getPath() }; + String[] vmsCmd = {createCommandFile(cmd).getPath()}; return super.exec(project, vmsCmd, env); } @@ -1026,7 +1078,7 @@ public class Execute { */ public Process exec(Project project, String[] cmd, String[] env, File workingDir) throws IOException { - String[] vmsCmd = { createCommandFile(cmd).getPath() }; + String[] vmsCmd = {createCommandFile(cmd).getPath()}; return super.exec(project, vmsCmd, env, workingDir); } @@ -1049,7 +1101,7 @@ public class Execute { if (out != null) { out.close(); } - } + } return script; }