Add <catalogpath> to <xmlcatalog>.

PR: 14978
Submitted by:	Jeff Turner <jefft at apache.org>


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

docs/manual/CoreTypes/xmlcatalog.html

@@ -63,8 +63,8 @@ task uses XMLCatalogs for both entity and URI resolution.</p>
 <p>XMLCatalogs are specified as either a reference to another
 XMLCatalog, defined previously in a build file, or as a list of
 <code>dtd</code> or <code>entity</code> locations.  In addition,
-external catalog files may be specified in <code>catalogfiles</code>
-filesets, but they will be ignored unless the resolver library from
+external catalog files may be specified in a nested <code>catalogpath</code> ,
+but they will be ignored unless the resolver library from
 xml-commons is available in the system classpath.  <b>Due to backwards
 incompatible changes in the resolver code after the release of
 resolver 1.0, Ant will not support resolver.jar in version 1.0 - we
@@ -84,9 +84,10 @@ href="http://oasis-open.org/committees/entity/background/9401.html">
 plain text format</a> or <a
 href="http://www.oasis-open.org/committees/entity/spec-2001-08-06.html">
 XML format</a>.  If the xml-commons resolver library is not found in the
-classpath, external catalog files, specified in <code>catalogfiles</code>
-filesets, will be ignored and a warning will be logged.  In this case, however,
-processing of inline entries will proceed normally.</p>
+classpath, external catalog files, specified in <code>catalogpath</code> (or
+the deprecated <code>catalogfiles</code>) , will be ignored and a warning
+will be logged.  In this case, however, processing of inline entries will
+proceed normally.</p>
 <p>Currently, only <code>&lt;dtd&gt;</code> and
 <code>&lt;entity&gt;</code> elements may be specified inline; these
 roughly correspond to OASIS catalog entry types <code>PUBLIC</code> and
@@ -207,21 +208,25 @@ basedir.
 <p>The classpath to use for <a href="#ResolverAlgorithm">entity
 resolution</a>.  The nested <code>&lt;classpath&gt;</code> is a
 <a href="../using.html#path">path</a>-like structure.</p>
-<h4>catalogfiles</h4>
+<h4>catalogpath</h4>
 <p>
-The nested <code>catalogfiles</code> element specifies a <a
-href="../CoreTypes/fileset.html">FileSet</a>.  All files included in
-this fileset are assumed to be OASIS catalog files, in either
+The nested <code>catalogpath</code> element is a <a
+href="using.html#path">path</a>-like structure listing catalog files to
+search.  All files in this path are assumed to be OASIS catalog files, in
+either
 <a href="http://oasis-open.org/committees/entity/background/9401.html">
 plain text format</a> or <a
 href="http://www.oasis-open.org/committees/entity/spec-2001-08-06.html">
-XML format</a>.  Multiple <code>catalogfiles</code> filesets may be
-specified.  Of course, if you use wildcards in your fileset, you will
-want to use some sort of naming convention to ensure that you don't
-accidentally match non-catalog files.  If the resolver library from
-xml-commons is not available in the classpath, all
-<code>catalogfiles</code> will be ignored and a warning will be
-logged.
+XML format</a>. Entries specifying nonexistent files will be ignored. If the
+resolver library from xml-commons is not available in the classpath, all
+<code>catalogpaths</code> will be ignored and a warning will be logged.
+</p>
+<h4>catalogfiles (deprecated)</h4>
+<p>
+The nested <code>catalogfiles</code> element specifies a <a
+href="../CoreTypes/fileset.html">FileSet</a>.  This is equivalent to
+specifying a <code>&lt;fileset&gt;</code> inside a <code>catalogpath</code>,
+and is retained for backwards-compatibility.
 </p>
 <h3>Examples</h3>
 <p>Set up an XMLCatalog with a single dtd referenced locally in a user's 
@@ -260,13 +265,17 @@ formats:</p>
         &lt;entity 
             publicId=&quot;LargeLogo&quot;
             location=&quot;com/arielpartners/images/ariel-logo-large.gif&quot;/&gt;
-    &lt;xmlcatalog refid="commonDTDs"/&gt;
-        &lt;catalogfiles 
-            dir=&quot;/anetwork/drive&quot;
-            includes=&quot;**/catalog&quot;/&gt;
-        &lt;catalogfiles 
-            dir=&quot;/my/catalogs&quot;
-            includes=&quot;**/catalog.xml&quot;/&gt;
+        &lt;xmlcatalog refid="commonDTDs"/&gt;
+            &lt;catalogpath&gt;
+                &lt;pathelement location="/etc/sgml/catalog"/&gt;
+                &lt;fileset 
+                    dir=&quot;/anetwork/drive&quot;
+                    includes=&quot;**/catalog&quot;/&gt;
+                &lt;fileset 
+                    dir=&quot;/my/catalogs&quot;
+                    includes=&quot;**/catalog.xml&quot;/&gt;
+            &lt;/catalogpath&gt;
+        &lt;/xmlcatalog&gt;
     &lt;/xmlcatalog&gt;
 </pre></blockquote>
 <p>To reference the above XMLCatalog in an <code>xslt</code> task:<p>

src/etc/testcases/taskdefs/optional/xmlvalidate.xml

@@ -49,6 +49,19 @@
       </xmlcatalog>
     </xmlvalidate>
   </target>
+ 
+  <target name="xmlcatalogpath">
+    <xmlvalidate warn="false">
+      <fileset dir="xml" includes="**/about.xml"/>
+      <xmlcatalog classpath="xml">
+        <catalogpath>
+          <pathelement location="xml/catalog"/>
+        </catalogpath>
+        <dtd publicID="-//stevo//DTD doc 1.0//EN"
+          location="doc.dtd"/>
+      </xmlcatalog>
+    </xmlvalidate>
+  </target>
 
   <target name="testSchemaGood">
     <xmlvalidate warn="false" lenient="no" >

src/main/org/apache/tools/ant/types/XMLCatalog.java

@@ -104,9 +104,13 @@ import org.xml.sax.XMLReader;
  * href="http://www.oasis-open.org/committees/entity/spec-2001-08-06.html">
  * XML format</a>.  If the xml-commons resolver library is not found
  * in the classpath, external catalog files, specified in
- * <code>&lt;catalogfiles&gt;</code> filesets, will be ignored and a
- * warning will be logged.  In this case, however, processing of
- * inline entries will proceed normally.</p>
+ * <code>&lt;catalogfiles&gt;</code> filesets and
+ * <code>&lt;catalogpath&gt;</code> paths, will be ignored and a warning will
+ * be logged.  In this case, however, processing of inline entries will proceed
+ * normally.</p>
+ * <p>Note that, as <code>&lt;catalogpath&gt;</code> can contain nested
+ * filesets, it is more general than <code>&lt;catalogfiles&gt;</code>, which
+ * should be considered deprecated.</p>
  *
  * <p>Currently, only <code>&lt;dtd&gt;</code> and
  * <code>&lt;entity&gt;</code> elements may be specified inline; these
@@ -121,12 +125,14 @@ import org.xml.sax.XMLReader;
  * &nbsp;&nbsp;&lt;dtd publicId="" location="/path/to/file2.jar" /&gt;<br>
  * &nbsp;&nbsp;&lt;entity publicId="" location="/path/to/file3.jar" /&gt;<br>
  * &nbsp;&nbsp;&lt;entity publicId="" location="/path/to/file4.jar" /&gt;<br>
- * &nbsp;&nbsp;&lt;catalogfiles dir="${basedir}" includes="**\catalog" /&gt;<br>
+ * &nbsp;&nbsp;&lt;catalogpath&gt;<br>
+ * &nbsp;&nbsp;&nbsp;&nbsp;&lt;pathelement location="/etc/sgml/catalog"/&gt;<br>
+ * &nbsp;&nbsp;&lt;/catalogpath&gt;<br>
  * &nbsp;&nbsp;&lt;catalogfiles dir="/opt/catalogs/" includes="**\catalog.xml" /&gt;<br>
  * &lt;/xmlcatalog&gt;<br>
  * </code>
  * <p>
- * The object implemention <code>sometask</code> must provide a method called
+ * Tasks wishing to use <code>&lt;xmlcatalog&gt;</code> must provide a method called
  * <code>createXMLCatalog</code> which returns an instance of
  * <code>XMLCatalog</code>. Nested DTD and entity definitions are handled by
  * the XMLCatalog object and must be labeled <code>dtd</code> and
@@ -154,6 +160,7 @@ import org.xml.sax.XMLReader;
  * @author dIon Gillard
  * @author Erik Hatcher
  * @author <a href="mailto:cstrong@arielpartners.com">Craeg Strong</a>
+ * @author Jeff Turner
  * @version $Id$
  */
 public class XMLCatalog extends DataType 
@@ -169,6 +176,11 @@ public class XMLCatalog extends DataType
      */
     private Path classpath;
 
+    /**
+     * Path listing external catalog files to search when resolving entities
+     */
+    private Path catalogPath;
+   
     /**
      * The name of the bridge to the Apache xml-commons resolver
      * class, used to determine whether resolver.jar is present in the
@@ -285,6 +297,52 @@ public class XMLCatalog extends DataType
         getElements().addElement(fs);
     }
 
+
+    /** Creates a nested <code>&lt;catalogpath&gt;</code> element.
+     * Not allowed if this catalog is itself a reference to another
+     * catalog -- that is, a catalog cannot both refer to another
+     * <em>and</em> contain elements or other attributes.
+     *
+     * @param fs the fileset of external catalogs.
+     * @exception BuildException
+     * if this is a reference and no nested elements are allowed.
+     */
+    public Path createCatalogPath() {
+      if (isReference()) {
+        throw noChildrenAllowed();
+      }
+      if (this.catalogPath == null) {
+        this.catalogPath = new Path(getProject());
+      }
+      setChecked( false );
+      return this.catalogPath.createPath();
+    }
+
+    /**
+     * Allows catalogpath reference.  Not allowed if this catalog is
+     * itself a reference to another catalog -- that is, a catalog
+     * cannot both refer to another <em>and</em> contain elements or
+     * other attributes.
+     */
+    public void setCatalogPathRef(Reference r) {
+        if (isReference()) {
+            throw tooManyAttributes();
+        }
+        createCatalogPath().setRefid(r);
+        setChecked( false );
+    }
+
+
+    /**
+     * Returns the catalog path in which to attempt to resolve DTDs.
+     *
+     * @return the catalog path
+     */
+    public Path getCatalogPath() {
+        return this.catalogPath;
+    }
+
+
     /**
      * Creates the nested <code>&lt;dtd&gt;</code> element.  Not
      * allowed if this catalog is itself a reference to another
@@ -344,6 +402,10 @@ public class XMLCatalog extends DataType
         // Append the classpath of the nested catalog
         Path nestedClasspath = catalog.getClasspath();
         createClasspath().append(nestedClasspath);
+
+        // Append the catalog path of the nested catalog
+        Path nestedCatalogPath = catalog.getCatalogPath();
+        createCatalogPath().append(nestedCatalogPath);
         setChecked( false );
     }
 
@@ -510,6 +572,12 @@ public class XMLCatalog extends DataType
                         break;
                     }
                 }
+                if (getCatalogPath() != null &&
+                    getCatalogPath().list().length != 0) {
+                        log("Warning: catalogpath listing external catalogs"+
+                                " will be ignored",
+                            Project.MSG_WARN);
+                }
             }
         }
         return catalogResolver;
@@ -1075,6 +1143,7 @@ public class XMLCatalog extends DataType
                     throw new BuildException(ex);
                 }
 
+                // Parse each catalog listed in nested <catalogfile> elements.
                 Enumeration enum = getElements().elements();
                 while (enum.hasMoreElements()) {
                     Object o = enum.nextElement();
@@ -1096,9 +1165,28 @@ public class XMLCatalog extends DataType
                         }
                     }
                 }
+
+                // Parse each catalog listed in nested <catalogpath> elements
+                Path catPath = getCatalogPath();
+                if (catPath != null) {
+                    log("Using catalogpath '" + getCatalogPath()+"'", Project.MSG_DEBUG);
+                    String[] catPathList = getCatalogPath().list();
+
+                    for (int i=0; i< catPathList.length; i++) {
+                        File catFile = new File(catPathList[i]); 
+                        log("Parsing "+catFile, Project.MSG_DEBUG);
+                        try {
+                            parseCatalog.invoke(resolverImpl, 
+                                    new Object[] 
+                                    { catFile.getPath() });
+                        }
+                        catch (Exception ex) {
+                            throw new BuildException(ex);
+                        }
+                    }
+                }
             }
             externalCatalogsProcessed = true;
         }
     }
-
 } //-- XMLCatalog

src/testcases/org/apache/tools/ant/taskdefs/optional/XmlValidateTest.java

@@ -132,6 +132,17 @@ public class XmlValidateTest extends BuildFileTest {
       executeTarget("xmlcatalogfiles");
     }
 
+    /**
+     * Test nested catalogpath.
+     * It should be ignored if resolver.jar is not
+     * present, but will be used if it is.  either
+     * way, test should work b/c we have a nested
+     * dtd with the same entity
+     */
+    public void testXmlCatalogPath() {
+      executeTarget("xmlcatalogpath");
+    }
+
     /**
      * Test nested xmlcatalog definitions
      */