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
18package java.sql;
19
20import java.io.InputStream;
21import java.io.Reader;
22import java.math.BigDecimal;
23import 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 */
41public 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     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
333    public void writeSQLXML(SQLXML theXml) throws SQLException;
334}
335