001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017:
018: package java.sql;
019:
020: import java.io.InputStream;
021: import java.io.Reader;
022: import java.math.BigDecimal;
023: import java.net.URL;
024:
025: /**
026: * The interface for an output stream used to write attributes of an SQL User
027: * Defined Type to the database. This interface is used for custom mapping of
028: * types and is called by the JDBC driver. It is not expected that this
029: * interface is used by applications.
030: * <p>
031: * When an object which implements the SQLData interface is used as an argument
032: * to an SQL statement, the JDBC driver calls the method
033: * <code>SQLData.getSQLType</code> to establish the type of the SQL UDT that
034: * is being passed. The driver then creates an SQLOutput stream and passes it to
035: * the <code>SQLData.writeSQL</code> method, which in turn uses the
036: * appropriate SQLOutput writer methods to write the data from the SQLData
037: * object into the stream according to the defined mapping.
038: */
039: public interface SQLOutput {
040:
041: /**
042: * Write a String value into the output stream.
043: *
044: * @param theString
045: * the String to write
046: * @throws SQLException
047: * if a database error occurs
048: */
049: public void writeString(String theString) throws SQLException;
050:
051: /**
052: * Write a boolean value into the output stream.
053: *
054: * @param theFlag
055: * the boolean value to write
056: * @throws SQLException
057: * if a database error occurs
058: */
059: public void writeBoolean(boolean theFlag) throws SQLException;
060:
061: /**
062: * Write a byte value into the output stream.
063: *
064: * @param theByte
065: * the byte value to write
066: * @throws SQLException
067: * if a database error occurs
068: */
069: public void writeByte(byte theByte) throws SQLException;
070:
071: /**
072: * Write a short value into the output stream.
073: *
074: * @param theShort
075: * the short value to write
076: * @throws SQLException
077: * if a database error occurs
078: */
079: public void writeShort(short theShort) throws SQLException;
080:
081: /**
082: * Write an int value into the output stream.
083: *
084: * @param theInt
085: * the int value to write
086: * @throws SQLException
087: * if a database error occurs
088: */
089: public void writeInt(int theInt) throws SQLException;
090:
091: /**
092: * Write a long value into the output stream.
093: *
094: * @param theLong
095: * the long value to write
096: * @throws SQLException
097: * if a database error occurs
098: */
099: public void writeLong(long theLong) throws SQLException;
100:
101: /**
102: * Write a float value into the output stream.
103: *
104: * @param theFloat
105: * the float value to write
106: * @throws SQLException
107: * if a database error occurs
108: */
109: public void writeFloat(float theFloat) throws SQLException;
110:
111: /**
112: * Write a double value into the output stream.
113: *
114: * @param theDouble
115: * the double value to write
116: * @throws SQLException
117: * if a database error occurs
118: */
119: public void writeDouble(double theDouble) throws SQLException;
120:
121: /**
122: * Write a java.math.BigDecimal value into the output stream.
123: *
124: * @param theBigDecimal
125: * the BigDecimal value to write
126: * @throws SQLException
127: * if a database error occurs
128: */
129: public void writeBigDecimal(BigDecimal theBigDecimal)
130: throws SQLException;
131:
132: /**
133: * Write an array of bytes into the output stream.
134: *
135: * @param theBytes
136: * the array of bytes to write
137: * @throws SQLException
138: * if a database error occurs
139: */
140: public void writeBytes(byte[] theBytes) throws SQLException;
141:
142: /**
143: * Write a java.sql.Date value into the output stream.
144: *
145: * @param theDate
146: * the Date value to write
147: * @throws SQLException
148: * if a database error occurs
149: */
150: public void writeDate(Date theDate) throws SQLException;
151:
152: /**
153: * Write a java.sql.Time value into the output stream.
154: *
155: * @param theTime
156: * the Time value to write
157: * @throws SQLException
158: * if a database error occurs
159: */
160: public void writeTime(Time theTime) throws SQLException;
161:
162: /**
163: * Write a java.sql.Timestamp value into the output stream.
164: *
165: * @param theTimestamp
166: * the Timestamp value to write
167: * @throws SQLException
168: * if a database error occurs
169: */
170: public void writeTimestamp(Timestamp theTimestamp)
171: throws SQLException;
172:
173: /**
174: * Write a stream of Unicode characters into the output stream.
175: *
176: * @param theStream
177: * the stream of Unicode characters to write, as a java.io.Reader
178: * object
179: * @throws SQLException
180: * if a database error occurs
181: */
182: public void writeCharacterStream(Reader theStream)
183: throws SQLException;
184:
185: /**
186: * Write a stream of ASCII characters into the output stream.
187: *
188: * @param theStream
189: * the stream of ASCII characters to write, as a
190: * java.io.InputStream object
191: * @throws SQLException
192: * if a database error occurs
193: */
194: public void writeAsciiStream(InputStream theStream)
195: throws SQLException;
196:
197: /**
198: * Write a stream of uninterpreted bytes into the output stream.
199: *
200: * @param theStream
201: * the stream of bytes to write, as a java.io.InputStream object
202: * @throws SQLException
203: * if a database error occurs
204: */
205: public void writeBinaryStream(InputStream theStream)
206: throws SQLException;
207:
208: /**
209: * Write an SQLData object into the output stream.
210: * <p>
211: * If the SQLData object is null, writes SQL NULL to the stream.
212: * <p>
213: * Otherwise, calls the <code>SQLData.writeSQL</code> method of the
214: * object, which writes the object's attributes to the stream by calling the
215: * appropriate SQLOutput writer methods for each attribute, in order. The
216: * order of the attributes is the order they are listed in the SQL
217: * definition of the User Defined Type.
218: *
219: * @param theObject
220: * the SQLData object to write
221: * @throws SQLException
222: * if a database error occurs
223: */
224: public void writeObject(SQLData theObject) throws SQLException;
225:
226: /**
227: * Write an SQL Ref value into the output stream.
228: *
229: * @param theRef
230: * the java.sql.Ref object to write
231: * @throws SQLException
232: * if a database error occurs
233: */
234: public void writeRef(Ref theRef) throws SQLException;
235:
236: /**
237: * Write an SQL Blob value into the output stream.
238: *
239: * @param theBlob
240: * the java.sql.Blob object to write
241: * @throws SQLException
242: * if a database error occurs
243: */
244: public void writeBlob(Blob theBlob) throws SQLException;
245:
246: /**
247: * Write an SQL Clob value into the output stream.
248: *
249: * @param theClob
250: * the java.sql.Clob object to write
251: * @throws SQLException
252: * if a database error occurs
253: */
254: public void writeClob(Clob theClob) throws SQLException;
255:
256: /**
257: * Write an SQL Struct value into the output stream.
258: *
259: * @param theStruct
260: * the java.sql.Struct object to write
261: * @throws SQLException
262: * if a database error occurs
263: */
264: public void writeStruct(Struct theStruct) throws SQLException;
265:
266: /**
267: * Write an SQL Array value into the output stream.
268: *
269: * @param theArray
270: * the java.sql.Array object to write
271: * @throws SQLException
272: * if a database error occurs
273: */
274: public void writeArray(Array theArray) throws SQLException;
275:
276: /**
277: * Write an SQL DATALINK value into the output stream.
278: *
279: * @param theURL
280: * the Datalink value as a java.net.URL to write
281: * @throws SQLException
282: * if a database error occurs
283: */
284: public void writeURL(URL theURL) throws SQLException;
285: }
|