001/*
002 * Copyright 2002-2018 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;
023
024import javax.xml.transform.Result;
025import javax.xml.transform.Source;
026
027import org.w3c.dom.Document;
028
029import org.springframework.lang.Nullable;
030
031/**
032 * Abstraction for handling XML fields in specific databases. Its main purpose
033 * is to isolate database-specific handling of XML stored in the database.
034 *
035 * <p>JDBC 4.0 introduces the new data type {@code java.sql.SQLXML}
036 * but most databases and their drivers currently rely on database-specific
037 * data types and features.
038 *
039 * <p>Provides accessor methods for XML fields and acts as factory for
040 * {@link SqlXmlValue} instances.
041 *
042 * @author Thomas Risberg
043 * @since 2.5.5
044 * @see Jdbc4SqlXmlHandler
045 * @see java.sql.SQLXML
046 * @see java.sql.ResultSet#getSQLXML
047 * @see java.sql.PreparedStatement#setSQLXML
048 */
049public interface SqlXmlHandler {
050
051        //-------------------------------------------------------------------------
052        // Convenience methods for accessing XML content
053        //-------------------------------------------------------------------------
054
055        /**
056         * Retrieve the given column as String from the given ResultSet.
057         * <p>Might simply invoke {@code ResultSet.getString} or work with
058         * {@code SQLXML} or database-specific classes depending on the
059         * database and driver.
060         * @param rs the ResultSet to retrieve the content from
061         * @param columnName the column name to use
062         * @return the content as String, or {@code null} in case of SQL NULL
063         * @throws SQLException if thrown by JDBC methods
064         * @see java.sql.ResultSet#getString
065         * @see java.sql.ResultSet#getSQLXML
066         */
067        @Nullable
068        String getXmlAsString(ResultSet rs, String columnName) throws SQLException;
069
070        /**
071         * Retrieve the given column as String from the given ResultSet.
072         * <p>Might simply invoke {@code ResultSet.getString} or work with
073         * {@code SQLXML} or database-specific classes depending on the
074         * database and driver.
075         * @param rs the ResultSet to retrieve the content from
076         * @param columnIndex the column index to use
077         * @return the content as String, or {@code null} in case of SQL NULL
078         * @throws SQLException if thrown by JDBC methods
079         * @see java.sql.ResultSet#getString
080         * @see java.sql.ResultSet#getSQLXML
081         */
082        @Nullable
083        String getXmlAsString(ResultSet rs, int columnIndex) throws SQLException;
084
085        /**
086         * Retrieve the given column as binary stream from the given ResultSet.
087         * <p>Might simply invoke {@code ResultSet.getAsciiStream} or work with
088         * {@code SQLXML} or database-specific classes depending on the
089         * database and driver.
090         * @param rs the ResultSet to retrieve the content from
091         * @param columnName the column name to use
092         * @return the content as a binary stream, or {@code null} in case of SQL NULL
093         * @throws SQLException if thrown by JDBC methods
094         * @see java.sql.ResultSet#getSQLXML
095         * @see java.sql.SQLXML#getBinaryStream
096         */
097        @Nullable
098        InputStream getXmlAsBinaryStream(ResultSet rs, String columnName) throws SQLException;
099
100        /**
101         * Retrieve the given column as binary stream from the given ResultSet.
102         * <p>Might simply invoke {@code ResultSet.getAsciiStream} or work with
103         * {@code SQLXML} or database-specific classes depending on the
104         * database and driver.
105         * @param rs the ResultSet to retrieve the content from
106         * @param columnIndex the column index to use
107         * @return the content as binary stream, or {@code null} in case of SQL NULL
108         * @throws SQLException if thrown by JDBC methods
109         * @see java.sql.ResultSet#getSQLXML
110         * @see java.sql.SQLXML#getBinaryStream
111         */
112        @Nullable
113        InputStream getXmlAsBinaryStream(ResultSet rs, int columnIndex) throws SQLException;
114
115        /**
116         * Retrieve the given column as character stream from the given ResultSet.
117         * <p>Might simply invoke {@code ResultSet.getCharacterStream} or work with
118         * {@code SQLXML} or database-specific classes depending on the
119         * database and driver.
120         * @param rs the ResultSet to retrieve the content from
121         * @param columnName the column name to use
122         * @return the content as character stream, or {@code null} in case of SQL NULL
123         * @throws SQLException if thrown by JDBC methods
124         * @see java.sql.ResultSet#getSQLXML
125         * @see java.sql.SQLXML#getCharacterStream
126         */
127        @Nullable
128        Reader getXmlAsCharacterStream(ResultSet rs, String columnName) throws SQLException;
129
130        /**
131         * Retrieve the given column as character stream from the given ResultSet.
132         * <p>Might simply invoke {@code ResultSet.getCharacterStream} or work with
133         * {@code SQLXML} or database-specific classes depending on the
134         * database and driver.
135         * @param rs the ResultSet to retrieve the content from
136         * @param columnIndex the column index to use
137         * @return the content as character stream, or {@code null} in case of SQL NULL
138         * @throws SQLException if thrown by JDBC methods
139         * @see java.sql.ResultSet#getSQLXML
140         * @see java.sql.SQLXML#getCharacterStream
141         */
142        @Nullable
143        Reader getXmlAsCharacterStream(ResultSet rs, int columnIndex) throws SQLException;
144
145        /**
146         * Retrieve the given column as Source implemented using the specified source class
147         * from the given ResultSet.
148         * <p>Might work with {@code SQLXML} or database-specific classes depending
149         * on the database and driver.
150         * @param rs the ResultSet to retrieve the content from
151         * @param columnName the column name to use
152         * @param sourceClass the implementation class to be used
153         * @return the content as character stream, or {@code null} in case of SQL NULL
154         * @throws SQLException if thrown by JDBC methods
155         * @see java.sql.ResultSet#getSQLXML
156         * @see java.sql.SQLXML#getSource
157         */
158        @Nullable
159        Source getXmlAsSource(ResultSet rs, String columnName, @Nullable Class<? extends Source> sourceClass) throws SQLException;
160
161        /**
162         * Retrieve the given column as Source implemented using the specified source class
163         * from the given ResultSet.
164         * <p>Might work with {@code SQLXML} or database-specific classes depending
165         * on the database and driver.
166         * @param rs the ResultSet to retrieve the content from
167         * @param columnIndex the column index to use
168         * @param sourceClass the implementation class to be used
169         * @return the content as character stream, or {@code null} in case of SQL NULL
170         * @throws SQLException if thrown by JDBC methods
171         * @see java.sql.ResultSet#getSQLXML
172         * @see java.sql.SQLXML#getSource
173         */
174        @Nullable
175        Source getXmlAsSource(ResultSet rs, int columnIndex, @Nullable Class<? extends Source> sourceClass) throws SQLException;
176
177
178        //-------------------------------------------------------------------------
179        // Convenience methods for building XML content
180        //-------------------------------------------------------------------------
181
182        /**
183         * Create a {@code SqlXmlValue} instance for the given XML data,
184         * as supported by the underlying JDBC driver.
185         * @param value the XML String value providing XML data
186         * @return the implementation specific instance
187         * @see SqlXmlValue
188         * @see java.sql.SQLXML#setString(String)
189         */
190        SqlXmlValue newSqlXmlValue(String value);
191
192        /**
193         * Create a {@code SqlXmlValue} instance for the given XML data,
194         * as supported by the underlying JDBC driver.
195         * @param provider the {@code XmlBinaryStreamProvider} providing XML data
196         * @return the implementation specific instance
197         * @see SqlXmlValue
198         * @see java.sql.SQLXML#setBinaryStream()
199         */
200        SqlXmlValue newSqlXmlValue(XmlBinaryStreamProvider provider);
201
202        /**
203         * Create a {@code SqlXmlValue} instance for the given XML data,
204         * as supported by the underlying JDBC driver.
205         * @param provider the {@code XmlCharacterStreamProvider} providing XML data
206         * @return the implementation specific instance
207         * @see SqlXmlValue
208         * @see java.sql.SQLXML#setCharacterStream()
209         */
210        SqlXmlValue newSqlXmlValue(XmlCharacterStreamProvider provider);
211
212        /**
213         * Create a {@code SqlXmlValue} instance for the given XML data,
214         * as supported by the underlying JDBC driver.
215         * @param resultClass the Result implementation class to be used
216         * @param provider the {@code XmlResultProvider} that will provide the XML data
217         * @return the implementation specific instance
218         * @see SqlXmlValue
219         * @see java.sql.SQLXML#setResult(Class)
220         */
221        SqlXmlValue newSqlXmlValue(Class<? extends Result> resultClass, XmlResultProvider provider);
222
223        /**
224         * Create a {@code SqlXmlValue} instance for the given XML data,
225         * as supported by the underlying JDBC driver.
226         * @param doc the XML Document to be used
227         * @return the implementation specific instance
228         * @see SqlXmlValue
229         */
230        SqlXmlValue newSqlXmlValue(Document doc);
231
232}