org.postgresql.jdbc

Class PgSQLXML

java.lang.Object

org.postgresql.jdbc.PgSQLXML

All Implemented Interfaces:

SQLXML

public class PgSQLXML
extends Object
implements SQLXML

Constructor Summary

Constructors

Constructor and Description
PgSQLXML(BaseConnection conn)
PgSQLXML(BaseConnection conn, String data)

Method Summary

Methods

Modifier and Type	Method and Description
void	free() This method closes this object and releases the resources that it held.
InputStream	getBinaryStream() Retrieves the XML value designated by this SQLXML instance as a stream.
Reader	getCharacterStream() Retrieves the XML value designated by this SQLXML instance as a java.io.Reader object.
<T extends Source> T	getSource(Class<T> sourceClass) Returns a Source for reading the XML value designated by this SQLXML instance.
String	getString() Returns a string representation of the XML value designated by this SQLXML instance.
OutputStream	setBinaryStream() Retrieves a stream that can be used to write the XML value that this SQLXML instance represents.
Writer	setCharacterStream() Retrieves a stream to be used to write the XML value that this SQLXML instance represents.
<T extends Result> T	setResult(Class<T> resultClass) Returns a Result for setting the XML value designated by this SQLXML instance.
void	setString(String value) 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

PgSQLXML

public PgSQLXML(BaseConnection conn)

PgSQLXML

public PgSQLXML(BaseConnection conn,
        String data)

Method Detail

free

public void free()

Description copied from interface: java.sql.SQLXML

This method closes this object and releases the resources that it held. The SQL XML object becomes invalid and neither readable or writeable when this method is called. After free has been called, any attempt to invoke a method other than free will result in a SQLException being thrown. If free is called multiple times, the subsequent calls to free are treated as a no-op.

Specified by:

free in interface SQLXML

getBinaryStream

public InputStream getBinaryStream()
                            throws SQLException

Description copied from interface: java.sql.SQLXML

Retrieves the XML value designated by this SQLXML instance as a stream. The bytes of the input stream are interpreted according to appendix F of the XML 1.0 specification. The behavior of this method is the same as ResultSet.getBinaryStream() 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:

getBinaryStream in interface SQLXML

Returns:

a stream containing the XML data.

Throws:

SQLException - if there is an error processing the XML value. An exception is thrown if the state is not readable.

SQLFeatureNotSupportedException - if the JDBC driver does not support this method

getCharacterStream

public Reader getCharacterStream()
                          throws SQLException

Description copied from interface: java.sql.SQLXML

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 SQLXML

Returns:

a stream containing the XML data.

Throws:

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.

SQLFeatureNotSupportedException - if the JDBC driver does not support this method

getSource

public <T extends Source> T getSource(Class<T> sourceClass)
                           throws SQLException

Description copied from interface: java.sql.SQLXML

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 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:

   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:

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.

SQLFeatureNotSupportedException - if the JDBC driver does not support this method

getString

public String getString()
                 throws SQLException

Description copied from interface: java.sql.SQLXML

Returns a string representation of the XML value designated by this SQLXML instance. 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.getString() 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:

getString in interface SQLXML

Returns:

a string representation of the XML value designated by this SQLXML instance.

Throws:

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.

SQLFeatureNotSupportedException - if the JDBC driver does not support this method

setBinaryStream

public OutputStream setBinaryStream()
                             throws SQLException

Description copied from interface: java.sql.SQLXML

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 SQLXML

Returns:

a stream to which data can be written.

Throws:

SQLException - if there is an error processing the XML value. An exception is thrown if the state is not writable.

SQLFeatureNotSupportedException - if the JDBC driver does not support this method

setCharacterStream

public Writer setCharacterStream()
                          throws SQLException

Description copied from interface: java.sql.SQLXML

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 SQLXML

Returns:

a stream to which data can be written.

Throws:

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.

SQLFeatureNotSupportedException - if the JDBC driver does not support this method

setResult

public <T extends Result> T setResult(Class<T> resultClass)
                           throws SQLException

Description copied from interface: java.sql.SQLXML

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 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:

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.

SQLFeatureNotSupportedException - if the JDBC driver does not support this method

setString

public void setString(String value)
               throws SQLException

Description copied from interface: java.sql.SQLXML

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 SQLXML

Parameters:

value - the XML value

Throws:

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.

SQLFeatureNotSupportedException - if the JDBC driver does not support this method