style

git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@274960 13f79535-47bb-0310-9956-ffa450edef68

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 :
+     * <ul>
+     * <li>if failIfExecFails is set to true and the process cannot be started</li>
+     * <li>the java13command launcher can send build exceptions</li>
+     * <li>this list is not exhaustive or limitative</li>
+     * </ul>
      */
     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
+     * <ul>
+     * <li>
+     * <code>true</code> if the os under which ant is running is
+     * matches one os in the os attribute
+     * or if the os attribute is null</li>
+     * <li><code>false</code> otherwise.</li>
+     * </ul>
      */
     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) {

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 <code>in</code> and adds them to
      * <code>environment</code>.  <code>in</code> 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;
         }