com.ibm.as400.access
Class AS400JDBCSQLXML

java.lang.Object
  extended by com.ibm.as400.access.AS400JDBCSQLXML
All Implemented Interfaces:
SQLXML
Direct Known Subclasses:
AS400JDBCSQLXMLLocator

public class AS400JDBCSQLXML
extends Object
implements SQLXML

This class provides the object interface for using XML data through JDBC. The mapping in the Java programming language for the SQL XML type. XML is a built-in type that stores an XML value as a column value in a row of a database table. The SQLXML interface provides methods for accessing the XML value as a String, a Reader or Writer, or as a Stream. This class returns the data as an XML type. The actual type on the host may vary. Instances of this class are created by AS400JDBCConnection. This class should not be used if JDK 1.6 is not in use.


Field Summary
protected  boolean isXML_
           
 
Constructor Summary
protected AS400JDBCSQLXML()
          Constructs an AS400JDBCSQLXML object.
 
Method Summary
 void free()
          This method frees the object and releases the the resources that it holds.
 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()
          Retrieves a string representation of the XML value designated by this SQLXML object.
 OutputStream setBinaryStream()
          Retrieves a stream that can be used to write the XML value that this SQLXML instance represents.
 Writer setCharacterStream()
          Retrieves a Writer 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 str)
          Writes the given Java String to the XML value that this SQLXML object designates.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

isXML_

protected boolean isXML_
Constructor Detail

AS400JDBCSQLXML

protected AS400JDBCSQLXML()
Constructs an AS400JDBCSQLXML object. This is only a dummy constructor used by subclasses.

Method Detail

getCharacterStream

public Reader getCharacterStream()
                          throws 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 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.

getString

public String getString()
                 throws SQLException
Retrieves a string representation of the XML value designated by this SQLXML object.

Specified by:
getString in interface SQLXML
Returns:
a String that is the string representation of the XML value
Throws:
SQLException - if there is an error accessing the XML value

setString

public void setString(String str)
               throws SQLException
Writes the given Java String to the XML value that this SQLXML object designates.

Specified by:
setString in interface SQLXML
Parameters:
str - the string to be written to the XML value that this SQLXML designates
Throws:
SQLException - if there is an error accessing the XML value

getBinaryStream

public InputStream getBinaryStream()
                            throws SQLException
Retrieves the XML value designated by this SQLXML instance as a stream.

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.

getSource

public <T extends Source> T getSource(Class<T> sourceClass)
                           throws 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.

Specified by:
getSource in interface SQLXML
Parameters:
sourceClass - The class of the source, or null. If the class is null, a vendor specific 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.

setBinaryStream

public OutputStream setBinaryStream()
                             throws SQLException
Retrieves a stream that can be used to write the XML value that this SQLXML instance represents.

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.
If - there is an error

setCharacterStream

public Writer setCharacterStream()
                          throws SQLException
Retrieves a Writer to be used to write the XML value that this SQLXML instance represents.

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.
If - there is an error

setResult

public <T extends Result> T setResult(Class<T> resultClass)
                           throws SQLException
Returns a Result for setting the XML value designated by this SQLXML instance.

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.
If - there is an error

free

public void free()
          throws SQLException
This method frees the object and releases the the resources that it holds. The object is invalid once the free method is called. If free is called multiple times, the subsequent calls to free are treated as a no-op.

Specified by:
free in interface SQLXML
Throws:
SQLException - if an error occurs releasing the Clob's resources