Implements org.xml.sax.ext.EntityResolver2.getExternalSubset.

Doc from org.xml.sax.ext.EntityResolver2.getExternalSubset.

Allows applications to provide an external subset for documents that don't explicitly define one. Documents with DOCTYPE declarations that omit an external subset can thus augment the declarations available for validation, entity processing, and attribute processing (normalization, defaulting, and reporting types including ID). This augmentation is reported through the startDTD() method as if the document text had originally included the external subset; this callback is made before any internal subset data or errors are reported.

This method can also be used with documents that have no DOCTYPE declaration. When the root element is encountered, but no DOCTYPE declaration has been seen, this method is invoked. If it returns a value for the external subset, that root element is declared to be the root element, giving the effect of splicing a DOCTYPE declaration at the end the prolog of a document that could not otherwise be valid. The sequence of parser callbacks in that case logically resembles this:

... comments and PIs from the prolog (as usual)
startDTD ("rootName", source.getPublicId (), source.getSystemId ());
startEntity ("[dtd]");
... declarations, comments, and PIs from the external subset
endEntity ("[dtd]");
endDTD ();
... then the rest of the document (as usual)
startElement (..., "rootName", ...);

Note that the InputSource gets no further resolution. Implementations of this method may wish to invoke resolveEntity() to gain benefits such as use of local caches of DTD entities. Also, this method will never be used by a (non-validating) processor that is not including external parameter entities.

Uses for this method include facilitating data validation when interoperating with XML processors that would always require undesirable network accesses for external entities, or which for other reasons adopt a "no DTDs" policy. Non-validation motives include forcing documents to include DTDs so that attributes are handled consistently. For example, an XPath processor needs to know which attributes have type "ID" before it can process a widely used type of reference.

Parameters

name:String

Identifies the document root element. This name comes from a DOCTYPE declaration (where available) or from the actual root element.

baseURI:String

The document's base URI, serving as an additional hint for selecting the external subset. This is always an absolute URI, unless it is null because the XMLReader was given an InputSource without one.

Returns:InputSource

An InputSource object describing the new external subset to be used by the parser, or null to indicate that no external subset is provided.

Annotations

@Override

Exceptions

SAXException:

Any SAX exception, possibly wrapping another exception.

IOException:

Probably indicating a failure to create a new InputStream or Reader, or an illegal URL.

Implements org.xml.sax.ext.EntityResolver2.resolveEntity.

Doc from org.xml.sax.ext.EntityResolver2.resolveEntity.

Allows applications to map references to external entities into input sources, or tell the parser it should use conventional URI resolution. This method is only called for external entities which have been properly declared. This method provides more flexibility than the EntityResolver interface, supporting implementations of more complex catalogue schemes such as the one defined by the OASIS XML Catalogs specification.

Parsers configured to use this resolver method will call it to determine the input source to use for any external entity being included because of a reference in the XML text. That excludes the document entity, and any external entity returned by getExternalSubset(). When a (non-validating) processor is configured not to include a class of entities (parameter or general) through use of feature flags, this method is not invoked for such entities.

Note that the entity naming scheme used here is the same one used in the LexicalHandler, or in the ContentHandler.skippedEntity() method.

Parameters

name:String

Identifies the external entity being resolved. Either "[dtd]" for the external subset, or a name starting with "%" to indicate a parameter entity, or else the name of a general entity. This is never null when invoked by a SAX2 parser.

publicId:String

The public identifier of the external entity being referenced (normalized as required by the XML specification), or null if none was supplied.

baseURI:String

The URI with respect to which relative systemIDs are interpreted. This is always an absolute URI, unless it is null (likely because the XMLReader was given an InputSource without one). This URI is defined by the XML specification to be the one associated with the "<" starting the relevant declaration.

systemId:String

The system identifier of the external entity being referenced; either a relative or absolute URI. This is never null when invoked by a SAX2 parser; only declared entities, and any external subset, are resolved by such parsers.

Returns:InputSource

An InputSource object describing the new input source to be used by the parser. Returning null directs the parser to resolve the system ID against the base URI and open a connection to resulting URI.

Annotations

@Override

@SuppressWarnings:squid:S2095

Exceptions

SAXException:

Any SAX exception, possibly wrapping another exception.

IOException:

Probably indicating a failure to create a new InputStream or Reader, or an illegal URL.

Implements org.xml.sax.EntityResolver.resolveEntity.

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

Allow the application to resolve external entities.

The parser will call this method before opening any external entity except the top-level document entity. Such entities include the external DTD subset and external parameter entities referenced within the DTD (in either case, only if the parser reads external parameter entities), and external general entities referenced within the document element (if the parser reads external general entities). The application may request that the parser locate the entity itself, that it use an alternative URI, or that it use data provided by the application (as a character or byte input stream).

Application writers can use this method to redirect external system identifiers to secure and/or local URIs, to look up public identifiers in a catalogue, or to read an entity from a database or other input source (including, for example, a dialog box). Neither XML nor SAX specifies a preferred policy for using public or system IDs to resolve resources. However, SAX specifies how to interpret any InputSource returned by this method, and that if none is returned, then the system ID will be dereferenced as a URL.

If the system identifier is a URL, the SAX parser must resolve it fully before reporting it to the application.

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.

Returns:InputSource

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

Annotations

@Override

Exceptions

SAXException:

Any SAX exception, possibly wrapping another exception.

IOException:

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

When set to true, a warning will be printed to the console if the XSD version used does not match the version of Liquibase. If "latest" is used as the XSD version, no warning is printed.