From 510f6b08f62143dee0fa468e9c659ccec0562589 Mon Sep 17 00:00:00 2001
From: Stefan Bodewig <bodewig@apache.org>
Date: Mon, 4 Jan 2010 05:57:17 +0000
Subject: [PATCH] target-group -> extension-point

git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@895567 13f79535-47bb-0310-9956-ffa450edef68
---
 WHATSNEW                                      |  3 ++
 docs/manual/conceptstypeslist.html            |  2 +-
 docs/manual/targets.html                      | 26 ++++++++---------
 .../{TargetGroup.java => ExtensionPoint.java} |  7 +++--
 .../tools/ant/helper/ProjectHelper2.java      | 28 +++++++++----------
 .../tools/ant/taskdefs/AntStructure.java      |  8 +++---
 ...roup-test.xml => extension-point-test.xml} | 28 +++++++++----------
 7 files changed, 53 insertions(+), 49 deletions(-)
 rename src/main/org/apache/tools/ant/{TargetGroup.java => ExtensionPoint.java} (85%)
 rename src/tests/antunit/core/{target-group-test.xml => extension-point-test.xml} (74%)
diff --git a/WHATSNEW b/WHATSNEW
index d73758f37..551949817 100644
--- a/WHATSNEW
+++ b/WHATSNEW
@@ -1040,6 +1040,9 @@ Other changes:
 
  * a new filterreader appendtolines complements prefixlines.
 
+ * a new top level element extension-point allows build files to be
+   extended with custom targets more easily.
+
 Changes from Ant 1.7.0 TO Ant 1.7.1
 =============================================
 
diff --git a/docs/manual/conceptstypeslist.html b/docs/manual/conceptstypeslist.html
index 54978e136..adf5b79ea 100644
--- a/docs/manual/conceptstypeslist.html
+++ b/docs/manual/conceptstypeslist.html
@@ -29,7 +29,7 @@
 
 <h3>Concepts</h3>
 <ul class="inlinelist">
-<li><a href="targets.html">Targets and Target-Groups</a></li>
+<li><a href="targets.html">Targets and Extension-Points</a></li>
 <li><a href="properties.html">Properties and PropertyHelpers</a></li>
 <li><a href="clonevm.html">ant.build.clonevm</a></li>
 <li><a href="sysclasspath.html">build.sysclasspath</a></li>
diff --git a/docs/manual/targets.html b/docs/manual/targets.html
index a57bb1441..d2b479771 100644
--- a/docs/manual/targets.html
+++ b/docs/manual/targets.html
@@ -19,7 +19,7 @@
 <head>
   <meta http-equiv="Content-Language" content="en-us"/>
   <link rel="stylesheet" type="text/css" href="stylesheets/style.css"/>
-  <title>Targets and Target-Groups</title>
+  <title>Targets and Extension-Points</title>
 </head>
 
 <body>
@@ -199,9 +199,9 @@
       <td align="center" valign="top">No</td>
     </tr>
     <tr>
-      <td valign="top">group</td>
+      <td valign="top">extensionOf</td>
       <td valign="top">Adds the current target to the depends list of
-        the named <a href="#target-groups">target-group</a>.
+        the named <a href="#extension-points">extension-point</a>.
         <em>since Ant 1.8.0.</em></td>
       <td align="center" valign="top">No</td>
     </tr>
@@ -225,11 +225,11 @@
     don't use Ants main class as entry point and calling them from the IDE
     is usually possible.</p>
 
-  <h1><a name="target-groups">Target-Groups</a></h1>
+  <h1><a name="extension-points">Extension-Points</a></h1>
 
   <p><em>since Ant 1.8.0.</em></p>
 
-  <p>Target-Groups are similar to targets in that they have a name and
+  <p>Extension-Points are similar to targets in that they have a name and
     a depends list and can be executed from the command line.  Just
     like targets they represent a state during the build process.</p>
 
@@ -237,18 +237,18 @@
     is to collect targets that contribute to the desired state in
     their depends list.</p>
 
-  <p>Targets can add themselves to a target-group's depends list via
-    their group attribute.  The targets that add themselves will be
+  <p>Targets can add themselves to an extension-points's depends list via
+    their extensionOf attribute.  The targets that add themselves will be
     added after the targets of the explicit depends-attribute of the
-    target-group, if multiple targets add themselves, their relative
+    extension-point, if multiple targets add themselves, their relative
     order is not defined.</p>
 
-  <p>The main purpose of a target-group is to act as an extension
+  <p>The main purpose of an extension-point is to act as an extension
     point for build files designed to
     be <a href="CoreTasks\import.html">imported</a>.  In the imported
-    file a target-groups defines a state that must be reached and
+    file an extension-point defines a state that must be reached and
     targets from other build files can join the depends list of said
-    target-group in order to contribute to that state.</p>
+    extension-point in order to contribute to that state.</p>
 
   <p>For example your imported build file may need to compile code, it
     might look like:</p>
@@ -256,7 +256,7 @@
 &lt;target name="create-directory-layout"&gt;
    ...
 &lt;/target&gt;
-&lt;target-group name="ready-to-compile"
+&lt;extension-point name="ready-to-compile"
               depends="create-directory-layout"/&gt;
 &lt;target name="compile" depends="ready-to-compile"&gt;
    ...
@@ -270,7 +270,7 @@
     your main build file you may use something like</p>
 <blockquote><pre>
 &lt;target name="generate-sources"
-        group="ready-to-compile"&gt;
+        extensionOf="ready-to-compile"&gt;
    ...
 &lt;/target&gt;
 </pre></blockquote>
diff --git a/src/main/org/apache/tools/ant/TargetGroup.java b/src/main/org/apache/tools/ant/ExtensionPoint.java
similarity index 85%
rename from src/main/org/apache/tools/ant/TargetGroup.java
rename to src/main/org/apache/tools/ant/ExtensionPoint.java
index 1e2b4aaf2..bc0f35b50 100644
--- a/src/main/org/apache/tools/ant/TargetGroup.java
+++ b/src/main/org/apache/tools/ant/ExtensionPoint.java
@@ -18,17 +18,18 @@
 package org.apache.tools.ant;
 
 /**
- * A special kind of target that must be empty.
+ * An extension point build files can provide as a place where other
+ * build files can add new dependencies.
  *
  * @since Ant 1.8.0
  */
-public class TargetGroup extends Target {
+public class ExtensionPoint extends Target {
 
     // no "clone" constructor since I'm not really sure where it is
     // used
 
     private static final String NO_CHILDREN_ALLOWED
-        = "you must not nest child elements into a target-group";
+        = "you must not nest child elements into an extension-point";
 
     /**
      * Throws an exception.
diff --git a/src/main/org/apache/tools/ant/helper/ProjectHelper2.java b/src/main/org/apache/tools/ant/helper/ProjectHelper2.java
index 5c3a1667a..3d16716e6 100644
--- a/src/main/org/apache/tools/ant/helper/ProjectHelper2.java
+++ b/src/main/org/apache/tools/ant/helper/ProjectHelper2.java
@@ -18,13 +18,13 @@
 package org.apache.tools.ant.helper;
 
 import org.apache.tools.ant.BuildException;
+import org.apache.tools.ant.ExtensionPoint;
 import org.apache.tools.ant.Location;
 import org.apache.tools.ant.MagicNames;
 import org.apache.tools.ant.Project;
 import org.apache.tools.ant.ProjectHelper;
 import org.apache.tools.ant.RuntimeConfigurable;
 import org.apache.tools.ant.Target;
-import org.apache.tools.ant.TargetGroup;
 import org.apache.tools.ant.Task;
 import org.apache.tools.ant.UnknownElement;
 import org.apache.tools.ant.types.Resource;
@@ -825,19 +825,19 @@ public class ProjectHelper2 extends ProjectHelper {
          * @exception org.xml.sax.SAXParseException if the tag given is not
          *            <code>"taskdef"</code>, <code>"typedef"</code>,
          *            <code>"property"</code>, <code>"target"</code>,
-         *            <code>"target-group"</code>
+         *            <code>"extension-point"</code>
          *            or a data type definition
          */
         public AntHandler onStartChild(String uri, String name, String qname, Attributes attrs,
                                        AntXMLContext context) throws SAXParseException {
-            return (name.equals("target") || name.equals("target-group"))
+            return (name.equals("target") || name.equals("extension-point"))
                 && (uri.equals("") || uri.equals(ANT_CORE_URI))
                 ? ProjectHelper2.targetHandler : ProjectHelper2.elementHandler;
         }
     }
 
     /**
-     * Handler for "target" and "target-group" elements.
+     * Handler for "target" and "extension-point" elements.
      */
     public static class TargetHandler extends AntHandler {
 
@@ -865,11 +865,11 @@ public class ProjectHelper2 extends ProjectHelper {
                                    AntXMLContext context) throws SAXParseException {
             String name = null;
             String depends = "";
-            String targetGroup = null;
+            String extensionPoint = null;
 
             Project project = context.getProject();
             Target target = "target".equals(tag)
-                ? new Target() : new TargetGroup();
+                ? new Target() : new ExtensionPoint();
             target.setProject(project);
             target.setLocation(new Location(context.getLocator()));
             context.addTarget(target);
@@ -899,8 +899,8 @@ public class ProjectHelper2 extends ProjectHelper {
                     }
                 } else if (key.equals("description")) {
                     target.setDescription(value);
-                } else if (key.equals("target-group")) {
-                    targetGroup = value;
+                } else if (key.equals("extensionOf")) {
+                    extensionPoint = value;
                 } else {
                     throw new SAXParseException("Unexpected attribute \"" + key + "\"", context
                             .getLocator());
@@ -969,9 +969,9 @@ public class ProjectHelper2 extends ProjectHelper {
                 context.getCurrentTargets().put(newName, newTarget);
                 project.addOrReplaceTarget(newName, newTarget);
             }
-            if (targetGroup != null) {
+            if (extensionPoint != null) {
                 for (Iterator iter =
-                         Target.parseDepends(targetGroup, name, "target-group")
+                         Target.parseDepends(extensionPoint, name, "extensionOf")
                          .iterator();
                      iter.hasNext(); ) {
                     String tgName = (String) iter.next();
@@ -980,16 +980,16 @@ public class ProjectHelper2 extends ProjectHelper {
                     }
                     if (!projectTargets.containsKey(tgName)) {
                         throw new BuildException("can't add target "
-                                                 + name + " to target-group "
+                                                 + name + " to extension-point "
                                                  + tgName
-                                                 + " because the target-group"
+                                                 + " because the extension-point"
                                                  + " is unknown.");
                     }
                     Target t = (Target) projectTargets.get(tgName);
-                    if (!(t instanceof TargetGroup)) {
+                    if (!(t instanceof ExtensionPoint)) {
                         throw new BuildException("referenced target "
                                                  + tgName
-                                                 + " is not a target-group");
+                                                 + " is not an extension-point");
                     }
                     t.addDependency(name);
                 }
diff --git a/src/main/org/apache/tools/ant/taskdefs/AntStructure.java b/src/main/org/apache/tools/ant/taskdefs/AntStructure.java
index 5fa927644..5468305b0 100644
--- a/src/main/org/apache/tools/ant/taskdefs/AntStructure.java
+++ b/src/main/org/apache/tools/ant/taskdefs/AntStructure.java
@@ -229,7 +229,7 @@ public class AntStructure extends Task {
 
             out.println("");
 
-            out.print("<!ELEMENT project (target | target-group | ");
+            out.print("<!ELEMENT project (target | extension-point | ");
             out.print(TASKS);
             out.print(" | ");
             out.print(TYPES);
@@ -252,9 +252,9 @@ public class AntStructure extends Task {
             out.println(")*>");
             out.println("");
             printTargetAttrs(out, "target");
-            out.println("<!ELEMENT target-group EMPTY>");
+            out.println("<!ELEMENT extension-point EMPTY>");
             out.println("");
-            printTargetAttrs(out, "target-group");
+            printTargetAttrs(out, "extension-point");
         }
 
         /**
@@ -268,7 +268,7 @@ public class AntStructure extends Task {
             out.println("          if          CDATA #IMPLIED");
             out.println("          unless      CDATA #IMPLIED");
             out.println("          depends     CDATA #IMPLIED");
-            out.println("          target-group CDATA #IMPLIED");
+            out.println("          extensionOf CDATA #IMPLIED");
             out.println("          description CDATA #IMPLIED>");
             out.println("");
         }
diff --git a/src/tests/antunit/core/target-group-test.xml b/src/tests/antunit/core/extension-point-test.xml
similarity index 74%
rename from src/tests/antunit/core/target-group-test.xml
rename to src/tests/antunit/core/extension-point-test.xml
index b098c80bf..012375c09 100644
--- a/src/tests/antunit/core/target-group-test.xml
+++ b/src/tests/antunit/core/extension-point-test.xml
@@ -19,7 +19,7 @@
 
   <import file="../antunit-base.xml"/>
 
-  <target-group name="testTargetGroupWorksLikeTarget"
+  <extension-point name="testExtensionPointWorksLikeTarget"
                 depends="setProperty, assertProperty"/>
 
   <target name="setProperty">
@@ -30,26 +30,26 @@
     <au:assertPropertyEquals name="foo" value="bar"/>
   </target>
 
-  <target name="testTargetGroupMustBeEmpty">
+  <target name="testExtensionPointMustBeEmpty">
     <mkdir dir="${output}"/>
     <echo file="${output}/build.xml"><![CDATA[
 <project>
-  <target-group name="foo">
+  <extension-point name="foo">
     <echo>bar</echo>
-  </target-group>
+  </extension-point>
 </project>]]></echo>
     <au:expectfailure
-       expectedMessage="you must not nest child elements into a target-group">
+       expectedMessage="you must not nest child elements into an extension-point">
       <ant dir="${output}"/>
     </au:expectfailure>
   </target>
 
-  <target name="testAddToTargetGroup">
+  <target name="testAddToExtensionPoint">
     <mkdir dir="${output}"/>
     <echo file="${output}/build.xml"><![CDATA[
 <project default="foo">
-  <target-group name="foo"/>
-  <target name="bar" target-group="foo">
+  <extension-point name="foo"/>
+  <target name="bar" extensionOf="foo">
     <echo>In target bar</echo>
   </target>
 </project>]]></echo>
@@ -57,15 +57,15 @@
     <au:assertLogContains text="In target bar"/>
   </target>
 
-  <target name="testTargetGroupMustBeKnown">
+  <target name="testExtensionPointMustBeKnown">
     <mkdir dir="${output}"/>
     <echo file="${output}/build.xml"><![CDATA[
 <project default="foo">
-  <target-group name="bar" target-group="foo"/>
-  <target-group name="foo"/>
+  <extension-point name="bar" extensionOf="foo"/>
+  <extension-point name="foo"/>
 </project>]]></echo>
     <au:expectfailure
-       expectedMessage="can't add target bar to target-group foo because the target-group is unknown">
+       expectedMessage="can't add target bar to extension-point foo because the extension-point is unknown">
       <ant dir="${output}"/>
     </au:expectfailure>
   </target>
@@ -75,10 +75,10 @@
     <echo file="${output}/build.xml"><![CDATA[
 <project default="foo">
   <target name="foo"/>
-  <target name="bar" target-group="foo"/>
+  <target name="bar" extensionOf="foo"/>
 </project>]]></echo>
     <au:expectfailure
-       expectedMessage="referenced target foo is not a target-group">
+       expectedMessage="referenced target foo is not an extension-point">
       <ant dir="${output}"/>
     </au:expectfailure>
   </target>
