XMLCatalog Type

From b9421dc80af485591a9c50cc8921f912e0def11e Mon Sep 17 00:00:00 2001 From: Ashlee Young Date: Fri, 23 Oct 2015 10:05:40 -0700 Subject: Removing sources to replace with download links instead. Change-Id: Ie28789a725051aec0d1b04dd291b7690a7898668 Signed-off-by: Ashlee Young --- .../apache-ant-1.9.6/manual/Types/xmlcatalog.html | 306 --------------------- 1 file changed, 306 deletions(-) delete mode 100644 framework/src/ant/apache-ant-1.9.6/manual/Types/xmlcatalog.html (limited to 'framework/src/ant/apache-ant-1.9.6/manual/Types/xmlcatalog.html') diff --git a/framework/src/ant/apache-ant-1.9.6/manual/Types/xmlcatalog.html b/framework/src/ant/apache-ant-1.9.6/manual/Types/xmlcatalog.html deleted file mode 100644 index a0ddafc0..00000000 --- a/framework/src/ant/apache-ant-1.9.6/manual/Types/xmlcatalog.html +++ /dev/null @@ -1,306 +0,0 @@ - - - - - - -XMLCatalog Type - - - - -

XMLCatalog

- -

An XMLCatalog is a catalog of public resources such as DTDs or -entities that are referenced in an XML document. Catalogs are -typically used to make web references to resources point to a locally -cached copy of the resource.

- -

This allows the XML Parser, XSLT Processor or other consumer of XML -documents -to efficiently allow a local substitution for a resource available on the -web. -

Note: This task uses, but does not depend on external -libraries not included in the Apache Ant distribution. See Library Dependencies for more -information.

This data type provides a catalog of resource locations based -on the -OASIS "Open Catalog" standard. The catalog entries are used -both for Entity resolution and URI resolution, in accordance with -the org.xml.sax.EntityResolver and -javax.xml.transform.URIResolver interfaces as defined -in the Java API for XML -Processing (JAXP) Specification.

For example, in a web.xml file, the DTD is referenced as: -

-<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN"
-  "http://java.sun.com/j2ee/dtds/web-app_2_2.dtd">
-

-The XML processor, without XMLCatalog support, would need to retrieve the -DTD from -the URL specified whenever validation of the document was required. -

This can be very time consuming during the build process, -especially where network throughput is limited. Alternatively, you -can do the following: -

Copy web-app_2_2.dtd onto your local disk somewhere (either in the -filesystem or even embedded inside a jar or zip file on the classpath).
Create an <xmlcatalog> with a <dtd> -element whose location attribute points to the file.
Success! The XML processor will now use the local copy instead of calling out -to the internet.

XMLCatalogs can appear inside tasks -that support this feature or at the same level as target -- i.e., as children of project for reuse across different -tasks, -e.g. XML Validation and XSLT Transformation. The XML Validate task -uses XMLCatalogs for entity resolution. The XSLT Transformation -task uses XMLCatalogs for both entity and URI resolution.

XMLCatalogs are specified as either a reference to another -XMLCatalog, defined previously in a build file, or as a list of -dtd or entity locations. In addition, -external catalog files may be specified in a nested catalogpath , -but they will be ignored unless the resolver library from -xml-commons is available in the system classpath. 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 -expect a resolver release 1.1 to happen before Ant 1.6 gets -released. A separate classpath for entity resolution may be -specified inline via nested classpath elements; otherwise -the system classpath is used for this as well.

XMLCatalogs can also be nested inside other XMLCatalogs. For -example, a "superset" XMLCatalog could be made by including several -nested XMLCatalogs that referred to other, previously defined -XMLCatalogs.

Resource locations can be specified either in-line or in -external catalog file(s), or both. In order to use an external -catalog file, the xml-commons resolver library ("resolver.jar") -must be in your path. External catalog files may be either -plain text format or -XML format. If the xml-commons resolver library is not found in the -classpath, external catalog files, specified in catalogpath, -will be ignored and a warning -will be logged. In this case, however, processing of inline entries will -proceed normally.

Currently, only <dtd> and -<entity> elements may be specified inline; these -roughly correspond to OASIS catalog entry types PUBLIC and -URI respectively. By contrast, external catalog files -may use any of the entry types defined in the - -+OASIS specification.

Entity/DTD/URI Resolution Algorithm

- -When an entity, DTD, or URI is looked up by the XML processor, the -XMLCatalog searches its list of entries to see if any match. That is, -it attempts to match the publicId attribute of each entry -with the PublicID or URI of the entity to be resolved. Assuming a -matching entry is found, XMLCatalog then executes the following steps: - -

1. Filesystem lookup

- -

The location is first looked up in the filesystem. If -the location is a relative path, the ant project basedir -attribute is used as the base directory. If the location -specifies an absolute path, it is used as is. Once we have an -absolute path in hand, we check to see if a valid and readable file -exists at that path. If so, we are done. If not, we proceed to the -next step.

- -

2. Classpath lookup

- -

The location is next looked up in the classpath. -Recall that jar files are merely fancy zip files. For classpath -lookup, the location is used as is (no base is -prepended). We use a Classloader to attempt to load the resource from -the classpath. For example, if hello.jar is in the classpath and it -contains foo/bar/blat.dtd it will resolve an entity whose -location is foo/bar/blat.dtd. Of course, it -will not resolve an entity whose location is -blat.dtd. - - -

3a. Apache xml-commons resolver lookup

- -

What happens next depends on whether the resolver library from -xml-commons is available on the classpath. If so, we defer all -further attempts at resolving to it. The resolver library supports -extremely sophisticated functionality like URL rewriting and so on, -which can be accessed by making the appropriate entries in external -catalog files (XMLCatalog does not yet provide inline support for all -of the entries defined in the OASIS -standard).

- -

3. URL-space lookup

- -

Finally, we attempt to make a URL out of the location. -At first this may seem like this would defeat the purpose of -XMLCatalogs -- why go back out to the internet? But in fact, this can -be used to (in a sense) implement HTTP redirects, substituting one URL -for another. The mapped-to URL might also be served by a local web -server. If the URL resolves to a valid and readable resource, we are -done. Otherwise, we give up. In this case, the XML processor will -perform its normal resolution algorithm. Depending on the processor -configuration, further resolution failures may or may not result in -fatal (i.e. build-ending) errors.

- -

XMLCatalog attributes

- - - - - - - - - - - - - - - - -

Attribute	Description	Required
id	a unique name for an XMLCatalog, used for referencing -the - XMLCatalog's contents from another XMLCatalog	No
refid	the `id` of another XMLCatalog whose -contents - you would like to be used for this XMLCatalog	No

- -

XMLCatalog nested elements

dtd/entity

The dtd and entity elements used to specify -XMLCatalogs are identical in their structure

- - - - - - - - - - - - - - - - -

Attribute	Description	Required
publicId	The public identifier used when defining a dtd or -entity, - e.g. `"-//Sun Microsystems, Inc.//DTD Web Application -2.2//EN"` -	Yes
location	The location of the local replacement to be used for -the public identifier specified. This may be specified as a file name, -resource name found on the classpath, or a URL. Relative paths will -be resolved according to the base, which by default is the Ant project -basedir. -	Yes

classpath

The classpath to use for entity -resolution. The nested <classpath> is a -path-like structure.

catalogpath

-The nested catalogpath element is a path-like structure listing catalog files to -search. All files in this path are assumed to be OASIS catalog files, in -either - -plain text format or -XML format. Entries specifying nonexistent files will be ignored. If the -resolver library from xml-commons is not available in the classpath, all -catalogpaths will be ignored and a warning will be logged. -

Examples

Set up an XMLCatalog with a single dtd referenced locally in a user's -home -directory:

-    <xmlcatalog>
-        <dtd 
-            publicId="-//OASIS//DTD DocBook XML V4.1.2//EN"
-            location="/home/dion/downloads/docbook/docbookx.dtd"/>
-    </xmlcatalog>
-

Set up an XMLCatalog with a multiple dtds to be found either in the -filesystem (relative to the Ant project basedir) or in the classpath: -

-    <xmlcatalog id="commonDTDs">
-        <dtd 
-            publicId="-//OASIS//DTD DocBook XML V4.1.2//EN"
-            location="docbook/docbookx.dtd"/>
-        <dtd 
-            publicId="-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN"
-            location="web-app_2_2.dtd"/>
-    </xmlcatalog>
-

- -

Set up an XMLCatalog with a combination of DTDs and entities as -well as a nested XMLCatalog and external catalog files in both -formats:

- -

-    <xmlcatalog id="allcatalogs">
-        <dtd 
-            publicId="-//ArielPartners//DTD XML Article V1.0//EN"
-            location="com/arielpartners/knowledgebase/dtd/article.dtd"/>
-        <entity 
-            publicId="LargeLogo"
-            location="com/arielpartners/images/ariel-logo-large.gif"/>
-        <xmlcatalog refid="commonDTDs"/>
-            <catalogpath>
-                <pathelement location="/etc/sgml/catalog"/>
-                <fileset 
-                    dir="/anetwork/drive"
-                    includes="**/catalog"/>
-                <fileset 
-                    dir="/my/catalogs"
-                    includes="**/catalog.xml"/>
-            </catalogpath>
-        </xmlcatalog>
-    </xmlcatalog>
-

To reference the above XMLCatalog in an xslt task:

-    <xslt basedir="${source.doc}"
-           destdir="${dest.xdocs}"
-           extension=".xml"
-           style="${source.xsl.converter.docbook}"
-           includes="**/*.xml"
-           force="true">
-        <xmlcatalog refid="allcatalogs"/>
-    </xslt>
-

- - - - - -- cgit 1.2.3-korg