org.backsource.utils.xml
Class CatalogResolver

java.lang.Object
  org.backsource.utils.xml.CatalogResolver

All Implemented Interfaces:

org.xml.sax.EntityResolver, javax.xml.transform.URIResolver

public class CatalogResolver

extends java.lang.Object

implements org.xml.sax.EntityResolver, javax.xml.transform.URIResolver

A Catalog based resolver which is originally based on org.apache.xml.resolver.tools.CatalogResolver.

It does currently not extend from the original resolver since the Catalog of that resolver has private access. This is a JAXP type resolver which adds the following featues to the original:

• It is possible to programatically set the Catalog the resolver should use.
• if catalog resolve of systemId or href fail both are translated to a "name" version - i.e last part of it is used to do one more lookup against the catalog. For example xerces translated systemId:s to the full path of its current working directory; so nitf.dtd will be called for examle file:///my/path/nitf.dtd, where /my/path actually is where the program happens to be running: to be able to write Catalog entries that do not have to know where programs are running the systemId id is also rewritten to the name part an tested again.
• It contains an implicit Catalog: if there is no entry in its Catalog the resource is translated to a name part, or if relative to that, and looked up in the filesystem relative to the base of the Catalog.
• It uses URI and friends to translate an uri to an URL.

Here's one way to use it, see Catalog on how to create the catalog

      CatalogResolver stdResolver = new CatalogResolver(catalog);
      TransformerFactory tfactory = TransformerFactory.newInstance();
      Transformer serializer = tfactory.newTransformer();
      serializer.setURIResolver( stdResolver );

      // Or
      DocumentBuilderFactory docBuilderFactory = DocumentBuilderFactory.newInstance();
      DocumentBuilder docBuilder = docBuilderFactory.newDocumentBuilder();
      docBuilder.setEntityResolver( stdResolver );
 

When using with utils in this package one often have to use the Resolver and ResolverContext classes to set the resolver in the environment. To get DocumentUtil to use a given resolver on could for example do this:

      Resolver res = new Resolver(stdResolver,stdResolver);
      ResolverContext.set(res);

      // This would then use that resolver
      Document doc = DocumentUtil.getDocument( myFile );

Through its use of URI to lookup resolved uris it is possible to lookup resources at other places than the filesystem or HTTP; it makes it possible to lookup resources in the classpath or in a servlet resoource context. It is possible to programaticallty set a URIFactory on a CatalogResolver, but when no one is specifyed the normal resolution mechanism is done where URIFactoryContext is used.

      classPathResolver = new CatalogResolver(catalog);
      URIFactory f = new URIFactory();
      f.register("class", new ClassContextURLFactory());
      classPathResolver.setURIFactory(f);

Since the default for URI factory is to use the classpath when al else fails this setup would make it possible to lookuo both these entries int the classpath:

      catalog.addCatalogEntry( CatalogEntry.getSystemEntry("log4j.dtd", "class:org/apache/log4j/xml/log4j.dtd") );
      catalog.addCatalogEntry( CatalogEntry.getSystemEntry("log4j.dtd", "/org/apache/log4j/xml/log4j.dtd") );

The following is one way to lookup the resource from the classpath in the current thread only.

      ResolverContext.setThreadLocal( new Resolver(classPathResolver,classPathResolver) );
      Document doc = DocumentUtil.getDocument( new FileInputStream(log4jFile ) );

Version:

$Revision: 1.3 $

Author:

Peter Antman, Norman Walsh Norman.Walsh@Sun.COM

See Also:

Catalog, EntityResolver, URIResolver, URIFactory

Field Summary

protected Catalog	catalog
protected URIFactory	uriFactory

Constructor Summary

CatalogResolver(Catalog catalog)

Method Summary

Catalog	getCatalog()
protected java.lang.String	getName(java.lang.String uriSpec) Deduce the name part of the URI
java.lang.String	getResolvedEntity(java.lang.String publicId, java.lang.String systemId) Implements the guts of the resolveEntity method for the SAX interface.
URIFactory	getURIFactory() Get the URIFactory that was set.
javax.xml.transform.Source	resolve(java.lang.String href, java.lang.String base) JAXP URIResolver API.
org.xml.sax.InputSource	resolveEntity(java.lang.String publicId, java.lang.String systemId) Implements the resolveEntity method for the SAX interface.
void	setURIFactory(URIFactory factory) Set the URIFactory that URI should use when translating uris to reasources.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

catalog

protected Catalog catalog

uriFactory

protected URIFactory uriFactory

Constructor Detail

CatalogResolver

public CatalogResolver(Catalog catalog)

Method Detail

getCatalog

public Catalog getCatalog()

setURIFactory

public void setURIFactory(URIFactory factory)

Set the URIFactory that URI should use when translating uris to reasources.

if no URIFactory is set the normal factory resolution mechanism is used in URI.

See Also:

URIFactory

getURIFactory

public URIFactory getURIFactory()

Get the URIFactory that was set.

getResolvedEntity

public java.lang.String getResolvedEntity(java.lang.String publicId,
                                          java.lang.String systemId)

Implements the guts of the resolveEntity method for the SAX interface.

Presented with an optional public identifier and a system identifier, this function attempts to locate a mapping in the catalogs.

If such a mapping is found, it is returned. If no mapping is found, null is returned.

Parameters:

publicId - The public identifier for the entity in question. This may be null.

systemId - The system identifier for the entity in question. XML requires a system identifier on all external entities, so this value is always specified.

Returns:

The resolved identifier (a URI reference).

resolveEntity

public org.xml.sax.InputSource resolveEntity(java.lang.String publicId,
                                             java.lang.String systemId)

Implements the resolveEntity method for the SAX interface.

Presented with an optional public identifier and a system identifier, this function attempts to locate a mapping in the catalogs.

if that fails the systemId is translated to a name (last part) and looked up again.

If such a mapping is found, the resolver creates an URI and lets the URIFactory in use translate the URI to and URL. This is opened as an InputSource and is returned. Exceptions are ignored and null is returned if the mapped value cannot be opened as an input source.

Last the systemId is used as a name (or if relative the relatove path) and looked up as a file with the resolver base URI as base path.

If no mapping is found (or an error occurs attempting to open the mapped value as an input source), null is returned and the system will use the specified system identifier as if no entityResolver was specified.

Specified by:

resolveEntity in interface org.xml.sax.EntityResolver

Parameters:

publicId - The public identifier for the entity in question. This may be null.

systemId - The system identifier for the entity in question. XML requires a system identifier on all external entities, so this value is always specified.

Returns:

An InputSource for the mapped identifier, or null.

resolve

public javax.xml.transform.Source resolve(java.lang.String href,
                                          java.lang.String base)
                                   throws javax.xml.transform.TransformerException

JAXP URIResolver API. Resolves href by the following steps.

1. Lookup href in catalog,
2. Remake href into a name, ie last part, and lookup in catalog
3. Take last part (or relative name) and lookup against the base url of the Catalog in the filesystem.
4. Use the base and lastly user.dir to locate the name of the resource

The firts two steps and the last are then looked up with the help of URI.

Specified by:

resolve in interface javax.xml.transform.URIResolver

Throws:

javax.xml.transform.TransformerException

getName

protected java.lang.String getName(java.lang.String uriSpec)
                            throws java.net.MalformedURLException

Deduce the name part of the URI

Throws:

java.net.MalformedURLException