diff --git a/src/main/org/apache/tools/ant/Target.java b/src/main/org/apache/tools/ant/Target.java
index 9fc17ad4f..148a81d65 100644
--- a/src/main/org/apache/tools/ant/Target.java
+++ b/src/main/org/apache/tools/ant/Target.java
@@ -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
@@ -59,29 +59,58 @@ import java.util.Vector;
import java.util.StringTokenizer;
/**
- * This class implements a target object with required parameters.
+ * Class to implement a target object with required parameters.
*
* @author James Davidson duncan@x180.com
*/
-
public class Target implements TaskContainer {
+ /** Name of this target. */
private String name;
+ /** The "if" condition to test on execution. */
private String ifCondition = "";
+ /** The "unless" condition to test on execution. */
private String unlessCondition = "";
+ /** List of targets this target is dependent on. */
private Vector dependencies = new Vector(2);
+ /** Children of this target (tasks and data types). */
private Vector children = new Vector(5);
+ /** Project this target belongs to. */
private Project project;
+ /** Description of this target, if any. */
private String description = null;
+ /** Sole constructor. */
+ public Target() {
+ }
+
+ /**
+ * Sets the project this target belongs to.
+ *
+ * @param project The project this target belongs to.
+ * Must not be null.
+ */
public void setProject(Project project) {
this.project = project;
}
+ /**
+ * Returns the project this target belongs to.
+ *
+ * @return The project this target belongs to, or null if
+ * the project has not been set yet.
+ */
public Project getProject() {
return project;
}
+ /**
+ * Sets the list of targets this target is dependent on.
+ * The targets themselves are not resolved at this time.
+ *
+ * @param depS A comma-separated list of targets this target
+ * depends on. Must not be null.
+ */
public void setDepends(String depS) {
if (depS.length() > 0) {
StringTokenizer tok =
@@ -89,7 +118,7 @@ public class Target implements TaskContainer {
while (tok.hasMoreTokens()) {
String token = tok.nextToken().trim();
- //Make sure the dependency is not empty string
+ // Make sure the dependency is not empty string
if (token.equals("") || token.equals(",")) {
throw new BuildException( "Syntax Error: Depend attribute " +
"for target \"" + getName() +
@@ -98,8 +127,8 @@ public class Target implements TaskContainer {
addDependency(token);
- //Make sure that depends attribute does not
- //end in a ,
+ // Make sure that depends attribute does not
+ // end in a ,
if (tok.hasMoreTokens()) {
token = tok.nextToken();
if (!tok.hasMoreTokens() || !token.equals(",")) {
@@ -112,26 +141,48 @@ public class Target implements TaskContainer {
}
}
+ /**
+ * Sets the name of this target.
+ *
+ * @param name The name of this target. Should not be null.
+ */
public void setName(String name) {
this.name = name;
}
+ /**
+ * Returns the name of this target.
+ *
+ * @return the name of this target, or null if the
+ * name has not been set yet.
+ */
public String getName() {
return name;
}
+ /**
+ * Adds a task to this target.
+ *
+ * @param task The task to be added. Must not be null.
+ */
public void addTask(Task task) {
children.addElement(task);
}
+ /**
+ * Adds the wrapper for a data type element to this target.
+ *
+ * @param r The wrapper for the data type element to be added.
+ * Must not be null.
+ */
public void addDataType(RuntimeConfigurable r) {
children.addElement(r);
}
/**
- * Get the current set of tasks to be executed by this target.
+ * Returns the current set of tasks to be executed by this target.
*
- * @return The current set of tasks.
+ * @return an array of the tasks currently within this target
*/
public Task[] getTasks() {
Vector tasks = new Vector(children.size());
@@ -148,34 +199,106 @@ public class Target implements TaskContainer {
return retval;
}
+ /**
+ * Adds a dependency to this target.
+ *
+ * @param dependency The name of a target this target is dependent on.
+ * Must not be null.
+ */
public void addDependency(String dependency) {
dependencies.addElement(dependency);
}
+ /**
+ * Returns an enumeration of the dependencies of this target.
+ *
+ * @return an enumeration of the dependencies of this target
+ */
public Enumeration getDependencies() {
return dependencies.elements();
}
+ /**
+ * Sets the "if" condition to test on execution. This is the
+ * name of a property to test for existence - if the property
+ * is not set, the task will not execute. The property goes
+ * through property substitution once before testing, so if
+ * property foo has value bar, setting
+ * the "if" condition to ${foo}_x will mean that the
+ * task will only execute if property bar_x is set.
+ *
+ * @param property The property condition to test on execution.
+ * May be null, in which case
+ * no "if" test is performed.
+ */
public void setIf(String property) {
this.ifCondition = (property == null) ? "" : property;
}
+ /**
+ * Sets the "unless" condition to test on execution. This is the
+ * name of a property to test for existence - if the property
+ * is set, the task will not execute. The property goes
+ * through property substitution once before testing, so if
+ * property foo has value bar, setting
+ * the "unless" condition to ${foo}_x will mean that the
+ * task will only execute if property bar_x isn't set.
+ *
+ * @param property The property condition to test on execution.
+ * May be null, in which case
+ * no "unless" test is performed.
+ */
public void setUnless(String property) {
this.unlessCondition = (property == null) ? "" : property;
}
+ /**
+ * Sets the description of this target.
+ *
+ * @param description The description for this target.
+ * May be null, indicating that no
+ * description is available.
+ */
public void setDescription(String description) {
this.description = description;
}
+ /**
+ * Returns the description of this target.
+ *
+ * @return the description of this target, or null if no
+ * description is available.
+ */
public String getDescription() {
return description;
}
+ /**
+ * Returns the name of this target.
+ *
+ * @return the name of this target, or null if the
+ * name has not been set yet.
+ */
public String toString() {
return name;
}
+ /**
+ * Executes the target if the "if" and "unless" conditions are
+ * satisfied. Dependency checking should be done before calling this
+ * method, as it does no checking of its own. If either the "if"
+ * or "unless" test prevents this target from being executed, a verbose
+ * message is logged giving the reason. It is recommended that clients
+ * of this class call performTasks rather than this method so that
+ * appropriate build events are fired.
+ *
+ * @exception BuildException if any of the tasks fail or if a data type
+ * configuration fails.
+ *
+ * @see #performTasks()
+ * @see #setIf(String)
+ * @see #setUnless(String)
+ */
public void execute() throws BuildException {
if (testIfCondition() && testUnlessCondition()) {
Enumeration enum = children.elements();
@@ -198,6 +321,13 @@ public class Target implements TaskContainer {
}
}
+ /**
+ * Performs the tasks within this target (if the conditions are met),
+ * firing target started/target finished messages around a call to
+ * execute.
+ *
+ * @see #execute()
+ */
public final void performTasks() {
try {
project.fireTargetStarted(this);
@@ -210,13 +340,45 @@ public class Target implements TaskContainer {
}
}
- void replaceChild(Task el, Object o) {
- int index = -1;
+ /**
+ * Replaces all occurrences of the given task in the list
+ * of children with the replacement data type wrapper.
+ *
+ * @param el The task to replace.
+ * Must not be null.
+ * @param o The data type wrapper to replace el with.
+ */
+ void replaceChild(Task el, RuntimeConfigurable o) {
+ int index;
while ((index = children.indexOf(el)) >= 0) {
children.setElementAt(o, index);
}
}
+ /**
+ * Replaces all occurrences of the given task in the list
+ * of children with the replacement task.
+ *
+ * @param el The task to replace.
+ * Must not be null.
+ * @param o The task to replace el with.
+ */
+ void replaceChild(Task el, Task o) {
+ int index;
+ while ((index = children.indexOf(el)) >= 0) {
+ children.setElementAt(o, index);
+ }
+ }
+
+ /**
+ * Tests whether or not the "if" condition is satisfied.
+ *
+ * @return whether or not the "if" condition is satisfied. If no
+ * condition (or an empty condition) has been set,
+ * true is returned.
+ *
+ * @see #setIf(String)
+ */
private boolean testIfCondition() {
if ("".equals(ifCondition)) {
return true;
@@ -226,6 +388,15 @@ public class Target implements TaskContainer {
return project.getProperty(test) != null;
}
+ /**
+ * Tests whether or not the "unless" condition is satisfied.
+ *
+ * @return whether or not the "unless" condition is satisfied. If no
+ * condition (or an empty condition) has been set,
+ * true is returned.
+ *
+ * @see #setUnless(String)
+ */
private boolean testUnlessCondition() {
if ("".equals(unlessCondition)) {
return true;
@@ -233,5 +404,4 @@ public class Target implements TaskContainer {
String test = project.replaceProperties(unlessCondition);
return project.getProperty(test) == null;
}
-
}
diff --git a/src/main/org/apache/tools/ant/UnknownElement.java b/src/main/org/apache/tools/ant/UnknownElement.java
index 1812082f2..b997ced9f 100644
--- a/src/main/org/apache/tools/ant/UnknownElement.java
+++ b/src/main/org/apache/tools/ant/UnknownElement.java
@@ -57,8 +57,9 @@ package org.apache.tools.ant;
import java.util.Vector;
/**
- * Wrapper class that holds all information necessary to create a task
- * or data type that did not exist when Ant started.
+ * Wrapper class that holds all the information necessary to create a task
+ * or data type that did not exist when Ant started, or one which
+ * has had its definition updated to use a different implementation class.
*
* @author Stefan Bodewig
*/
@@ -66,7 +67,8 @@ public class UnknownElement extends Task {
/**
* Holds the name of the task/type or nested child element of a
- * task/type that hasn't been defined at parser time.
+ * task/type that hasn't been defined at parser time or has
+ * been redefined since original creation.
*/
private String elementName;
@@ -76,29 +78,36 @@ public class UnknownElement extends Task {
private Object realThing;
/**
- * Childelements, holds UnknownElement instances.
+ * List of child elements (UnknownElements).
*/
private Vector children = new Vector();
/**
- * Create an UnknownElement for the given element name.
+ * Creates an UnknownElement for the given element name.
*
- * @param elementName the name of the unknown element.
+ * @param elementName The name of the unknown element.
+ * Must not be null.
*/
public UnknownElement (String elementName) {
this.elementName = elementName;
}
/**
- * @return the corresponding XML element name.
+ * Returns the name of the XML element which generated this unknown
+ * element.
+ *
+ * @return the name of the XML element which generated this unknown
+ * element.
*/
public String getTag() {
return elementName;
}
/**
- * creates the real object instance, creates child elements, configures
- * the attributes of the real object.
+ * Creates the real object instance and child elements, then configures
+ * the attributes and text of the real object. This unknown element
+ * is then replaced with the real object in the containing target's list
+ * of children.
*
* @exception BuildException if the configuration fails
*/
@@ -114,16 +123,16 @@ public class UnknownElement extends Task {
wrapper.maybeConfigure(project);
if (realThing instanceof Task) {
- target.replaceChild(this, realThing);
+ target.replaceChild(this, (Task) realThing);
} else {
target.replaceChild(this, wrapper);
}
}
/**
- * Handle output sent to System.out by this task or its real task.
+ * Handles output sent to System.out by this task or its real task.
*
- * @param line the output string
+ * @param line The line of output to log. Should not be null.
*/
protected void handleOutput(String line) {
if (realThing instanceof Task) {
@@ -134,9 +143,9 @@ public class UnknownElement extends Task {
}
/**
- * Handle error output sent to System.err by this task or its real task.
+ * Handles error output sent to System.err by this task or its real task.
*
- * @param line the error string
+ * @param line The error line to log. Should not be null.
*/
protected void handleErrorOutput(String line) {
if (realThing instanceof Task) {
@@ -147,7 +156,8 @@ public class UnknownElement extends Task {
}
/**
- * Called when the real task has been configured for the first time.
+ * Executes the real object if it's a task. If it's not a task
+ * (e.g. a data type) then this method does nothing.
*/
public void execute() {
if (realThing == null) {
@@ -165,17 +175,18 @@ public class UnknownElement extends Task {
/**
* Adds a child element to this element.
*
- * @param child the child element
+ * @param child The child element to add. Must not be null.
*/
public void addChild(UnknownElement child) {
children.addElement(child);
}
/**
- * Creates child elements, creates children of the children, sets
- * attributes of the child elements.
+ * Creates child elements, creates children of the children
+ * (recursively), and sets attributes of the child elements.
*
- * @param parent the configured object for the parent
+ * @param parent The configured object for the parent.
+ * Must not be null.
* @exception BuildException if the children cannot be configured.
*/
protected void handleChildren(Object parent,
@@ -215,8 +226,14 @@ public class UnknownElement extends Task {
}
/**
- * Creates a named task or data type - if it is a task,
- * configure it up to the init() stage.
+ * Creates a named task or data type. If the real object is a task,
+ * it is configured up to the init() stage.
+ *
+ * @param ue The unknown element to create the real object for.
+ * Must not be null.
+ * @param w Ignored in this implementation.
+ *
+ * @return the task or data type represented by the given unknown element.
*/
protected Object makeObject(UnknownElement ue, RuntimeConfigurable w) {
Object o = makeTask(ue, w, true);
@@ -230,7 +247,19 @@ public class UnknownElement extends Task {
}
/**
- * Create a named task and configure it up to the init() stage.
+ * Creates a named task and configures it up to the init() stage.
+ *
+ * @param ue The UnknownElement to create the real task for.
+ * Must not be null.
+ * @param w Ignored.
+ * @param onTopLevel Whether or not this is definitely trying to create
+ * a task. If this is true and the
+ * task name is not recognised, a BuildException
+ * is thrown.
+ *
+ * @return the task specified by the given unknown element, or
+ * null if the task name is not recognised and
+ * onTopLevel is false.
*/
protected Task makeTask(UnknownElement ue, RuntimeConfigurable w,
boolean onTopLevel) {
@@ -248,6 +277,16 @@ public class UnknownElement extends Task {
return task;
}
+ /**
+ * Returns a very verbose exception for when a task/data type cannot
+ * be found.
+ *
+ * @param what The kind of thing being created. For example, when
+ * a task name could not be found, this would be
+ * "task". Should not be null.
+ * @param elementName The name of the element which could not be found.
+ * Should not be null.
+ */
protected BuildException getNotFoundException(String what,
String elementName) {
String lSep = System.getProperty("line.separator");
@@ -288,7 +327,7 @@ public class UnknownElement extends Task {
}
/**
- * Get the name to use in logging messages.
+ * Returns the name to use in logging messages.
*
* @return the name to use in logging messages.
*/
@@ -298,12 +337,13 @@ public class UnknownElement extends Task {
}
/**
- * Return the task instance after it has been created and if it is a task.
+ * Returns the task instance after it has been created and if it is a task.
*
- * @return a task instance or null if the real object is not a task
+ * @return a task instance or null if the real object is not
+ * a task.
*/
public Task getTask() {
- if (realThing != null && realThing instanceof Task) {
+ if (realThing instanceof Task) {
return (Task) realThing;
}
return null;