antoine 2003/07/27 16:22:01
Modified: src/main/org/apache/tools/ant/taskdefs Execute.java
ExecTask.java
Log:
style
Revision Changes Path
1.61 +72 -20 ant/src/main/org/apache/tools/ant/taskdefs/Execute.java
Index: Execute.java
===================================================================
RCS file: /home/cvs/ant/src/main/org/apache/tools/ant/taskdefs/Execute.java,v
retrieving revision 1.60
retrieving revision 1.61
diff -u -r1.60 -r1.61
--- Execute.java 25 Jul 2003 14:06:36 -0000 1.60
+++ Execute.java 27 Jul 2003 23:22:00 -0000 1.61
@@ -171,8 +171,12 @@
}
}
+
/**
* 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 @@
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 @@
* 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 @@
* 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 @@
* @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 @@
}
}
+ /**
+ * 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 @@
}
}
+ /**
+ * set the exit value
+ *
+ * @param value exit value of the process
+ */
protected void setExitValue(int value) {
exitValue = value;
}
@@ -596,7 +619,7 @@
/**
* 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 @@
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 @@
* @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 @@
* 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 @@
/**
* 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 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 @@
+ 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 @@
}
}
- private Method _execWithCWD;
+ private Method myExecWithCWD;
}
/**
@@ -768,19 +801,23 @@
*/
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 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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 @@
private static class ScriptCommandLauncher extends CommandLauncherProxy {
ScriptCommandLauncher(String script, CommandLauncher launcher) {
super(launcher);
- _script = script;
+ myScript = script;
}
/**
@@ -928,7 +980,7 @@
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 @@
return exec(project, newcmd, env);
}
- private String _script;
+ private String myScript;
}
/**
@@ -955,7 +1007,7 @@
extends CommandLauncherProxy {
PerlScriptCommandLauncher(String script, CommandLauncher launcher) {
super(launcher);
- _script = script;
+ myScript = script;
}
/**
@@ -978,7 +1030,7 @@
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 @@
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 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 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 @@
if (out != null) {
out.close();
}
- }
+ }
return script;
}
1.57 +95 -9 ant/src/main/org/apache/tools/ant/taskdefs/ExecTask.java
Index: ExecTask.java
===================================================================
RCS file: /home/cvs/ant/src/main/org/apache/tools/ant/taskdefs/ExecTask.java,v
retrieving revision 1.56
retrieving revision 1.57
diff -u -r1.56 -r1.57
--- ExecTask.java 25 Jul 2003 10:06:31 -0000 1.56
+++ ExecTask.java 27 Jul 2003 23:22:01 -0000 1.57
@@ -102,6 +102,8 @@
/**
* 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 @@
/**
* 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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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 @@
* 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 @@
/**
* 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 @@
}
/**
- * 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 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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 @@
}
/**
- * 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 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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) {
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
