Added the TaskFactory and modified Project.

This is not organized as a 'project' - the files here needs to replace
the ones in the main tree. I'll probably import the rest of the core
and make it a standalone replacement, so it's easy to review.

The goals are to:
- make ant more 'embeddable'
- integrate it better in other tools
- support SAX2 and namespaces
- support pluggable behavior for the XML reader
- support pluggable task factories - the factory will have full control
over the class loader
- better support and integration with existing java beans.

All that while maintaining full compatibility with ant1.4 - all
the code here is just an additional set of hooks, with the previous
behavior preserved and remaining as default.

Eventually this can be refactored into a standalone component
that will implement a task engine for ant1.x.


git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@271572 13f79535-47bb-0310-9956-ffa450edef68

proposal/sandbox/embed/TaskAdapter.java

@@ -56,11 +56,10 @@ package org.apache.tools.ant;
 
 import java.lang.reflect.Method;
 
-
-
 /**
- *  Use introspection to "adapt" an arbitrary Bean ( not extending Task, but with similar
- *  patterns).
+ * Uses introspection to "adapt" an arbitrary Bean which doesn't
+ * itself extend Task, but still contains an execute method and optionally 
+ * a setProject method.
  *
  *  The adapter can also be used to wrap tasks that are loaded in a different class loader
  *  by ant, when used in programatic mode.
@@ -69,19 +68,28 @@ import java.lang.reflect.Method;
  */
 public class TaskAdapter extends Task {
 
+    /** Object to act as a proxy for. */
     private Object proxy;
     private String methodName="execute";
+    Object proxy;
     
     /**
-     * Checks a class, whether it is suitable to be adapted by TaskAdapter.
+     * Checks whether or not a class is suitable to be adapted by TaskAdapter.
      *
-     * Checks conditions only, which are additionally required for a tasks
-     * adapted by TaskAdapter. Thus, this method should be called by
-     * {@link Project#checkTaskClass}.
+     * This only checks conditions which are additionally required for 
+     * tasks adapted by TaskAdapter. Thus, this method should be called by
+     * Project.checkTaskClass.
      *
      * Throws a BuildException and logs as Project.MSG_ERR for
-     * conditions, that will cause the task execution to fail.
+     * conditions that will cause the task execution to fail.
      * Logs other suspicious conditions with Project.MSG_WARN.
+     * 
+     * @param taskClass Class to test for suitability. 
+     *                  Must not be <code>null</code>.
+     * @param project   Project to log warnings/errors to. 
+     *                  Must not be <code>null</code>.
+     * 
+     * @see Project#checkTaskClass(Class)
      */
     public static void checkTaskClass(final Class taskClass, final Project project) {
         // Any task can be used via adapter. If it doesn't have any execute()
@@ -154,7 +162,7 @@ public class TaskAdapter extends Task {
     }
     
     /**
-     * Do the execution.
+     * Executes the proxied task.
      */
     public void execute() throws BuildException {
         Method setProjectM = null;
@@ -201,12 +209,19 @@ public class TaskAdapter extends Task {
     }
     
     /**
-     * Set the target object class
+     * Sets the target object to proxy for.
+     * 
+     * @param o The target object. Must not be <code>null</code>.
      */
     public void setProxy(Object o) {
         this.proxy = o;
     }
 
+    /**
+     * Returns the target object being proxied.
+     * 
+     * @return the target proxy object
+     */
     public Object getProxy() {
         return this.proxy ;
     }

proposal/sandbox/embed/TaskFactory.java

@@ -0,0 +1,95 @@
+/*
+ * The Apache Software License, Version 1.1
+ *
+ * Copyright (c) 2000-2002 The Apache Software Foundation.  All rights
+ * reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright
+ *    notice, this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in
+ *    the documentation and/or other materials provided with the
+ *    distribution.
+ *
+ * 3. The end-user documentation included with the redistribution, if
+ *    any, must include the following acknowlegement:
+ *       "This product includes software developed by the
+ *        Apache Software Foundation (http://www.apache.org/)."
+ *    Alternately, this acknowlegement may appear in the software itself,
+ *    if and wherever such third-party acknowlegements normally appear.
+ *
+ * 4. The names "The Jakarta Project", "Ant", and "Apache Software
+ *    Foundation" must not be used to endorse or promote products derived
+ *    from this software without prior written permission. For written
+ *    permission, please contact apache@apache.org.
+ *
+ * 5. Products derived from this software may not be called "Apache"
+ *    nor may "Apache" appear in their names without prior written
+ *    permission of the Apache Group.
+ *
+ * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
+ * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+ * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
+ * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
+ * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+ * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
+ * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+ * SUCH DAMAGE.
+ * ====================================================================
+ *
+ * This software consists of voluntary contributions made by many
+ * individuals on behalf of the Apache Software Foundation.  For more
+ * information on the Apache Software Foundation, please see
+ * <http://www.apache.org/>.
+ */
+
+package org.apache.tools.ant;
+
+import java.io.File;
+import java.io.InputStream;
+import java.io.IOException;
+import java.util.Hashtable;
+import java.util.Vector;
+import java.util.Properties;
+import java.util.Enumeration;
+import java.util.Stack;
+import java.lang.reflect.Modifier;
+
+
+import org.apache.tools.ant.types.FilterSet; 
+import org.apache.tools.ant.types.FilterSetCollection; 
+import org.apache.tools.ant.util.FileUtils; 
+
+/**
+ * Create tasks. Multiple task factories can be enabled at
+ * any time. The common 'Chain' pattern is used to construct
+ * tasks, with the original behavior ( Class ) tried last.
+ *
+ * @author Costin Manolache
+ */
+public interface TaskFactory  {
+
+    /** Creates or get a previously created task.
+     *
+     *  The task factory can be registered with the Project by a Task or by an
+     * application embedding ant.
+     *
+     * A factory may have knowledge about the tasks it creates. It can return
+     * an object extending TaskAdapter that emulates Task on it's adapter.
+     *
+     * @param project the context for task creation.
+     * @param ns namespace ( for use with SAX2 projects ).
+     * @param taskName the name of the task.
+     */
+    public Task createTask( Project project, String ns, String taskName )
+        throws BuildException;
+}