JDBC4MysqlSQLXML
Date: 2016-03-08

com.mysql.jdbc

## Class JDBC4MysqlSQLXML

- java.lang.Object
- - com.mysql.jdbc.JDBC4MysqlSQLXML

- All Implemented Interfaces:
    java.sql.SQLXML

      public class JDBC4MysqlSQLXML
      extends java.lang.Object
      implements java.sql.SQLXML

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `(package private) class` | `JDBC4MysqlSQLXML.SimpleSaxToReader`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `JDBC4MysqlSQLXML(ExceptionInterceptor exceptionInterceptor)`
    `protected` | `JDBC4MysqlSQLXML(ResultSetInternalMethods owner, int index, ExceptionInterceptor exceptionInterceptor)`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected java.lang.String` | `domSourceToString()`
    `void` | `free()`
    `java.io.InputStream` | `getBinaryStream()`
    `java.io.Reader` | `getCharacterStream()` Retrieves the XML value designated by this SQLXML instance as a java.io.Reader object.
    `javax.xml.transform.Source` | `getSource(java.lang.Class clazz)` Returns a Source for reading the XML value designated by this SQLXML instance.
    `java.lang.String` | `getString()`
    `boolean` | `isEmpty()`
    `protected java.lang.String` | `readerToString(java.io.Reader reader)`
    `protected java.io.Reader` | `serializeAsCharacterStream()`
    `protected java.lang.String` | `serializeAsString()`
    `java.io.OutputStream` | `setBinaryStream()` Retrieves a stream that can be used to write the XML value that this SQLXML instance represents.
    `java.io.Writer` | `setCharacterStream()` Retrieves a stream to be used to write the XML value that this SQLXML instance represents.
    `javax.xml.transform.Result` | `setResult(java.lang.Class clazz)` Returns a Result for setting the XML value designated by this SQLXML instance.
    `void` | `setString(java.lang.String str)` Sets the XML value designated by this SQLXML instance to the given String representation.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### JDBC4MysqlSQLXML

          protected JDBC4MysqlSQLXML(ResultSetInternalMethods owner,
                          int index,
                          ExceptionInterceptor exceptionInterceptor)

    - #### JDBC4MysqlSQLXML

          protected JDBC4MysqlSQLXML(ExceptionInterceptor exceptionInterceptor)

  - ### Method Detail

    - #### free

          public void free()
                    throws java.sql.SQLException

      Specified by:
        `free` in interface `java.sql.SQLXML`
      Throws:
        `java.sql.SQLException`

    - #### getString

          public java.lang.String getString()
                                     throws java.sql.SQLException

      Specified by:
        `getString` in interface `java.sql.SQLXML`
      Throws:
        `java.sql.SQLException`

    - #### setString

          public void setString(java.lang.String str)
                         throws java.sql.SQLException

      Sets the XML value designated by this SQLXML instance to the given String representation. The format of this String is defined by org.xml.sax.InputSource, where the characters in the stream represent the unicode code points for XML according to section 2 and appendix B of the XML 1.0 specification. Although an encoding declaration other than unicode may be present, the encoding of the String is unicode. The behavior of this method is the same as ResultSet.updateString() when the designated column of the ResultSet has a type java.sql.Types of SQLXML.

      The SQL XML object becomes not writeable when this method is called and may also become not readable depending on implementation.

      Specified by:
        `setString` in interface `java.sql.SQLXML`
      Parameters:
        `value` - the XML value
      Throws:
        `java.sql.SQLException` - if there is an error processing the XML value. The getCause() method of the exception may provide a more detailed exception, for example, if the stream does not contain valid characters. An exception is thrown if the state is not writable.
        `java.sql.SQLFeatureNotSupportedException` - if the JDBC driver does not support this method
      Since:
        1.6

    - #### isEmpty

          public boolean isEmpty()
                          throws java.sql.SQLException

      Throws:
        `java.sql.SQLException`

    - #### getBinaryStream

          public java.io.InputStream getBinaryStream()
                                              throws java.sql.SQLException

      Specified by:
        `getBinaryStream` in interface `java.sql.SQLXML`
      Throws:
        `java.sql.SQLException`

    - #### getCharacterStream

          public java.io.Reader getCharacterStream()
                                            throws java.sql.SQLException

      Retrieves the XML value designated by this SQLXML instance as a java.io.Reader object. The format of this stream is defined by org.xml.sax.InputSource, where the characters in the stream represent the unicode code points for XML according to section 2 and appendix B of the XML 1.0 specification. Although an encoding declaration other than unicode may be present, the encoding of the stream is unicode. The behavior of this method is the same as ResultSet.getCharacterStream() when the designated column of the ResultSet has a type java.sql.Types of SQLXML.

      The SQL XML object becomes not readable when this method is called and may also become not writable depending on implementation.

      Specified by:
        `getCharacterStream` in interface `java.sql.SQLXML`
      Returns:
        a stream containing the XML data.
      Throws:
        `java.sql.SQLException` - if there is an error processing the XML value. The getCause() method of the exception may provide a more detailed exception, for example, if the stream does not contain valid characters. An exception is thrown if the state is not readable.
        `java.sql.SQLFeatureNotSupportedException` - if the JDBC driver does not support this method
      Since:
        1.6

    - #### getSource

          public javax.xml.transform.Source getSource(java.lang.Class clazz)
                                               throws java.sql.SQLException

      Returns a Source for reading the XML value designated by this SQLXML instance. Sources are used as inputs to XML parsers and XSLT transformers.

      Sources for XML parsers will have namespace processing on by default. The systemID of the Source is implementation dependent.

      The SQL XML object becomes not readable when this method is called and may also become not writable depending on implementation.

      Note that SAX is a callback architecture, so a returned SAXSource should then be set with a content handler that will receive the SAX events from parsing. The content handler will receive callbacks based on the contents of the XML.

           SAXSource saxSource = sqlxml.getSource(SAXSource.class);
           XMLReader xmlReader = saxSource.getXMLReader();
           xmlReader.setContentHandler(myHandler);
           xmlReader.parse(saxSource.getInputSource());

      Specified by:
        `getSource` in interface `java.sql.SQLXML`
      Parameters:
        `sourceClass` - The class of the source, or null. If the class is null, a vendor specifc Source implementation will be returned. The following classes are supported at a minimum: (MySQL returns a SAXSource if sourceClass == null)

                javax.xml.transform.dom.DOMSource - returns a DOMSource
                javax.xml.transform.sax.SAXSource - returns a SAXSource
                javax.xml.transform.stax.StAXSource - returns a StAXSource
                javax.xml.transform.stream.StreamSource - returns a StreamSource

      Returns:
        a Source for reading the XML value.
      Throws:
        `java.sql.SQLException` - if there is an error processing the XML value or if this feature is not supported. The getCause() method of the exception may provide a more detailed exception, for example, if an XML parser exception occurs. An exception is thrown if the state is not readable.
        `java.sql.SQLFeatureNotSupportedException` - if the JDBC driver does not support this method
      Since:
        1.6

    - #### setBinaryStream

          public java.io.OutputStream setBinaryStream()
                                               throws java.sql.SQLException

      Retrieves a stream that can be used to write the XML value that this SQLXML instance represents. The stream begins at position 0. The bytes of the stream are interpreted according to appendix F of the XML 1.0 specification The behavior of this method is the same as ResultSet.updateBinaryStream() when the designated column of the ResultSet has a type java.sql.Types of SQLXML.

      The SQL XML object becomes not writeable when this method is called and may also become not readable depending on implementation.

      Specified by:
        `setBinaryStream` in interface `java.sql.SQLXML`
      Returns:
        a stream to which data can be written.
      Throws:
        `java.sql.SQLException` - if there is an error processing the XML value. An exception is thrown if the state is not writable.
        `java.sql.SQLFeatureNotSupportedException` - if the JDBC driver does not support this method
      Since:
        1.6

    - #### setCharacterStream

          public java.io.Writer setCharacterStream()
                                            throws java.sql.SQLException

      Retrieves a stream to be used to write the XML value that this SQLXML instance represents. The format of this stream is defined by org.xml.sax.InputSource, where the characters in the stream represent the unicode code points for XML according to section 2 and appendix B of the XML 1.0 specification. Although an encoding declaration other than unicode may be present, the encoding of the stream is unicode. The behavior of this method is the same as ResultSet.updateCharacterStream() when the designated column of the ResultSet has a type java.sql.Types of SQLXML.

      The SQL XML object becomes not writeable when this method is called and may also become not readable depending on implementation.

      Specified by:
        `setCharacterStream` in interface `java.sql.SQLXML`
      Returns:
        a stream to which data can be written.
      Throws:
        `java.sql.SQLException` - if there is an error processing the XML value. The getCause() method of the exception may provide a more detailed exception, for example, if the stream does not contain valid characters. An exception is thrown if the state is not writable.
        `java.sql.SQLFeatureNotSupportedException` - if the JDBC driver does not support this method
      Since:
        1.6

    - #### setResult

          public javax.xml.transform.Result setResult(java.lang.Class clazz)
                                               throws java.sql.SQLException

      Returns a Result for setting the XML value designated by this SQLXML instance.

      The systemID of the Result is implementation dependent.

      The SQL XML object becomes not writeable when this method is called and may also become not readable depending on implementation.

      Note that SAX is a callback architecture and the returned SAXResult has a content handler assigned that will receive the SAX events based on the contents of the XML. Call the content handler with the contents of the XML document to assign the values.

           SAXResult saxResult = sqlxml.setResult(SAXResult.class);
           ContentHandler contentHandler = saxResult.getXMLReader().getContentHandler();
           contentHandler.startDocument();
           // set the XML elements and attributes into the result
           contentHandler.endDocument();

      Specified by:
        `setResult` in interface `java.sql.SQLXML`
      Parameters:
        `resultClass` - The class of the result, or null. If resultClass is null, a vendor specific Result implementation will be returned. The following classes are supported at a minimum:

                javax.xml.transform.dom.DOMResult - returns a DOMResult
                javax.xml.transform.sax.SAXResult - returns a SAXResult
                javax.xml.transform.stax.StAXResult - returns a StAXResult
                javax.xml.transform.stream.StreamResult - returns a StreamResult

      Returns:
        Returns a Result for setting the XML value.
      Throws:
        `java.sql.SQLException` - if there is an error processing the XML value or if this feature is not supported. The getCause() method of the exception may provide a more detailed exception, for example, if an XML parser exception occurs. An exception is thrown if the state is not writable.
        `java.sql.SQLFeatureNotSupportedException` - if the JDBC driver does not support this method
      Since:
        1.6

    - #### readerToString

          protected java.lang.String readerToString(java.io.Reader reader)
                                             throws java.sql.SQLException

      Throws:
        `java.sql.SQLException`

    - #### serializeAsCharacterStream

          protected java.io.Reader serializeAsCharacterStream()
                                                       throws java.sql.SQLException

      Throws:
        `java.sql.SQLException`

    - #### domSourceToString

          protected java.lang.String domSourceToString()
                                                throws java.sql.SQLException

      Throws:
        `java.sql.SQLException`

    - #### serializeAsString

          protected java.lang.String serializeAsString()
                                                throws java.sql.SQLException

      Throws:
        `java.sql.SQLException`