Return-Path: Delivered-To: apmail-jakarta-ant-dev-archive@apache.org Received: (qmail 49482 invoked from network); 1 Mar 2002 14:48:17 -0000 Received: from unknown (HELO nagoya.betaversion.org) (192.18.49.131) by daedalus.apache.org with SMTP; 1 Mar 2002 14:48:17 -0000 Received: (qmail 1482 invoked by uid 97); 1 Mar 2002 14:47:59 -0000 Delivered-To: qmlist-jakarta-archive-ant-dev@jakarta.apache.org Received: (qmail 1458 invoked by uid 97); 1 Mar 2002 14:47:58 -0000 Mailing-List: contact ant-dev-help@jakarta.apache.org; run by ezmlm Precedence: bulk List-Unsubscribe: List-Subscribe: List-Help: List-Post: List-Id: "Ant Developers List" Reply-To: "Ant Developers List" Delivered-To: mailing list ant-dev@jakarta.apache.org Received: (qmail 1441 invoked by uid 97); 1 Mar 2002 14:47:58 -0000 Date: 1 Mar 2002 14:47:56 -0000 Message-ID: <20020301144756.47641.qmail@icarus.apache.org> From: jskeet@apache.org To: jakarta-ant-cvs@apache.org Subject: cvs commit: jakarta-ant/src/main/org/apache/tools/ant Task.java X-Spam-Rating: daedalus.apache.org 1.6.2 0/1000/N X-Spam-Rating: daedalus.apache.org 1.6.2 0/1000/N 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. * - *

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 null, 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 null 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 null. */ 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 null. */ 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 null, 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 null 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 null. 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 null - 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 null, 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 null. + */ 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 null. + */ 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 null. */ 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 null. + * @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: For additional commands, e-mail: