SQLOutput


1   /*
2    * @(#)SQLOutput.java   1.20 03/12/19
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   package java.sql;
9   
10  /**
11   * The output stream for writing the attributes of a user-defined
12   * type back to the database.  This interface, used 
13   * only for custom mapping, is used by the driver, and its
14   * methods are never directly invoked by a programmer.
15   * <p>When an object of a class implementing the interface
16   * <code>SQLData</code> is passed as an argument to an SQL statement, the
17   * JDBC driver calls the method <code>SQLData.getSQLType</code> to
18   * determine the  kind of SQL
19   * datum being passed to the database.
20   * The driver then creates an instance of <code>SQLOutput</code> and
21   * passes it to the method <code>SQLData.writeSQL</code>.
22   * The method <code>writeSQL</code> in turn calls the
23   * appropriate <code>SQLOutput</code> <i>writer</i> methods 
24   * <code>writeBoolean</code>, <code>writeCharacterStream</code>, and so on)
25   * to write data from the <code>SQLData</code> object to
26   * the <code>SQLOutput</code> output stream as the 
27   * representation of an SQL user-defined type.
28   * @since 1.2
29   */
30  
31   public interface SQLOutput {
32  
33    //================================================================
34    // Methods for writing attributes to the stream of SQL data.
35    // These methods correspond to the column-accessor methods of
36    // java.sql.ResultSet.
37    //================================================================
38  
39    /**
40     * Writes the next attribute to the stream as a <code>String</code>
41     * in the Java programming language.
42     *
43     * @param x the value to pass to the database
44     * @exception SQLException if a database access error occurs
45     */
46    void writeString(String   x) throws SQLException  ;
47  
48    /**
49     * Writes the next attribute to the stream as a Java boolean.
50     * Writes the next attribute to the stream as a <code>String</code>
51     * in the Java programming language.
52     *
53     * @param x the value to pass to the database
54     * @exception SQLException if a database access error occurs
55     */
56    void writeBoolean(boolean x) throws SQLException  ;
57  
58    /**
59     * Writes the next attribute to the stream as a Java byte.
60     * Writes the next attribute to the stream as a <code>String</code>
61     * in the Java programming language.
62     *
63     * @param x the value to pass to the database
64     * @exception SQLException if a database access error occurs
65     */
66    void writeByte(byte x) throws SQLException  ;
67  
68    /**
69     * Writes the next attribute to the stream as a Java short.
70     * Writes the next attribute to the stream as a <code>String</code>
71     * in the Java programming language.
72     *
73     * @param x the value to pass to the database
74     * @exception SQLException if a database access error occurs
75     */
76    void writeShort(short x) throws SQLException  ;
77  
78    /**
79     * Writes the next attribute to the stream as a Java int.
80     * Writes the next attribute to the stream as a <code>String</code>
81     * in the Java programming language.
82     *
83     * @param x the value to pass to the database
84     * @exception SQLException if a database access error occurs
85     */
86    void writeInt(int x) throws SQLException  ;
87  
88    /**
89     * Writes the next attribute to the stream as a Java long.
90     * Writes the next attribute to the stream as a <code>String</code>
91     * in the Java programming language.
92     *
93     * @param x the value to pass to the database
94     * @exception SQLException if a database access error occurs
95     */
96    void writeLong(long x) throws SQLException  ;
97  
98    /**
99     * Writes the next attribute to the stream as a Java float.
100    * Writes the next attribute to the stream as a <code>String</code>
101    * in the Java programming language.
102    *
103    * @param x the value to pass to the database
104    * @exception SQLException if a database access error occurs
105    */
106   void writeFloat(float x) throws SQLException  ;
107 
108   /**
109    * Writes the next attribute to the stream as a Java double.
110    * Writes the next attribute to the stream as a <code>String</code>
111    * in the Java programming language.
112    *
113    * @param x the value to pass to the database
114    * @exception SQLException if a database access error occurs
115    */
116   void writeDouble(double x) throws SQLException  ;
117 
118   /**
119    * Writes the next attribute to the stream as a java.math.BigDecimal object.
120    * Writes the next attribute to the stream as a <code>String</code>
121    * in the Java programming language.
122    *
123    * @param x the value to pass to the database
124    * @exception SQLException if a database access error occurs
125    */
126   void writeBigDecimal(java.math.BigDecimal   x) throws SQLException  ;
127 
128   /**
129    * Writes the next attribute to the stream as an array of bytes.
130    * Writes the next attribute to the stream as a <code>String</code>
131    * in the Java programming language.
132    *
133    * @param x the value to pass to the database
134    * @exception SQLException if a database access error occurs
135    */
136   void writeBytes(byte[] x) throws SQLException  ;
137 
138   /**
139    * Writes the next attribute to the stream as a java.sql.Date object.
140    * Writes the next attribute to the stream as a <code>java.sql.Date</code> object
141    * in the Java programming language.
142    *
143    * @param x the value to pass to the database
144    * @exception SQLException if a database access error occurs
145    */
146   void writeDate(java.sql.Date   x) throws SQLException  ;
147 
148   /**
149    * Writes the next attribute to the stream as a java.sql.Time object.
150    * Writes the next attribute to the stream as a <code>java.sql.Date</code> object
151    * in the Java programming language.
152    *
153    * @param x the value to pass to the database
154    * @exception SQLException if a database access error occurs
155    */
156   void writeTime(java.sql.Time   x) throws SQLException  ;
157 
158   /**
159    * Writes the next attribute to the stream as a java.sql.Timestamp object.
160    * Writes the next attribute to the stream as a <code>java.sql.Date</code> object
161    * in the Java programming language.
162    *
163    * @param x the value to pass to the database
164    * @exception SQLException if a database access error occurs
165    */
166   void writeTimestamp(java.sql.Timestamp   x) throws SQLException  ;
167 
168   /**
169    * Writes the next attribute to the stream as a stream of Unicode characters.
170    *
171    * @param x the value to pass to the database
172    * @exception SQLException if a database access error occurs
173    */
174   void writeCharacterStream(java.io.Reader   x) throws SQLException  ;
175 
176   /**
177    * Writes the next attribute to the stream as a stream of ASCII characters.
178    *
179    * @param x the value to pass to the database
180    * @exception SQLException if a database access error occurs
181    */
182   void writeAsciiStream(java.io.InputStream   x) throws SQLException  ;
183 
184   /**
185    * Writes the next attribute to the stream as a stream of uninterpreted
186    * bytes.
187    *
188    * @param x the value to pass to the database
189    * @exception SQLException if a database access error occurs
190    */
191   void writeBinaryStream(java.io.InputStream   x) throws SQLException  ;
192   
193   //================================================================
194   // Methods for writing items of SQL user-defined types to the stream.
195   // These methods pass objects to the database as values of SQL
196   // Structured Types, Distinct Types, Constructed Types, and Locator
197   // Types.  They decompose the Java object(s) and write leaf data
198   // items using the methods above.
199   //================================================================
200 
201   /**
202    * Writes to the stream the data contained in the given 
203    * <code>SQLData</code> object.
204    * When the <code>SQLData</code> object is <code>null</code>, this
205    * method writes an SQL <code>NULL</code> to the stream.  
206    * Otherwise, it calls the <code>SQLData.writeSQL</code>
207    * method of the given object, which 
208    * writes the object's attributes to the stream.
209    * The implementation of the method <code>SQLData.writeSQ</code>
210    * calls the appropriate <code>SQLOutput</code> writer method(s)
211    * for writing each of the object's attributes in order.
212    * The attributes must be read from an <code>SQLInput</code>
213    * input stream and written to an <code>SQLOutput</code>
214    * output stream in the same order in which they were
215    * listed in the SQL definition of the user-defined type.
216    * 
217    * @param x the object representing data of an SQL structured or
218    * distinct type
219    * @exception SQLException if a database access error occurs
220    */
221   void writeObject(SQLData   x) throws SQLException  ;
222 
223   /**
224    * Writes an SQL <code>REF</code> value to the stream.
225    *
226    * @param x a <code>Ref</code> object representing data of an SQL
227    * <code>REF</code> value
228    * @exception SQLException if a database access error occurs
229    */
230   void writeRef(Ref   x) throws SQLException  ;
231 
232   /**
233    * Writes an SQL <code>BLOB</code> value to the stream.
234    *
235    * @param x a <code>Blob</code> object representing data of an SQL
236    * <code>BLOB</code> value
237    *
238    * @exception SQLException if a database access error occurs
239    */
240   void writeBlob(Blob   x) throws SQLException  ;
241 
242   /**
243    * Writes an SQL <code>CLOB</code> value to the stream.
244    *
245    * @param x a <code>Clob</code> object representing data of an SQL
246    * <code>CLOB</code> value
247    *
248    * @exception SQLException if a database access error occurs
249    */
250   void writeClob(Clob   x) throws SQLException  ;
251 
252   /**
253    * Writes an SQL structured type value to the stream.
254    *
255    * @param x a <code>Struct</code> object representing data of an SQL
256    * structured type 
257    *
258    * @exception SQLException if a database access error occurs
259    */
260   void writeStruct(Struct   x) throws SQLException  ;
261 
262   /**
263    * Writes an SQL <code>ARRAY</code> value to the stream.
264    *
265    * @param x an <code>Array</code> object representing data of an SQL
266    * <code>ARRAY</code> type
267    *
268    * @exception SQLException if a database access error occurs
269    */
270   void writeArray(Array   x) throws SQLException  ;
271 
272      //--------------------------- JDBC 3.0 ------------------------
273 
274      /** 
275       * Writes a SQL <code>DATALINK</code> value to the stream.
276       *
277       * @param x a <code>java.net.URL</code> object representing the data
278       * of SQL DATALINK type
279       *
280       * @exception SQLException if a database access error occurs
281       * @since 1.4
282       */
283      void writeURL(java.net.URL   x) throws SQLException  ;
284 
285 }
286  
287
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags