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.

    • Method Detail

      • 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​(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

      • 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