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 Target.java UnknownElement.java
Date Fri, 01 Mar 2002 15:54:53 GMT
jskeet      02/03/01 07:54:53

  Modified:    src/main/org/apache/tools/ant Target.java
                        UnknownElement.java
  Log:
  JavaDoc comments and a couple of code changes.
  
  Code changes:
  Removed an unneeded nullity test null instanceof Foo is always false.
  Changed replaceChild(UnknownElement, Object) with two methods:
  replaceChild(UnknownElement,Task) and
  replaceChild(UnknownElement,RuntimeConfigurable) to make it
  absolutely clear that you can't just replace the children with random
  elements.
  
  I must admit I'm still far from entirely clear exactly how 
  UnknownElement works. It probably counts as black magic...
  
  Revision  Changes    Path
  1.32      +181 -11   jakarta-ant/src/main/org/apache/tools/ant/Target.java
  
  Index: Target.java
  ===================================================================
  RCS file: /home/cvs/jakarta-ant/src/main/org/apache/tools/ant/Target.java,v
  retrieving revision 1.31
  retrieving revision 1.32
  diff -u -r1.31 -r1.32
  --- Target.java	10 Jan 2002 11:21:19 -0000	1.31
  +++ Target.java	1 Mar 2002 15:54:53 -0000	1.32
  @@ -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.StringTokenizer;
   
   /**
  - * This class implements a target object with required parameters.
  + * Class to implement a target object with required parameters.
    *
    * @author James Davidson <a href="mailto:duncan@x180.com">duncan@x180.com</a>
    */
  -
   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 <code>null</code>.
  +     */
       public void setProject(Project project) {
           this.project = project;
       }
   
  +    /**
  +     * Returns the project this target belongs to.
  +     * 
  +     * @return The project this target belongs to, or <code>null</code> 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 <code>null</code>.
  +     */
       public void setDepends(String depS) {
           if (depS.length() > 0) {
               StringTokenizer tok =
  @@ -89,7 +118,7 @@
               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 @@
   
                   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 @@
           }
       }
   
  +    /**
  +     * Sets the name of this target.
  +     * 
  +     * @param name The name of this target. Should not be <code>null</code>.
  +     */
       public void setName(String name) {
           this.name = name;
       }
   
  +    /**
  +     * Returns the name of this target.
  +     * 
  +     * @return the name of this target, or <code>null</code> 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 <code>null</code>.
  +     */
       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 <code>null</code>.
  +     */
       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 @@
           return retval;
       }
   
  +    /**
  +     * Adds a dependency to this target.
  +     * 
  +     * @param dependency The name of a target this target is dependent on.
  +     *                   Must not be <code>null</code>.
  +     */
       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 <code>foo</code> has value <code>bar</code>, setting
  +     * the "if" condition to <code>${foo}_x</code> will mean that the
  +     * task will only execute if property <code>bar_x</code> is set.
  +     * 
  +     * @param property The property condition to test on execution.
  +     *                 May be <code>null</code>, 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 <code>foo</code> has value <code>bar</code>, setting
  +     * the "unless" condition to <code>${foo}_x</code> will mean that the
  +     * task will only execute if property <code>bar_x</code> isn't set.
  +     * 
  +     * @param property The property condition to test on execution.
  +     *                 May be <code>null</code>, 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 <code>null</code>, 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 <code>null</code> if no
  +     *         description is available.
  +     */
       public String getDescription() {
           return description;
       }
   
  +    /**
  +     * Returns the name of this target.
  +     * 
  +     * @return the name of this target, or <code>null</code> 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 @@
           }
       }
   
  +    /**
  +     * 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 @@
           }
       }
       
  -    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 <code>null</code>.
  +     * @param o  The data type wrapper to replace <code>el</code> 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 <code>null</code>.
  +     * @param o  The task to replace <code>el</code> 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,
  +     *         <code>true</code> is returned.
  +     *
  +     * @see #setIf(String)
  +     */
       private boolean testIfCondition() {
           if ("".equals(ifCondition)) {
               return true;
  @@ -226,6 +388,15 @@
           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,
  +     *         <code>true</code> is returned.
  +     *
  +     * @see #setUnless(String)
  +     */
       private boolean testUnlessCondition() {
           if ("".equals(unlessCondition)) {
               return true;
  @@ -233,5 +404,4 @@
           String test = project.replaceProperties(unlessCondition);
           return project.getProperty(test) == null;
       }
  -
   }
  
  
  
  1.23      +66 -26    jakarta-ant/src/main/org/apache/tools/ant/UnknownElement.java
  
  Index: UnknownElement.java
  ===================================================================
  RCS file: /home/cvs/jakarta-ant/src/main/org/apache/tools/ant/UnknownElement.java,v
  retrieving revision 1.22
  retrieving revision 1.23
  diff -u -r1.22 -r1.23
  --- UnknownElement.java	21 Feb 2002 15:38:16 -0000	1.22
  +++ UnknownElement.java	1 Mar 2002 15:54:53 -0000	1.23
  @@ -57,8 +57,9 @@
   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 <a href="mailto:stefan.bodewig@epost.de">Stefan Bodewig</a>
    */
  @@ -66,7 +67,8 @@
   
       /**
        * 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 @@
       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 <code>null</code>.
        */
       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 @@
   
           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 <code>null</code>.
        */
       protected void handleOutput(String line) {
           if (realThing instanceof Task) {
  @@ -134,9 +143,9 @@
       }
       
       /**
  -     * 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 <code>null</code>.
        */
       protected void handleErrorOutput(String line) {
           if (realThing instanceof Task) {
  @@ -147,7 +156,8 @@
       }
       
       /**
  -     * 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 @@
       /**
        * Adds a child element to this element.
        *
  -     * @param child the child element
  +     * @param child The child element to add. Must not be <code>null</code>.
        */
       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 <code>null</code>.
        * @exception BuildException if the children cannot be configured.
        */
       protected void handleChildren(Object parent,
  @@ -215,8 +226,14 @@
       }
   
       /**
  -     * 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 <code>null</code>.
  +     * @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 @@
       }
   
       /**
  -     * 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 <code>null</code>.
  +     * @param w  Ignored.
  +     * @param onTopLevel Whether or not this is definitely trying to create
  +     *                   a task. If this is <code>true</code> and the
  +     *                   task name is not recognised, a BuildException
  +     *                   is thrown.
  +     * 
  +     * @return the task specified by the given unknown element, or 
  +     *         <code>null</code> if the task name is not recognised and
  +     *         onTopLevel is <code>false</code>.
        */
       protected Task makeTask(UnknownElement ue, RuntimeConfigurable w,
                               boolean onTopLevel) {
  @@ -248,6 +277,16 @@
           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
  +     *             <code>"task"</code>. Should not be <code>null</code>.
  +     * @param elementName The name of the element which could not be found.
  +     *                    Should not be <code>null</code>.
  +     */
       protected BuildException getNotFoundException(String what,
                                                     String elementName) {
           String lSep = System.getProperty("line.separator");
  @@ -288,7 +327,7 @@
       }
   
       /**
  -     * 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 @@
       }
   
       /**
  -     * 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 <code>null</code> 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;
  
  
  

--
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