1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one or more 3 * contributor license agreements. See the NOTICE file distributed with 4 * this work for additional information regarding copyright ownership. 5 * The ASF licenses this file to You under the Apache License, Version 2.0 6 * (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 18 package java.sql; 19 20 import java.io.InputStream; 21 import java.io.Reader; 22 import java.math.BigDecimal; 23 import java.net.URL; 24 25 /** 26 * The interface for an output stream used to write attributes of an SQL <i>User 27 * Defined Type</i> (UDT) to the database. This interface is used for custom 28 * mapping of types and is called by the JDBC driver. It is not intended to be 29 * used by applications. 30 * <p> 31 * When an object which implements the {@code SQLData} interface is used as an 32 * argument to an SQL statement, the JDBC driver calls the method {@code 33 * SQLData.getSQLType} to establish the type of the SQL UDT that is being 34 * passed. The driver then creates an {@code SQLOutput} stream and passes it to 35 * the {@code SQLData.writeSQL} method, which in turn uses the appropriate 36 * {@code SQLOutput} writer methods to write the data from the {@code SQLData} 37 * object into the stream according to the defined mapping. 38 * 39 * @see SQLData 40 */ 41 public interface SQLOutput { 42 43 /** 44 * Write a {@code String} value into the output stream. 45 * 46 * @param theString 47 * the {@code String} to write. 48 * @throws SQLException 49 * if a database error occurs. 50 */ writeString(String theString)51 public void writeString(String theString) throws SQLException; 52 53 /** 54 * Write a {@code boolean} value into the output stream. 55 * 56 * @param theFlag 57 * the {@code boolean} value to write. 58 * @throws SQLException 59 * if a database error occurs. 60 */ writeBoolean(boolean theFlag)61 public void writeBoolean(boolean theFlag) throws SQLException; 62 63 /** 64 * Write a {@code byte} value into the output stream. 65 * 66 * @param theByte 67 * the {@code byte} value to write. 68 * @throws SQLException 69 * if a database error occurs. 70 */ writeByte(byte theByte)71 public void writeByte(byte theByte) throws SQLException; 72 73 /** 74 * Write a {@code short} value into the output stream. 75 * 76 * @param theShort 77 * the {@code short} value to write. 78 * @throws SQLException 79 * if a database error occurs. 80 */ writeShort(short theShort)81 public void writeShort(short theShort) throws SQLException; 82 83 /** 84 * Write an {@code int} value into the output stream. 85 * 86 * @param theInt 87 * the {@code int} value to write. 88 * @throws SQLException 89 * if a database error occurs. 90 */ writeInt(int theInt)91 public void writeInt(int theInt) throws SQLException; 92 93 /** 94 * Write a {@code long} value into the output stream. 95 * 96 * @param theLong 97 * the {@code long} value to write. 98 * @throws SQLException 99 * if a database error occurs. 100 */ writeLong(long theLong)101 public void writeLong(long theLong) throws SQLException; 102 103 /** 104 * Write a {@code float} value into the output stream. 105 * 106 * @param theFloat 107 * the {@code float} value to write. 108 * @throws SQLException 109 * if a database error occurs. 110 */ writeFloat(float theFloat)111 public void writeFloat(float theFloat) throws SQLException; 112 113 /** 114 * Write a {@code double} value into the output stream. 115 * 116 * @param theDouble 117 * the {@code double} value to write. 118 * @throws SQLException 119 * if a database error occurs. 120 */ writeDouble(double theDouble)121 public void writeDouble(double theDouble) throws SQLException; 122 123 /** 124 * Write a {@code java.math.BigDecimal} value into the output stream. 125 * 126 * @param theBigDecimal 127 * the {@code BigDecimal} value to write. 128 * @throws SQLException 129 * if a database error occurs. 130 */ writeBigDecimal(BigDecimal theBigDecimal)131 public void writeBigDecimal(BigDecimal theBigDecimal) throws SQLException; 132 133 /** 134 * Write an array of bytes into the output stream. 135 * 136 * @param theBytes 137 * the array of bytes to write. 138 * @throws SQLException 139 * if a database error occurs. 140 */ writeBytes(byte[] theBytes)141 public void writeBytes(byte[] theBytes) throws SQLException; 142 143 /** 144 * Write a {@code java.sql.Date} value into the output stream. 145 * 146 * @param theDate 147 * the {@code Date} value to write. 148 * @throws SQLException 149 * if a database error occurs. 150 * @see Date 151 */ writeDate(Date theDate)152 public void writeDate(Date theDate) throws SQLException; 153 154 /** 155 * Write a {@code java.sql.Time} value into the output stream. 156 * 157 * @param theTime 158 * the {@code Time} value to write. 159 * @throws SQLException 160 * if a database error occurs. 161 * @see Time 162 */ writeTime(Time theTime)163 public void writeTime(Time theTime) throws SQLException; 164 165 /** 166 * Write a {@code java.sql.Timestamp} value into the output stream. 167 * 168 * @param theTimestamp 169 * the {@code Timestamp} value to write. 170 * @throws SQLException 171 * if a database error occurs. 172 * @see Timestamp 173 */ writeTimestamp(Timestamp theTimestamp)174 public void writeTimestamp(Timestamp theTimestamp) throws SQLException; 175 176 /** 177 * Write a stream of unicode characters into the output stream. 178 * 179 * @param theStream 180 * the stream of unicode characters to write, as a {@code 181 * java.io.Reader} object. 182 * @throws SQLException 183 * if a database error occurs. 184 */ writeCharacterStream(Reader theStream)185 public void writeCharacterStream(Reader theStream) throws SQLException; 186 187 /** 188 * Write a stream of ASCII characters into the output stream. 189 * 190 * @param theStream 191 * the stream of ASCII characters to write, as a {@code 192 * java.io.InputStream} object 193 * @throws SQLException 194 * if a database error occurs. 195 */ writeAsciiStream(InputStream theStream)196 public void writeAsciiStream(InputStream theStream) throws SQLException; 197 198 /** 199 * Write a stream of uninterpreted bytes into the output stream. 200 * 201 * @param theStream 202 * the stream of bytes to write, as a {@code java.io.InputStream} 203 * object 204 * @throws SQLException 205 * if a database error occurs. 206 */ writeBinaryStream(InputStream theStream)207 public void writeBinaryStream(InputStream theStream) throws SQLException; 208 209 /** 210 * Write an {@code SQLData} object into the output stream. 211 * <p> 212 * If the {@code SQLData} object is null, writes {@code NULL} to the stream. 213 * <p> 214 * Otherwise, calls the {@code SQLData.writeSQL} method of the object, which 215 * writes the object's attributes to the stream by calling the appropriate 216 * SQLOutput writer methods for each attribute, in order. The order of the 217 * attributes is the order they are listed in the SQL definition of the User 218 * Defined Type. 219 * 220 * @param theObject 221 * the {@code SQLData} object to write. 222 * @throws SQLException 223 * if a database error occurs. 224 * @see SQLData 225 */ writeObject(SQLData theObject)226 public void writeObject(SQLData theObject) throws SQLException; 227 228 /** 229 * Write an SQL {@code Ref} value into the output stream. 230 * 231 * @param theRef 232 * the {@code java.sql.Ref} object to write. 233 * @throws SQLException 234 * if a database error occurs. 235 * @see Ref 236 */ writeRef(Ref theRef)237 public void writeRef(Ref theRef) throws SQLException; 238 239 /** 240 * Write an SQL {@code Blob} value into the output stream. 241 * 242 * @param theBlob 243 * the {@code java.sql.Blob} object to write. 244 * @throws SQLException 245 * if a database error occurs. 246 * @see Blob 247 */ writeBlob(Blob theBlob)248 public void writeBlob(Blob theBlob) throws SQLException; 249 250 /** 251 * Write an SQL {@code Clob} value into the output stream. 252 * 253 * @param theClob 254 * the {@code java.sql.Clob} object to write. 255 * @throws SQLException 256 * if a database error occurs. 257 * @see Clob 258 */ writeClob(Clob theClob)259 public void writeClob(Clob theClob) throws SQLException; 260 261 /** 262 * Write an SQL {@code Struct} value into the output stream. 263 * 264 * @param theStruct 265 * the {@code java.sql.Struct} object to write. 266 * @throws SQLException 267 * if a database error occurs. 268 * @see Struct 269 */ writeStruct(Struct theStruct)270 public void writeStruct(Struct theStruct) throws SQLException; 271 272 /** 273 * Write an SQL {@code Array} value into the output stream. 274 * 275 * @param theArray 276 * the {@code java.sql.Array} object to write. 277 * @throws SQLException 278 * if a database error occurs. 279 * @see Array 280 */ writeArray(Array theArray)281 public void writeArray(Array theArray) throws SQLException; 282 283 /** 284 * Write a {@code URL} into the output stream as an SQL DATALINK. 285 * 286 * @param theURL 287 * the datalink value as a {@code java.net.URL} to write. 288 * @throws SQLException 289 * if a database error occurs. 290 * @see java.net.URL 291 */ writeURL(URL theURL)292 public void writeURL(URL theURL) throws SQLException; 293 294 /** 295 * Write a {@code String} into the output stream as an SQL NCHAR, NVARCHAR, 296 * or LONGNVARCHAR. 297 * 298 * @param theString 299 * the {@code String} to write. 300 * @throws SQLException 301 * if a database error occurs. 302 */ writeNString(String theString)303 public void writeNString(String theString) throws SQLException; 304 305 /** 306 * Write a {@code Clob} into the output stream as an SQL NCLOB. 307 * 308 * @param theNClob 309 * the {@code java.sql.Clob} object to write. 310 * @throws SQLException 311 * if a database error occurs. 312 */ writeNClob(NClob theNClob)313 public void writeNClob(NClob theNClob) throws SQLException; 314 315 /** 316 * Write a {@code RowId} into the output stream as an SQL ROWID. 317 * 318 * @param theRowId 319 * the {@code java.sql.RowId} object to write. 320 * @throws SQLException 321 * if a database error occurs. 322 */ writeRowId(RowId theRowId)323 public void writeRowId(RowId theRowId) throws SQLException; 324 325 /** 326 * Write a {@code SQLXML} into the output stream as an SQL XML. 327 * 328 * @param theXml 329 * the {@code java.sql.SQLXML} object to write. 330 * @throws SQLException 331 * if a database error occurs. 332 */ writeSQLXML(SQLXML theXml)333 public void writeSQLXML(SQLXML theXml) throws SQLException; 334 } 335