Module org.postgresql.pljava

Package org.postgresql.pljava

Interface Adjusting.XML.SourceResult

All Superinterfaces:

Adjusting.XML.Parsing<Adjusting.XML.Result<Adjusting.XML.SourceResult>>, Adjusting.XML.Result<Adjusting.XML.SourceResult>, Result

Enclosing class:

Adjusting.XML

public static interface Adjusting.XML.SourceResult
extends Adjusting.XML.Result<Adjusting.XML.SourceResult>

Specialized Result type for setting a new PL/Java SQLXML instance's content from an arbitrary Source object of any of the types JDBC requires the SQLXML type to support.

The set method must be called before any of the inherited adjustment methods, and the getSQLXML method only after any adjustments.

This is used transparently when another JDBC driver's SQLXML instance is returned from a PL/Java function, or passed to a ResultSet or PreparedStatement, to produce the PL/Java instance that is ultimately needed. In that case, the source SQLXML instance's getSource method is passed a null sourceClass argument, allowing the source instance to return whichever flavor of Source it efficiently implements, and that will be passed to this interface's set method.

Through explicit use of this interface, code can adjust the parser restrictions that may be applied in the process, in case the defaults are too restrictive.

Field Summary

Fields inherited from interface javax.xml.transform.Result

PI_DISABLE_OUTPUT_ESCAPING, PI_ENABLE_OUTPUT_ESCAPING

Method Summary

Modifier and Type	Method	Description
SQLXML	getSQLXML()	Returns the result SQLXML instance ready for handing off to PostgreSQL.
Adjusting.XML.SourceResult	set(String source)	Provides the content to be copied in the form of a String.
Adjusting.XML.SourceResult	set(DOMSource source)	Specialization of set for an argument of type DOMSource.
Adjusting.XML.SourceResult	set(SAXSource source)	Specialization of set for an argument of type SAXSource.
Adjusting.XML.SourceResult	set(Source source)	Supplies the Source instance that is the source of the content.
Adjusting.XML.SourceResult	set(StAXSource source)	Specialization of set for an argument of type StAXSource.
Adjusting.XML.SourceResult	set(StreamSource source)	Specialization of set for an argument of type StreamSource.

Methods inherited from interface org.postgresql.pljava.Adjusting.XML.Parsing

accessExternalDTD, accessExternalSchema, allowDTD, defaults, elementAttributeLimit, entityExpansionLimit, entityReplacementLimit, entityResolver, expandEntityReferences, externalGeneralEntities, externalParameterEntities, lax, loadExternalDTD, maxElementDepth, maxGeneralEntitySizeLimit, maxParameterEntitySizeLimit, maxXMLNameLimit, schema, setFirstSupportedFeature, setFirstSupportedProperty, totalEntitySizeLimit, xIncludeAware

Methods inherited from interface org.postgresql.pljava.Adjusting.XML.Result

get

Methods inherited from interface javax.xml.transform.Result

getSystemId, setSystemId

Method Details

set

Adjusting.XML.SourceResult set(Source source)
                        throws SQLException

Supplies the Source instance that is the source of the content.

This method must be called before any of the inherited adjustment methods. The argument may be a StreamSource, SAXSource, StAXSource, or DOMSource. If it is an instance of Adjusting.XML.Source, its get method will be called, and must return one of those four supported types.

Throws:

SQLException

set

Adjusting.XML.SourceResult set(StreamSource source)
                        throws SQLException

Specialization of set for an argument of type StreamSource.

It may encapsulate either an InputStream or a Reader. In either case (even for a Reader), the start of the stream will be checked for an encoding declaration and compared to PostgreSQL's server encoding. If the encoding matches, a direct copy is done. If the encoding does not match but the source character set is contained in the server character set, a transcoding via Unicode is done. In either case, an XML parser is used to verify that the copied content is XML, and the parser's restrictions can be adjusted by the methods on this interface.

If the source character set is neither the same as nor contained in the server's, the content will be parsed to SAX events and reserialized into the server encoding, and this parser's restrictions can be adjusted by the methods on this interface.

Throws:

SQLException

set

Adjusting.XML.SourceResult set(SAXSource source)
                        throws SQLException

Specialization of set for an argument of type SAXSource.

Because the content will be received in an already-parsed form, the parser-adjusting methods will have no effect.

Throws:

SQLException

set

Adjusting.XML.SourceResult set(StAXSource source)
                        throws SQLException

Specialization of set for an argument of type StAXSource.

Because the content will be received in an already-parsed form, the parser-adjusting methods will have no effect.

Throws:

SQLException

set

Adjusting.XML.SourceResult set(String source)
                        throws SQLException

Provides the content to be copied in the form of a String.

An exception from the pattern of Source-typed arguments, this method simplifies retrofitting adjustments into code that was using SQLXML's setString. Has the same effect as set with a StreamSource wrapping a StringReader over the String.

Throws:

SQLException

set

Adjusting.XML.SourceResult set(DOMSource source)
                        throws SQLException

Specialization of set for an argument of type DOMSource.

Because the content will be received in an already-parsed form, the parser-adjusting methods will have no effect.

Throws:

SQLException

getSQLXML

SQLXML getSQLXML()
          throws SQLException

Returns the result SQLXML instance ready for handing off to PostgreSQL.

The handling/logging of exceptions normally handled in a get method happens here for a SourceResult.

Any necessary calls of the inherited adjustment methods must be made before this method is called.

Throws:

SQLException