diff --git a/src/main/org/apache/tools/ant/taskdefs/AbstractCvsTask.java b/src/main/org/apache/tools/ant/taskdefs/AbstractCvsTask.java index ec59eb15a..d19ca4f4b 100644 --- a/src/main/org/apache/tools/ant/taskdefs/AbstractCvsTask.java +++ b/src/main/org/apache/tools/ant/taskdefs/AbstractCvsTask.java @@ -90,6 +90,7 @@ public abstract class AbstractCvsTask extends Task { * setCompression( true ). */ public static final int DEFAULT_COMPRESSION_LEVEL = 3; + private static final int MAXIMUM_COMRESSION_LEVEL = 9; private Commandline cmd = new Commandline(); @@ -114,7 +115,7 @@ public abstract class AbstractCvsTask extends Task { /** * the default command. */ - private static final String default_command = "checkout"; + private static final String DEFAULT_COMMAND = "checkout"; /** * the CVS command to execute. */ @@ -182,10 +183,18 @@ public abstract class AbstractCvsTask extends Task { super(); } + /** + * sets the handler + * @param handler a handler able of processing the output and error streams from the cvs exe + */ public void setExecuteStreamHandler(ExecuteStreamHandler handler) { this.executeStreamHandler = handler; } + /** + * find the handler and instantiate it if it does not exist yet + * @return handler for output and error streams + */ protected ExecuteStreamHandler getExecuteStreamHandler() { if (this.executeStreamHandler == null) { @@ -196,12 +205,23 @@ public abstract class AbstractCvsTask extends Task { return this.executeStreamHandler; } - + /** + * sets a stream to which the output from the cvs executable should be sent + * @param outputStream stream to which the stdout from cvs should go + */ protected void setOutputStream(OutputStream outputStream) { this.outputStream = outputStream; } + /** + * access the stream to which the stdout from cvs should go + * if this stream has already been set, it will be returned + * if the stream has not yet been set, if the attribute output + * has been set, the output stream will go to the output file + * otherwise the output will go to ant's logging system + * @return output stream to which cvs'stdout should go to + */ protected OutputStream getOutputStream() { if (this.outputStream == null) { @@ -224,11 +244,23 @@ public abstract class AbstractCvsTask extends Task { return this.outputStream; } + /** + * sets a stream to which the stderr from the cvs exe should go + * @param errorStream an output stream willing to process stderr + */ protected void setErrorStream(OutputStream errorStream) { this.errorStream = errorStream; } + /** + * access the stream to which the stderr from cvs should go + * if this stream has already been set, it will be returned + * if the stream has not yet been set, if the attribute error + * has been set, the output stream will go to the file denoted by the error attribute + * otherwise the stderr output will go to ant's logging system + * @return output stream to which cvs'stderr should go to + */ protected OutputStream getErrorStream() { if (this.errorStream == null) { @@ -253,7 +285,8 @@ public abstract class AbstractCvsTask extends Task { /** * Sets up the environment for toExecute and then runs it. - * @throws BuildException + * @param toExecute the command line to execute + * @throws BuildException if failonError is set to true and the cvs command fails */ protected void runCommand(Commandline toExecute) throws BuildException { // XXX: we should use JCVS (www.ice.com/JCVS) instead of @@ -386,13 +419,17 @@ public abstract class AbstractCvsTask extends Task { } } + /** + * do the work + * @throws BuildException if failonerror is set to true and the cvs command fails. + */ public void execute() throws BuildException { String savedCommand = getCommand(); if (this.getCommand() == null && vecCommandlines.size() == 0) { // re-implement legacy behaviour: - this.setCommand(AbstractCvsTask.default_command); + this.setCommand(AbstractCvsTask.DEFAULT_COMMAND); } String c = this.getCommand(); @@ -442,7 +479,7 @@ public abstract class AbstractCvsTask extends Task { /** * The CVSROOT variable. * - * @param root + * @param root the CVSROOT variable */ public void setCvsRoot(String root) { @@ -456,6 +493,10 @@ public abstract class AbstractCvsTask extends Task { this.cvsRoot = root; } + /** + * access the the CVSROOT variable + * @return CVSROOT + */ public String getCvsRoot() { return this.cvsRoot; @@ -464,7 +505,7 @@ public abstract class AbstractCvsTask extends Task { /** * The CVS_RSH variable. * - * @param rsh + * @param rsh the CVS_RSH variable */ public void setCvsRsh(String rsh) { // Check if not real cvsrsh => set it to null @@ -477,6 +518,10 @@ public abstract class AbstractCvsTask extends Task { this.cvsRsh = rsh; } + /** + * access the CVS_RSH variable + * @return the CVS_RSH variable + */ public String getCvsRsh() { return this.cvsRsh; @@ -485,12 +530,16 @@ public abstract class AbstractCvsTask extends Task { /** * Port used by CVS to communicate with the server. * - * @param port + * @param port port of CVS */ public void setPort(int port) { this.port = port; } + /** + * access the port of CVS + * @return the port of CVS + */ public int getPort() { return this.port; @@ -499,12 +548,16 @@ public abstract class AbstractCvsTask extends Task { /** * Password file to read passwords from. * - * @param passFile + * @param passFile password file to read passwords from */ public void setPassfile(File passFile) { this.passFile = passFile; } + /** + * find the password file + * @return password file + */ public File getPassFile() { return this.passFile; @@ -513,12 +566,17 @@ public abstract class AbstractCvsTask extends Task { /** * The directory where the checked out files should be placed. * - * @param dest + * @param dest directory where the checked out files should be placed */ public void setDest(File dest) { this.dest = dest; } + /** + * get the file where the checked out files should be placed + * + * @return directory where the checked out files should be placed + */ public File getDest() { return this.dest; @@ -527,12 +585,17 @@ public abstract class AbstractCvsTask extends Task { /** * The package/module to operate upon. * - * @param p + * @param p package or module to operate upon */ public void setPackage(String p) { this.cvsPackage = p; } + /** + * access the package or module to operate upon + * + * @return package/module + */ public String getPackage() { return this.cvsPackage; @@ -540,7 +603,7 @@ public abstract class AbstractCvsTask extends Task { /** * The tag of the package/module to operate upon. - * @param p + * @param p tag */ public void setTag(String p) { // Check if not real tag => set it to null @@ -553,11 +616,22 @@ public abstract class AbstractCvsTask extends Task { /** * This needs to be public to allow configuration * of commands externally. + * @param arg command argument */ public void addCommandArgument(String arg) { this.addCommandArgument(cmd, arg); } + /** + * add a command line argument to an external command + * + * I do not understand what this method does in this class ??? + * particulary not why it is public ???? + * AntoineLL July 23d 2003 + * + * @param c command line to which one argument should be added + * @param arg argument to add + */ public void addCommandArgument(Commandline c, String arg) { c.createArgument().setValue(arg); } @@ -565,7 +639,8 @@ public abstract class AbstractCvsTask extends Task { /** * Use the most recent revision no later than the given date. - * @param p + * @param p a date as string in a format that the CVS executable can understand + * see man cvs */ public void setDate(String p) { if (p != null && p.trim().length() > 0) { @@ -576,18 +651,30 @@ public abstract class AbstractCvsTask extends Task { /** * The CVS command to execute. - * @param c + * + * This should be deprecated, it is better to use the Commandline class ? + * AntoineLL July 23d 2003 + * + * @param c a command as string */ public void setCommand(String c) { this.command = c; } + /** + * accessor to a command line as string + * + * This should be deprecated + * AntoineLL July 23d 2003 + * + * @return command line as string + */ public String getCommand() { return this.command; } /** * If true, suppress informational messages. - * @param q + * @param q if true, suppress informational messages */ public void setQuiet(boolean q) { quiet = q; @@ -596,7 +683,7 @@ public abstract class AbstractCvsTask extends Task { /** * If true, report only and don't change any files. * - * @param ne + * @param ne if true, report only and do not change any files. */ public void setNoexec(boolean ne) { noexec = ne; @@ -604,7 +691,7 @@ public abstract class AbstractCvsTask extends Task { /** * The file to direct standard output from the command. - * @param output + * @param output a file to which stdout should go */ public void setOutput(File output) { this.output = output; @@ -613,7 +700,7 @@ public abstract class AbstractCvsTask extends Task { /** * The file to direct standard error from the command. * - * @param error + * @param error a file to which stderr should go */ public void setError(File error) { this.error = error; @@ -621,7 +708,7 @@ public abstract class AbstractCvsTask extends Task { /** * Whether to append output/error when redirecting to a file. - * @param value + * @param value true indicated you want to append */ public void setAppend(boolean value) { this.append = value; @@ -631,7 +718,8 @@ public abstract class AbstractCvsTask extends Task { * Stop the build process if the command exits with * a return code other than 0. * Defaults to false. - * @param failOnError + * @param failOnError stop the build process if the command exits with + * a return code other than 0 */ public void setFailOnError(boolean failOnError) { this.failOnError = failOnError; @@ -639,6 +727,22 @@ public abstract class AbstractCvsTask extends Task { /** * Configure a commandline element for things like cvsRoot, quiet, etc. + * @param c the command line which will be configured + * if the commandline is initially null, the function is a noop + * otherwise the function append to the commandline arguments concerning + * */ protected void configureCommandline(Commandline c) { if (c == null) { @@ -648,7 +752,7 @@ public abstract class AbstractCvsTask extends Task { if (cvsPackage != null) { c.createArgument().setLine(cvsPackage); } - if (this.compression > 0 && this.compression < 10) { + if (this.compression > 0 && this.compression <= MAXIMUM_COMRESSION_LEVEL) { c.createArgument(true).setValue("-z" + this.compression); } if (quiet) { @@ -662,21 +766,27 @@ public abstract class AbstractCvsTask extends Task { } } + /** + * remove a particular command from a vector of command lines + * @param c command line which should be removed + */ protected void removeCommandline(Commandline c) { vecCommandlines.removeElement(c); } /** * Adds direct command-line to execute. - * @param c + * @param c command line to execute */ public void addConfiguredCommandline(Commandline c) { this.addConfiguredCommandline(c, false); } /** - * Configures and adds the given Commandline. - * @param insertAtStart If true, c is + * Configures and adds the given Commandline. + * @param c commandline to insert + * @param insertAtStart If true, c is + * inserted at the beginning of the vector of command lines */ public void addConfiguredCommandline(Commandline c, boolean insertAtStart) { @@ -694,6 +804,7 @@ public abstract class AbstractCvsTask extends Task { /** * If set to a value 1-9 it adds -zN to the cvs command line, else * it disables compression. + * @param level compression level 1 to 9 */ public void setCompressionLevel(int level) { this.compression = level; diff --git a/src/main/org/apache/tools/ant/taskdefs/Ant.java b/src/main/org/apache/tools/ant/taskdefs/Ant.java index f9f2c7aab..9a226e317 100644 --- a/src/main/org/apache/tools/ant/taskdefs/Ant.java +++ b/src/main/org/apache/tools/ant/taskdefs/Ant.java @@ -136,6 +136,7 @@ public class Ant extends Task { /** * If true, pass all properties to the new Ant project. * Defaults to true. + * @param value if true pass all properties to the new Ant project. */ public void setInheritAll(boolean value) { inheritAll = value; @@ -144,6 +145,7 @@ public class Ant extends Task { /** * If true, pass all references to the new Ant project. * Defaults to false. + * @param value if true, pass all references to the new Ant project */ public void setInheritRefs(boolean value) { inheritRefs = value; @@ -261,6 +263,7 @@ public class Ant extends Task { /** * Pass output sent to System.out to the new project. * + * @param output a line of output * @since Ant 1.5 */ public void handleOutput(String output) { @@ -272,6 +275,16 @@ public class Ant extends Task { } /** + * Process input into the ant task + * + * @param buffer the buffer into which data is to be read. + * @param offset the offset into the buffer at which data is stored. + * @param length the amount of data to read + * + * @return the number of bytes read + * + * @exception IOException if the data cannot be read + * * @see Task#handleInput(byte[], int, int) * * @since Ant 1.6 @@ -288,6 +301,8 @@ public class Ant extends Task { /** * Pass output sent to System.out to the new project. * + * @param output The output to log. Should not be null. + * * @since Ant 1.5.2 */ public void handleFlush(String output) { @@ -301,6 +316,8 @@ public class Ant extends Task { /** * Pass output sent to System.err to the new project. * + * @param output The error output to log. Should not be null. + * * @since Ant 1.5 */ public void handleErrorOutput(String output) { @@ -314,6 +331,8 @@ public class Ant extends Task { /** * Pass output sent to System.err to the new project. * + * @param output The error output to log. Should not be null. + * * @since Ant 1.5.2 */ public void handleErrorFlush(String output) { @@ -326,6 +345,8 @@ public class Ant extends Task { /** * Do the execution. + * @throws BuildException if a target tries to call itself + * probably also if a BuildException is thrown by the new project */ public void execute() throws BuildException { File savedDir = dir; @@ -414,6 +435,7 @@ public class Ant extends Task { /** * Override the properties in the new project with the one * explicitly defined as nested elements here. + * @throws BuildException under unknown circumstances */ private void overrideProperties() throws BuildException { Enumeration e = properties.elements(); @@ -430,6 +452,7 @@ public class Ant extends Task { * new project. Also copy over all references that don't override * existing references in the new project if inheritrefs has been * requested. + * @throws BuildException if a reference does not have a refid */ private void addReferences() throws BuildException { Hashtable thisReferences @@ -528,7 +551,7 @@ public class Ant extends Task { * Copies all properties from the given table to the new project - * ommiting those that have already been set in the new project as * well as properties named basedir or ant.file. - * + * @param props properties to copy to the new project * @since Ant 1.6 */ private void addAlmostAll(Hashtable props) { @@ -554,6 +577,7 @@ public class Ant extends Task { * Defaults to the current project's basedir, unless inheritall * has been set to false, in which case it doesn't have a default * value. This will override the basedir setting of the called project. + * @param d new directory */ public void setDir(File d) { this.dir = d; @@ -563,6 +587,7 @@ public class Ant extends Task { * The build file to use. * Defaults to "build.xml". This file is expected to be a filename relative * to the dir attribute given. + * @param s build file to use */ public void setAntfile(String s) { // @note: it is a string and not a file to handle relative/absolute @@ -574,6 +599,7 @@ public class Ant extends Task { /** * The target of the new Ant project to execute. * Defaults to the new project's default target. + * @param s target to invoke */ public void setTarget(String s) { if (s.equals("")) { @@ -588,6 +614,7 @@ public class Ant extends Task { * This is relative to the value of the dir attribute * if it has been set or to the base directory of the * current project otherwise. + * @param s file to which the output should go to */ public void setOutput(String s) { this.output = s; @@ -596,6 +623,7 @@ public class Ant extends Task { /** * Property to pass to the new project. * The property is passed as a 'user property' + * @return new property created */ public Property createProperty() { if (newProject == null) { @@ -611,6 +639,7 @@ public class Ant extends Task { /** * Reference element identifying a data type to carry * over to the new project. + * @param r reference to add */ public void addReference(Reference r) { references.addElement(r); @@ -619,6 +648,7 @@ public class Ant extends Task { /** * Set of properties to pass to the new project. * + * @param ps property set to add * @since Ant 1.6 */ public void addPropertyset(PropertySet ps) { diff --git a/src/main/org/apache/tools/ant/taskdefs/AntStructure.java b/src/main/org/apache/tools/ant/taskdefs/AntStructure.java index 04971c6bb..4bfca28d4 100644 --- a/src/main/org/apache/tools/ant/taskdefs/AntStructure.java +++ b/src/main/org/apache/tools/ant/taskdefs/AntStructure.java @@ -96,6 +96,7 @@ public class AntStructure extends Task { /** * The output file. + * @param output the output file */ public void setOutput(File output) { this.output = output; @@ -358,6 +359,8 @@ public class AntStructure extends Task { /** * Does this String match the XML-NMTOKEN production? + * @param s the string to test + * @return true if the string matche the XML-NMTOKEN */ protected boolean isNmtoken(String s) { final int length = s.length(); @@ -377,6 +380,8 @@ public class AntStructure extends Task { * *

Otherwise they are not suitable as an enumerated attribute, * for example.

+ * @param s the array of string to test + * @return true if all the strings in the array math XML-NMTOKEN */ protected boolean areNmtokens(String[] s) { for (int i = 0; i < s.length; i++) { diff --git a/src/main/org/apache/tools/ant/taskdefs/Available.java b/src/main/org/apache/tools/ant/taskdefs/Available.java index a90c0ae4e..f36ecb64b 100644 --- a/src/main/org/apache/tools/ant/taskdefs/Available.java +++ b/src/main/org/apache/tools/ant/taskdefs/Available.java @@ -202,6 +202,7 @@ public class Available extends Task implements Condition { * setType(Available.FileDir) to make Ant's Introspection * mechanism do the work and also to encapsulate operations on * the type in its own class. + * @param type the type of resource */ public void setType(String type) { log("DEPRECATED - The setType(String) method has been deprecated." @@ -510,13 +511,13 @@ public class Available extends Task implements Condition { */ public static class FileDir extends EnumeratedAttribute { - private static final String[] values = {"file", "dir"}; + private static final String[] VALUES = {"file", "dir"}; /** * @see EnumeratedAttribute#getValues */ public String[] getValues() { - return values; + return VALUES; } /** diff --git a/src/main/org/apache/tools/ant/taskdefs/Basename.java b/src/main/org/apache/tools/ant/taskdefs/Basename.java index 1abae7979..4e9fc24fc 100644 --- a/src/main/org/apache/tools/ant/taskdefs/Basename.java +++ b/src/main/org/apache/tools/ant/taskdefs/Basename.java @@ -95,14 +95,16 @@ public class Basename extends Task { private String suffix; /** - * File or directory to get base name from. - */ + * file or directory to get base name from + * @param file file or directory to get base name from + */ public void setFile(File file) { this.file = file; } /** * Property to set base name to. + * @param property name of property */ public void setProperty(String property) { this.property = property; @@ -110,13 +112,17 @@ public class Basename extends Task { /** * Optional suffix to remove from base name. + * @param suffix suffix to remove from base name */ public void setSuffix(String suffix) { this.suffix = suffix; } - - // The method executing the task + /** + * do the work + * @throws BuildException if required attributes are not supplied + * property and attribute are required attributes + */ public void execute() throws BuildException { if (property == null) { throw new BuildException("property attribute required", getLocation()); diff --git a/src/main/org/apache/tools/ant/taskdefs/BuildNumber.java b/src/main/org/apache/tools/ant/taskdefs/BuildNumber.java index 90e7b0417..579970585 100644 --- a/src/main/org/apache/tools/ant/taskdefs/BuildNumber.java +++ b/src/main/org/apache/tools/ant/taskdefs/BuildNumber.java @@ -1,7 +1,7 @@ /* * The Apache Software License, Version 1.1 * - * Copyright (c) 2002 The Apache Software Foundation. All rights + * Copyright (c) 2002-2003 The Apache Software Foundation. All rights * reserved. * * Redistribution and use in source and binary forms, with or without @@ -60,6 +60,7 @@ import java.io.IOException; import java.util.Properties; import org.apache.tools.ant.BuildException; import org.apache.tools.ant.Task; +import org.apache.tools.ant.Project; import org.apache.tools.ant.util.FileUtils; /** @@ -86,7 +87,7 @@ public class BuildNumber private static final String DEFAULT_FILENAME = DEFAULT_PROPERTY_NAME; /** The File in which the build number is stored. */ - private File m_file; + private File myFile; /** @@ -96,7 +97,7 @@ public class BuildNumber * @param file the file in which build number is stored. */ public void setFile(final File file) { - m_file = file; + myFile = file; } @@ -107,7 +108,7 @@ public class BuildNumber */ public void execute() throws BuildException { - File savedFile = m_file; // may be altered in validate + File savedFile = myFile; // may be altered in validate validate(); @@ -121,13 +122,13 @@ public class BuildNumber FileOutputStream output = null; try { - output = new FileOutputStream(m_file); + output = new FileOutputStream(myFile); final String header = "Build Number for ANT. Do not edit!"; properties.save(output, header); } catch (final IOException ioe) { - final String message = "Error while writing " + m_file; + final String message = "Error while writing " + myFile; throw new BuildException(message, ioe); } finally { @@ -135,9 +136,10 @@ public class BuildNumber try { output.close(); } catch (final IOException ioe) { + getProject().log("error closing output stream " + ioe, Project.MSG_ERR); } } - m_file = savedFile; + myFile = savedFile; } //Finally set the property @@ -163,7 +165,7 @@ public class BuildNumber return Integer.parseInt(buildNumber); } catch (final NumberFormatException nfe) { final String message = - m_file + " contains a non integer build number: " + buildNumber; + myFile + " contains a non integer build number: " + buildNumber; throw new BuildException(message, nfe); } @@ -183,7 +185,7 @@ public class BuildNumber try { final Properties properties = new Properties(); - input = new FileInputStream(m_file); + input = new FileInputStream(myFile); properties.load(input); return properties; } catch (final IOException ioe) { @@ -193,6 +195,7 @@ public class BuildNumber try { input.close(); } catch (final IOException ioe) { + getProject().log("error closing input stream " + ioe, Project.MSG_ERR); } } } @@ -206,29 +209,29 @@ public class BuildNumber */ private void validate() throws BuildException { - if (null == m_file) { - m_file = getProject().resolveFile(DEFAULT_FILENAME); + if (null == myFile) { + myFile = getProject().resolveFile(DEFAULT_FILENAME); } - if (!m_file.exists()) { + if (!myFile.exists()) { try { - FileUtils.newFileUtils().createNewFile(m_file); + FileUtils.newFileUtils().createNewFile(myFile); } catch (final IOException ioe) { final String message = - m_file + " doesn't exist and new file can't be created."; + myFile + " doesn't exist and new file can't be created."; throw new BuildException(message, ioe); } } - if (!m_file.canRead()) { - final String message = "Unable to read from " + m_file + "."; + if (!myFile.canRead()) { + final String message = "Unable to read from " + myFile + "."; throw new BuildException(message); } - if (!m_file.canWrite()) { - final String message = "Unable to write to " + m_file + "."; + if (!myFile.canWrite()) { + final String message = "Unable to write to " + myFile + "."; throw new BuildException(message); }