MSV Core 2022.7 · com.sun.msv.scanner.dtd.Resolver

This entity resolver class provides a number of utilities which can help managment of external parsed entities in XML. These are commonly used to hold markup declarations that are to be used as part of a Document Type Declaration (DTD), or to hold text marked up with XML.

Features include:

Static factory methods are provided for constructing SAX InputSource objects from Files, URLs, or MIME objects. This eliminates a class of error-prone coding in applications.
Character encodings for XML documents are correctly supported:
- The encodings defined in the RFCs for MIME content types (2046 for general MIME, and 2376 for XML in particular), are supported, handling charset=... attributes and accepting content types which are known to be safe for use with XML;
- The character encoding autodetection algorithm identified in the XML specification is used, and leverages all of the JDK 1.1 (and later) character encoding support.
- The use of MIME typing may optionally be disabled, forcing the use of autodetection, to support web servers which don't correctly report MIME types for XML. For example, they may report text that is encoded in EUC-JP as being US-ASCII text, leading to fatal errors during parsing.
- The InputSource objects returned by this class always have a java.io.Reader available as the "character stream" property.
Catalog entries can map public identifiers to Java resources or to local URLs. These are used to reduce network dependencies and loads, and will often be used for external DTD components. For example, packages shipping DTD files as resources in JAR files can eliminate network traffic when accessing them, and sites may provide local caches of common DTDs. Note that no particular catalog syntax is supported by this class, only the notion of a set of entries.

Subclasses can perform tasks such as supporting new URI schemes for URIs which are not URLs, such as URNs (see RFC 2396) or for accessing MIME entities which are part of a multipart/related group (see RFC 2387). They may also be used to support particular catalog syntaxes, such as the SGML/Open Catalog (SOCAT) which supports the SGML notion of "Formal Public Identifiers (FPIs).

Field Summary

Modifier and Type	Field and Description
private HashMap<String, ClassLoader>	id2loader
private HashMap<String, String>	id2resource
private HashMap<String, String>	id2uri
private boolean	ignoringMIME
private static final String[]	types

Constructor Summary

Access	Constructor and Description
public	Resolver() Constructs a resolver.

Method Summary

Modifier and Type	Method and Description
public static InputSource	createInputSource(String The MIME content type for the source for which an InputSource is desired, such as text/xml;charset=utf-8. contentType, InputStream The input byte stream for the input source. stream, boolean If true, this verifies that the content type is known to support XML documents, such as application/xml. checkType, String Unless this is "file", unspecified MIME types default to US-ASCII. Files are always autodetected since most file systems discard character encoding information. scheme) Returns an input source, using the MIME type information and URL scheme to statically determine the correct character encoding if possible and otherwise autodetecting it.
public static InputSource	createInputSource(URL the URI (system ID) for the entity uri, boolean if true, the MIME content type for the entity is checked for document type and character set encoding. checkType) Creates an input source from a given URI.
public static InputSource	createInputSource(File file) Creates an input source from a given file, autodetecting the character encoding.
public boolean	isIgnoringMIME() Returns true if this resolver is ignoring MIME types in the documents it returns, to work around bugs in how servers have reported the documents' MIME types.
private InputStream	mapResource(String publicId)
private String	name2uri(String publicId)
public void	registerCatalogEntry(String The managed public ID being mapped publicId, String The URI of the preferred copy of that entity uri) Registers the given public ID as corresponding to a particular URI, typically a local copy.
public void	registerCatalogEntry(String The managed public ID being mapped publicId, String The name of the Java resource resourceName, ClassLoader The class loader holding the resource, or null if it is a system resource. loader) Registers a given public ID as corresponding to a particular Java resource in a given class loader, typically distributed with a software package.
public InputSource	resolveEntity(String Used to find alternate copies of the entity, when this value is non-null; this is the XML "public ID". name, String Used when no alternate copy of the entity is found; this is the XML "system ID", normally a URI. uri) Implements org.xml.sax.EntityResolver.resolveEntity. SAX: Resolve the given entity into an input source.
public void	setIgnoringMIME(boolean value) Tells the resolver whether to ignore MIME types in the documents it retrieves.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

id2loader	back to summary
private HashMap<String, ClassLoader> id2loader

id2resource	back to summary
private HashMap<String, String> id2resource

id2uri	back to summary
private HashMap<String, String> id2uri

ignoringMIME	back to summary
private boolean ignoringMIME

types	back to summary
private static final String[] types

Constructor Detail

Resolver	back to summary
public Resolver() Constructs a resolver.

Method Detail

createInputSource	back to summary
public static InputSource createInputSource(String contentType, InputStream stream, boolean checkType, String scheme) throws IOException Returns an input source, using the MIME type information and URL scheme to statically determine the correct character encoding if possible and otherwise autodetecting it. MIME carefully specifies the character encoding defaults, and how attributes of the content type can change it. XML further specifies two mandatory encodings (UTF-8 and UTF-16), and includes an XML declaration which can be used to internally label most documents encoded using US-ASCII supersets (such as Shift_JIS, EUC-JP, ISO-2022-, ISO-8859-, and more). This method can be used to access XML documents which do not have URIs (such as servlet input streams, or most JavaMail message entities) and to support access methods such as HTTP POST or PUT. (URLs normally return content using the GET method.) The caller should set the system ID in order for relative URIs found in this document to be interpreted correctly. In some cases, a custom resolver will need to be used; for example, documents may be grouped in a single MIME "multipart/related" bundle, and relative URLs would refer to other documents in that bundle. Parameters contentType:String The MIME content type for the source for which an InputSource is desired, such as text/xml;charset=utf-8. stream:InputStream The input byte stream for the input source. checkType:boolean If true, this verifies that the content type is known to support XML documents, such as application/xml. scheme:String Unless this is "file", unspecified MIME types default to US-ASCII. Files are always autodetected since most file systems discard character encoding information.

createInputSource

back to summary

public static InputSource createInputSource(String contentType, InputStream stream, boolean checkType, String scheme) throws IOException

Returns an input source, using the MIME type information and URL scheme to statically determine the correct character encoding if possible and otherwise autodetecting it. MIME carefully specifies the character encoding defaults, and how attributes of the content type can change it. XML further specifies two mandatory encodings (UTF-8 and UTF-16), and includes an XML declaration which can be used to internally label most documents encoded using US-ASCII supersets (such as Shift_JIS, EUC-JP, ISO-2022-*, ISO-8859-*, and more).

This method can be used to access XML documents which do not have URIs (such as servlet input streams, or most JavaMail message entities) and to support access methods such as HTTP POST or PUT. (URLs normally return content using the GET method.)

The caller should set the system ID in order for relative URIs found in this document to be interpreted correctly. In some cases, a custom resolver will need to be used; for example, documents may be grouped in a single MIME "multipart/related" bundle, and relative URLs would refer to other documents in that bundle.

Parameters

contentType:String: The MIME content type for the source for which an InputSource is desired, such as text/xml;charset=utf-8.
stream:InputStream: The input byte stream for the input source.
checkType:boolean: If true, this verifies that the content type is known to support XML documents, such as application/xml.
scheme:String: Unless this is "file", unspecified MIME types default to US-ASCII. Files are always autodetected since most file systems discard character encoding information.

createInputSource	back to summary
public static InputSource createInputSource(URL uri, boolean checkType) throws IOException Creates an input source from a given URI. Parameters uri:URL the URI (system ID) for the entity checkType:boolean if true, the MIME content type for the entity is checked for document type and character set encoding.

createInputSource

back to summary

public static InputSource createInputSource(URL uri, boolean checkType) throws IOException

Creates an input source from a given URI.

Parameters

uri:URL: the URI (system ID) for the entity
checkType:boolean: if true, the MIME content type for the entity is checked for document type and character set encoding.

createInputSource	back to summary
public static InputSource createInputSource(File file) throws IOException Creates an input source from a given file, autodetecting the character encoding.

isIgnoringMIME	back to summary
public boolean isIgnoringMIME() Returns true if this resolver is ignoring MIME types in the documents it returns, to work around bugs in how servers have reported the documents' MIME types.

mapResource	back to summary
private InputStream mapResource(String publicId)

name2uri	back to summary
private String name2uri(String publicId)

registerCatalogEntry	back to summary
public void registerCatalogEntry(String publicId, String uri) Registers the given public ID as corresponding to a particular URI, typically a local copy. This URI will be used in preference to ones provided as system IDs in XML entity declarations. This mechanism would most typically be used for Document Type Definitions (DTDs), where the public IDs are formally managed and versioned. Parameters publicId:String The managed public ID being mapped uri:String The URI of the preferred copy of that entity

registerCatalogEntry

back to summary

public void registerCatalogEntry(String publicId, String uri)

Registers the given public ID as corresponding to a particular URI, typically a local copy. This URI will be used in preference to ones provided as system IDs in XML entity declarations. This mechanism would most typically be used for Document Type Definitions (DTDs), where the public IDs are formally managed and versioned.

Parameters

publicId:String: The managed public ID being mapped
uri:String: The URI of the preferred copy of that entity

registerCatalogEntry	back to summary
public void registerCatalogEntry(String publicId, String resourceName, ClassLoader loader) Registers a given public ID as corresponding to a particular Java resource in a given class loader, typically distributed with a software package. This resource will be preferred over system IDs included in XML documents. This mechanism should most typically be used for Document Type Definitions (DTDs), where the public IDs are formally managed and versioned. If a mapping to a URI has been provided, that mapping takes precedence over this one. Parameters publicId:String The managed public ID being mapped resourceName:String The name of the Java resource loader:ClassLoader The class loader holding the resource, or null if it is a system resource.

registerCatalogEntry

back to summary

public void registerCatalogEntry(String publicId, String resourceName, ClassLoader loader)

Registers a given public ID as corresponding to a particular Java resource in a given class loader, typically distributed with a software package. This resource will be preferred over system IDs included in XML documents. This mechanism should most typically be used for Document Type Definitions (DTDs), where the public IDs are formally managed and versioned.

If a mapping to a URI has been provided, that mapping takes precedence over this one.

Parameters

publicId:String: The managed public ID being mapped
resourceName:String: The name of the Java resource
loader:ClassLoader: The class loader holding the resource, or null if it is a system resource.

resolveEntity	back to summary
public InputSource resolveEntity(String name, String uri) throws IOException Implements org.xml.sax.EntityResolver.resolveEntity. SAX: Resolve the given entity into an input source. If the name can't be mapped to a preferred form of the entity, the URI is used. To resolve the entity, first a local catalog mapping names to URIs is consulted. If no mapping is found there, a catalog mapping names to java resources is consulted. Finally, if neither mapping found a copy of the entity, the specified URI is used. When a URI is used, createInputSource is used to correctly deduce the character encoding used by this entity. No MIME type checking is done. Parameters name:String Used to find alternate copies of the entity, when this value is non-null; this is the XML "public ID". uri:String Used when no alternate copy of the entity is found; this is the XML "system ID", normally a URI. Returns:InputSource Doc from org.xml.sax.EntityResolver.resolveEntity. An InputSource object describing the new input source, or null to request that the parser open a regular URI connection to the system identifier. Exceptions IOException: Doc from org.xml.sax.EntityResolver.resolveEntity. A Java-specific IO exception, possibly the result of creating a new InputStream or Reader for the InputSource.

resolveEntity

back to summary

public InputSource resolveEntity(String name, String uri) throws IOException

Implements org.xml.sax.EntityResolver.resolveEntity.

SAX: Resolve the given entity into an input source. If the name can't be mapped to a preferred form of the entity, the URI is used. To resolve the entity, first a local catalog mapping names to URIs is consulted. If no mapping is found there, a catalog mapping names to java resources is consulted. Finally, if neither mapping found a copy of the entity, the specified URI is used.

When a URI is used, createInputSource is used to correctly deduce the character encoding used by this entity. No MIME type checking is done.

Parameters

name:String: Used to find alternate copies of the entity, when this value is non-null; this is the XML "public ID".
uri:String: Used when no alternate copy of the entity is found; this is the XML "system ID", normally a URI.

Returns:InputSource

Doc from org.xml.sax.EntityResolver.resolveEntity.

An InputSource object describing the new input source, or null to request that the parser open a regular URI connection to the system identifier.

Exceptions

IOException:

Doc from org.xml.sax.EntityResolver.resolveEntity.

A Java-specific IO exception, possibly the result of creating a new InputStream or Reader for the InputSource.

setIgnoringMIME	back to summary
public void setIgnoringMIME(boolean value) Tells the resolver whether to ignore MIME types in the documents it retrieves. Many web servers incorrectly assign text documents a default character encoding, even when that is incorrect. For example, all HTTP text documents default to use ISO-8859-1 (used for Western European languages), and other MIME sources default text documents to use US-ASCII (a seven bit encoding). For XML documents which include text encoding declarations (as most should do), these server bugs can be worked around by ignoring the MIME type entirely.

setIgnoringMIME

back to summary

public void setIgnoringMIME(boolean value)

Tells the resolver whether to ignore MIME types in the documents it retrieves. Many web servers incorrectly assign text documents a default character encoding, even when that is incorrect. For example, all HTTP text documents default to use ISO-8859-1 (used for Western European languages), and other MIME sources default text documents to use US-ASCII (a seven bit encoding). For XML documents which include text encoding declarations (as most should do), these server bugs can be worked around by ignoring the MIME type entirely.

public Class Resolver

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail