A Catalog Resolver that implements SAX org.xml.sax.EntityResolver, StAX javax.xml.stream.XMLResolver, DOM LS org.w3c.dom.ls.LSResourceResolver used by Schema Validation, and Transform javax.xml.transform.URIResolver, and resolves external references using catalogs.

The Catalog Standard distinguished external identifiers from uri entries as being used to solely identify DTDs, while uri entries for other resources such as stylesheets and schema. The Java APIs, such as javax.xml.stream.XMLResolver and org.w3c.dom.ls.LSResourceResolver however, make no such distinction. In consistent with the existing Java API, this CatalogResolver recognizes a system identifier as a URI and will search both system and uri entries in a catalog in order to find a matching entry.

The search is started in the current catalog. If a match is found, no further attempt will be made. Only if there is no match in the current catalog, will alternate catalogs including delegate and next catalogs be considered.

Search Order

The resolver will first search the system-type of entries with the specified systemId. The system entries include system, rewriteSystem and systemSuffix entries.

If no match is found, public entries may be searched in accordance with the prefer attribute.

The prefer attribute: if the prefer is public, and there is no match found through the system entries, public entries will be considered. If it is not specified, the prefer is public by default (Note that by the OASIS standard, system entries will always be considered before public entries. Prefer public means that public entries will be matched when both system and public identifiers are specified. In general therefore, prefer public is recommended.)

If no match is found with the systemId and public identifier, the resolver will continue searching uri entries with the specified systemId or href. The uri entries include uri, rewriteURI, and uriSuffix entries.

Error Handling

The interfaces that the CatalogResolver extend specified checked exceptions, including:

The CatalogResolver however, will throw javax.xml.catalog.CatalogException only when javax.xml.catalog.resolve is specified as strict. For applications that expect to handle the checked Exceptions, it may be necessary to use a custom resolver to wrap the CatalogResolver or implement it with a javax.xml.catalog.Catalog object.

Nested and Inner Type Summary

Modifier and Type	Class and Description
public static enum	CatalogResolver.NotFoundAction Defines the actions that a CatalogResolver may take when it is unable to resolve an external reference.

Method Summary

Modifier and Type	Method and Description
public Source	Returns: a `javax.xml.transform.Source` object if a mapping is found. If no mapping is found, returns an empty `javax.xml.transform.Source` object if the `javax.xml.catalog.resolve` property is set to `ignore`; returns a `javax.xml.transform.Source` object with the original URI (href, or href resolved with base if base is not null) if the `javax.xml.catalog.resolve` property is set to `continue`. resolve(String the href attribute that specifies the URI of a style sheet, which may be relative or absolute href, String The base URI against which the href attribute will be made absolute if the absolute URI is required base) Redeclares javax.xml.transform.URIResolver.resolve. Implements URIResolver.
public InputSource	Returns: a `org.xml.sax.InputSource` object if a mapping is found. If no mapping is found, returns a `org.xml.sax.InputSource` object containing an empty `java.io.Reader` if the `javax.xml.catalog.resolve` property is set to `ignore`; returns null if the `javax.xml.catalog.resolve` property is set to `continue`. resolveEntity(String the public identifier of the external entity being referenced, or null if none was supplied publicId, String the system identifier of the external entity being referenced. A system identifier is required on all external entities. XML requires a system identifier on all external entities, so this value is always specified. systemId) Redeclares org.xml.sax.EntityResolver.resolveEntity. Implements `org.xml.sax.EntityResolver`.
public InputStream	Returns: an `java.io.InputStream` object if a mapping is found; null if no mapping is found and the `javax.xml.catalog.resolve` property is set to `continue` or `ignore`. Note that for XMLResolver, it is not possible to ignore a reference, `ignore` is therefore treated the same as `continue`. resolveEntity(String the public identifier of the external entity being referenced, or null if none was supplied publicId, String the system identifier of the external entity being referenced. A system identifier is required on all external entities. XML requires a system identifier on all external entities, so this value is always specified. systemId, String the absolute base URI, not used by the CatalogResolver baseUri, String the namespace of the entity to resolve, not used by the CatalogResolver. namespace) Redeclares javax.xml.stream.XMLResolver.resolveEntity. Implements `javax.xml.stream.XMLResolver`.
public LSInput	Returns: a `org.w3c.dom.ls.LSInput` object if a mapping is found; null if no mapping is found and the `javax.xml.catalog.resolve` property is set to `continue` or `ignore`. Note that for `org.w3c.dom.ls.LSResourceResolver`, it is not possible to ignore a reference, `ignore` is therefore treated the same as `continue`. resolveResource(String the type of the resource being resolved, not used by the CatalogResolver type, String the namespace of the resource being resolved, not used by the CatalogResolver namespaceUri, String the public identifier of the external entity being referenced, or `null` if no public identifier was supplied or if the resource is not an entity. publicId, String the system identifier, a URI reference of the external resource being referenced systemId, String the absolute base URI, not used by the CatalogResolver baseUri) Redeclares org.w3c.dom.ls.LSResourceResolver.resolveResource. Implements `org.w3c.dom.ls.LSResourceResolver`.

Method Detail

resolve back to summary

resolve	back to summary
public Source resolve(String href, String base) Redeclares javax.xml.transform.URIResolver.resolve. Implements URIResolver. The method searches through the catalog entries in the main and alternative catalogs to attempt to find a match with the specified `href` attribute. The `href` attribute will be used literally, with no attempt to be made absolute to the `base`. If the value is a URN, the `href` attribute is recognized as a `publicId`, and used to search `public` entries. If the value is a URI, it is taken as a `systemId`, and used to search both `system` and `uri` entries. Parameters href:String the href attribute that specifies the URI of a style sheet, which may be relative or absolute base:String The base URI against which the href attribute will be made absolute if the absolute URI is required Returns:Source a `javax.xml.transform.Source` object if a mapping is found. If no mapping is found, returns an empty `javax.xml.transform.Source` object if the `javax.xml.catalog.resolve` property is set to `ignore`; returns a `javax.xml.transform.Source` object with the original URI (href, or href resolved with base if base is not null) if the `javax.xml.catalog.resolve` property is set to `continue`. Annotations @Override Exceptions CatalogException: if no mapping is found and `javax.xml.catalog.resolve` is specified as `strict`

public Source resolve(String href, String base)

Redeclares javax.xml.transform.URIResolver.resolve.

Implements URIResolver. The method searches through the catalog entries in the main and alternative catalogs to attempt to find a match with the specified href attribute. The href attribute will be used literally, with no attempt to be made absolute to the base.

If the value is a URN, the href attribute is recognized as a publicId, and used to search public entries. If the value is a URI, it is taken as a systemId, and used to search both system and uri entries.

Parameters

href:String: the href attribute that specifies the URI of a style sheet, which may be relative or absolute
base:String: The base URI against which the href attribute will be made absolute if the absolute URI is required

Returns:Source

a javax.xml.transform.Source object if a mapping is found. If no mapping is found, returns an empty javax.xml.transform.Source object if the javax.xml.catalog.resolve property is set to ignore; returns a javax.xml.transform.Source object with the original URI (href, or href resolved with base if base is not null) if the javax.xml.catalog.resolve property is set to continue.

Annotations

@Override

Exceptions

CatalogException:: if no mapping is found and javax.xml.catalog.resolve is specified as strict

resolveEntity back to summary

resolveEntity	back to summary
public InputSource resolveEntity(String publicId, String systemId) Redeclares org.xml.sax.EntityResolver.resolveEntity. Implements `org.xml.sax.EntityResolver`. The method searches through the catalog entries in the main and alternative catalogs to attempt to find a match with the specified `publicId` or systemId. Parameters publicId:String the public identifier of the external entity being referenced, or null if none was supplied systemId:String the system identifier of the external entity being referenced. A system identifier is required on all external entities. XML requires a system identifier on all external entities, so this value is always specified. Returns:InputSource a `org.xml.sax.InputSource` object if a mapping is found. If no mapping is found, returns a `org.xml.sax.InputSource` object containing an empty `java.io.Reader` if the `javax.xml.catalog.resolve` property is set to `ignore`; returns null if the `javax.xml.catalog.resolve` property is set to `continue`. Annotations @Override Exceptions CatalogException: if no mapping is found and `javax.xml.catalog.resolve` is specified as `strict`

public InputSource resolveEntity(String publicId, String systemId)

Redeclares org.xml.sax.EntityResolver.resolveEntity.

Implements org.xml.sax.EntityResolver. The method searches through the catalog entries in the main and alternative catalogs to attempt to find a match with the specified publicId or systemId.

Parameters

publicId:String: the public identifier of the external entity being referenced, or null if none was supplied
systemId:String: the system identifier of the external entity being referenced. A system identifier is required on all external entities. XML requires a system identifier on all external entities, so this value is always specified.

Returns:InputSource

a org.xml.sax.InputSource object if a mapping is found. If no mapping is found, returns a org.xml.sax.InputSource object containing an empty java.io.Reader if the javax.xml.catalog.resolve property is set to ignore; returns null if the javax.xml.catalog.resolve property is set to continue.

Annotations

@Override

Exceptions

CatalogException:: if no mapping is found and javax.xml.catalog.resolve is specified as strict

resolveEntity back to summary

resolveEntity	back to summary
public InputStream resolveEntity(String publicId, String systemId, String baseUri, String namespace) Redeclares javax.xml.stream.XMLResolver.resolveEntity. Implements `javax.xml.stream.XMLResolver`. For the purpose of resolving `publicId` and `systemId`, this method is equivalent to `resolveEntity(java.lang.String, java.lang.String)`. The `systemId` will be used literally, with no attempt to be made absolute to the `baseUri`. The `baseUri` and `namespace` are not used in the search for a match in a catalog. However, a relative `systemId` in an xml source may have been made absolute by the parser with the `baseURI`, thus making it unable to find a `system` entry. In such a case, a `systemSuffix` entry is recommended over a `system` entry. Parameters publicId:String the public identifier of the external entity being referenced, or null if none was supplied systemId:String the system identifier of the external entity being referenced. A system identifier is required on all external entities. XML requires a system identifier on all external entities, so this value is always specified. baseUri:String the absolute base URI, not used by the CatalogResolver namespace:String the namespace of the entity to resolve, not used by the CatalogResolver. Returns:InputStream an `java.io.InputStream` object if a mapping is found; null if no mapping is found and the `javax.xml.catalog.resolve` property is set to `continue` or `ignore`. Note that for XMLResolver, it is not possible to ignore a reference, `ignore` is therefore treated the same as `continue`. Annotations @Override Exceptions CatalogException: if no mapping is found and `javax.xml.catalog.resolve` is specified as `strict`

public InputStream resolveEntity(String publicId, String systemId, String baseUri, String namespace)

Redeclares javax.xml.stream.XMLResolver.resolveEntity.

Implements javax.xml.stream.XMLResolver. For the purpose of resolving publicId and systemId, this method is equivalent to resolveEntity(java.lang.String, java.lang.String).

The systemId will be used literally, with no attempt to be made absolute to the baseUri. The baseUri and namespace are not used in the search for a match in a catalog. However, a relative systemId in an xml source may have been made absolute by the parser with the baseURI, thus making it unable to find a system entry. In such a case, a systemSuffix entry is recommended over a system entry.

Parameters

publicId:String: the public identifier of the external entity being referenced, or null if none was supplied
systemId:String: the system identifier of the external entity being referenced. A system identifier is required on all external entities. XML requires a system identifier on all external entities, so this value is always specified.
baseUri:String: the absolute base URI, not used by the CatalogResolver
namespace:String: the namespace of the entity to resolve, not used by the CatalogResolver.

Returns:InputStream

an java.io.InputStream object if a mapping is found; null if no mapping is found and the javax.xml.catalog.resolve property is set to continue or ignore. Note that for XMLResolver, it is not possible to ignore a reference, ignore is therefore treated the same as continue.

Annotations

@Override

Exceptions

CatalogException:: if no mapping is found and javax.xml.catalog.resolve is specified as strict

resolveResource back to summary

resolveResource	back to summary
public LSInput resolveResource(String type, String namespaceUri, String publicId, String systemId, String baseUri) Redeclares org.w3c.dom.ls.LSResourceResolver.resolveResource. Implements `org.w3c.dom.ls.LSResourceResolver`. For the purpose of resolving `publicId` and `systemId`, this method is equivalent to `resolveEntity(java.lang.String, java.lang.String)`. The `systemId` will be used literally, with no attempt to be made absolute to the `baseUri`. The `baseUri`, `namespaceUri` and `type` are not used in the search for a match in a catalog. However, a relative `systemId` in a source may have been made absolute by the parser with the `baseURI`, thus making it unable to find a `system` entry. In such a case, a `systemSuffix` entry is recommended over a `system` entry. Parameters type:String the type of the resource being resolved, not used by the CatalogResolver namespaceUri:String the namespace of the resource being resolved, not used by the CatalogResolver publicId:String the public identifier of the external entity being referenced, or `null` if no public identifier was supplied or if the resource is not an entity. systemId:String the system identifier, a URI reference of the external resource being referenced baseUri:String the absolute base URI, not used by the CatalogResolver Returns:LSInput a `org.w3c.dom.ls.LSInput` object if a mapping is found; null if no mapping is found and the `javax.xml.catalog.resolve` property is set to `continue` or `ignore`. Note that for `org.w3c.dom.ls.LSResourceResolver`, it is not possible to ignore a reference, `ignore` is therefore treated the same as `continue`. Annotations @Override Exceptions CatalogException: if no mapping is found and `javax.xml.catalog.resolve` is specified as `strict`

public LSInput resolveResource(String type, String namespaceUri, String publicId, String systemId, String baseUri)

Redeclares org.w3c.dom.ls.LSResourceResolver.resolveResource.

Implements org.w3c.dom.ls.LSResourceResolver. For the purpose of resolving publicId and systemId, this method is equivalent to resolveEntity(java.lang.String, java.lang.String).

The systemId will be used literally, with no attempt to be made absolute to the baseUri. The baseUri, namespaceUri and type are not used in the search for a match in a catalog. However, a relative systemId in a source may have been made absolute by the parser with the baseURI, thus making it unable to find a system entry. In such a case, a systemSuffix entry is recommended over a system entry.

Parameters

type:String: the type of the resource being resolved, not used by the CatalogResolver
namespaceUri:String: the namespace of the resource being resolved, not used by the CatalogResolver
publicId:String: the public identifier of the external entity being referenced, or null if no public identifier was supplied or if the resource is not an entity.
systemId:String: the system identifier, a URI reference of the external resource being referenced
baseUri:String: the absolute base URI, not used by the CatalogResolver

Returns:LSInput

a org.w3c.dom.ls.LSInput object if a mapping is found; null if no mapping is found and the javax.xml.catalog.resolve property is set to continue or ignore. Note that for org.w3c.dom.ls.LSResourceResolver, it is not possible to ignore a reference, ignore is therefore treated the same as continue.

Annotations

@Override

Exceptions

CatalogException:: if no mapping is found and javax.xml.catalog.resolve is specified as strict

javax.xml.catalog back to summary

public sealed Enum CatalogResolver.NotFoundAction

Class Inheritance

extends Enum<CatalogResolver.NotFoundAction>

java.lang.Object
java.lang.Enum
javax.xml.catalog.CatalogResolver.NotFoundAction

Defines the actions that a CatalogResolver may take when it is unable to resolve an external reference. The actions are mapped to the string values of the RESOLVE property.

Since: 22

Field Summary

Modifier and Type	Field and Description
public static final CatalogResolver.NotFoundAction	CONTINUE Indicates that the processing should continue as defined by the `RESOLVE` property.
public static final CatalogResolver.NotFoundAction	IGNORE Indicates that the reference is skipped as defined by the `RESOLVE` property.
public static final CatalogResolver.NotFoundAction	STRICT Indicates that the resolver should throw a CatalogException as defined by the `RESOLVE` property.

Constructor Summary

Access	Constructor and Description
private	NotFoundAction()

Method Summary

Modifier and Type	Method and Description
public static CatalogResolver.NotFoundAction	Returns: the action type getType(String the value of the RESOLVE property resolve) Returns the action type mapped to the specified `resolve` property.
public static CatalogResolver.NotFoundAction	valueOf(String name)
public static CatalogResolver.NotFoundAction[]	values()

Inherited from java.lang.Enum:: clone compareTo describeConstable equals finalize getDeclaringClass hashCode name ordinal toString valueOf

Field Detail

CONTINUE	back to summary
public static final CatalogResolver.NotFoundAction CONTINUE Indicates that the processing should continue as defined by the `RESOLVE` property.

IGNORE	back to summary
public static final CatalogResolver.NotFoundAction IGNORE Indicates that the reference is skipped as defined by the `RESOLVE` property.

STRICT	back to summary
public static final CatalogResolver.NotFoundAction STRICT Indicates that the resolver should throw a CatalogException as defined by the `RESOLVE` property.

Constructor Detail

NotFoundAction	back to summary
private NotFoundAction()

Method Detail

getType back to summary

getType	back to summary
public static CatalogResolver.NotFoundAction getType(String resolve) Returns the action type mapped to the specified `resolve` property. Parameters resolve:String the value of the RESOLVE property Returns:CatalogResolver.NotFoundAction the action type

public static CatalogResolver.NotFoundAction getType(String resolve)

Returns the action type mapped to the specified resolve property.

Parameters

resolve:String: the value of the RESOLVE property

Returns:CatalogResolver.NotFoundAction

the action type

valueOf	back to summary
public static CatalogResolver.NotFoundAction valueOf(String name)

values	back to summary
public static CatalogResolver.NotFoundAction[] values()

public Interface CatalogResolver

Search Order

Error Handling

Nested and Inner Type Summary

Method Summary

Method Detail

public sealed Enum CatalogResolver.NotFoundAction

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail