1071 

  1072     //--------------------------JDBC 4.2 -----------------------------

  1073 

  1074     /**

  1075      *  Retrieves the current result as an update count; if the result

  1076      * is a <code>ResultSet</code> object or there are no more results, -1

  1077      *  is returned. This method should be called only once per result.

  1078      * <p>

  1079      * This method should be used when the returned row count may exceed

  1080      * {@link Integer.MAX_VALUE}.

  1081      *<p>

  1082      * The default implementation will throw {@code UnsupportedOperationException}

  1083      *

  1084      * @return the current result as an update count; -1 if the current result

  1085      * is a <code>ResultSet</code> object or there are no more results

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

  1087      * this method is called on a closed <code>Statement</code>

  1088      * @see #execute

  1089      * @since 1.8

  1090      */

  1091     default long getLargeUpdateCount() throws SQLException {

  1092         throw new UnsupportedOperationException("getLargeUpdateCount not implemented");

  1093     }

  1094 

  1095     /**

  1096      * Sets the limit for the maximum number of rows that any

  1097      * <code>ResultSet</code> object  generated by this <code>Statement</code>

  1098      * object can contain to the given number.

  1099      * If the limit is exceeded, the excess

  1100      * rows are silently dropped.

  1101      * <p>

  1102      * This method should be used when the row limit may exceed

  1103      * {@link Integer.MAX_VALUE}.

  1104      *<p>

  1105      * The default implementation will throw {@code UnsupportedOperationException}

  1106      *

  1107      * @param max the new max rows limit; zero means there is no limit

  1108      * @exception SQLException if a database access error occurs,

  1109      * this method is called on a closed <code>Statement</code>

  1110      *            or the condition max >= 0 is not satisfied

  1111      * @see #getMaxRows

  1112      * @since 1.8

  1113      */

  1114     default void setLargeMaxRows(long max) throws SQLException {

  1115         throw new UnsupportedOperationException("setLargeMaxRows not implemented");

  1116     }

  1117 

  1118     /**

  1119      * Retrieves the maximum number of rows that a

  1120      * <code>ResultSet</code> object produced by this

  1121      * <code>Statement</code> object can contain.  If this limit is exceeded,

  1122      * the excess rows are silently dropped.

  1123      * <p>

  1124      * This method should be used when the returned row limit may exceed

  1125      * {@link Integer.MAX_VALUE}.

  1126      *<p>

  1127      * The default implementation will return {@code 0}

  1128      *

  1129      * @return the current maximum number of rows for a <code>ResultSet</code>

  1130      *         object produced by this <code>Statement</code> object;

  1131      *         zero means there is no limit

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

  1133      * this method is called on a closed <code>Statement</code>

  1134      * @see #setMaxRows

  1135      * @since 1.8

  1136      */

  1137     default long getLargeMaxRows() throws SQLException {

  1138         return 0;

  1139     }

  1140 

  1141     /**

  1142      * Submits a batch of commands to the database for execution and

  1143      * if all commands execute successfully, returns an array of update counts.

  1144      * The <code>long</code> elements of the array that is returned are ordered

  1145      * to correspond to the commands in the batch, which are ordered

  1146      * according to the order in which they were added to the batch.

  1147      * The elements in the array returned by the method {@code executeLargeBatch}

  1148      * may be one of the following:

  1149      * <OL>

  1150      * <LI>A number greater than or equal to zero -- indicates that the

  1151      * command was processed successfully and is an update count giving the

  1152      * number of rows in the database that were affected by the command's

  1153      * execution

  1154      * <LI>A value of <code>SUCCESS_NO_INFO</code> -- indicates that the command was

  1155      * processed successfully but that the number of rows affected is

  1156      * unknown

  1157      * <P>

  1158      * If one of the commands in a batch update fails to execute properly,

  1159      * this method throws a <code>BatchUpdateException</code>, and a JDBC

  1160      * driver may or may not continue to process the remaining commands in

  1161      * the batch.  However, the driver's behavior must be consistent with a

  1162      * particular DBMS, either always continuing to process commands or never

  1163      * continuing to process commands.  If the driver continues processing

  1164      * after a failure, the array returned by the method

  1165      * <code>BatchUpdateException.getLargeUpdateCounts</code>

  1166      * will contain as many elements as there are commands in the batch, and

  1167      * at least one of the elements will be the following:

  1168      * <P>

  1169      * <LI>A value of <code>EXECUTE_FAILED</code> -- indicates that the command failed

  1170      * to execute successfully and occurs only if a driver continues to

  1171      * process commands after a command fails

  1172      * </OL>

  1173      * <p>

  1174      * This method should be used when the returned row count may exceed

  1175      * {@link Integer.MAX_VALUE}.

  1176      *<p>

  1177      * The default implementation will throw {@code UnsupportedOperationException}

  1178      *

  1179      * @return an array of update counts containing one element for each

  1180      * command in the batch.  The elements of the array are ordered according

  1181      * to the order in which commands were added to the batch.

  1182      * @exception SQLException if a database access error occurs,

  1183      * this method is called on a closed <code>Statement</code> or the

  1184      * driver does not support batch statements. Throws {@link BatchUpdateException}

  1185      * (a subclass of <code>SQLException</code>) if one of the commands sent to the

  1186      * database fails to execute properly or attempts to return a result set.

  1187      * @throws SQLTimeoutException when the driver has determined that the

  1188      * timeout value that was specified by the {@code setQueryTimeout}

  1189      * method has been exceeded and has at least attempted to cancel

  1190      * the currently running {@code Statement}

  1191      *

  1192      * @see #addBatch

  1193      * @see DatabaseMetaData#supportsBatchUpdates

  1194      * @since 1.8

  1195      */

  1196     default long[] executeLargeBatch() throws SQLException {

  1197         throw new UnsupportedOperationException("executeLargeBatch not implemented");

  1198     }

  1199 

  1200     /**

  1201      * Executes the given SQL statement, which may be an <code>INSERT</code>,

  1202      * <code>UPDATE</code>, or <code>DELETE</code> statement or an

  1203      * SQL statement that returns nothing, such as an SQL DDL statement.

  1204      * <p>

  1205      * This method should be used when the returned row count may exceed

  1206      * {@link Integer.MAX_VALUE}.

  1207      * <p>

  1208      * <strong>Note:</strong>This method cannot be called on a

  1209      * <code>PreparedStatement</code> or <code>CallableStatement</code>.

  1210      *<p>

  1211      * The default implementation will throw {@code UnsupportedOperationException}

  1212      *

  1213      * @param sql an SQL Data Manipulation Language (DML) statement,

  1214      * such as <code>INSERT</code>, <code>UPDATE</code> or

  1215      * <code>DELETE</code>; or an SQL statement that returns nothing,

  1216      * such as a DDL statement.

  1217      *

  1218      * @return either (1) the row count for SQL Data Manipulation Language

  1219      * (DML) statements or (2) 0 for SQL statements that return nothing

  1220      *

  1221      * @exception SQLException if a database access error occurs,

  1222      * this method is called on a closed <code>Statement</code>, the given

  1223      * SQL statement produces a <code>ResultSet</code> object, the method is called on a

  1224      * <code>PreparedStatement</code> or <code>CallableStatement</code>

  1225      * @throws SQLTimeoutException when the driver has determined that the

  1226      * timeout value that was specified by the {@code setQueryTimeout}

  1227      * method has been exceeded and has at least attempted to cancel

  1228      * the currently running {@code Statement}

  1229      * @since 1.8

  1230      */

  1231     default long executeLargeUpdate(String sql) throws SQLException {

  1232         throw new UnsupportedOperationException("executeLargeUpdate not implemented");

  1233     }

  1234 

  1235     /**

  1236      * Executes the given SQL statement and signals the driver with the

  1237      * given flag about whether the

  1238      * auto-generated keys produced by this <code>Statement</code> object

  1239      * should be made available for retrieval.  The driver will ignore the

  1240      * flag if the SQL statement

  1241      * is not an <code>INSERT</code> statement, or an SQL statement able to return

  1242      * auto-generated keys (the list of such statements is vendor-specific).

  1243      * <p>

  1244      * This method should be used when the returned row count may exceed

  1245      * {@link Integer.MAX_VALUE}.

  1246      * <p>

  1247      * <strong>Note:</strong>This method cannot be called on a

  1248      * <code>PreparedStatement</code> or <code>CallableStatement</code>.

  1249      *<p>

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

  1251      *

  1252      * @param sql an SQL Data Manipulation Language (DML) statement,

  1253      * such as <code>INSERT</code>, <code>UPDATE</code> or

  1254      * <code>DELETE</code>; or an SQL statement that returns nothing,

  1255      * such as a DDL statement.

  1256      *

  1257      * @param autoGeneratedKeys a flag indicating whether auto-generated keys

  1258      *        should be made available for retrieval;

  1259      *         one of the following constants:

  1260      *         <code>Statement.RETURN_GENERATED_KEYS</code>

  1261      *         <code>Statement.NO_GENERATED_KEYS</code>

  1262      * @return either (1) the row count for SQL Data Manipulation Language (DML) statements

  1263      *         or (2) 0 for SQL statements that return nothing

  1264      *

  1265      * @exception SQLException if a database access error occurs,

  1266      *  this method is called on a closed <code>Statement</code>, the given

  1267      *            SQL statement returns a <code>ResultSet</code> object,

  1268      *            the given constant is not one of those allowed, the method is called on a

  1269      * <code>PreparedStatement</code> or <code>CallableStatement</code>

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

  1271      * this method with a constant of Statement.RETURN_GENERATED_KEYS

  1272      * @throws SQLTimeoutException when the driver has determined that the

  1273      * timeout value that was specified by the {@code setQueryTimeout}

  1274      * method has been exceeded and has at least attempted to cancel

  1275      * the currently running {@code Statement}

  1276      * @since 1.8

  1277      */

  1278     default long executeLargeUpdate(String sql, int autoGeneratedKeys)

  1279             throws SQLException {

  1280         throw new SQLFeatureNotSupportedException("executeLargeUpdate not implemented");

  1281     }

  1282 

  1283     /**

  1284      * Executes the given SQL statement and signals the driver that the

  1285      * auto-generated keys indicated in the given array should be made available

  1286      * for retrieval.   This array contains the indexes of the columns in the

  1287      * target table that contain the auto-generated keys that should be made

  1288      * available. The driver will ignore the array if the SQL statement

  1289      * is not an <code>INSERT</code> statement, or an SQL statement able to return

  1290      * auto-generated keys (the list of such statements is vendor-specific).

  1291      * <p>

  1292      * This method should be used when the returned row count may exceed

  1293      * {@link Integer.MAX_VALUE}.

  1294      * <p>

  1295      * <strong>Note:</strong>This method cannot be called on a

  1296      * <code>PreparedStatement</code> or <code>CallableStatement</code>.

  1297      *<p>

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

  1299      *

  1300      * @param sql an SQL Data Manipulation Language (DML) statement,

  1301      * such as <code>INSERT</code>, <code>UPDATE</code> or

  1302      * <code>DELETE</code>; or an SQL statement that returns nothing,

  1303      * such as a DDL statement.

  1304      *

  1305      * @param columnIndexes an array of column indexes indicating the columns

  1306      *        that should be returned from the inserted row

  1307      * @return either (1) the row count for SQL Data Manipulation Language (DML) statements

  1308      *         or (2) 0 for SQL statements that return nothing

  1309      *

  1310      * @exception SQLException if a database access error occurs,

  1311      * this method is called on a closed <code>Statement</code>, the SQL

  1312      * statement returns a <code>ResultSet</code> object,the second argument

  1313      * supplied to this method is not an

  1314      * <code>int</code> array whose elements are valid column indexes, the method is called on a

  1315      * <code>PreparedStatement</code> or <code>CallableStatement</code>

  1316      * @throws SQLFeatureNotSupportedException  if the JDBC driver does not support this method

  1317      * @throws SQLTimeoutException when the driver has determined that the

  1318      * timeout value that was specified by the {@code setQueryTimeout}

  1319      * method has been exceeded and has at least attempted to cancel

  1320      * the currently running {@code Statement}

  1321      * @since 1.8

  1322      */

  1323     default long executeLargeUpdate(String sql, int columnIndexes[]) throws SQLException {

  1324         throw new SQLFeatureNotSupportedException("executeLargeUpdate not implemented");

  1325     }

  1326 

  1327     /**

  1328      * Executes the given SQL statement and signals the driver that the

  1329      * auto-generated keys indicated in the given array should be made available

  1330      * for retrieval.   This array contains the names of the columns in the

  1331      * target table that contain the auto-generated keys that should be made

  1332      * available. The driver will ignore the array if the SQL statement

  1333      * is not an <code>INSERT</code> statement, or an SQL statement able to return

  1334      * auto-generated keys (the list of such statements is vendor-specific).

  1335      * <p>

  1336      * This method should be used when the returned row count may exceed

  1337      * {@link Integer.MAX_VALUE}.

  1338      * <p>

  1339      * <strong>Note:</strong>This method cannot be called on a

  1340      * <code>PreparedStatement</code> or <code>CallableStatement</code>.

  1341      *<p>

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

  1343      *

  1344      * @param sql an SQL Data Manipulation Language (DML) statement,

  1345      * such as <code>INSERT</code>, <code>UPDATE</code> or

  1346      * <code>DELETE</code>; or an SQL statement that returns nothing,

  1347      * such as a DDL statement.

  1348      * @param columnNames an array of the names of the columns that should be

  1349      *        returned from the inserted row

  1350      * @return either the row count for <code>INSERT</code>, <code>UPDATE</code>,

  1351      *         or <code>DELETE</code> statements, or 0 for SQL statements

  1352      *         that return nothing

  1353      * @exception SQLException if a database access error occurs,

  1354      *  this method is called on a closed <code>Statement</code>, the SQL

  1355      *            statement returns a <code>ResultSet</code> object, the

  1356      *            second argument supplied to this method is not a <code>String</code> array

  1357      *            whose elements are valid column names, the method is called on a

  1358      * <code>PreparedStatement</code> or <code>CallableStatement</code>

  1359      * @throws SQLFeatureNotSupportedException  if the JDBC driver does not support this method

  1360      * @throws SQLTimeoutException when the driver has determined that the

  1361      * timeout value that was specified by the {@code setQueryTimeout}

  1362      * method has been exceeded and has at least attempted to cancel

  1363      * the currently running {@code Statement}

  1364      * @since 1.8

  1365      */

  1366     default long executeLargeUpdate(String sql, String columnNames[])

  1367             throws SQLException {

  1368         throw new SQLFeatureNotSupportedException("executeLargeUpdate not implemented");

  1369     }

  1371