You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@ant.apache.org by js...@apache.org on 2002/03/01 15:47:56 UTC
cvs commit: jakarta-ant/src/main/org/apache/tools/ant Task.java
jskeet 02/03/01 06:47:56
Modified: src/main/org/apache/tools/ant Task.java
Log:
JavaDoc comments.
Note: maybeConfigure implies that calling it twice will have no effect.
I have a suspicion that children would be added twice. Search for XXX
to find the details.
Revision Changes Path
1.25 +127 -34 jakarta-ant/src/main/org/apache/tools/ant/Task.java
Index: Task.java
===================================================================
RCS file: /home/cvs/jakarta-ant/src/main/org/apache/tools/ant/Task.java,v
retrieving revision 1.24
retrieving revision 1.25
diff -u -r1.24 -r1.25
--- Task.java 10 Jan 2002 11:21:19 -0000 1.24
+++ Task.java 1 Mar 2002 14:47:56 -0000 1.25
@@ -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
@@ -57,108 +57,165 @@
/**
* Base class for all tasks.
*
- * <p>Use {@link Project#createTask Project.createTask} to create a new Task.
+ * Use Project.createTask to create a new task instance rather than
+ * using this class directly for construction.
+ *
+ * @see Project#createTask
*/
public abstract class Task extends ProjectComponent {
-
+ /** Target this task belongs to, if any. */
protected Target target = null;
+ /** Description of this task, if any. */
protected String description=null;
+ /** Location within the build file of this task definition. */
protected Location location = Location.UNKNOWN_LOCATION;
+ /**
+ * Name of this task to be used for logging purposes.
+ * This defaults to the same as the type, but may be
+ * overridden by the user. For instance, the name "java"
+ * isn't terribly descriptive for a task used within
+ * another task - the outer task code can probably
+ * provide a better one.
+ */
protected String taskName = null;
+ /** Type of this task. */
protected String taskType = null;
+ /** Wrapper for this object, used to configure it at runtime. */
protected RuntimeConfigurable wrapper;
+ /**
+ * Whether or not this task is invalid. A task becomes invalid
+ * if a conflicting class is specified as the implementation for
+ * its type.
+ */
private boolean invalid = false;
+ /** Sole constructor. */
+ public Task() {
+ }
+
/**
- * Sets the target object of this task.
+ * Sets the target container of this task.
*
* @param target Target in whose scope this task belongs.
+ * May be <code>null</code>, indicating a top-level task.
*/
public void setOwningTarget(Target target) {
this.target = target;
}
/**
- * Get the Target to which this task belongs
+ * Returns the container target of this task.
*
- * @return the task's target.
+ * @return The target containing this task, or <code>null</code> if
+ * this task is a top-level task.
*/
public Target getOwningTarget() {
return target;
}
/**
- * Set the name to use in logging messages.
+ * Sets the name to use in logging messages.
*
- * @param name the name to use in logging messages.
+ * @param name The name to use in logging messages.
+ * Should not be <code>null</code>.
*/
public void setTaskName(String name) {
this.taskName = name;
}
/**
- * Get the name to use in logging messages.
+ * Returns the name to use in logging messages.
*
- * @return the name to use in logging messages.
+ * @return the name to use in logging messages.
*/
public String getTaskName() {
return taskName;
}
/**
- * Set the name with which the task has been invoked.
+ * Sets the name with which the task has been invoked.
*
- * @param type the name the task has been invoked as.
+ * @param type The name the task has been invoked as.
+ * Should not be <code>null</code>.
*/
void setTaskType(String type) {
this.taskType = type;
}
- /** Sets a description of the current action. It will be usefull in commenting
- * what we are doing.
+ /**
+ * Sets a description of the current action. This may be used for logging
+ * purposes.
+ *
+ * @param desc Description of the current action.
+ * May be <code>null</code>, indicating that no description is
+ * available.
+ *
*/
public void setDescription( String desc ) {
description=desc;
}
+ /**
+ * Returns the description of the current action.
+ *
+ * @return the description of the current action, or <code>null</code> if
+ * no description is available.
+ */
public String getDescription() {
return description;
}
/**
- * Called by the project to let the task initialize properly.
+ * Called by the project to let the task initialize properly.
+ * The default implementation is a no-op.
*
- * @throws BuildException if someting goes wrong with the build
+ * @exception BuildException if someting goes wrong with the build
*/
public void init() throws BuildException {}
/**
- * Called by the project to let the task do it's work. This method may be
+ * Called by the project to let the task do its work. This method may be
* called more than once, if the task is invoked more than once. For example,
* if target1 and target2 both depend on target3, then running
* "ant target1 target2" will run all tasks in target3 twice.
*
- * @throws BuildException if someting goes wrong with the build
+ * @exception BuildException if something goes wrong with the build
*/
public void execute() throws BuildException {}
/**
- * Returns the file location where this task was defined.
+ * Returns the file/location where this task was defined.
+ *
+ * @return the file/location where this task was defined.
+ * Should not return <code>null</code>. Location.UNKNOWN_LOCATION
+ * is used for unknown locations.
+ *
+ * @see Location#UNKNOWN_LOCATION
*/
public Location getLocation() {
return location;
}
/**
- * Sets the file location where this task was defined.
+ * Sets the file/location where this task was defined.
+ *
+ * @param location The file/location where this task was defined.
+ * Should not be <code>null</code> - use
+ * Location.UNKNOWN_LOCATION if the location isn't known.
+ *
+ * @see Location#UNKNOWN_LOCATION
*/
public void setLocation(Location location) {
this.location = location;
}
/**
- * Returns the wrapper class for runtime configuration.
+ * Returns the wrapper used for runtime configuration.
+ *
+ * @return the wrapper used for runtime configuration. This
+ * method will generate a new wrapper (and cache it)
+ * if one isn't set already.
*/
public RuntimeConfigurable getRuntimeConfigurableWrapper() {
if (wrapper == null) {
@@ -167,12 +224,26 @@
return wrapper;
}
+ /**
+ * Sets the wrapper to be used for runtime configuration.
+ *
+ * @param wrapper The wrapper to be used for runtime configuration.
+ * May be <code>null</code>, in which case the next call
+ * to getRuntimeConfigurableWrapper will generate a new
+ * wrapper.
+ */
protected void setRuntimeConfigurableWrapper(RuntimeConfigurable wrapper) {
this.wrapper = wrapper;
}
- /**
- * Configure this task - if it hasn't been done already.
+ // XXX: (Jon Skeet) The comment "if it hasn't been done already" may
+ // not be strictly true. wrapper.maybeConfigure() won't configure the same
+ // attributes/text more than once, but it may well add the children again,
+ // unless I've missed something.
+ /**
+ * Configures this task - if it hasn't been done already.
+ * If the task has been invalidated, it is replaced with an
+ * UnknownElement task which uses the new definition in the project.
*/
public void maybeConfigure() throws BuildException {
if (!invalid) {
@@ -184,36 +255,53 @@
}
}
+ /**
+ * Handles a line of output by logging it with the INFO priority.
+ *
+ * @param line The line of output to log. Should not be <code>null</code>.
+ */
protected void handleOutput(String line) {
log(line, Project.MSG_INFO);
}
+ /**
+ * Handles an error line by logging it with the INFO priority.
+ *
+ * @param line The error line to log. Should not be <code>null</code>.
+ */
protected void handleErrorOutput(String line) {
log(line, Project.MSG_ERR);
}
-
-
+
/**
- * 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. This delegates
+ * the actual logging to the project.
*
- * @param the message to be logged.
- * @param msgLevel the message priority at which this message is 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) {
project.log(this, msg, msgLevel);
}
/**
- * Perform this task
+ * Performs this task if it's still valid, or gets a replacement
+ * version and performs that otherwise.
+ *
+ * Performing a task consists of firing a task started event,
+ * configuring the task, executing it, and then firing task finished
+ * event. If a runtime exception is thrown, the task finished event
+ * is still fired, but with the exception as the cause.
*/
public final void perform() {
if (!invalid) {
@@ -241,16 +329,22 @@
}
/**
- * Mark this task as invalid.
+ * Marks this task as invalid. Any further use of this task
+ * will go through a replacement with the updated definition.
*/
final void markInvalid() {
invalid = true;
}
+ /**
+ * Replacement element used if this task is invalidated.
+ */
private UnknownElement replacement;
/**
- * Create an UnknownElement that can be used to replace this task.
+ * Creates an UnknownElement that can be used to replace this task.
+ * Once this has been created once, it is cached and returned by
+ * future calls.
*/
private UnknownElement getReplacement() {
if (replacement == null) {
@@ -268,4 +362,3 @@
return replacement;
}
}
-
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>