From 944781202f02835a2c48c44a1fa7b9c01b6c9cd8 Mon Sep 17 00:00:00 2001
From: Stefan Bodewig <bodewig@apache.org>
Date: Mon, 29 Nov 2010 16:06:11 +0000
Subject: [PATCH] Try to be more explicit about classloaders and their impact
 on typedef/taskdef

git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@1040166 13f79535-47bb-0310-9956-ffa450edef68
---
 docs/manual/Tasks/taskdef.html |  3 ++-
 docs/manual/Tasks/typedef.html | 21 +++++++++++++++++++++
 2 files changed, 23 insertions(+), 1 deletion(-)

diff --git a/docs/manual/Tasks/taskdef.html b/docs/manual/Tasks/taskdef.html
index 22180c50c..4f6f5d2b9 100644
--- a/docs/manual/Tasks/taskdef.html
+++ b/docs/manual/Tasks/taskdef.html
@@ -31,7 +31,8 @@
   <p>This task is a form of <a href="typedef.html">Typedef</a> with the
     attributes "adapter" and "adaptto" set to the values 
     "org.apache.tools.ant.TaskAdapter" and "org.apache.tools.ant.Task"
-    respectively.
+    respectively.  Anything said in the <a href="typedef.html">manual
+      page of typedef</a> applies to taskdef as well.</p>
 <h3>Examples</h3>
 <pre>  &lt;taskdef name=&quot;myjavadoc&quot; classname=&quot;com.mydomain.JavadocTask&quot;/&gt;</pre>
 <p>makes a task called <code>myjavadoc</code> available to Apache Ant. The class <code>com.mydomain.JavadocTask</code>
diff --git a/docs/manual/Tasks/typedef.html b/docs/manual/Tasks/typedef.html
index f9061b14a..7d0de52c3 100644
--- a/docs/manual/Tasks/typedef.html
+++ b/docs/manual/Tasks/typedef.html
@@ -62,6 +62,27 @@
     <a href="../Types/antlib.html">Antlib</a> section.
   </p>
 
+  <p>If you are defining tasks or types that share the same classpath
+    with multiple taskdef or typedef tasks, the corresponding classes
+    will be loaded by different
+    Java <a href="http://download.oracle.com/javase/1.4.2/docs/api/java/lang/ClassLoader.html">ClassLoaders</a>.
+    Two classes with the same name loaded via different ClassLoaders
+    are not the same class from the point of view of the Java VM, they
+    don't share static variables and instances of these classes can't
+    access private methods or attributes of instances defined by "the
+    other class" of the same name.  They don't even belong to the same
+    Java package and can't access package private code, either.</p>
+
+  <p>The best way to load several tasks/types that are supposed to
+    cooperate with each other via shared Java code is to use the
+    resource attribute and an antlib descriptor.  If this is not
+    possible, the second best option is to use the loaderref attribute
+    and specify the same name for each and every typedef/taskdef -
+    this way the classes will share the same ClassLoader.  Note that
+    the typedef/taskdef tasks must use identical classpath defintions
+    (this includes the order of path components) for the loaderref
+    attribute to work.</p>
+
 <h3>Parameters</h3>
 <table border="1" cellpadding="2" cellspacing="0">
   <tr>