ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jsk...@apache.org
Subject cvs commit: jakarta-ant/src/main/org/apache/tools/ant Task.java
Date Fri, 01 Mar 2002 14:47:56 GMT
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:   <mailto:ant-dev-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:ant-dev-help@jakarta.apache.org>


Mime
View raw message