1 /*

     2  * Copyright (c) 1998, 2013, Oracle and/or its affiliates. All rights reserved.

     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

     4  *

     5  * This code is free software; you can redistribute it and/or modify it

     6  * under the terms of the GNU General Public License version 2 only, as

     7  * published by the Free Software Foundation.  Oracle designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Oracle in the LICENSE file that accompanied this code.

    10  *

    11  * This code is distributed in the hope that it will be useful, but WITHOUT

    12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

    13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

    14  * version 2 for more details (a copy is included in the LICENSE file that

    15  * accompanied this code).

    16  *

    17  * You should have received a copy of the GNU General Public License version

    18  * 2 along with this work; if not, write to the Free Software Foundation,

    19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

    20  *

    21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

    22  * or visit www.oracle.com if you need additional information or have any

    23  * questions.

    24  */

    25 

    26 package java.sql;

    27 

    28 /**

    29  * The output stream for writing the attributes of a user-defined

    30  * type back to the database.  This interface, used

    31  * only for custom mapping, is used by the driver, and its

    32  * methods are never directly invoked by a programmer.

    33  * <p>When an object of a class implementing the interface

    34  * <code>SQLData</code> is passed as an argument to an SQL statement, the

    35  * JDBC driver calls the method <code>SQLData.getSQLType</code> to

    36  * determine the  kind of SQL

    37  * datum being passed to the database.

    38  * The driver then creates an instance of <code>SQLOutput</code> and

    39  * passes it to the method <code>SQLData.writeSQL</code>.

    40  * The method <code>writeSQL</code> in turn calls the

    41  * appropriate <code>SQLOutput</code> <i>writer</i> methods

    42  * <code>writeBoolean</code>, <code>writeCharacterStream</code>, and so on)

    43  * to write data from the <code>SQLData</code> object to

    44  * the <code>SQLOutput</code> output stream as the

    45  * representation of an SQL user-defined type.

    46  * @since 1.2

    47  */

    48 

    49  public interface SQLOutput {

    50 

    51   //================================================================

    52   // Methods for writing attributes to the stream of SQL data.

    53   // These methods correspond to the column-accessor methods of

    54   // java.sql.ResultSet.

    55   //================================================================

    56 

    57   /**

    58    * Writes the next attribute to the stream as a <code>String</code>

    59    * in the Java programming language.

    60    *

    61    * @param x the value to pass to the database

    62    * @exception SQLException if a database access error occurs

    63    * @exception SQLFeatureNotSupportedException if the JDBC driver does not support

    64    * this method

    65    * @since 1.2

    66    */

    67   void writeString(String x) throws SQLException;

    68 

    69   /**

    70    * Writes the next attribute to the stream as a Java boolean.

    71    * Writes the next attribute to the stream as a <code>String</code>

    72    * in the Java programming language.

    73    *

    74    * @param x the value to pass to the database

    75    * @exception SQLException if a database access error occurs

    76    * @exception SQLFeatureNotSupportedException if the JDBC driver does not support

    77    * this method

    78    * @since 1.2

    79    */

    80   void writeBoolean(boolean x) throws SQLException;

    81 

    82   /**

    83    * Writes the next attribute to the stream as a Java byte.

    84    * Writes the next attribute to the stream as a <code>String</code>

    85    * in the Java programming language.

    86    *

    87    * @param x the value to pass to the database

    88    * @exception SQLException if a database access error occurs

    89    * @exception SQLFeatureNotSupportedException if the JDBC driver does not support

    90    * this method

    91    * @since 1.2

    92    */

    93   void writeByte(byte x) throws SQLException;

    94 

    95   /**

    96    * Writes the next attribute to the stream as a Java short.

    97    * Writes the next attribute to the stream as a <code>String</code>

    98    * in the Java programming language.

    99    *

   100    * @param x the value to pass to the database

   101    * @exception SQLException if a database access error occurs

   102    * @exception SQLFeatureNotSupportedException if the JDBC driver does not support

   103    * this method

   104    * @since 1.2

   105    */

   106   void writeShort(short x) throws SQLException;

   107 

   108   /**

   109    * Writes the next attribute to the stream as a Java int.

   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    * @exception SQLFeatureNotSupportedException if the JDBC driver does not support

   116    * this method

   117    * @since 1.2

   118    */

   119   void writeInt(int x) throws SQLException;

   120 

   121   /**

   122    * Writes the next attribute to the stream as a Java long.

   123    * Writes the next attribute to the stream as a <code>String</code>

   124    * in the Java programming language.

   125    *

   126    * @param x the value to pass to the database

   127    * @exception SQLException if a database access error occurs

   128    * @exception SQLFeatureNotSupportedException if the JDBC driver does not support

   129    * this method

   130    * @since 1.2

   131    */

   132   void writeLong(long x) throws SQLException;

   133 

   134   /**

   135    * Writes the next attribute to the stream as a Java float.

   136    * Writes the next attribute to the stream as a <code>String</code>

   137    * in the Java programming language.

   138    *

   139    * @param x the value to pass to the database

   140    * @exception SQLException if a database access error occurs

   141    * @exception SQLFeatureNotSupportedException if the JDBC driver does not support

   142    * this method

   143    * @since 1.2

   144    */

   145   void writeFloat(float x) throws SQLException;

   146 

   147   /**

   148    * Writes the next attribute to the stream as a Java double.

   149    * Writes the next attribute to the stream as a <code>String</code>

   150    * in the Java programming language.

   151    *

   152    * @param x the value to pass to the database

   153    * @exception SQLException if a database access error occurs

   154    * @exception SQLFeatureNotSupportedException if the JDBC driver does not support

   155    * this method

   156    * @since 1.2

   157    */

   158   void writeDouble(double x) throws SQLException;

   159 

   160   /**

   161    * Writes the next attribute to the stream as a java.math.BigDecimal object.

   162    * Writes the next attribute to the stream as a <code>String</code>

   163    * in the Java programming language.

   164    *

   165    * @param x the value to pass to the database

   166    * @exception SQLException if a database access error occurs

   167    * @exception SQLFeatureNotSupportedException if the JDBC driver does not support

   168    * this method

   169    * @since 1.2

   170    */

   171   void writeBigDecimal(java.math.BigDecimal x) throws SQLException;

   172 

   173   /**

   174    * Writes the next attribute to the stream as an array of bytes.

   175    * Writes the next attribute to the stream as a <code>String</code>

   176    * in the Java programming language.

   177    *

   178    * @param x the value to pass to the database

   179    * @exception SQLException if a database access error occurs

   180    * @exception SQLFeatureNotSupportedException if the JDBC driver does not support

   181    * this method

   182    * @since 1.2

   183    */

   184   void writeBytes(byte[] x) throws SQLException;

   185 

   186   /**

   187    * Writes the next attribute to the stream as a java.sql.Date object.

   188    * Writes the next attribute to the stream as a <code>java.sql.Date</code> object

   189    * in the Java programming language.

   190    *

   191    * @param x the value to pass to the database

   192    * @exception SQLException if a database access error occurs

   193    * @exception SQLFeatureNotSupportedException if the JDBC driver does not support

   194    * this method

   195    * @since 1.2

   196    */

   197   void writeDate(java.sql.Date x) throws SQLException;

   198 

   199   /**

   200    * Writes the next attribute to the stream as a java.sql.Time object.

   201    * Writes the next attribute to the stream as a <code>java.sql.Date</code> object

   202    * in the Java programming language.

   203    *

   204    * @param x the value to pass to the database

   205    * @exception SQLException if a database access error occurs

   206    * @exception SQLFeatureNotSupportedException if the JDBC driver does not support

   207    * this method

   208    * @since 1.2

   209    */

   210   void writeTime(java.sql.Time x) throws SQLException;

   211 

   212   /**

   213    * Writes the next attribute to the stream as a java.sql.Timestamp object.

   214    * Writes the next attribute to the stream as a <code>java.sql.Date</code> object

   215    * in the Java programming language.

   216    *

   217    * @param x the value to pass to the database

   218    * @exception SQLException if a database access error occurs

   219    * @exception SQLFeatureNotSupportedException if the JDBC driver does not support

   220    * this method

   221    * @since 1.2

   222    */

   223   void writeTimestamp(java.sql.Timestamp x) throws SQLException;

   224 

   225   /**

   226    * Writes the next attribute to the stream as a stream of Unicode characters.

   227    *

   228    * @param x the value to pass to the database

   229    * @exception SQLException if a database access error occurs

   230    * @exception SQLFeatureNotSupportedException if the JDBC driver does not support

   231    * this method

   232    * @since 1.2

   233    */

   234   void writeCharacterStream(java.io.Reader x) throws SQLException;

   235 

   236   /**

   237    * Writes the next attribute to the stream as a stream of ASCII characters.

   238    *

   239    * @param x the value to pass to the database

   240    * @exception SQLException if a database access error occurs

   241    * @exception SQLFeatureNotSupportedException if the JDBC driver does not support

   242    * this method

   243    * @since 1.2

   244    */

   245   void writeAsciiStream(java.io.InputStream x) throws SQLException;

   246 

   247   /**

   248    * Writes the next attribute to the stream as a stream of uninterpreted

   249    * bytes.

   250    *

   251    * @param x the value to pass to the database

   252    * @exception SQLException if a database access error occurs

   253    * @exception SQLFeatureNotSupportedException if the JDBC driver does not support

   254    * this method

   255    * @since 1.2

   256    */

   257   void writeBinaryStream(java.io.InputStream x) throws SQLException;

   258 

   259   //================================================================

   260   // Methods for writing items of SQL user-defined types to the stream.

   261   // These methods pass objects to the database as values of SQL

   262   // Structured Types, Distinct Types, Constructed Types, and Locator

   263   // Types.  They decompose the Java object(s) and write leaf data

   264   // items using the methods above.

   265   //================================================================

   266 

   267   /**

   268    * Writes to the stream the data contained in the given

   269    * <code>SQLData</code> object.

   270    * When the <code>SQLData</code> object is <code>null</code>, this

   271    * method writes an SQL <code>NULL</code> to the stream.

   272    * Otherwise, it calls the <code>SQLData.writeSQL</code>

   273    * method of the given object, which

   274    * writes the object's attributes to the stream.

   275    * The implementation of the method <code>SQLData.writeSQL</code>

   276    * calls the appropriate <code>SQLOutput</code> writer method(s)

   277    * for writing each of the object's attributes in order.

   278    * The attributes must be read from an <code>SQLInput</code>

   279    * input stream and written to an <code>SQLOutput</code>

   280    * output stream in the same order in which they were

   281    * listed in the SQL definition of the user-defined type.

   282    *

   283    * @param x the object representing data of an SQL structured or

   284    * distinct type

   285    * @exception SQLException if a database access error occurs

   286    * @exception SQLFeatureNotSupportedException if the JDBC driver does not support

   287    * this method

   288    * @since 1.2

   289    */

   290   void writeObject(SQLData x) throws SQLException;

   291 

   292   /**

   293    * Writes an SQL <code>REF</code> value to the stream.

   294    *

   295    * @param x a <code>Ref</code> object representing data of an SQL

   296    * <code>REF</code> value

   297    * @exception SQLException if a database access error occurs

   298    * @exception SQLFeatureNotSupportedException if the JDBC driver does not support

   299    * this method

   300    * @since 1.2

   301    */

   302   void writeRef(Ref x) throws SQLException;

   303 

   304   /**

   305    * Writes an SQL <code>BLOB</code> value to the stream.

   306    *

   307    * @param x a <code>Blob</code> object representing data of an SQL

   308    * <code>BLOB</code> value

   309    *

   310    * @exception SQLException if a database access error occurs

   311    * @exception SQLFeatureNotSupportedException if the JDBC driver does not support

   312    * this method

   313    * @since 1.2

   314    */

   315   void writeBlob(Blob x) throws SQLException;

   316 

   317   /**

   318    * Writes an SQL <code>CLOB</code> value to the stream.

   319    *

   320    * @param x a <code>Clob</code> object representing data of an SQL

   321    * <code>CLOB</code> value

   322    *

   323    * @exception SQLException if a database access error occurs

   324    * @exception SQLFeatureNotSupportedException if the JDBC driver does not support

   325    * this method

   326    * @since 1.2

   327    */

   328   void writeClob(Clob x) throws SQLException;

   329 

   330   /**

   331    * Writes an SQL structured type value to the stream.

   332    *

   333    * @param x a <code>Struct</code> object representing data of an SQL

   334    * structured type

   335    *

   336    * @exception SQLException if a database access error occurs

   337    * @exception SQLFeatureNotSupportedException if the JDBC driver does not support

   338    * this method

   339    * @since 1.2

   340    */

   341   void writeStruct(Struct x) throws SQLException;

   342 

   343   /**

   344    * Writes an SQL <code>ARRAY</code> value to the stream.

   345    *

   346    * @param x an <code>Array</code> object representing data of an SQL

   347    * <code>ARRAY</code> type

   348    *

   349    * @exception SQLException if a database access error occurs

   350    * @exception SQLFeatureNotSupportedException if the JDBC driver does not support

   351    * this method

   352    * @since 1.2

   353    */

   354   void writeArray(Array x) throws SQLException;

   355 

   356      //--------------------------- JDBC 3.0 ------------------------

   357 

   358      /**

   359       * Writes a SQL <code>DATALINK</code> value to the stream.

   360       *

   361       * @param x a <code>java.net.URL</code> object representing the data

   362       * of SQL DATALINK type

   363       *

   364       * @exception SQLException if a database access error occurs

   365       * @exception SQLFeatureNotSupportedException if the JDBC driver does not support

   366       * this method

   367       * @since 1.4

   368       */

   369      void writeURL(java.net.URL x) throws SQLException;

   370 

   371      //--------------------------- JDBC 4.0 ------------------------

   372 

   373   /**

   374    * Writes the next attribute to the stream as a <code>String</code>

   375    * in the Java programming language. The driver converts this to a

   376    * SQL <code>NCHAR</code> or

   377    * <code>NVARCHAR</code> or <code>LONGNVARCHAR</code> value

   378    * (depending on the argument's

   379    * size relative to the driver's limits on <code>NVARCHAR</code> values)

   380    * when it sends it to the stream.

   381    *

   382    * @param x the value to pass to the database

   383    * @exception SQLException if a database access error occurs

   384    * @exception SQLFeatureNotSupportedException if the JDBC driver does not support

   385    * this method

   386    * @since 1.6

   387    */

   388   void writeNString(String x) throws SQLException;

   389 

   390   /**

   391    * Writes an SQL <code>NCLOB</code> value to the stream.

   392    *

   393    * @param x a <code>NClob</code> object representing data of an SQL

   394    * <code>NCLOB</code> value

   395    *

   396    * @exception SQLException if a database access error occurs

   397    * @exception SQLFeatureNotSupportedException if the JDBC driver does not support

   398    * this method

   399    * @since 1.6

   400    */

   401   void writeNClob(NClob x) throws SQLException;

   402 

   403 

   404   /**

   405    * Writes an SQL <code>ROWID</code> value to the stream.

   406    *

   407    * @param x a <code>RowId</code> object representing data of an SQL

   408    * <code>ROWID</code> value

   409    *

   410    * @exception SQLException if a database access error occurs

   411    * @exception SQLFeatureNotSupportedException if the JDBC driver does not support

   412    * this method

   413    * @since 1.6

   414    */

   415   void writeRowId(RowId x) throws SQLException;

   416 

   417 

   418   /**

   419    * Writes an SQL <code>XML</code> value to the stream.

   420    *

   421    * @param x a <code>SQLXML</code> object representing data of an SQL

   422    * <code>XML</code> value

   423    *

   424    * @throws SQLException if a database access error occurs,

   425    * the <code>java.xml.transform.Result</code>,

   426    *  <code>Writer</code> or <code>OutputStream</code> has not been closed for the <code>SQLXML</code> object or

   427    *  if there is an error processing the XML value.  The <code>getCause</code> method

   428    *  of the exception may provide a more detailed exception, for example, if the

   429    *  stream does not contain valid XML.

   430    * @exception SQLFeatureNotSupportedException if the JDBC driver does not support

   431    * this method

   432    * @since 1.6

   433    */

   434   void writeSQLXML(SQLXML x) throws SQLException;

   435 

   436   //--------------------------JDBC 4.2 -----------------------------

   437 

   438   /**

   439    * Writes to the stream the data contained in the given object. The

   440    * object will be converted to the specified targetSqlType

   441    * before being sent to the stream.

   442    *<p>

   443    * When the {@code object} is {@code null}, this

   444    * method writes an SQL {@code NULL} to the stream.

   445    * <p>

   446    * If the object has a custom mapping (is of a class implementing the

   447    * interface {@code SQLData}),

   448    * the JDBC driver should call the method {@code SQLData.writeSQL} to

   449    * write it to the SQL data stream.

   450    * If, on the other hand, the object is of a class implementing

   451    * {@code Ref}, {@code Blob}, {@code Clob},  {@code NClob},

   452    *  {@code Struct}, {@code java.net.URL},

   453    * or {@code Array}, the driver should pass it to the database as a

   454    * value of the corresponding SQL type.

   455    *<P>

   456    * The default implementation will throw {@code SQLFeatureNotSupportedException}

   457    *

   458    * @param x the object containing the input parameter value

   459    * @param targetSqlType the SQL type to be sent to the database.

   460    * @exception SQLException if a database access error occurs  or

   461    *            if the Java Object specified by x is an InputStream

   462    *            or Reader object and the value of the scale parameter is less

   463    *            than zero

   464    * @exception SQLFeatureNotSupportedException if

   465    * the JDBC driver does not support this data type

   466    * @see JDBCType

   467    * @see SQLType

   468    * @since 1.8

   469    */

   470   default void writeObject(Object x, SQLType targetSqlType) throws SQLException {

   471         throw new SQLFeatureNotSupportedException();

   472   }

   473 

   474 }

   475