001/*
002 * Copyright 2002-2015 the original author or authors.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *      https://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package org.springframework.jdbc.support.xml;
018
019import java.io.InputStream;
020import java.io.Reader;
021import java.sql.ResultSet;
022import java.sql.SQLException;
023import javax.xml.transform.Result;
024import javax.xml.transform.Source;
025
026import org.w3c.dom.Document;
027
028/**
029 * Abstraction for handling XML fields in specific databases. Its main purpose
030 * is to isolate database-specific handling of XML stored in the database.
031 *
032 * <p>JDBC 4.0 introduces the new data type {@code java.sql.SQLXML}
033 * but most databases and their drivers currently rely on database-specific
034 * data types and features.
035 *
036 * <p>Provides accessor methods for XML fields and acts as factory for
037 * {@link SqlXmlValue} instances.
038 *
039 * @author Thomas Risberg
040 * @since 2.5.5
041 * @see Jdbc4SqlXmlHandler
042 * @see java.sql.SQLXML
043 * @see java.sql.ResultSet#getSQLXML
044 * @see java.sql.PreparedStatement#setSQLXML
045 */
046public interface SqlXmlHandler {
047
048        //-------------------------------------------------------------------------
049        // Convenience methods for accessing XML content
050        //-------------------------------------------------------------------------
051
052        /**
053         * Retrieve the given column as String from the given ResultSet.
054         * <p>Might simply invoke {@code ResultSet.getString} or work with
055         * {@code SQLXML} or database-specific classes depending on the
056         * database and driver.
057         * @param rs the ResultSet to retrieve the content from
058         * @param columnName the column name to use
059         * @return the content as String, or {@code null} in case of SQL NULL
060         * @throws SQLException if thrown by JDBC methods
061         * @see java.sql.ResultSet#getString
062         * @see java.sql.ResultSet#getSQLXML
063         */
064        String getXmlAsString(ResultSet rs, String columnName) throws SQLException;
065
066        /**
067         * Retrieve the given column as String from the given ResultSet.
068         * <p>Might simply invoke {@code ResultSet.getString} or work with
069         * {@code SQLXML} or database-specific classes depending on the
070         * database and driver.
071         * @param rs the ResultSet to retrieve the content from
072         * @param columnIndex the column index to use
073         * @return the content as String, or {@code null} in case of SQL NULL
074         * @throws SQLException if thrown by JDBC methods
075         * @see java.sql.ResultSet#getString
076         * @see java.sql.ResultSet#getSQLXML
077         */
078        String getXmlAsString(ResultSet rs, int columnIndex) throws SQLException;
079
080        /**
081         * Retrieve the given column as binary stream from the given ResultSet.
082         * <p>Might simply invoke {@code ResultSet.getAsciiStream} or work with
083         * {@code SQLXML} or database-specific classes depending on the
084         * database and driver.
085         * @param rs the ResultSet to retrieve the content from
086         * @param columnName the column name to use
087         * @return the content as a binary stream, or {@code null} in case of SQL NULL
088         * @throws SQLException if thrown by JDBC methods
089         * @see java.sql.ResultSet#getSQLXML
090         * @see java.sql.SQLXML#getBinaryStream
091         */
092        InputStream getXmlAsBinaryStream(ResultSet rs, String columnName) throws SQLException;
093
094        /**
095         * Retrieve the given column as binary stream from the given ResultSet.
096         * <p>Might simply invoke {@code ResultSet.getAsciiStream} or work with
097         * {@code SQLXML} or database-specific classes depending on the
098         * database and driver.
099         * @param rs the ResultSet to retrieve the content from
100         * @param columnIndex the column index to use
101         * @return the content as binary stream, or {@code null} in case of SQL NULL
102         * @throws SQLException if thrown by JDBC methods
103         * @see java.sql.ResultSet#getSQLXML
104         * @see java.sql.SQLXML#getBinaryStream
105         */
106        InputStream getXmlAsBinaryStream(ResultSet rs, int columnIndex) throws SQLException;
107
108        /**
109         * Retrieve the given column as character stream from the given ResultSet.
110         * <p>Might simply invoke {@code ResultSet.getCharacterStream} or work with
111         * {@code SQLXML} or database-specific classes depending on the
112         * database and driver.
113         * @param rs the ResultSet to retrieve the content from
114         * @param columnName the column name to use
115         * @return the content as character stream, or {@code null} in case of SQL NULL
116         * @throws SQLException if thrown by JDBC methods
117         * @see java.sql.ResultSet#getSQLXML
118         * @see java.sql.SQLXML#getCharacterStream
119         */
120        Reader getXmlAsCharacterStream(ResultSet rs, String columnName) throws SQLException;
121
122        /**
123         * Retrieve the given column as character stream from the given ResultSet.
124         * <p>Might simply invoke {@code ResultSet.getCharacterStream} or work with
125         * {@code SQLXML} or database-specific classes depending on the
126         * database and driver.
127         * @param rs the ResultSet to retrieve the content from
128         * @param columnIndex the column index to use
129         * @return the content as character stream, or {@code null} in case of SQL NULL
130         * @throws SQLException if thrown by JDBC methods
131         * @see java.sql.ResultSet#getSQLXML
132         * @see java.sql.SQLXML#getCharacterStream
133         */
134        Reader getXmlAsCharacterStream(ResultSet rs, int columnIndex) throws SQLException;
135
136        /**
137         * Retrieve the given column as Source implemented using the specified source class
138         * from the given ResultSet.
139         * <p>Might work with {@code SQLXML} or database-specific classes depending
140         * on the database and driver.
141         * @param rs the ResultSet to retrieve the content from
142         * @param columnName the column name to use
143         * @param sourceClass the implementation class to be used
144         * @return the content as character stream, or {@code null} in case of SQL NULL
145         * @throws SQLException if thrown by JDBC methods
146         * @see java.sql.ResultSet#getSQLXML
147         * @see java.sql.SQLXML#getSource
148         */
149        Source getXmlAsSource(ResultSet rs, String columnName, Class<? extends Source> sourceClass) throws SQLException;
150
151        /**
152         * Retrieve the given column as Source implemented using the specified source class
153         * from the given ResultSet.
154         * <p>Might work with {@code SQLXML} or database-specific classes depending
155         * on the database and driver.
156         * @param rs the ResultSet to retrieve the content from
157         * @param columnIndex the column index to use
158         * @param sourceClass the implementation class to be used
159         * @return the content as character stream, or {@code null} in case of SQL NULL
160         * @throws SQLException if thrown by JDBC methods
161         * @see java.sql.ResultSet#getSQLXML
162         * @see java.sql.SQLXML#getSource
163         */
164        Source getXmlAsSource(ResultSet rs, int columnIndex, Class<? extends Source> sourceClass) throws SQLException;
165
166
167        //-------------------------------------------------------------------------
168        // Convenience methods for building XML content
169        //-------------------------------------------------------------------------
170
171        /**
172         * Create a {@code SqlXmlValue} instance for the given XML data,
173         * as supported by the underlying JDBC driver.
174         * @param value the XML String value providing XML data
175         * @return the implementation specific instance
176         * @see SqlXmlValue
177         * @see java.sql.SQLXML#setString(String)
178         */
179        SqlXmlValue newSqlXmlValue(String value);
180
181        /**
182         * Create a {@code SqlXmlValue} instance for the given XML data,
183         * as supported by the underlying JDBC driver.
184         * @param provider the {@code XmlBinaryStreamProvider} providing XML data
185         * @return the implementation specific instance
186         * @see SqlXmlValue
187         * @see java.sql.SQLXML#setBinaryStream()
188         */
189        SqlXmlValue newSqlXmlValue(XmlBinaryStreamProvider provider);
190
191        /**
192         * Create a {@code SqlXmlValue} instance for the given XML data,
193         * as supported by the underlying JDBC driver.
194         * @param provider the {@code XmlCharacterStreamProvider} providing XML data
195         * @return the implementation specific instance
196         * @see SqlXmlValue
197         * @see java.sql.SQLXML#setCharacterStream()
198         */
199        SqlXmlValue newSqlXmlValue(XmlCharacterStreamProvider provider);
200
201        /**
202         * Create a {@code SqlXmlValue} instance for the given XML data,
203         * as supported by the underlying JDBC driver.
204         * @param resultClass the Result implementation class to be used
205         * @param provider the {@code XmlResultProvider} that will provide the XML data
206         * @return the implementation specific instance
207         * @see SqlXmlValue
208         * @see java.sql.SQLXML#setResult(Class)
209         */
210        SqlXmlValue newSqlXmlValue(Class<? extends Result> resultClass, XmlResultProvider provider);
211
212        /**
213         * Create a {@code SqlXmlValue} instance for the given XML data,
214         * as supported by the underlying JDBC driver.
215         * @param doc the XML Document to be used
216         * @return the implementation specific instance
217         * @see SqlXmlValue
218         */
219        SqlXmlValue newSqlXmlValue(Document doc);
220
221}