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}