- Enclosing class:
public static final class Adjusting.XML extends ObjectClass that collects adjustment APIs for affecting the behavior of PL/Java's XML support.
XML parser behavior adjustments
Retrieving or verifying the XML content in a JDBC
SQLXMLobject can involve applying an XML parser. The full XML specification includes features that can require an XML parser to retrieve external resources or consume unexpected amounts of memory. The full feature support may be an asset in an environment where the XML content will always be from a known, trusted source, or a liability if less is known about the XML content being processed.
The Open Web Application Security Project (OWASP) advocates for the default use of settings that strictly limit the related features of Java XML parsers, as outlined in a "cheat sheet" the organization publishes. The strict default settings can then be selectively relaxed in applications where the features are needed and the content is sufficiently trusted.
However, the recommended defaults really are severely restrictive (for example, disabling document-type declarations by default will cause PL/Java's
SQLXMLimplementation to reject all XML values that contain DTDs). Therefore, there must be a simple and clear way for code to selectively adjust the settings, or adopting the strictest settings by default would pose an unacceptable burden to developers.
The usual way that Java XML parsers expose their settings for adjustment is through
setPropertymethods that must be passed particular URIs that identify adjustable features, and objects of appropriate types (often boolean) as the values for those properties. The supported properties and the URIs that identify them can be different from one parser implementation to another or one version to another. That is not the "simple and clear" adjustment mechanism needed here. Furthermore, the JDBC
SQLXMLAPI conceals much of the complexity of configuring any underlying XML parser behind a simple
getSourcemethod whose result can be used directly with other Java APIs expecting some flavor of
Sourceobject, and for some of those flavors, the returned object does not even expose the methods one would need to call to adjust the underlying parser, if any.
Hence this adjustment API. JDBC already provides for extensibility of the
SQLXML.getSourcemethod; it is passed the class object for a desired subtype of
Sourceand, if the implementation supports it, returns an object of that type. The subtypes that every conformant implementation must support are
nullis passed, the implementation will choose which flavor to return, often based on internal implementation details making one most natural or efficient.
Adjusting.XML.DOMSourceare used the same way, by passing the corresponding class literal to
getSourcemethod, which will return an object providing the chainable adjustment methods of
Adjusting.XML.Source, with the chain ending in a
getmethod that returns the corresponding Java
Sourceobject, configured as adjusted.
SAXSource src1 = sqx1.getSource(SAXSource.class); SAXSource src2 = sqx2.getSource(Adjusting.XML.SAXSource.class) .allowDTD(true).get();
src1would be assigned a
SAXSourceobject configured with the OWASP-recommended defaults, which will not allow the content to have a DTD, among other restrictions, while
src2would be assigned a
SAXSourceobject configured with the other default restrictions (as if the
allowDTD(true)is preceded by an implied
defaults()), but with DTD parsing enabled.
Adjusting.XML.StreamSourceis needed or provided, as any application code that requests a
StreamSourcewill have to provide and configure its own parser anyway.
getSource, passing the parent interface
Adjusting.XML.Source.classwill allow the implementation to choose which subtype of
Adjusting.XML.Sourceto return. The object returned by
getcan then be passed directly to Java APIs like
Transformerthat accept several flavors of
Source, or examined to see of what class it is.
Nested Class Summary
Nested Classes Modifier and Type Class Description
Adjusting.XML.DOMSourceAdjusting version of a
Adjusting.XML.Parsing<T extends Adjusting.XML.Parsing<T>>Interface with methods to adjust the restrictions on XML parsing that are commonly considered when XML content might be from untrusted sources.
Adjusting.XML.Result<T extends Result>Adjusting version of
javax.xml.transform.Result, offering the adjustment methods of
Adjusting.XML.Parsing, chiefly so that there is a way to apply those adjustments to any implicitly-created parser used to verify the content that will be written to the
Adjusting.XML.SAXResultAdjusting version of a
Adjusting.XML.SAXSourceAdjusting version of a
Adjusting.XML.Source<T extends Source>Adjusting version of
javax.xml.transform.Source, allowing various parser features to be configured before calling
get()to obtain the usable
Resulttype for setting a new PL/Java
SQLXMLinstance's content from an arbitrary
Sourceobject of any of the types JDBC requires the
SQLXMLtype to support.
Adjusting.XML.StAXSourceAdjusting version of a
Adjusting.XML.StreamResultAdjusting version of a