org.springframework.jdbc.support.xml

## Interface SqlXmlHandler

All Known Subinterfaces:
  SqlXmlObjectMappingHandler

All Known Implementing Classes:
  Jdbc4SqlXmlHandler

    public interface SqlXmlHandler

Abstraction for handling XML fields in specific databases. Its main purpose is to isolate database-specific handling of XML stored in the database.

JDBC 4.0 introduces the new data type `java.sql.SQLXML` but most databases and their drivers currently rely on database-specific data types and features.

Provides accessor methods for XML fields and acts as factory for `SqlXmlValue` instances.

Since:
  2.5.5
Author:
  Thomas Risberg
See Also:
  `Jdbc4SqlXmlHandler`, `SQLXML`, `ResultSet.getSQLXML(int)`, `PreparedStatement.setSQLXML(int, java.sql.SQLXML)`

### Method Summary

Methods
`InputStream` `getXmlAsBinaryStream(ResultSet rs, int columnIndex)` Retrieve the given column as binary stream from the given ResultSet.
`InputStream` `getXmlAsBinaryStream(ResultSet rs, String columnName)` Retrieve the given column as binary stream from the given ResultSet.
`Reader` `getXmlAsCharacterStream(ResultSet rs, int columnIndex)` Retrieve the given column as character stream from the given ResultSet.
`Reader` `getXmlAsCharacterStream(ResultSet rs, String columnName)` Retrieve the given column as character stream from the given ResultSet.
`Source` `getXmlAsSource(ResultSet rs, int columnIndex, Class sourceClass)` Retrieve the given column as Source implemented using the specified source class from the given ResultSet.
`Source` `getXmlAsSource(ResultSet rs, String columnName, Class sourceClass)` Retrieve the given column as Source implemented using the specified source class from the given ResultSet.
`String` `getXmlAsString(ResultSet rs, int columnIndex)` Retrieve the given column as String from the given ResultSet.
`String` `getXmlAsString(ResultSet rs, String columnName)` Retrieve the given column as String from the given ResultSet.
`SqlXmlValue` `newSqlXmlValue(Class resultClass, XmlResultProvider provider)` Create a `SqlXmlValue` instance for the given XML data, as supported by the underlying JDBC driver.
`SqlXmlValue` `newSqlXmlValue(Document doc)` Create a `SqlXmlValue` instance for the given XML data, as supported by the underlying JDBC driver.
`SqlXmlValue` `newSqlXmlValue(String value)` Create a `SqlXmlValue` instance for the given XML data, as supported by the underlying JDBC driver.
`SqlXmlValue` `newSqlXmlValue(XmlBinaryStreamProvider provider)` Create a `SqlXmlValue` instance for the given XML data, as supported by the underlying JDBC driver.
`SqlXmlValue` `newSqlXmlValue(XmlCharacterStreamProvider provider)` Create a `SqlXmlValue` instance for the given XML data, as supported by the underlying JDBC driver.

### Method Detail

#### getXmlAsString

    String getXmlAsString(ResultSet rs,
                        String columnName)
                          throws SQLException

Retrieve the given column as String from the given ResultSet.

Might simply invoke `ResultSet.getString` or work with `SQLXML` or database-specific classes depending on the database and driver.

Parameters:
  `rs` - the ResultSet to retrieve the content from
  `columnName` - the column name to use
Returns:
  the content as String, or `null` in case of SQL NULL
Throws:
  `SQLException` - if thrown by JDBC methods
See Also:
  `ResultSet.getString(int)`, `ResultSet.getSQLXML(int)`

#### getXmlAsString

    String getXmlAsString(ResultSet rs,
                        int columnIndex)
                          throws SQLException

Retrieve the given column as String from the given ResultSet.

Might simply invoke `ResultSet.getString` or work with `SQLXML` or database-specific classes depending on the database and driver.

Parameters:
  `rs` - the ResultSet to retrieve the content from
  `columnIndex` - the column index to use
Returns:
  the content as String, or `null` in case of SQL NULL
Throws:
  `SQLException` - if thrown by JDBC methods
See Also:
  `ResultSet.getString(int)`, `ResultSet.getSQLXML(int)`

#### getXmlAsBinaryStream

    InputStream getXmlAsBinaryStream(ResultSet rs,
                                   String columnName)
                                     throws SQLException

Retrieve the given column as binary stream from the given ResultSet.

Might simply invoke `ResultSet.getAsciiStream` or work with `SQLXML` or database-specific classes depending on the database and driver.

Parameters:
  `rs` - the ResultSet to retrieve the content from
  `columnName` - the column name to use
Returns:
  the content as a binary stream, or `null` in case of SQL NULL
Throws:
  `SQLException` - if thrown by JDBC methods
See Also:
  `ResultSet.getSQLXML(int)`, `SQLXML.getBinaryStream()`

#### getXmlAsBinaryStream

    InputStream getXmlAsBinaryStream(ResultSet rs,
                                   int columnIndex)
                                     throws SQLException

Retrieve the given column as binary stream from the given ResultSet.

Might simply invoke `ResultSet.getAsciiStream` or work with `SQLXML` or database-specific classes depending on the database and driver.

Parameters:
  `rs` - the ResultSet to retrieve the content from
  `columnIndex` - the column index to use
Returns:
  the content as binary stream, or `null` in case of SQL NULL
Throws:
  `SQLException` - if thrown by JDBC methods
See Also:
  `ResultSet.getSQLXML(int)`, `SQLXML.getBinaryStream()`

#### getXmlAsCharacterStream

    Reader getXmlAsCharacterStream(ResultSet rs,
                                 String columnName)
                                   throws SQLException

Retrieve the given column as character stream from the given ResultSet.

Might simply invoke `ResultSet.getCharacterStream` or work with `SQLXML` or database-specific classes depending on the database and driver.

Parameters:
  `rs` - the ResultSet to retrieve the content from
  `columnName` - the column name to use
Returns:
  the content as character stream
Throws:
  `SQLException` - if thrown by JDBC methods
See Also:
  `ResultSet.getSQLXML(int)`, `SQLXML.getCharacterStream()`

#### getXmlAsCharacterStream

    Reader getXmlAsCharacterStream(ResultSet rs,
                                 int columnIndex)
                                   throws SQLException

Retrieve the given column as character stream from the given ResultSet.

Might simply invoke `ResultSet.getCharacterStream` or work with `SQLXML` or database-specific classes depending on the database and driver.

Parameters:
  `rs` - the ResultSet to retrieve the content from
  `columnIndex` - the column index to use
Returns:
  the content as character stream
Throws:
  `SQLException` - if thrown by JDBC methods
See Also:
  `ResultSet.getSQLXML(int)`, `SQLXML.getCharacterStream()`

#### getXmlAsSource

    Source getXmlAsSource(ResultSet rs,
                        String columnName,
                        Class sourceClass)
                          throws SQLException

Retrieve the given column as Source implemented using the specified source class from the given ResultSet.

Might work with `SQLXML` or database-specific classes depending on the database and driver.

Parameters:
  `rs` - the ResultSet to retrieve the content from
  `columnName` - the column name to use
  `sourceClass` - the implementation class to be used
Returns:
  the content as character stream
Throws:
  `SQLException` - if thrown by JDBC methods
See Also:
  `ResultSet.getSQLXML(int)`, `SQLXML.getSource(java.lang.Class<T>)`

#### getXmlAsSource

    Source getXmlAsSource(ResultSet rs,
                        int columnIndex,
                        Class sourceClass)
                          throws SQLException

Retrieve the given column as Source implemented using the specified source class from the given ResultSet.

Might work with `SQLXML` or database-specific classes depending on the database and driver.

Parameters:
  `rs` - the ResultSet to retrieve the content from
  `columnIndex` - the column index to use
  `sourceClass` - the implementation class to be used
Returns:
  the content as character stream
Throws:
  `SQLException` - if thrown by JDBC methods
See Also:
  `ResultSet.getSQLXML(int)`, `SQLXML.getSource(java.lang.Class<T>)`

#### newSqlXmlValue

    SqlXmlValue newSqlXmlValue(String value)

Create a `SqlXmlValue` instance for the given XML data, as supported by the underlying JDBC driver.

Parameters:
  `value` - the XML String value providing XML data
Returns:
  the implementation specific instance
See Also:
  `SqlXmlValue`, `SQLXML.setString(String)`

#### newSqlXmlValue

    SqlXmlValue newSqlXmlValue(XmlBinaryStreamProvider provider)

Create a `SqlXmlValue` instance for the given XML data, as supported by the underlying JDBC driver.

Parameters:
  `provider` - the `XmlBinaryStreamProvider` providing XML data
Returns:
  the implementation specific instance
See Also:
  `SqlXmlValue`, `SQLXML.setBinaryStream()`

#### newSqlXmlValue

    SqlXmlValue newSqlXmlValue(XmlCharacterStreamProvider provider)

Create a `SqlXmlValue` instance for the given XML data, as supported by the underlying JDBC driver.

Parameters:
  `provider` - the `XmlCharacterStreamProvider` providing XML data
Returns:
  the implementation specific instance
See Also:
  `SqlXmlValue`, `SQLXML.setCharacterStream()`

#### newSqlXmlValue

    SqlXmlValue newSqlXmlValue(Class resultClass,
                             XmlResultProvider provider)

Create a `SqlXmlValue` instance for the given XML data, as supported by the underlying JDBC driver.

Parameters:
  `resultClass` - the Result implementation class to be used
  `provider` - the `XmlResultProvider` that will provide the XML data
Returns:
  the implementation specific instance
See Also:
  `SqlXmlValue`, `SQLXML.setResult(Class)`

#### newSqlXmlValue

    SqlXmlValue newSqlXmlValue(Document doc)

Create a `SqlXmlValue` instance for the given XML data, as supported by the underlying JDBC driver.

Parameters:
  `doc` - the XML Document to be used
Returns:
  the implementation specific instance
See Also:
  `SqlXmlValue`