diff options
Diffstat (limited to 'src/share/classes/java/sql/CallableStatement.java')
| -rw-r--r-- | src/share/classes/java/sql/CallableStatement.java | 366 |
1 files changed, 344 insertions, 22 deletions
diff --git a/src/share/classes/java/sql/CallableStatement.java b/src/share/classes/java/sql/CallableStatement.java index a86caa69eb..1200f771da 100644 --- a/src/share/classes/java/sql/CallableStatement.java +++ b/src/share/classes/java/sql/CallableStatement.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1996, 2012, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1996, 2013, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -1079,9 +1079,7 @@ public interface CallableStatement extends PreparedStatement { int length) throws SQLException; /** - * Sets the value of the designated parameter with the given object. The second - * argument must be an object type; for integral values, the - * <code>java.lang</code> equivalent objects should be used. + * Sets the value of the designated parameter with the given object. * * <p>The given Java object will be converted to the given targetSqlType * before being sent to the database. @@ -1109,13 +1107,8 @@ public interface CallableStatement extends PreparedStatement { * @exception SQLException if parameterName does not correspond to a named * parameter; if a database access error occurs or * this method is called on a closed <code>CallableStatement</code> - * @exception SQLFeatureNotSupportedException if <code>targetSqlType</code> is - * a <code>ARRAY</code>, <code>BLOB</code>, <code>CLOB</code>, - * <code>DATALINK</code>, <code>JAVA_OBJECT</code>, <code>NCHAR</code>, - * <code>NCLOB</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>, - * <code>REF</code>, <code>ROWID</code>, <code>SQLXML</code> - * or <code>STRUCT</code> data type and the JDBC driver does not support - * this data type + * @exception SQLFeatureNotSupportedException if + * the JDBC driver does not support this data type * @see Types * @see #getObject * @since 1.4 @@ -1125,8 +1118,10 @@ public interface CallableStatement extends PreparedStatement { /** * Sets the value of the designated parameter with the given object. - * This method is like the method <code>setObject</code> - * above, except that it assumes a scale of zero. + * + * This method is similar to {@link #setObject(String parameterName, + * Object x, int targetSqlType, int scaleOrLength)}, + * except that it assumes a scale of zero. * * @param parameterName the name of the parameter * @param x the object containing the input parameter value @@ -1135,13 +1130,8 @@ public interface CallableStatement extends PreparedStatement { * @exception SQLException if parameterName does not correspond to a named * parameter; if a database access error occurs or * this method is called on a closed <code>CallableStatement</code> - * @exception SQLFeatureNotSupportedException if <code>targetSqlType</code> is - * a <code>ARRAY</code>, <code>BLOB</code>, <code>CLOB</code>, - * <code>DATALINK</code>, <code>JAVA_OBJECT</code>, <code>NCHAR</code>, - * <code>NCLOB</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>, - * <code>REF</code>, <code>ROWID</code>, <code>SQLXML</code> - * or <code>STRUCT</code> data type and the JDBC driver does not support - * this data type + * @exception SQLFeatureNotSupportedException if + * the JDBC driver does not support this data type * @see #getObject * @since 1.4 */ @@ -1150,8 +1140,6 @@ public interface CallableStatement extends PreparedStatement { /** * Sets the value of the designated parameter with the given object. - * The second parameter must be of type <code>Object</code>; therefore, the - * <code>java.lang</code> equivalent objects should be used for built-in types. * * <p>The JDBC specification specifies a standard mapping from * Java <code>Object</code> types to SQL types. The given argument @@ -2497,4 +2485,338 @@ public interface CallableStatement extends PreparedStatement { */ public <T> T getObject(String parameterName, Class<T> type) throws SQLException; + //------------------------- JDBC 4.2 ----------------------------------- + + /** + * <p>Sets the value of the designated parameter with the given object. + * + * If the second argument is an {@code InputStream} then the stream + * must contain the number of bytes specified by scaleOrLength. + * If the second argument is a {@code Reader} then the reader must + * contain the number of characters specified + * by scaleOrLength. If these conditions are not true the driver + * will generate a + * {@code SQLException} when the prepared statement is executed. + * + * <p>The given Java object will be converted to the given targetSqlType + * before being sent to the database. + * + * If the object has a custom mapping (is of a class implementing the + * interface {@code SQLData}), + * the JDBC driver should call the method {@code SQLData.writeSQL} to + * write it to the SQL data stream. + * If, on the other hand, the object is of a class implementing + * {@code Ref}, {@code Blob}, {@code Clob}, {@code NClob}, + * {@code Struct}, {@code java.net.URL}, + * or {@code Array}, the driver should pass it to the database as a + * value of the corresponding SQL type. + * + * <p>Note that this method may be used to pass database-specific + * abstract data types. + *<P> + * The default implementation will throw {@code SQLFeatureNotSupportedException} + * + * @param parameterName the name of the parameter + * @param x the object containing the input parameter value + * @param targetSqlType the SQL type to be + * sent to the database. The scale argument may further qualify this type. + * @param scaleOrLength for {@code java.sql.JDBCType.DECIMAL} + * or {@code java.sql.JDBCType.NUMERIC types}, + * this is the number of digits after the decimal point. For + * Java Object types {@code InputStream} and {@code Reader}, + * this is the length + * of the data in the stream or reader. For all other types, + * this value will be ignored. + * @exception SQLException if parameterName does not correspond to a named + * parameter; if a database access error occurs + * or this method is called on a closed {@code CallableStatement} or + * if the Java Object specified by x is an InputStream + * or Reader object and the value of the scale parameter is less + * than zero + * @exception SQLFeatureNotSupportedException if + * the JDBC driver does not support this data type + * @see JDBCType + * @see SQLType + * + * @since 1.8 + */ + default void setObject(String parameterName, Object x, SQLType targetSqlType, + int scaleOrLength) throws SQLException { + throw new SQLFeatureNotSupportedException("setObject not implemented"); + } + /** + * Sets the value of the designated parameter with the given object. + * + * This method is similar to {@link #setObject(String parameterName, + * Object x, SQLType targetSqlType, int scaleOrLength)}, + * except that it assumes a scale of zero. + *<P> + * The default implementation will throw {@code SQLFeatureNotSupportedException} + * + * @param parameterName the name of the parameter + * @param x the object containing the input parameter value + * @param targetSqlType the SQL type to be sent to the database + * @exception SQLException if parameterName does not correspond to a named + * parameter; if a database access error occurs + * or this method is called on a closed {@code CallableStatement} + * @exception SQLFeatureNotSupportedException if + * the JDBC driver does not support this data type + * @see JDBCType + * @see SQLType + * @since 1.8 + */ + default void setObject(String parameterName, Object x, SQLType targetSqlType) + throws SQLException { + throw new SQLFeatureNotSupportedException("setObject not implemented"); + } + + /** + * Registers the OUT parameter in ordinal position + * {@code parameterIndex} to the JDBC type + * {@code sqlType}. All OUT parameters must be registered + * before a stored procedure is executed. + * <p> + * The JDBC type specified by {@code sqlType} for an OUT + * parameter determines the Java type that must be used + * in the {@code get} method to read the value of that parameter. + * <p> + * If the JDBC type expected to be returned to this output parameter + * is specific to this particular database, {@code sqlType} + * may be {@code JDBCType.OTHER} or a {@code SQLType} that is supported by + * the JDBC driver. The method + * {@link #getObject} retrieves the value. + *<P> + * The default implementation will throw {@code SQLFeatureNotSupportedException} + * + * @param parameterIndex the first parameter is 1, the second is 2, + * and so on + * @param sqlType the JDBC type code defined by {@code SQLType} to use to + * register the OUT Parameter. + * If the parameter is of JDBC type {@code JDBCType.NUMERIC} + * or {@code JDBCType.DECIMAL}, the version of + * {@code registerOutParameter} that accepts a scale value + * should be used. + * + * @exception SQLException if the parameterIndex is not valid; + * if a database access error occurs or + * this method is called on a closed {@code CallableStatement} + * @exception SQLFeatureNotSupportedException if + * the JDBC driver does not support this data type + * @see JDBCType + * @see SQLType + * @since 1.8 + */ + default void registerOutParameter(int parameterIndex, SQLType sqlType) + throws SQLException { + throw new SQLFeatureNotSupportedException("registerOutParameter not implemented"); + } + + /** + * Registers the parameter in ordinal position + * {@code parameterIndex} to be of JDBC type + * {@code sqlType}. All OUT parameters must be registered + * before a stored procedure is executed. + * <p> + * The JDBC type specified by {@code sqlType} for an OUT + * parameter determines the Java type that must be used + * in the {@code get} method to read the value of that parameter. + * <p> + * This version of {@code registrOutParameter} should be + * used when the parameter is of JDBC type {@code JDBCType.NUMERIC} + * or {@code JDBCType.DECIMAL}. + *<P> + * The default implementation will throw {@code SQLFeatureNotSupportedException} + * + * @param parameterIndex the first parameter is 1, the second is 2, + * and so on + * @param sqlType the JDBC type code defined by {@code SQLType} to use to + * register the OUT Parameter. + * @param scale the desired number of digits to the right of the + * decimal point. It must be greater than or equal to zero. + * @exception SQLException if the parameterIndex is not valid; + * if a database access error occurs or + * this method is called on a closed {@code CallableStatement} + * @exception SQLFeatureNotSupportedException if + * the JDBC driver does not support this data type + * @see JDBCType + * @see SQLType + * @since 1.8 + */ + default void registerOutParameter(int parameterIndex, SQLType sqlType, + int scale) throws SQLException { + throw new SQLFeatureNotSupportedException("registerOutParameter not implemented"); + } + /** + * Registers the designated output parameter. + * This version of + * the method {@code registrOutParameter} + * should be used for a user-defined or {@code REF} output parameter. + * Examples + * of user-defined types include: {@code STRUCT}, {@code DISTINCT}, + * {@code JAVA_OBJECT}, and named array types. + *<p> + * All OUT parameters must be registered + * before a stored procedure is executed. + * <p> For a user-defined parameter, the fully-qualified SQL + * type name of the parameter should also be given, while a {@code REF} + * parameter requires that the fully-qualified type name of the + * referenced type be given. A JDBC driver that does not need the + * type code and type name information may ignore it. To be portable, + * however, applications should always provide these values for + * user-defined and {@code REF} parameters. + * + * Although it is intended for user-defined and {@code REF} parameters, + * this method may be used to register a parameter of any JDBC type. + * If the parameter does not have a user-defined or {@code REF} type, the + * <i>typeName</i> parameter is ignored. + * + * <P><B>Note:</B> When reading the value of an out parameter, you + * must use the getter method whose Java type corresponds to the + * parameter's registered SQL type. + *<P> + * The default implementation will throw {@code SQLFeatureNotSupportedException} + * + * @param parameterIndex the first parameter is 1, the second is 2,... + * @param sqlType the JDBC type code defined by {@code SQLType} to use to + * register the OUT Parameter. + * @param typeName the fully-qualified name of an SQL structured type + * @exception SQLException if the parameterIndex is not valid; + * if a database access error occurs or + * this method is called on a closed {@code CallableStatement} + * @exception SQLFeatureNotSupportedException if + * the JDBC driver does not support this data type + * @see JDBCType + * @see SQLType + * @since 1.8 + */ + default void registerOutParameter (int parameterIndex, SQLType sqlType, + String typeName) throws SQLException { + throw new SQLFeatureNotSupportedException("registerOutParameter not implemented"); + } + + /** + * Registers the OUT parameter named + * <code>parameterName</code> to the JDBC type + * {@code sqlType}. All OUT parameters must be registered + * before a stored procedure is executed. + * <p> + * The JDBC type specified by {@code sqlType} for an OUT + * parameter determines the Java type that must be used + * in the {@code get} method to read the value of that parameter. + * <p> + * If the JDBC type expected to be returned to this output parameter + * is specific to this particular database, {@code sqlType} + * should be {@code JDBCType.OTHER} or a {@code SQLType} that is supported + * by the JDBC driver.. The method + * {@link #getObject} retrieves the value. + *<P> + * The default implementation will throw {@code SQLFeatureNotSupportedException} + * + * @param parameterName the name of the parameter + * @param sqlType the JDBC type code defined by {@code SQLType} to use to + * register the OUT Parameter. + * If the parameter is of JDBC type {@code JDBCType.NUMERIC} + * or {@code JDBCType.DECIMAL}, the version of + * {@code registrOutParameter} that accepts a scale value + * should be used. + * @exception SQLException if parameterName does not correspond to a named + * parameter; if a database access error occurs or + * this method is called on a closed {@code CallableStatement} + * @exception SQLFeatureNotSupportedException if + * the JDBC driver does not support this data type + * or if the JDBC driver does not support + * this method + * @since 1.8 + * @see JDBCType + * @see SQLType + */ + default void registerOutParameter(String parameterName, SQLType sqlType) + throws SQLException { + throw new SQLFeatureNotSupportedException("registerOutParameter not implemented"); + } + + /** + * Registers the parameter named + * <code>parameterName</code> to be of JDBC type + * {@code sqlType}. All OUT parameters must be registered + * before a stored procedure is executed. + * <p> + * The JDBC type specified by {@code sqlType} for an OUT + * parameter determines the Java type that must be used + * in the {@code get} method to read the value of that parameter. + * <p> + * This version of {@code registrOutParameter} should be + * used when the parameter is of JDBC type {@code JDBCType.NUMERIC} + * or {@code JDBCType.DECIMAL}. + *<P> + * The default implementation will throw {@code SQLFeatureNotSupportedException} + * + * @param parameterName the name of the parameter + * @param sqlType the JDBC type code defined by {@code SQLType} to use to + * register the OUT Parameter. + * @param scale the desired number of digits to the right of the + * decimal point. It must be greater than or equal to zero. + * @exception SQLException if parameterName does not correspond to a named + * parameter; if a database access error occurs or + * this method is called on a closed {@code CallableStatement} + * @exception SQLFeatureNotSupportedException if + * the JDBC driver does not support this data type + * or if the JDBC driver does not support + * this method + * @since 1.8 + * @see JDBCType + * @see SQLType + */ + default void registerOutParameter(String parameterName, SQLType sqlType, + int scale) throws SQLException { + throw new SQLFeatureNotSupportedException("registerOutParameter not implemented"); + } + + /** + * Registers the designated output parameter. This version of + * the method {@code registrOutParameter} + * should be used for a user-named or REF output parameter. Examples + * of user-named types include: STRUCT, DISTINCT, JAVA_OBJECT, and + * named array types. + *<p> + * All OUT parameters must be registered + * before a stored procedure is executed. + * </p> + * For a user-named parameter the fully-qualified SQL + * type name of the parameter should also be given, while a REF + * parameter requires that the fully-qualified type name of the + * referenced type be given. A JDBC driver that does not need the + * type code and type name information may ignore it. To be portable, + * however, applications should always provide these values for + * user-named and REF parameters. + * + * Although it is intended for user-named and REF parameters, + * this method may be used to register a parameter of any JDBC type. + * If the parameter does not have a user-named or REF type, the + * typeName parameter is ignored. + * + * <P><B>Note:</B> When reading the value of an out parameter, you + * must use the {@code getXXX} method whose Java type XXX corresponds to the + * parameter's registered SQL type. + *<P> + * The default implementation will throw {@code SQLFeatureNotSupportedException} + * + * @param parameterName the name of the parameter + * @param sqlType the JDBC type code defined by {@code SQLType} to use to + * register the OUT Parameter. + * @param typeName the fully-qualified name of an SQL structured type + * @exception SQLException if parameterName does not correspond to a named + * parameter; if a database access error occurs or + * this method is called on a closed {@code CallableStatement} + * @exception SQLFeatureNotSupportedException if + * the JDBC driver does not support this data type + * or if the JDBC driver does not support this method + * @see JDBCType + * @see SQLType + * @since 1.8 + */ + default void registerOutParameter (String parameterName, SQLType sqlType, + String typeName) throws SQLException { + throw new SQLFeatureNotSupportedException("registerOutParameter not implemented"); + } } |