Notes:
The JavaDocs for ProjectComponent.setProject say (and I haven't changed
this):
<quote>
This method is used by Project when a component is added to it so that
the component has access to the functions of the project. It should not
be used for any other purpose.
</quote>
Looking for where it actually *is* used, I get 17 hits
(mentally prepend org.apache.tools.ant to each package name):
IntrospectionHelper.createAttributeSetter (Method, Class)
IntrospectionHelper.createElement (Project, Object, String)
Project.createDataType (String)
Project.createTask (String)
ProjectHelper.NestedElementHandler.init (String, AttributeList)
ProjectHelper.TaskHandler.init (String, AttributeList)
Task.getReplacement()
taskdefs.Ant.copyReference (String, String)
taskdefs.Ant.createProperty ()
taskdefs.Ant.overrideProperties()
taskdefs.Available.eval()
taskdefs.condition.ConditionBase.ConditionEnumeration.nextElement()
types.FileList.FileList(FileList)
types.FileSet.FileSet(FileSet)
types.Mapper.Mapper(Project)
types.Path.list()
types.Path.Path(Project)
My guess is it's easier to remove the stipulation from the JavaDocs than
it is to fix all of those up... but do we need to worry about this?
Index: src/main/org/apache/tools/ant/Location.java
===================================================================
RCS file:
/home/cvspublic/jakarta-ant/src/main/org/apache/tools/ant/Location.java,v
retrieving revision 1.5
diff -u -r1.5 Location.java
--- src/main/org/apache/tools/ant/Location.java 10 Jan 2002 11:21:19 -0000
1.5
+++ src/main/org/apache/tools/ant/Location.java 22 Feb 2002 09:54:36 -0000
@@ -1,7 +1,7 @@
/*
* The Apache Software License, Version 1.1
*
- * Copyright (c) 2000 The Apache Software Foundation. All rights
+ * Copyright (c) 2000,2002 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
@@ -55,13 +55,20 @@
package org.apache.tools.ant;
/**
- * Stores the file name and line number in a file.
+ * Stores the location of a piece of text within a file (file name,
+ * line number and column number). Note that the column number is
+ * currently ignored.
*/
public class Location {
+
+ /** Name of the file. */
private String fileName;
+ /** Line number within the file. */
private int lineNumber;
+ /** Column number within the file. */
private int columnNumber;
+ /** Location to use when one is needed but no information is available */
public final static Location UNKNOWN_LOCATION = new Location();
/**
@@ -72,14 +79,28 @@
}
/**
- * Creates a location consisting of a file name but no line number.
+ * Creates a location consisting of a file name but no line number or
+ * column number.
+ *
+ * @param fileName The name of the file. May be <code>null</code>,
+ * in which case the location is equivalent to
+ * [EMAIL PROTECTED] #UNKNOWN_LOCATION UNKNOWN_LOCATION}.
*/
public Location(String fileName) {
this(fileName, 0, 0);
}
/**
- * Creates a location consisting of a file name and line number.
+ * Creates a location consisting of a file name, line number and
+ * column number.
+ *
+ * @param fileName The name of the file. May be <code>null</code>,
+ * in which case the location is equivalent to
+ * [EMAIL PROTECTED] #UNKNOWN_LOCATION UNKNOWN_LOCATION}.
+ *
+ * @param lineNumber Line number within the file. Use 0 for unknown
+ * positions within a file.
+ * @param columnNumber Column number within the line.
*/
public Location(String fileName, int lineNumber, int columnNumber) {
this.fileName = fileName;
@@ -88,9 +109,14 @@
}
/**
- * Returns the file name, line number and a trailing space. An error
- * message can be appended easily. For unknown locations, returns
- * an empty string.
+ * Returns the file name, line number, a colon and a trailing space.
+ * An error message can be appended easily. For unknown locations, an
+ * empty string is returned.
+ *
+ * @return a String of the form <code>"fileName: lineNumber: "</code>
+ * if both file name and line number are known,
+ * <code>"fileName: "</code> if only the file name is known,
+ * and the empty string for unknown locations.
*/
public String toString() {
StringBuffer buf = new StringBuffer();
Index: src/main/org/apache/tools/ant/Main.java
===================================================================
RCS file: /home/cvspublic/jakarta-ant/src/main/org/apache/tools/ant/Main.java,v
retrieving revision 1.56
diff -u -r1.56 Main.java
--- src/main/org/apache/tools/ant/Main.java 2 Feb 2002 00:13:32 -0000
1.56
+++ src/main/org/apache/tools/ant/Main.java 22 Feb 2002 09:54:39 -0000
@@ -78,57 +78,63 @@
*/
public class Main {
- /** The default build file name */
+ /** The default build file name. */
public final static String DEFAULT_BUILD_FILENAME = "build.xml";
- /** Our current message output status. Follows Project.MSG_XXX */
+ /** Our current message output status. Follows Project.MSG_XXX. */
private int msgOutputLevel = Project.MSG_INFO;
- /** File that we are using for configuration */
- private File buildFile; /** null */
+ /** File that we are using for configuration. */
+ private File buildFile; /* null */
- /** Stream that we are using for logging */
+ /** Stream to use for logging. */
private PrintStream out = System.out;
- /** Stream that we are using for logging error messages */
+ /** Stream that we are using for logging error messages. */
private PrintStream err = System.err;
- /** The build targets */
+ /** The build targets. */
private Vector targets = new Vector(5);
- /** Set of properties that can be used by tasks */
+ /** Set of properties that can be used by tasks. */
private Properties definedProps = new Properties();
- /** Names of classes to add as listeners to project */
+ /** Names of classes to add as listeners to project. */
private Vector listeners = new Vector(5);
- /** File names of property files to load on startup */
+ /** File names of property files to load on startup. */
private Vector propertyFiles = new Vector(5);
-
+
/**
- * The Ant logger class. There may be only one logger. It will have the
- * right to use the 'out' PrintStream. The class must implements the
BuildLogger
- * interface
+ * The Ant logger class. There may be only one logger. It will have
+ * the right to use the 'out' PrintStream. The class must implements the
+ * BuildLogger interface.
*/
private String loggerClassname = null;
/**
- * Indicates whether output to the log is to be unadorned.
+ * Whether or not output to the log is to be unadorned.
*/
private boolean emacsMode = false;
/**
- * Indicates if this ant should be run.
+ * Whether or not this instance has successfully been
+ * constructed and is ready to run.
*/
private boolean readyToRun = false;
/**
- * Indicates we should only parse and display the project help information
+ * Whether or not we should only parse and display the project help
+ * information.
*/
private boolean projectHelp = false;
/**
- * Prints the message of the Throwable if it's not null.
+ * Prints the message of the Throwable if it (the message) is not
+ * <code>null</code>.
+ *
+ * @param t Throwable to print the message of.
+ * Must not be <code>null</code>.
*/
private static void printMessage(Throwable t) {
String message = t.getMessage();
@@ -138,7 +144,16 @@
}
/**
- * Entry point method.
+ * Creates a new instance of this class using the
+ * arguments specified, gives it any extra user properties which have been
+ * specified, and then runs the build using the classloader provided.
+ *
+ * @param args Command line arguments. Must not be <code>null</code>.
+ * @param additionalUserProperties Any extra properties to use in this
+ * build. May be <code>null</code>, which is the equivalent to
+ * passing in an empty set of properties.
+ * @param coreLoader Classloader used for core classes. May be
+ * <code>null</code> in which case the system classloader is used.
*/
public static void start(String[] args, Properties
additionalUserProperties,
ClassLoader coreLoader) {
@@ -173,20 +188,31 @@
System.exit(1);
}
}
-
-
-
+
/**
* Command line entry point. This method kicks off the building
* of a project object and executes a build using either a given
* target or the default target.
*
- * @param args Command line args.
+ * @param args Command line arguments. Must not be <code>null</code>.
*/
public static void main(String[] args) {
start(args, null, null);
}
+ // XXX: (Jon Skeet) Error handling appears to be inconsistent here.
+ // Sometimes there's just a return statement, and sometimes a
+ // BuildException is thrown. What's the rationale for when to do
+ // what?
+ /**
+ * Sole constructor, which parses and deals with command line
+ * arguments.
+ *
+ * @param args Command line arguments. Must not be <code>null</code>.
+ *
+ * @exception BuildException if the specified build file doesn't exist
+ * or is a directory.
+ */
protected Main(String[] args) throws BuildException {
String searchForThis = null;
@@ -253,7 +279,7 @@
/* Interestingly enough, we get to here when a user
* uses -Dname=value. However, in some cases, the JDK
- * goes ahead * and parses this out to args
+ * goes ahead and parses this out to args
* {"-Dname", "value"}
* so instead of parsing on "=", we just make the "-D"
* characters go away and skip one argument forward.
@@ -383,10 +409,10 @@
/**
* Helper to get the parent file for a given file.
+ * <p>
+ * Added to simulate File.getParentFile() from JDK 1.2.
*
- * <P>Added to simulate File.getParentFile() from JDK 1.2.
- *
- * @param file File
+ * @param file File to find parent of. Must not be <code>null</code>.
* @return Parent file or null if none
*/
private File getParentFile(File file) {
@@ -403,16 +429,20 @@
/**
* Search parent directories for the build file.
+ * <p>
+ * Takes the given target as a suffix to append to each
+ * parent directory in seach of a build file. Once the
+ * root of the file-system has been reached an exception
+ * is thrown.
*
- * <P>Takes the given target as a suffix to append to each
- * parent directory in seach of a build file. Once the
- * root of the file-system has been reached an exception
- * is thrown.
+ * @param start Leaf directory of search.
+ * Must not be <code>null</code>.
+ * @param suffix Suffix filename to look for in parents.
+ * Must not be <code>null</code>.
+ *
+ * @return A handle to the build file if one is found
*
- * @param suffix Suffix filename to look for in parents.
- * @return A handle to the build file
- *
- * @exception BuildException Failed to locate a build file
+ * @exception BuildException if no build file is found
*/
private File findBuildFile(String start, String suffix) throws
BuildException {
if (msgOutputLevel >= Project.MSG_INFO) {
@@ -441,7 +471,15 @@
}
/**
- * Executes the build.
+ * Executes the build. If the constructor for this instance failed
+ * (e.g. returned after issuing a warning), this method returns
+ * immediately.
+ *
+ * @param coreLoader The classloader to use to find core classes.
+ * May be <code>null</code>, in which case the
+ * system classloader is used.
+ *
+ * @exception BuildException if the build fails
*/
private void runBuild(ClassLoader coreLoader) throws BuildException {
@@ -552,6 +590,13 @@
}
}
+ /**
+ * Adds the listeners specified in the command line arguments,
+ * along with the default listener, to the specified project.
+ *
+ * @param project The project to add listeners to.
+ * Must not be <code>null</code>.
+ */
protected void addBuildListeners(Project project) {
// Add the default listener
@@ -570,6 +615,10 @@
}
}
+ // XXX: (Jon Skeet) Any reason for writing a message and then using a bare
+ // RuntimeException rather than just using a BuildException here? Is it
+ // in case the message could end up being written to no loggers (as the
loggers
+ // could have failed to be created due to this failure)?
/**
* Creates the default build logger for sending build events to the ant
log.
*/
@@ -603,7 +652,7 @@
}
/**
- * Prints the usage of how to use this class to System.out
+ * Prints the usage information for this class to <code>System.out</code>.
*/
private static void printUsage() {
String lSep = System.getProperty("line.separator");
@@ -629,12 +678,30 @@
System.out.println(msg.toString());
}
+ /**
+ * Prints the Ant version information to <code>System.out</code>.
+ *
+ * @exception BuildException if the version information is unavailable
+ */
private static void printVersion() throws BuildException {
System.out.println(getAntVersion());
}
+ /**
+ * Cache of the Ant version information when it has been loaded.
+ */
private static String antVersion = null;
+ /**
+ * Returns the Ant version information, if available. Once the information
+ * has been loaded once, it's cached and returned from the cache on future
+ * calls.
+ *
+ * @return the Ant version information as a String
+ * (always non-<code>null</code>)
+ *
+ * @exception BuildException if the version information is unavailable
+ */
public static synchronized String getAntVersion() throws BuildException {
if (antVersion == null) {
try {
@@ -662,7 +729,11 @@
}
/**
- * Print the project description, if any
+ * Prints the description of a project (if there is one) to
+ * <code>System.out</code>.
+ *
+ * @param project The project to display a description of.
+ * Must not be <code>null</code>.
*/
private static void printDescription(Project project) {
if (project.getDescription() != null) {
@@ -671,7 +742,13 @@
}
/**
- * Print out a list of all targets in the current buildfile
+ * Prints a list of all targets in the specified project to
+ * <code>System.out</code>, optionally including subtargets.
+ *
+ * @param project The project to display a description of.
+ * Must not be <code>null</code>.
+ * @param printSubTargets Whether or not subtarget names should also be
+ * printed.
*/
private static void printTargets(Project project, boolean printSubTargets)
{
// find the target with the longest name
@@ -717,7 +794,14 @@
}
/**
- * Search for the insert position to keep names a sorted list of Strings
+ * Searches for the correct place to insert a name into a list so as
+ * to keep the list sorted alphabetically.
+ *
+ * @param names The current list of names. Must not be <code>null</code>.
+ * @param name The name to find a place for.
+ * Must not be <code>null</code>.
+ *
+ * @return the correct place in the list for the given name
*/
private static int findTargetPosition(Vector names, String name) {
int res = names.size();
@@ -730,7 +814,8 @@
}
/**
- * Output a formatted list of target names with an optional description
+ * Writes a formatted list of target names to <code>System.out</code>
+ * with an optional description
*/
private static void printTargets(Vector names, Vector descriptions, String
heading, int maxlen) {
// now, start printing the targets and their descriptions
Index: src/main/org/apache/tools/ant/NoBannerLogger.java
===================================================================
RCS file:
/home/cvspublic/jakarta-ant/src/main/org/apache/tools/ant/NoBannerLogger.java,v
retrieving revision 1.5
diff -u -r1.5 NoBannerLogger.java
--- src/main/org/apache/tools/ant/NoBannerLogger.java 10 Jan 2002 11:21:19
-0000 1.5
+++ src/main/org/apache/tools/ant/NoBannerLogger.java 22 Feb 2002 09:54:41
-0000
@@ -1,7 +1,7 @@
/*
* The Apache Software License, Version 1.1
*
- * Copyright (c) 2000-2001 The Apache Software Foundation. All rights
+ * Copyright (c) 2000-2002 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
@@ -63,16 +63,44 @@
*/
public class NoBannerLogger extends DefaultLogger {
+ /**
+ * Name of the current target, if it should
+ * be displayed on the next message. This is
+ * set when a target starts building, and reset
+ * to <code>null</code> after the first message for
+ * the target is logged.
+ */
protected String targetName;
+ /** Sole constructor. */
+ public NoBannerLogger() {
+ }
+
+ /**
+ * Notes the name of the target so it can be logged
+ * if it generates any messages.
+ *
+ * @param event A BuildEvent containing target information.
+ * Must not be <code>null</code>.
+ */
public void targetStarted(BuildEvent event) {
targetName = event.getTarget().getName();
}
+ /** Resets the current target name to <code>null</code>. */
public void targetFinished(BuildEvent event) {
targetName = null;
}
+ /**
+ * Logs a message for a target if it is of an appropriate
+ * priority, also logging the name of the target if this
+ * is the first message which needs to be logged for the
+ * target.
+ *
+ * @param event A BuildEvent containing message information.
+ * Must not be <code>null</code>.
+ */
public void messageLogged(BuildEvent event) {
if( event.getPriority() > msgOutputLevel ||
Index: src/main/org/apache/tools/ant/PathTokenizer.java
===================================================================
RCS file:
/home/cvspublic/jakarta-ant/src/main/org/apache/tools/ant/PathTokenizer.java,v
retrieving revision 1.6
diff -u -r1.6 PathTokenizer.java
--- src/main/org/apache/tools/ant/PathTokenizer.java 10 Jan 2002 11:21:19
-0000 1.6
+++ src/main/org/apache/tools/ant/PathTokenizer.java 22 Feb 2002 09:54:43
-0000
@@ -1,7 +1,7 @@
/*
* The Apache Software License, Version 1.1
*
- * Copyright (c) 2000 The Apache Software Foundation. All rights
+ * Copyright (c) 2000,2002 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
@@ -62,7 +62,7 @@
* that path.
*
* The path can use path separators of either ':' or ';' and file separators
- * of either '/' or '\'
+ * of either '/' or '\'.
*
* @author Conor MacNeill ([EMAIL PROTECTED])
*
@@ -74,21 +74,35 @@
private StringTokenizer tokenizer;
/**
- * A String which stores any path components which have been read ahead.
+ * A String which stores any path components which have been read ahead
+ * due to DOS filesystem compensation.
*/
private String lookahead = null;
/**
- * Flag to indicate whether we are running on a platform with a DOS style
- * filesystem
+ * Flag to indicate whether or not we are running on a platform with a
+ * DOS style filesystem
*/
private boolean dosStyleFilesystem;
+ /**
+ * Constructs a path tokenizer for the specified path.
+ *
+ * @param path The path to tokenize. Must not be <code>null</code>.
+ */
public PathTokenizer(String path) {
tokenizer = new StringTokenizer(path, ":;", false);
dosStyleFilesystem = File.pathSeparatorChar == ';';
}
+ /**
+ * Tests if there are more path elements available from this tokenizer's
+ * path. If this method returns <code>true</code>, then a subsequent call
+ * to nextToken will successfully return a token.
+ *
+ * @return <code>true</code> if and only if there is at least one token
+ * in the string after the current position; <code>false</code> otherwise.
+ */
public boolean hasMoreTokens() {
if (lookahead != null) {
return true;
@@ -97,6 +111,14 @@
return tokenizer.hasMoreTokens();
}
+ /**
+ * Returns the next path element from this tokenizer.
+ *
+ * @return the next path element from this tokenizer.
+ *
+ * @exception NoSuchElementException if there are no more elements in this
+ * tokenizer's path.
+ */
public String nextToken() throws NoSuchElementException {
String token = null;
if (lookahead != null) {
Index: src/main/org/apache/tools/ant/ProjectComponent.java
===================================================================
RCS file:
/home/cvspublic/jakarta-ant/src/main/org/apache/tools/ant/ProjectComponent.java,v
retrieving revision 1.1
diff -u -r1.1 ProjectComponent.java
--- src/main/org/apache/tools/ant/ProjectComponent.java 4 Aug 2001 14:30:36
-0000 1.1
+++ src/main/org/apache/tools/ant/ProjectComponent.java 22 Feb 2002 09:54:44
-0000
@@ -1,7 +1,7 @@
/*
* The Apache Software License, Version 1.1
*
- * Copyright (c) 2001 The Apache Software Foundation. All rights
+ * Copyright (c) 2001,2002 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
@@ -55,30 +55,36 @@
package org.apache.tools.ant;
/**
- * Base class for components of a project, including tasks and data types.
Provides
- * common facilities.
+ * Base class for components of a project, including tasks and data types.
+ * Provides common facilities.
*
* @author <a href="mailto:[EMAIL PROTECTED]">Conor MacNeill</a>
*/
public abstract class ProjectComponent {
+ /** Project object of this component. */
protected Project project = null;
+ /** Sole constructor. */
+ public ProjectComponent() {
+ }
+
/**
* Sets the project object of this component. This method is used by
- * project when a component is added to it so that the component has
+ * Project when a component is added to it so that the component has
* access to the functions of the project. It should not be used
* for any other purpose.
*
* @param project Project in whose scope this component belongs.
+ * Must not be <code>null</code>.
*/
public void setProject(Project project) {
this.project = project;
}
/**
- * Get the Project to which this component belongs
+ * Returns the project to which this component belongs.
*
* @return the components's project.
*/
@@ -87,18 +93,18 @@
}
/**
- * Log a message with the default (INFO) priority.
+ * Logs a message with the default (INFO) priority.
*
- * @param the message to be logged.
+ * @param msg The message to be logged. Should not be <code>null</code>.
*/
public void log(String msg) {
log(msg, Project.MSG_INFO);
}
/**
- * Log a mesage with the give priority.
+ * Logs a mesage with the given priority.
*
- * @param the message to be logged.
+ * @param msg The message to be logged. Should not be <code>null</code>.
* @param msgLevel the message priority at which this message is to be
logged.
*/
public void log(String msg, int msgLevel) {
@@ -107,4 +113,3 @@
}
}
}
-
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
