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}