Java > Open Source Codes > org > apache > tools > ant > types > XMLCatalog


1 /*
2  * Licensed to the Apache Software Foundation (ASF) under one or more
3  * contributor license agreements. See the NOTICE file distributed with
4  * this work for additional information regarding copyright ownership.
5  * The ASF licenses this file to You under the Apache License, Version 2.0
6  * (the "License"); you may not use this file except in compliance with
7  * the License. You may obtain a copy of the License at
8  *
9  * http://www.apache.org/licenses/LICENSE-2.0
10  *
11  * Unless required by applicable law or agreed to in writing, software
12  * distributed under the License is distributed on an "AS IS" BASIS,
13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14  * See the License for the specific language governing permissions and
15  * limitations under the License.
16  *
17  */
18
19 package org.apache.tools.ant.types;
20
21 import java.lang.reflect.Method ;
22
23 import java.io.File ;
24 import java.io.FileInputStream ;
25 import java.io.IOException ;
26 import java.io.InputStream ;
27 import java.net.MalformedURLException ;
28 import java.net.URL ;
29 import java.util.Enumeration ;
30 import java.util.Vector ;
31 import javax.xml.parsers.ParserConfigurationException ;
32 import javax.xml.parsers.SAXParserFactory ;
33 import javax.xml.transform.Source ;
34 import javax.xml.transform.TransformerException ;
35 import javax.xml.transform.URIResolver ;
36 import javax.xml.transform.sax.SAXSource ;
37 import org.apache.tools.ant.AntClassLoader;
38 import org.apache.tools.ant.BuildException;
39 import org.apache.tools.ant.Project;
40 import org.apache.tools.ant.util.FileUtils;
41 import org.apache.tools.ant.util.JAXPUtils;
42 import org.xml.sax.EntityResolver ;
43 import org.xml.sax.InputSource ;
44 import org.xml.sax.SAXException ;
45 import org.xml.sax.XMLReader ;
46
47
48
49 /**
50  * <p>This data type provides a catalog of resource locations (such as
51  * DTDs and XML entities), based on the <a
52  * HREF="http://oasis-open.org/committees/entity/spec-2001-08-06.html">
53  * OASIS "Open Catalog" standard</a>. The catalog entries are used
54  * both for Entity resolution and URI resolution, in accordance with
55  * the {@link org.xml.sax.EntityResolver EntityResolver} and {@link
56  * javax.xml.transform.URIResolver URIResolver} interfaces as defined
57  * in the <a HREF="http://java.sun.com/xml/jaxp">Java API for XML
58  * Processing Specification</a>.</p>
59  *
60  * <p>Resource locations can be specified either in-line or in
61  * external catalog file(s), or both. In order to use an external
62  * catalog file, the xml-commons resolver library ("resolver.jar")
63  * must be in your classpath. External catalog files may be either <a
64  * HREF="http://oasis-open.org/committees/entity/background/9401.html">
65  * plain text format</a> or <a
66  * HREF="http://www.oasis-open.org/committees/entity/spec-2001-08-06.html">
67  * XML format</a>. If the xml-commons resolver library is not found
68  * in the classpath, external catalog files, specified in
69  * <code>&lt;catalogpath&gt;</code> paths, will be ignored and a warning will
70  * be logged. In this case, however, processing of inline entries will proceed
71  * normally.</p>
72  *
73  * <p>Currently, only <code>&lt;dtd&gt;</code> and
74  * <code>&lt;entity&gt;</code> elements may be specified inline; these
75  * correspond to OASIS catalog entry types <code>PUBLIC</code> and
76  * <code>URI</code> respectively.</p>
77  *
78  * <p>The following is a usage example:</p>
79  *
80  * <code>
81  * &lt;xmlcatalog&gt;<br>
82  * &nbsp;&nbsp;&lt;dtd publicId="" location="/path/to/file.jar" /&gt;<br>
83  * &nbsp;&nbsp;&lt;dtd publicId="" location="/path/to/file2.jar" /&gt;<br>
84  * &nbsp;&nbsp;&lt;entity publicId="" location="/path/to/file3.jar" /&gt;<br>
85  * &nbsp;&nbsp;&lt;entity publicId="" location="/path/to/file4.jar" /&gt;<br>
86  * &nbsp;&nbsp;&lt;catalogpath&gt;<br>
87  * &nbsp;&nbsp;&nbsp;&nbsp;&lt;pathelement location="/etc/sgml/catalog"/&gt;<br>
88  * &nbsp;&nbsp;&lt;/catalogpath&gt;<br>
89  * &nbsp;&nbsp;&lt;catalogfiles dir="/opt/catalogs/" includes="**\catalog.xml" /&gt;<br>
90  * &lt;/xmlcatalog&gt;<br>
91  * </code>
92  * <p>
93  * Tasks wishing to use <code>&lt;xmlcatalog&gt;</code> must provide a method called
94  * <code>createXMLCatalog</code> which returns an instance of
95  * <code>XMLCatalog</code>. Nested DTD and entity definitions are handled by
96  * the XMLCatalog object and must be labeled <code>dtd</code> and
97  * <code>entity</code> respectively.</p>
98  *
99  * <p>The following is a description of the resolution algorithm:
100  * entities/URIs/dtds are looked up in each of the following contexts,
101  * stopping when a valid and readable resource is found:
102  * <ol>
103  * <li>In the local filesystem</li>
104  * <li>In the classpath</li>
105  * <li>Using the Apache xml-commons resolver (if it is available)</li>
106  * <li>In URL-space</li>
107  * </ol>
108  * </p>
109  *
110  * <p>See {@link
111  * org.apache.tools.ant.taskdefs.optional.XMLValidateTask
112  * XMLValidateTask} for an example of a task that has integrated
113  * support for XMLCatalogs.</p>
114  *
115  * <p>Possible future extension could provide for additional OASIS
116  * entry types to be specified inline.</p>
117  *
118  */
119 public class XMLCatalog extends DataType
120     implements Cloneable , EntityResolver , URIResolver {
121
122     /** helper for some File.toURL connversions */
123     private static final FileUtils FILE_UTILS = FileUtils.getFileUtils();
124
125     //-- Fields ----------------------------------------------------------------
126
127     /** Holds dtd/entity objects until needed. */
128     private Vector elements = new Vector ();
129
130     /**
131      * Classpath in which to attempt to resolve resources.
132      */
133     private Path classpath;
134
135     /**
136      * Path listing external catalog files to search when resolving entities
137      */
138     private Path catalogPath;
139
140     /**
141      * The name of the bridge to the Apache xml-commons resolver
142      * class, used to determine whether resolver.jar is present in the
143      * classpath.
144      */
145     public static final String APACHE_RESOLVER
146         = "org.apache.tools.ant.types.resolver.ApacheCatalogResolver";
147
148     /**
149      * Resolver base class
150      */
151     public static final String CATALOG_RESOLVER
152         = "org.apache.xml.resolver.tools.CatalogResolver";
153
154         //-- Methods ---------------------------------------------------------------
155
156     /**
157      * Default constructor
158      */
159     public XMLCatalog() {
160         setChecked(false);
161     }
162
163     /**
164      * Returns the elements of the catalog - ResourceLocation objects.
165      *
166      * @return the elements of the catalog - ResourceLocation objects
167      */
168     private Vector getElements() {
169         return getRef().elements;
170     }
171
172     /**
173      * Returns the classpath in which to attempt to resolve resources.
174      *
175      * @return the classpath
176      */
177     private Path getClasspath() {
178         return getRef().classpath;
179     }
180
181     /**
182      * Allows nested classpath elements. Not allowed if this catalog
183      * is itself a reference to another catalog -- that is, a catalog
184      * cannot both refer to another <em>and</em> contain elements or
185      * other attributes.
186      *
187      * @return a Path instance to be configured.
188      */
189     public Path createClasspath() {
190         if (isReference()) {
191             throw noChildrenAllowed();
192         }
193         if (this.classpath == null) {
194             this.classpath = new Path(getProject());
195         }
196         setChecked(false);
197         return this.classpath.createPath();
198     }
199
200     /**
201      * Allows simple classpath string. Not allowed if this catalog is
202      * itself a reference to another catalog -- that is, a catalog
203      * cannot both refer to another <em>and</em> contain elements or
204      * other attributes.
205      *
206      * @param classpath the classpath to use to look up entities.
207      */
208     public void setClasspath(Path classpath) {
209         if (isReference()) {
210             throw tooManyAttributes();
211         }
212         if (this.classpath == null) {
213             this.classpath = classpath;
214         } else {
215             this.classpath.append(classpath);
216         }
217         setChecked(false);
218     }
219
220     /**
221      * Allows classpath reference. Not allowed if this catalog is
222      * itself a reference to another catalog -- that is, a catalog
223      * cannot both refer to another <em>and</em> contain elements or
224      * other attributes.
225      *
226      * @param r an Ant reference containing a classpath.
227      */
228     public void setClasspathRef(Reference r) {
229         if (isReference()) {
230             throw tooManyAttributes();
231         }
232         createClasspath().setRefid(r);
233         setChecked(false);
234     }
235
236     /** Creates a nested <code>&lt;catalogpath&gt;</code> element.
237      * Not allowed if this catalog is itself a reference to another
238      * catalog -- that is, a catalog cannot both refer to another
239      * <em>and</em> contain elements or other attributes.
240      *
241      * @return a path to be configured as the catalog path.
242      * @exception BuildException
243      * if this is a reference and no nested elements are allowed.
244      */
245     public Path createCatalogPath() {
246         if (isReference()) {
247             throw noChildrenAllowed();
248         }
249         if (this.catalogPath == null) {
250             this.catalogPath = new Path(getProject());
251         }
252         setChecked(false);
253         return this.catalogPath.createPath();
254     }
255
256     /**
257      * Allows catalogpath reference. Not allowed if this catalog is
258      * itself a reference to another catalog -- that is, a catalog
259      * cannot both refer to another <em>and</em> contain elements or
260      * other attributes.
261      *
262      * @param r an Ant reference containing a classpath to be used as
263      * the catalog path.
264      */
265     public void setCatalogPathRef(Reference r) {
266         if (isReference()) {
267             throw tooManyAttributes();
268         }
269         createCatalogPath().setRefid(r);
270         setChecked(false);
271     }
272
273
274     /**
275      * Returns the catalog path in which to attempt to resolve DTDs.
276      *
277      * @return the catalog path
278      */
279     public Path getCatalogPath() {
280         return getRef().catalogPath;
281     }
282
283
284     /**
285      * Creates the nested <code>&lt;dtd&gt;</code> element. Not
286      * allowed if this catalog is itself a reference to another
287      * catalog -- that is, a catalog cannot both refer to another
288      * <em>and</em> contain elements or other attributes.
289      *
290      * @param dtd the information about the PUBLIC resource mapping to
291      * be added to the catalog
292      * @exception BuildException if this is a reference and no nested
293      * elements are allowed.
294      */
295     public void addDTD(ResourceLocation dtd) throws BuildException {
296         if (isReference()) {
297             throw noChildrenAllowed();
298         }
299
300         getElements().addElement(dtd);
301         setChecked(false);
302     }
303
304     /**
305      * Creates the nested <code>&lt;entity&gt;</code> element. Not
306      * allowed if this catalog is itself a reference to another
307      * catalog -- that is, a catalog cannot both refer to another
308      * <em>and</em> contain elements or other attributes.
309      *
310      * @param entity the information about the URI resource mapping to be
311      * added to the catalog.
312      * @exception BuildException if this is a reference and no nested
313      * elements are allowed.
314      */
315     public void addEntity(ResourceLocation entity) throws BuildException {
316         addDTD(entity);
317     }
318
319     /**
320      * Loads a nested <code>&lt;xmlcatalog&gt;</code> into our
321      * definition. Not allowed if this catalog is itself a reference
322      * to another catalog -- that is, a catalog cannot both refer to
323      * another <em>and</em> contain elements or other attributes.
324      *
325      * @param catalog Nested XMLCatalog
326      */
327     public void addConfiguredXMLCatalog(XMLCatalog catalog) {
328         if (isReference()) {
329             throw noChildrenAllowed();
330         }
331
332         // Add all nested elements to our catalog
333 Vector newElements = catalog.getElements();
334         Vector ourElements = getElements();
335         Enumeration e = newElements.elements();
336         while (e.hasMoreElements()) {
337             ourElements.addElement(e.nextElement());
338         }
339
340         // Append the classpath of the nested catalog
341 Path nestedClasspath = catalog.getClasspath();
342         createClasspath().append(nestedClasspath);
343
344         // Append the catalog path of the nested catalog
345 Path nestedCatalogPath = catalog.getCatalogPath();
346         createCatalogPath().append(nestedCatalogPath);
347         setChecked(false);
348     }
349
350     /**
351      * Makes this instance in effect a reference to another XMLCatalog
352      * instance.
353      *
354      * <p>You must not set another attribute or nest elements inside
355      * this element if you make it a reference. That is, a catalog
356      * cannot both refer to another <em>and</em> contain elements or
357      * attributes.</p>
358      *
359      * @param r the reference to which this catalog instance is associated
360      * @exception BuildException if this instance already has been configured.
361      */
362     public void setRefid(Reference r) throws BuildException {
363         if (!elements.isEmpty()) {
364             throw tooManyAttributes();
365         }
366         super.setRefid(r);
367     }
368
369     /**
370      * Implements the EntityResolver.resolveEntity() interface method.
371      * @param publicId the public id to resolve.
372      * @param systemId the system id to resolve.
373      * @throws SAXException if there is a parsing problem.
374      * @throws IOException if there is an IO problem.
375      * @return the resolved entity.
376      * @see org.xml.sax.EntityResolver#resolveEntity
377      */
378     public InputSource resolveEntity(String publicId, String systemId)
379         throws SAXException , IOException {
380
381         if (isReference()) {
382             return getRef().resolveEntity(publicId, systemId);
383         }
384
385         dieOnCircularReference();
386
387         log("resolveEntity: '" + publicId + "': '" + systemId + "'",
388             Project.MSG_DEBUG);
389
390         InputSource inputSource =
391             getCatalogResolver().resolveEntity(publicId, systemId);
392
393         if (inputSource == null) {
394             log("No matching catalog entry found, parser will use: '"
395                 + systemId + "'", Project.MSG_DEBUG);
396         }
397
398         return inputSource;
399     }
400
401     /**
402      * Implements the URIResolver.resolve() interface method.
403      * @param href an href attribute.
404      * @param base the base URI.
405      * @return a Source object, or null if href cannot be resolved.
406      * @throws TransformerException if an error occurs.
407      * @see javax.xml.transform.URIResolver#resolve
408      */
409     public Source resolve(String href, String base)
410         throws TransformerException {
411
412         if (isReference()) {
413             return getRef().resolve(href, base);
414         }
415
416         dieOnCircularReference();
417
418         SAXSource source = null;
419
420         String uri = removeFragment(href);
421
422         log("resolve: '" + uri + "' with base: '" + base + "'", Project.MSG_DEBUG);
423
424         source = (SAXSource ) getCatalogResolver().resolve(uri, base);
425
426         if (source == null) {
427             log("No matching catalog entry found, parser will use: '"
428                 + href + "'", Project.MSG_DEBUG);
429             //
430 // Cannot return a null source, because we have to call
431 // setEntityResolver (see setEntityResolver javadoc comment)
432 //
433 source = new SAXSource ();
434             URL baseURL = null;
435             try {
436                 if (base == null) {
437                     baseURL = FILE_UTILS.getFileURL(getProject().getBaseDir());
438                 } else {
439                     baseURL = new URL (base);
440                 }
441                 URL url = (uri.length() == 0 ? baseURL : new URL (baseURL, uri));
442                 source.setInputSource(new InputSource (url.toString()));
443             } catch (MalformedURLException ex) {
444                 // At this point we are probably in failure mode, but
445 // try to use the bare URI as a last gasp
446 source.setInputSource(new InputSource (uri));
447             }
448         }
449
450         setEntityResolver(source);
451         return source;
452     }
453
454     /**
455      * @since Ant 1.6
456      */
457     private XMLCatalog getRef() {
458         if (!isReference()) {
459             return this;
460         }
461         return (XMLCatalog) getCheckedRef(XMLCatalog.class, "xmlcatalog");
462     }
463
464     /**
465      * The instance of the CatalogResolver strategy to use.
466      */
467     private CatalogResolver catalogResolver = null;
468
469     /**
470      * Factory method for creating the appropriate CatalogResolver
471      * strategy implementation.
472      * <p> Until we query the classpath, we don't know whether the Apache
473      * resolver (Norm Walsh's library from xml-commons) is available or not.
474      * This method determines whether the library is available and creates the
475      * appropriate implementation of CatalogResolver based on the answer.</p>
476      * <p>This is an application of the Gang of Four Strategy Pattern
477      * combined with Template Method.</p>
478      */
479     private CatalogResolver getCatalogResolver() {
480
481         if (catalogResolver == null) {
482
483             AntClassLoader loader = null;
484
485             loader = getProject().createClassLoader(Path.systemClasspath);
486
487             try {
488                 Class clazz = Class.forName(APACHE_RESOLVER, true, loader);
489
490                 // The Apache resolver is present - Need to check if it can
491 // be seen by the catalog resolver class. Start by getting
492 // the actual loader
493 ClassLoader apacheResolverLoader = clazz.getClassLoader();
494
495                 // load the base class through this loader.
496 Class baseResolverClass
497                     = Class.forName(CATALOG_RESOLVER, true, apacheResolverLoader);
498
499                 // and find its actual loader
500 ClassLoader baseResolverLoader
501                     = baseResolverClass.getClassLoader();
502
503                 // We have the loader which is being used to load the
504 // CatalogResolver. Can it see the ApacheResolver? The
505 // base resolver will only be able to create the ApacheResolver
506 // if it can see it - doesn't use the context loader.
507 clazz = Class.forName(APACHE_RESOLVER, true, baseResolverLoader);
508
509                 Object obj = clazz.newInstance();
510                 //
511 // Success! The xml-commons resolver library is
512 // available, so use it.
513 //
514 catalogResolver = new ExternalResolver(clazz, obj);
515             } catch (Throwable ex) {
516                 //
517 // The xml-commons resolver library is not
518 // available, so we can't use it.
519 //
520 catalogResolver = new InternalResolver();
521                 if (getCatalogPath() != null
522                     && getCatalogPath().list().length != 0) {
523                         log("Warning: XML resolver not found; external catalogs"
524                             + " will be ignored", Project.MSG_WARN);
525                     }
526                 log("Failed to load Apache resolver: " + ex, Project.MSG_DEBUG);
527             }
528         }
529         return catalogResolver;
530     }
531
532     /**
533      * <p>This is called from the URIResolver to set an EntityResolver
534      * on the SAX parser to be used for new XML documents that are
535      * encountered as a result of the document() function, xsl:import,
536      * or xsl:include. This is done because the XSLT processor calls
537      * out to the SAXParserFactory itself to create a new SAXParser to
538      * parse the new document. The new parser does not automatically
539      * inherit the EntityResolver of the original (although arguably
540      * it should). See below:</p>
541      *
542      * <tt>"If an application wants to set the ErrorHandler or
543      * EntityResolver for an XMLReader used during a transformation,
544      * it should use a URIResolver to return the SAXSource which
545      * provides (with getXMLReader) a reference to the XMLReader"</tt>
546      *
547      * <p>...quoted from page 118 of the Java API for XML
548      * Processing 1.1 specification</p>
549      *
550      */
551     private void setEntityResolver(SAXSource source) throws TransformerException {
552
553         XMLReader reader = source.getXMLReader();
554         if (reader == null) {
555             SAXParserFactory spFactory = SAXParserFactory.newInstance();
556             spFactory.setNamespaceAware(true);
557             try {
558                 reader = spFactory.newSAXParser().getXMLReader();
559             } catch (ParserConfigurationException ex) {
560                 throw new TransformerException (ex);
561             } catch (SAXException ex) {
562                 throw new TransformerException (ex);
563             }
564         }
565         reader.setEntityResolver(this);
566         source.setXMLReader(reader);
567     }
568
569     /**
570      * Find a ResourceLocation instance for the given publicId.
571      *
572      * @param publicId the publicId of the Resource for which local information
573      * is required.
574      * @return a ResourceLocation instance with information on the local location
575      * of the Resource or null if no such information is available.
576      */
577     private ResourceLocation findMatchingEntry(String publicId) {
578         Enumeration e = getElements().elements();
579         ResourceLocation element = null;
580         while (e.hasMoreElements()) {
581             Object o = e.nextElement();
582             if (o instanceof ResourceLocation) {
583                 element = (ResourceLocation) o;
584                 if (element.getPublicId().equals(publicId)) {
585                     return element;
586                 }
587             }
588         }
589         return null;
590     }
591
592     /**
593      * Utility method to remove trailing fragment from a URI.
594      * For example,
595      * <code>http://java.sun.com/index.html#chapter1</code>
596      * would return <code>http://java.sun.com/index.html</code>.
597      *
598      * @param uri The URI to process. It may or may not contain a
599      * fragment.
600      * @return The URI sans fragment.
601      */
602     private String removeFragment(String uri) {
603         String result = uri;
604         int hashPos = uri.indexOf("#");
605         if (hashPos >= 0) {
606             result = uri.substring(0, hashPos);
607         }
608         return result;
609     }
610
611     /**
612      * Utility method to lookup a ResourceLocation in the filesystem.
613      *
614      * @return An InputSource for reading the file, or <code>null</code>
615      * if the file does not exist or is not readable.
616      */
617     private InputSource filesystemLookup(ResourceLocation matchingEntry) {
618
619         String uri = matchingEntry.getLocation();
620         // the following line seems to be necessary on Windows under JDK 1.2
621 uri = uri.replace(File.separatorChar, '/');
622         URL baseURL = null;
623
624         //
625 // The ResourceLocation may specify a relative path for its
626 // location attribute. This is resolved using the appropriate
627 // base.
628 //
629 if (matchingEntry.getBase() != null) {
630             baseURL = matchingEntry.getBase();
631         } else {
632             try {
633                 baseURL = FILE_UTILS.getFileURL(getProject().getBaseDir());
634             } catch (MalformedURLException ex) {
635                 throw new BuildException("Project basedir cannot be converted to a URL");
636             }
637         }
638
639         InputSource source = null;
640         URL url = null;
641         try {
642             url = new URL (baseURL, uri);
643         } catch (MalformedURLException ex) {
644             // this processing is useful under Windows when the location of the DTD
645 // has been given as an absolute path
646 // see Bugzilla Report 23913
647 File testFile = new File (uri);
648             if (testFile.exists() && testFile.canRead()) {
649                 log("uri : '"
650                     + uri + "' matches a readable file", Project.MSG_DEBUG);
651                 try {
652                     url = FILE_UTILS.getFileURL(testFile);
653                 } catch (MalformedURLException ex1) {
654                     throw new BuildException(
655                         "could not find an URL for :" + testFile.getAbsolutePath());
656                 }
657             } else {
658                 log("uri : '"
659                     + uri + "' does not match a readable file", Project.MSG_DEBUG);
660
661             }
662         }
663
664         if (url != null && url.getProtocol().equals("file")) {
665             String fileName = FILE_UTILS.fromURI(url.toString());
666             if (fileName != null) {
667                 log("fileName " + fileName, Project.MSG_DEBUG);
668                 File resFile = new File (fileName);
669                 if (resFile.exists() && resFile.canRead()) {
670                     try {
671                         source = new InputSource (new FileInputStream (resFile));
672                         String sysid = JAXPUtils.getSystemId(resFile);
673                         source.setSystemId(sysid);
674                         log("catalog entry matched a readable file: '"
675                             + sysid + "'", Project.MSG_DEBUG);
676                     } catch (IOException ex) {
677                         // ignore
678 }
679                 }
680             }
681         }
682         return source;
683     }
684
685     /**
686      * Utility method to lookup a ResourceLocation in the classpath.
687      *
688      * @return An InputSource for reading the resource, or <code>null</code>
689      * if the resource does not exist in the classpath or is not readable.
690      */
691     private InputSource classpathLookup(ResourceLocation matchingEntry) {
692
693         InputSource source = null;
694
695         AntClassLoader loader = null;
696         Path cp = classpath;
697         if (cp != null) {
698             cp = classpath.concatSystemClasspath("ignore");
699         } else {
700             cp = (new Path(getProject())).concatSystemClasspath("last");
701         }
702         loader = getProject().createClassLoader(cp);
703
704         //
705 // for classpath lookup we ignore the base directory
706 //
707 InputStream is
708             = loader.getResourceAsStream(matchingEntry.getLocation());
709
710         if (is != null) {
711             source = new InputSource (is);
712             URL entryURL = loader.getResource(matchingEntry.getLocation());
713             String sysid = entryURL.toExternalForm();
714             source.setSystemId(sysid);
715             log("catalog entry matched a resource in the classpath: '"
716                 + sysid + "'", Project.MSG_DEBUG);
717         }
718
719         return source;
720     }
721
722     /**
723      * Utility method to lookup a ResourceLocation in URL-space.
724      *
725      * @return An InputSource for reading the resource, or <code>null</code>
726      * if the resource does not identify a valid URL or is not readable.
727      */
728     private InputSource urlLookup(ResourceLocation matchingEntry) {
729
730         String uri = matchingEntry.getLocation();
731         URL baseURL = null;
732
733         //
734 // The ResourceLocation may specify a relative url for its
735 // location attribute. This is resolved using the appropriate
736 // base.
737 //
738 if (matchingEntry.getBase() != null) {
739             baseURL = matchingEntry.getBase();
740         } else {
741             try {
742                 baseURL = FILE_UTILS.getFileURL(getProject().getBaseDir());
743             } catch (MalformedURLException ex) {
744                 throw new BuildException("Project basedir cannot be converted to a URL");
745             }
746         }
747
748         InputSource source = null;
749         URL url = null;
750
751         try {
752             url = new URL (baseURL, uri);
753         } catch (MalformedURLException ex) {
754             // ignore
755 }
756
757         if (url != null) {
758             try {
759                 InputStream is = url.openStream();
760                 if (is != null) {
761                     source = new InputSource (is);
762                     String sysid = url.toExternalForm();
763                     source.setSystemId(sysid);
764                     log("catalog entry matched as a URL: '"
765                         + sysid + "'", Project.MSG_DEBUG);
766                 }
767             } catch (IOException ex) {
768                 // ignore
769 }
770         }
771
772         return source;
773
774     }
775
776     /**
777      * Interface implemented by both the InternalResolver strategy and
778      * the ExternalResolver strategy.
779      */
780     private interface CatalogResolver extends URIResolver , EntityResolver {
781
782         InputSource resolveEntity(String publicId, String systemId);
783
784         Source resolve(String href, String base) throws TransformerException ;
785     }
786
787     /**
788      * The InternalResolver strategy is used if the Apache resolver
789      * library (Norm Walsh's library from xml-commons) is not
790      * available. In this case, external catalog files will be
791      * ignored.
792      *
793      */
794     private class InternalResolver implements CatalogResolver {
795
796         public InternalResolver() {
797             log("Apache resolver library not found, internal resolver will be used",
798                 Project.MSG_VERBOSE);
799         }
800
801         public InputSource resolveEntity(String publicId,
802                                          String systemId) {
803             InputSource result = null;
804             ResourceLocation matchingEntry = findMatchingEntry(publicId);
805
806             if (matchingEntry != null) {
807
808                 log("Matching catalog entry found for publicId: '"
809                     + matchingEntry.getPublicId() + "' location: '"
810                     + matchingEntry.getLocation() + "'",
811                     Project.MSG_DEBUG);
812
813                 result = filesystemLookup(matchingEntry);
814
815                 if (result == null) {
816                     result = classpathLookup(matchingEntry);
817                 }
818
819                 if (result == null) {
820                     result = urlLookup(matchingEntry);
821                 }
822             }
823             return result;
824         }
825
826         public Source resolve(String href, String base)
827