You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@harmony.apache.org by te...@apache.org on 2009/04/30 11:45:42 UTC
svn commit: r770130 [8/10] - in
/harmony/enhanced/classlib/trunk/modules/sql/src/main/java: java/sql/
javax/sql/
Modified: harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/Statement.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/Statement.java?rev=770130&r1=770129&r2=770130&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/Statement.java (original)
+++ harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/Statement.java Thu Apr 30 09:45:40 2009
@@ -18,29 +18,33 @@
package java.sql;
/**
- * Interface used for executing static SQL statements and returning their
- * results.
- *
- * By default, an object implementing the Statement interface can returns
- * results as ResultSets. For any given Statement object, only one ResultSet can
- * be open at one time. A call to any of the execution methods of Statement will
- * cause any previously created ResultSet object for that Statement to be closed
- * implicitly.
+ * Interface used for executing static SQL statements to retrieve query results.
+ * The resulting table rows are returned as {@code ResultSet}s. For any given
+ * {@code Statement} object, only one {@code ResultSet} can be opened at one
+ * time. A call to any of the execution methods of {@code Statement} will cause
+ * any previously created {@code ResultSet} object for that {@code Statement} to
+ * be closed implicitly.
* <p>
- * To have multiple ResultSet objects open concurrently, multiple Statement
- * objects must be used.
+ * To have multiple {@code ResultSet} objects opened concurrently, multiple
+ * {@code Statement} objects must be created and then executed.
+ * <p>
+ * To obtain such an executable statement one needs to invoke {@code
+ * Connection#createStatement}.
+ *
+ * @see ResultSet
+ * @see Connection#createStatement
*/
public interface Statement {
/**
- * Passing this constant to getMoreResults implies that all ResultSet
- * objects previously kept open should be closed.
+ * Passing this constant to {@link #getMoreResults} implies that all {@code
+ * ResultSet} objects previously kept open should be closed.
*/
public static final int CLOSE_ALL_RESULTS = 3;
/**
- * Passing this constant to getMoreResults implies that the current
- * ResultSet object should be closed
+ * Passing this constant to {@link #getMoreResults} implies that the current
+ * {@code ResultSet} object should be closed.
*/
public static final int CLOSE_CURRENT_RESULT = 1;
@@ -51,8 +55,8 @@
public static final int EXECUTE_FAILED = -3;
/**
- * Passing this constant to getMoreResults implies that the current
- * ResultSet object should not be closed.
+ * Passing this constant to <i>getMoreResults</i> implies that the current
+ * {@code ResultSet} object should not be closed.
*/
public static final int KEEP_CURRENT_RESULT = 2;
@@ -73,143 +77,149 @@
public static final int SUCCESS_NO_INFO = -2;
/**
- * Adds a specified SQL commands to the list of commands for this Statement.
+ * Adds a specified SQL command to the list of commands for this {@code
+ * Statement}.
* <p>
- * The list of commands is executed by invoking the
- * <code>executeBatch</code> method.
- *
+ * The list of commands is executed by invoking the {@code executeBatch}
+ * method.
+ *
* @param sql
- * the SQL command as a String. Typically an INSERT or UPDATE
- * statement.
+ * the SQL command as a String. Typically an {@code INSERT} or
+ * {@code UPDATE} statement.
* @throws SQLException
* if an error occurs accessing the database or the database
- * does not support batch updates
+ * does not support batch updates.
*/
public void addBatch(String sql) throws SQLException;
/**
- * Cancels this Statement execution if both the database and the JDBC driver
- * support aborting an SQL statement in flight. This method can be used by
- * one thread to stop a Statement that is being executed on another thread.
+ * Cancels this statement's execution if both the database and the JDBC
+ * driver support aborting an SQL statement in flight. This method can be
+ * used by one thread to stop a statement that is executed on another
+ * thread.
*
* @throws SQLException
- * if an error occurs accessing the database
+ * if an error occurs accessing the database.
*/
public void cancel() throws SQLException;
/**
- * Clears the current list of SQL commands for this Statement.
+ * Clears the current list of SQL commands for this statement.
*
* @throws SQLException
* if an error occurs accessing the database or the database
- * does not support batch updates
+ * does not support batch updates.
*/
public void clearBatch() throws SQLException;
/**
- * Clears all SQLWarnings from this Statement.
+ * Clears all {@code SQLWarnings} from this statement.
*
* @throws SQLException
- * if an error occurs accessing the database
+ * if an error occurs accessing the database.
*/
public void clearWarnings() throws SQLException;
/**
- * Releases this Statement's database and JDBC driver resources.
+ * Releases this statement's database and JDBC driver resources.
* <p>
* Using this method to release these resources as soon as possible is
- * strongly recommended. It is not a good idea to rely on these resources
- * being released when the Statement object is finalized during garbage
- * collection. Doing so can result in unpredictable performance
- * characteristics for the application.
- *
+ * strongly recommended.
+ * <p>
+ * One should not rely on the resources being automatically released when
+ * finalized during garbage collection. Doing so can result in unpredictable
+ * behavior for the application.
+ *
* @throws SQLException
- * if an error occurs accessing the database
+ * if an error occurs accessing the database.
*/
public void close() throws SQLException;
/**
- * Executes a supplied SQL statement. This may return multiple ResultSets.
+ * Executes a supplied SQL statement. This may return multiple {@code
+ * ResultSet}s.
* <p>
- * Use the <code>getResultSet</code> or <code>getUpdateCount</code>
- * methods to get the first result and <code>getMoreResults</code> to get
- * any subsequent results.
- *
+ * Use the {@code getResultSet} or {@code getUpdateCount} methods to get the
+ * first result and {@code getMoreResults} to get any subsequent results.
+ *
* @param sql
* the SQL statement to execute
- * @return true if the first result is a ResultSet, false if the first
- * result is an update count or if there is no result
+ * @return {@code true} if the first result is a {@code ResultSet}, {@code
+ * false} if the first result is an update count or if there is no
+ * result.
* @throws SQLException
- * if an error occurs accessing the database
+ * if an error occurs accessing the database.
*/
public boolean execute(String sql) throws SQLException;
/**
- * Executes a supplied SQL statement. This may return multiple ResultSets.
- * This method allows control of whether auto-generated Keys should be made
- * available for retrieval, if the SQL statement is an INSERT statement.
- * <p>
- * Use the <code>getResultSet</code> or <code>getUpdateCount</code>
- * methods to get the first result and <code>getMoreResults</code> to get
- * any subsequent results.
- *
+ * Executes a supplied SQL statement. This may return multiple {@code
+ * ResultSet}s. This method allows control of whether auto-generated Keys
+ * should be made available for retrieval, if the SQL statement is an
+ * {@code INSERT} statement.
+ * <p>
+ * Use the {@code getResultSet} or {@code getUpdateCount} methods to get the
+ * first result and {@code getMoreResults} to get any subsequent results.
+ *
* @param sql
- * the SQL statement to execute
+ * the SQL statement to execute.
* @param autoGeneratedKeys
* a flag indicating whether to make auto generated keys
- * available for retrieval. This parameter must be one of
- * Statement.NO_GENERATED_KEYS or Statement.RETURN_GENERATED_KEYS
- * @return true if results exists and the first result is a ResultSet, false
- * if the first result is an update count or if there is no result
+ * available for retrieval. This parameter must be one of {@code
+ * Statement.NO_GENERATED_KEYS} or {@code
+ * Statement.RETURN_GENERATED_KEYS}.
+ * @return {@code true} if results exists and the first result is a {@code
+ * ResultSet}, {@code false} if the first result is an update count
+ * or if there is no result.
* @throws SQLException
- * if an error occurs accessing the database
+ * if an error occurs accessing the database.
*/
public boolean execute(String sql, int autoGeneratedKeys)
throws SQLException;
/**
- * Executes the supplied SQL statement. This may return multiple ResultSets.
- * This method allows retrieval of auto generated keys specified by the
- * supplied array of column indexes, if the SQL statement is an INSERT
- * statement.
- * <p>
- * Use the <code>getResultSet</code> or <code>getUpdateCount</code>
- * methods to get the first result and <code>getMoreResults</code> to get
- * any subsequent results.
- *
+ * Executes the supplied SQL statement. This may return multiple {@code
+ * ResultSet}s. This method allows retrieval of auto generated keys
+ * specified by the supplied array of column indexes, if the SQL statement
+ * is an {@code INSERT} statement.
+ * <p>
+ * Use the {@code getResultSet} or {@code getUpdateCount} methods to get the
+ * first result and {@code getMoreResults} to get any subsequent results.
+ *
* @param sql
- * the SQL statement to execute
+ * the SQL statement to execute.
* @param columnIndexes
* an array of indexes of the columns in the inserted row which
- * should be made available for retrieval via the
- * <code>getGeneratedKeys</code> method.
- * @return true if the first result is a ResultSet, false if the first
- * result is an update count or if there is no result
+ * should be made available for retrieval via the {@code
+ * getGeneratedKeys} method.
+ * @return {@code true} if the first result is a {@code ResultSet}, {@code
+ * false} if the first result is an update count or if there is no
+ * result.
* @throws SQLException
- * if an error occurs accessing the database
+ * if an error occurs accessing the database.
*/
public boolean execute(String sql, int[] columnIndexes) throws SQLException;
/**
- * Executes the supplied SQL statement. This may return multiple ResultSets.
- * This method allows retrieval of auto generated keys specified by the
- * supplied array of column indexes, if the SQL statement is an INSERT
- * statement.
- * <p>
- * Use the <code>getResultSet</code> or <code>getUpdateCount</code>
- * methods to get the first result and <code>getMoreResults</code> to get
- * any subsequent results.
- *
+ * Executes the supplied SQL statement. This may return multiple {@code
+ * ResultSet}s. This method allows retrieval of auto generated keys
+ * specified by the supplied array of column indexes, if the SQL statement
+ * is an {@code INSERT} statement.
+ * <p>
+ * Use the {@code getResultSet} or {@code getUpdateCount} methods to get the
+ * first result and {@code getMoreResults} to get any subsequent results.
+ *
* @param sql
- * the SQL statement to execute
+ * the SQL statement to execute.
* @param columnNames
* an array of column names in the inserted row which should be
- * made available for retrieval via the
- * <code>getGeneratedKeys</code> method.
- * @return true if the first result is a ResultSet, false if the first
- * result is an update count or if there is no result
+ * made available for retrieval via the {@code getGeneratedKeys}
+ * method.
+ * @return {@code true} if the first result is a {@code ResultSet}, {@code
+ * false} if the first result is an update count or if there is no
+ * result
* @throws SQLException
- * if an error occurs accessing the database
+ * if an error occurs accessing the database.
*/
public boolean execute(String sql, String[] columnNames)
throws SQLException;
@@ -219,57 +229,60 @@
* update counts, if all the commands execute successfully.
* <p>
* If one of the commands in the batch fails, this method can throw a
- * BatchUpdateException and the JDBC driver may or may not process the
- * remaining commands. The JDBC driver must behave consistently with the
- * underlying database, either always continuing or never continuing. If the
+ * {@link BatchUpdateException} and the JDBC driver may or may not process
+ * the remaining commands. The JDBC driver must behave consistently with the
+ * underlying database, following the "all or nothing" principle. If the
* driver continues processing, the array of results returned contains the
* same number of elements as there are commands in the batch, with a
- * minimum of one of the elements having the EXECUTE_FAILED value.
+ * minimum of one of the elements having the {@code EXECUTE_FAILED} value.
*
* @return an array of update counts, with one entry for each command in the
* batch. The elements are ordered according to the order in which
* the commands were added to the batch.
* <p>
* <ol>
- * <li> If the value of an element is >=0, the corresponding command
- * completed successfully and the value is the update count for that
- * command, which is the number of rows in the database affected by
- * the command.</li>
- * <li> If the value is SUCCESS_NO_INFO, the command completed
- * successfully but the number of rows affected is unknown.
+ * <li>If the value of an element is ≥ 0, the corresponding
+ * command completed successfully and the value is the <i>update
+ * count</i> (the number of rows in the database affected by the
+ * command) for that command.</li>
+ * <li>If the value is {@code SUCCESS_NO_INFO}, the command
+ * completed successfully but the number of rows affected is
+ * unknown.
* <li>
- * <li> If the value is EXECUTE_FAILED, the command failed.
+ * <li>If the value is {@code EXECUTE_FAILED}, the command failed.
* </ol>
* @throws SQLException
- * if an error occurs accessing the database
+ * if an error occurs accessing the database.
*/
public int[] executeBatch() throws SQLException;
/**
- * Executes a supplied SQL statement. Returns a single ResultSet.
+ * Executes a supplied SQL statement. Returns a single {@code ResultSet}.
*
* @param sql
- * an SQL statement to execute. Typically a SELECT statement
- * @return a ResultSet containing the data produced by the SQL statement.
- * Never null.
+ * an SQL statement to execute. Typically a {@code SELECT}
+ * statement
+ * @return a {@code ResultSet} containing the data produced by the SQL
+ * statement. Never null.
* @throws SQLException
* if an error occurs accessing the database or if the statement
- * produces anything other than a single ResultSet
+ * produces anything other than a single {@code ResultSet}.
*/
public ResultSet executeQuery(String sql) throws SQLException;
/**
- * Executes the supplied SQL statement. The statement may be an INSERT,
- * UPDATE or DELETE statement or a statement which returns nothing.
+ * Executes the supplied SQL statement. The statement may be an {@code
+ * INSERT}, {@code UPDATE} or {@code DELETE} statement or a statement which
+ * returns nothing.
*
* @param sql
- * an SQL statement to execute - an SQL INSERT, UPDATE, DELETE or
- * a statement which returns nothing
+ * an SQL statement to execute - an SQL {@code INSERT}, {@code
+ * UPDATE}, {@code DELETE} or a statement which returns nothing
* @return the count of updated rows, or 0 for a statement that returns
* nothing.
* @throws SQLException
* if an error occurs accessing the database or if the statement
- * produces a ResultSet
+ * produces a {@code ResultSet}.
*/
public int executeUpdate(String sql) throws SQLException;
@@ -278,17 +291,19 @@
* whether auto-generated Keys should be made available for retrieval.
*
* @param sql
- * an SQL statement to execute - an SQL INSERT, UPDATE, DELETE or
- * a statement which does not return anything.
+ * an SQL statement to execute - an SQL {@code INSERT}, {@code
+ * UPDATE}, {@code DELETE} or a statement which does not return
+ * anything.
* @param autoGeneratedKeys
* a flag that indicates whether to allow retrieval of auto
- * generated keys. Parameter must be one of
- * Statement.RETURN_GENERATED_KEYS or Statement.NO_GENERATED_KEYS
+ * generated keys. Parameter must be one of {@code
+ * Statement.RETURN_GENERATED_KEYS} or {@code
+ * Statement.NO_GENERATED_KEYS}
* @return the number of updated rows, or 0 if the statement returns
* nothing.
* @throws SQLException
* if an error occurs accessing the database or if the statement
- * produces a ResultSet
+ * produces a {@code ResultSet}.
*/
public int executeUpdate(String sql, int autoGeneratedKeys)
throws SQLException;
@@ -298,17 +313,17 @@
* generated keys specified by the supplied array of column indexes.
*
* @param sql
- * an SQL statement to execute - an SQL INSERT, UPDATE, DELETE or
- * a statement which returns nothing
+ * an SQL statement to execute - an SQL {@code INSERT}, {@code
+ * UPDATE}, {@code DELETE} or a statement which returns nothing
* @param columnIndexes
* an array of indexes of the columns in the inserted row which
- * should be made available for retrieval via the
- * <code>getGeneratedKeys</code> method.
+ * should be made available for retrieval via the {@code
+ * getGeneratedKeys} method.
* @return the count of updated rows, or 0 for a statement that returns
* nothing.
* @throws SQLException
* if an error occurs accessing the database or if the statement
- * produces a ResultSet
+ * produces a {@code ResultSet}.
*/
public int executeUpdate(String sql, int[] columnIndexes)
throws SQLException;
@@ -318,219 +333,231 @@
* generated keys specified by the supplied array of column names.
*
* @param sql
- * an SQL statement to execute - an SQL INSERT, UPDATE, DELETE or
- * a statement which returns nothing
+ * an SQL statement to execute - an SQL {@code INSERT}, {@code
+ * UPDATE}, {@code DELETE} or a statement which returns nothing
* @param columnNames
* an array of column names in the inserted row which should be
- * made available for retrieval via the
- * <code>getGeneratedKeys</code> method.
+ * made available for retrieval via the {@code getGeneratedKeys}
+ * method.
* @return the count of updated rows, or 0 for a statement that returns
* nothing.
* @throws SQLException
* if an error occurs accessing the database or if the statement
- * produces a ResultSet
+ * produces a {@code ResultSet}.
*/
public int executeUpdate(String sql, String[] columnNames)
throws SQLException;
/**
- * Gets the Connection that produced this Statement.
+ * Gets the {@code Connection} object which created this statement.
*
- * @return the Connection
+ * @return the {@code Connection} through which this statement is
+ * transmitted to the database.
* @throws SQLException
- * if an error occurs accessing the database
+ * if an error occurs accessing the database.
*/
public Connection getConnection() throws SQLException;
/**
- * Gets the default direction for fetching rows for ResultSets generated
- * from this Statement.
+ * Gets the default direction for fetching rows for {@code ResultSet}s
+ * generated from this statement.
*
- * @return an integer describing the default fetch direction, one of:
- * ResultSet.FETCH_FORWARD, ResultSet.FETCH_REVERSE,
- * ResultSet.FETCH_UNKNOWN
+ * @return the default fetch direction, one of:
+ * <ul>
+ * <li>ResultSet.FETCH_FORWARD</li> <li>ResultSet.FETCH_REVERSE</li>
+ * <li>ResultSet.FETCH_UNKNOWN</li>
+ * </ul>
* @throws SQLException
- * if an error occurs accessing the database
+ * if an error occurs accessing the database.
*/
public int getFetchDirection() throws SQLException;
/**
- * Gets the default number of rows for a fetch for the ResultSet objects
- * returned from this Statement.
+ * Gets the default number of rows for a fetch for the {@code ResultSet}
+ * objects returned from this statement.
*
- * @return the default fetch size for ResultSets produced by this Statement
+ * @return the default fetch size for {@code ResultSet}s produced by this
+ * statement.
* @throws SQLException
- * if an error occurs accessing the database
+ * if an error occurs accessing the database.
*/
public int getFetchSize() throws SQLException;
/**
- * Returns auto generated keys created by executing this Statement.
+ * Returns auto generated keys created by executing this statement.
*
- * @return a ResultSet containing the auto generated keys - empty if no keys
- * were generated by the Statement
+ * @return a {@code ResultSet} containing the auto generated keys - empty if
+ * no keys are generated by this statement.
* @throws SQLException
- * if an error occurs accessing the database
+ * if an error occurs accessing the database.
*/
public ResultSet getGeneratedKeys() throws SQLException;
/**
- * Gets the maximum number of bytes which can be returned for values from
- * Character and Binary values in a ResultSet derived from this Statement.
- * This limit applies to BINARY, VARBINARY, LONGVARBINARY, CHAR, VARCHAR,
- * and LONGVARCHAR types. Any data exceeding the maximum size is abandoned
+ * Gets the maximum number of bytes which can be returned as values from
+ * character and binary type columns in a {@code ResultSet} derived from this
+ * statement. This limit applies to {@code BINARY}, {@code VARBINARY},
+ * {@code LONGVARBINARY}, {@code CHAR}, {@code VARCHAR}, and {@code
+ * LONGVARCHAR} types. Any data exceeding the maximum size is abandoned
* without announcement.
*
- * @return the current size limit, where 0 means that there is no limit
+ * @return the current size limit, where {@code 0} means that there is no
+ * limit.
* @throws SQLException
- * if an error occurs accessing the database
+ * if an error occurs accessing the database.
*/
public int getMaxFieldSize() throws SQLException;
/**
- * Gets the maximum number of rows that a ResultSet can contain when
- * produced from this Statement. If the limit is exceeded, the excess rows
+ * Gets the maximum number of rows that a {@code ResultSet} can contain when
+ * produced from this statement. If the limit is exceeded, the excess rows
* are discarded silently.
*
- * @return the current row limit, where 0 means that there is no limit.
+ * @return the current row limit, where {@code 0} means that there is no
+ * limit.
* @throws SQLException
- * if an error occurs accessing the database
+ * if an error occurs accessing the database.
*/
public int getMaxRows() throws SQLException;
/**
- * Moves to this Statement's next result. Returns true if it is a ResultSet.
- * Any current ResultSet objects previously obtained with
- * <code>getResultSet()</code> are closed implicitly.
- *
- * @return true if the next result is a ResultSet, false if the next result
- * is not a ResultSet or if there are no more results. Note that if
- * there is no more data, this method will return false and
- * <code>getUpdateCount</code> will return -1.
+ * Moves to this statement's next result. Returns {@code true} if it is a
+ * {@code ResultSet}. Any current {@code ResultSet} objects previously
+ * obtained with {@code getResultSet()} are closed implicitly.
+ *
+ * @return {@code true} if the next result is a {@code ResultSet}, {@code
+ * false} if the next result is not a {@code ResultSet} or if there
+ * are no more results. Note that if there is no more data, this
+ * method will return {@code false} and {@code getUpdateCount} will
+ * return -1.
* @throws SQLException
- * if an error occurs accessing the database
+ * if an error occurs accessing the database.
*/
public boolean getMoreResults() throws SQLException;
/**
- * Moves to this Statement's next result. Returns true if the next result is
- * a ResultSet. Any current ResultSet objects previously obtained with
- * <code>getResultSet()</code> are handled as indicated by a supplied Flag
- * parameter.
+ * Moves to this statement's next result. Returns {@code true} if the next
+ * result is a {@code ResultSet}. Any current {@code ResultSet} objects
+ * previously obtained with {@code getResultSet()} are handled as indicated
+ * by a supplied Flag parameter.
*
* @param current
- * a flag indicating what to do with existing ResultSets. This
- * parameter must be one of Statement.CLOSE_ALL_RESULTS,
- * Statement.CLOSE_CURRENT_RESULT or
- * Statement.KEEP_CURRENT_RESULT.
- * @return true if the next result exists and is a ResultSet, false if the
- * next result is not a ResultSet or if there are no more results.
- * Note that if there is no more data, this method will return false
- * and <code>getUpdateCount</code> will return -1.
+ * a flag indicating what to do with existing {@code ResultSet}s.
+ * This parameter must be one of {@code
+ * Statement.CLOSE_ALL_RESULTS}, {@code
+ * Statement.CLOSE_CURRENT_RESULT} or {@code
+ * Statement.KEEP_CURRENT_RESULT}.
+ * @return {@code true} if the next result exists and is a {@code ResultSet}
+ * , {@code false} if the next result is not a {@code ResultSet} or
+ * if there are no more results. Note that if there is no more data,
+ * this method will return {@code false} and {@code getUpdateCount}
+ * will return -1.
* @throws SQLException
- * if an error occurs accessing the database
+ * if an error occurs accessing the database.
*/
public boolean getMoreResults(int current) throws SQLException;
/**
- * Gets the timeout value for Statement execution. The JDBC driver will wait
- * up to this value for the execution to complete - after the limit is
- * exceeded an SQL Exception is thrown.
+ * Gets the timeout value for the statement's execution time. The JDBC
+ * driver will wait up to this value for the execution to complete - after
+ * the limit is exceeded an SQL {@code Exception} is thrown.
*
- * @return the current Query Timeout value, where 0 indicates that there is
- * no current timeout.
+ * @return the current query timeout value, where {@code 0} indicates that
+ * there is no current timeout.
* @throws SQLException
- * if an error occurs accessing the database
+ * if an error occurs accessing the database.
*/
public int getQueryTimeout() throws SQLException;
/**
* Gets the current result. Should only be called once per result.
*
- * @return the ResultSet for the current result. null if the result is an
- * update count or if there are no more results.
+ * @return the {@code ResultSet} for the current result. {@code null} if the
+ * result is an update count or if there are no more results.
* @throws SQLException
- * if an error occurs accessing the database
+ * if an error occurs accessing the database.
*/
public ResultSet getResultSet() throws SQLException;
/**
- * Gets the concurrency setting for ResultSet objects generated by this
- * Statement.
+ * Gets the concurrency setting for {@code ResultSet} objects generated by
+ * this statement.
*
- * @return ResultSet.CONCUR_READ_ONLY or ResultSet.CONCUR_UPDATABLE
+ * @return {@code ResultSet.CONCUR_READ_ONLY} or {@code
+ * ResultSet.CONCUR_UPDATABLE}.
* @throws SQLException
- * if an error occurs accessing the database
+ * if an error occurs accessing the database.
*/
public int getResultSetConcurrency() throws SQLException;
/**
- * Gets the cursor hold setting for ResultSet objects generated by this
- * Statement.
+ * Gets the cursor hold setting for {@code ResultSet} objects generated by
+ * this statement.
*
- * @return ResultSet.HOLD_CURSORS_OVER_COMMIT or
- * ResultSet.CLOSE_CURSORS_AT_COMMIT
+ * @return {@code ResultSet.HOLD_CURSORS_OVER_COMMIT} or {@code
+ * ResultSet.CLOSE_CURSORS_AT_COMMIT}
* @throws SQLException
- * if there is an error while accessing the database
+ * if there is an error while accessing the database.
*/
public int getResultSetHoldability() throws SQLException;
/**
- * Gets the ResultSet type setting for ResultSets derived from this
- * Statement.
+ * Gets the {@code ResultSet} type setting for {@code ResultSet}s derived
+ * from this statement.
*
- * @return ResultSet.TYPE_FORWARD_ONLY for a ResultSet where the cursor can
- * only move forward, ResultSet.TYPE_SCROLL_INSENSITIVE for a
- * ResultSet which is Scrollable but is not sensitive to changes
- * made by others, ResultSet.TYPE_SCROLL_SENSITIVE for a ResultSet
- * which is Scrollable but is sensitive to changes made by others
+ * @return {@code ResultSet.TYPE_FORWARD_ONLY} for a {@code ResultSet} where
+ * the cursor can only move forwards, {@code
+ * ResultSet.TYPE_SCROLL_INSENSITIVE} for a {@code ResultSet} which
+ * is scrollable but is not sensitive to changes made by others,
+ * {@code ResultSet.TYPE_SCROLL_SENSITIVE} for a {@code ResultSet}
+ * which is scrollable but is sensitive to changes made by others.
* @throws SQLException
- * if there is an error accessing the database
+ * if there is an error accessing the database.
*/
public int getResultSetType() throws SQLException;
/**
- * Gets an update count for the current result if it is not a ResultSet.
+ * Gets an update count for the current result if it is not a {@code
+ * ResultSet}.
*
- * @return the current result as an update count. -1 if the current result
- * is a ResultSet or if there are no more results
+ * @return the current result as an update count. {@code -1} if the current
+ * result is a {@code ResultSet} or if there are no more results.
* @throws SQLException
- * if an error occurs accessing the database
+ * if an error occurs accessing the database.
*/
public int getUpdateCount() throws SQLException;
/**
- * Retrieves the first SQLWarning reported by calls on this Statement.
- * <p>
- * If there are multiple warnings, subsequent warnings are chained to the
- * first one.
- * <p>
- * The chain or warnings is cleared each time the Statement is executed.
- * <p>
- * Warnings associated with reads from the ResultSet returned from executing
- * a Statement will be attached to the ResultSet, not the Statement object.
- *
+ * Retrieves the first {@code SQLWarning} reported by calls on this
+ * statement. If there are multiple warnings, subsequent warnings are
+ * chained to the first one. The chain of warnings is cleared each time the
+ * statement is executed.
+ * <p>
+ * Warnings associated with reads from the {@code ResultSet} returned from
+ * executing the statement will be attached to the {@code ResultSet}, not the
+ * statement object.
+ *
* @return an SQLWarning, null if there are no warnings
* @throws SQLException
- * if an error occurs accessing the database
+ * if an error occurs accessing the database.
*/
public SQLWarning getWarnings() throws SQLException;
/**
- * Sets the SQL cursor name. This name is used by subsequent Statement
+ * Sets the SQL cursor name. This name is used by subsequent statement
* execute methods.
* <p>
* Cursor names must be unique within one Connection.
* <p>
- * With the Cursor name set, it can then be utilized in SQL positioned
- * update or delete statements to determine the current row in a ResultSet
- * generated from this Statement. The positioned update or delete must be
- * done with a different Statement than this one.
- *
+ * With the cursor name set, it can then be used in SQL positioned
+ * update or delete statements to determine the current row in a {@code
+ * ResultSet} generated from this statement. The positioned update or delete
+ * must be done with a different statement than this one.
+ *
* @param name
- * the Cursor name as a String,
+ * the Cursor name as a string,
* @throws SQLException
- * if an error occurs accessing the database
+ * if an error occurs accessing the database.
*/
public void setCursorName(String name) throws SQLException;
@@ -539,28 +566,32 @@
* <p>
* If Escape Processing is on, the JDBC driver will do escape substitution
* on an SQL statement before sending it for execution. This does not apply
- * to PreparedStatements since they are processed when created, before this
- * method can be called.
- *
+ * to {@link PreparedStatement}s since they are processed when created,
+ * before this method can be called.
+ *
* @param enable
- * true to set escape processing mode on, false to turn it off.
+ * {@code true} to set escape processing mode <i>on</i>, {@code
+ * false} to turn it <i>off</i>.
* @throws SQLException
- * if an error occurs accessing the database
+ * if an error occurs accessing the database.
*/
public void setEscapeProcessing(boolean enable) throws SQLException;
/**
* Sets the fetch direction - a hint to the JDBC driver about the direction
- * of processing of rows in ResultSets created by this Statement. The
- * default fetch direction is FETCH_FORWARD.
+ * of processing of rows in {@code ResultSet}s created by this statement.
+ * The default fetch direction is {@code FETCH_FORWARD}.
*
* @param direction
* which fetch direction to use. This parameter should be one of
- * ResultSet.FETCH_UNKNOWN, ResultSet.FETCH_FORWARD or
- * ResultSet.FETCH_REVERSE
+ * <ul>
+ * <li>{@code ResultSet.FETCH_UNKNOWN}</li>
+ * <li>{@code ResultSet.FETCH_FORWARD}</li>
+ * <li>{@code ResultSet.FETCH_REVERSE}</li>
+ * </ul>
* @throws SQLException
* if there is an error while accessing the database or if the
- * fetch direction is unrecognized
+ * fetch direction is unrecognized.
*/
public void setFetchDirection(int direction) throws SQLException;
@@ -570,10 +601,9 @@
* application processing.
*
* @param rows
- * the number of rows that should be fetched. 0 tells the driver
- * to ignore the hint. Should be less than
- * <code>getMaxRows</code> for this statement. Should not be
- * negative.
+ * the number of rows that should be fetched. {@code 0} tells the driver
+ * to ignore the hint. Should be less than {@code getMaxRows} for
+ * this statement. Should not be negative.
* @throws SQLException
* if an error occurs accessing the database, or if the rows
* parameter is out of range.
@@ -581,40 +611,43 @@
public void setFetchSize(int rows) throws SQLException;
/**
- * Sets the maximum number of bytes for ResultSet columns that contain
- * character or binary values. This applies to BINARY, VARBINARY,
- * LONGVARBINARY, CHAR, VARCHAR, and LONGVARCHAR fields. Any data exceeding
- * the maximum size is abandoned without announcement.
+ * Sets the maximum number of bytes for {@code ResultSet} columns that
+ * contain character or binary values. This applies to {@code BINARY},
+ * {@code VARBINARY}, {@code LONGVARBINARY}, {@code CHAR}, {@code VARCHAR},
+ * and {@code LONGVARCHAR} fields. Any data exceeding the maximum size is
+ * abandoned without announcement.
*
* @param max
- * the maximum field size in bytes. O means "no limit".
+ * the maximum field size in bytes. {@code 0} means "no limit".
* @throws SQLException
- * if an error occurs accessing the database or the max value is
- * <0.
+ * if an error occurs accessing the database or the {@code max}
+ * value is < {@code 0}.
*/
public void setMaxFieldSize(int max) throws SQLException;
/**
- * Sets the maximum number of rows that any ResultSet can contain. If the
- * number of rows exceeds this value, the additional rows are silently
- * discarded.
+ * Sets the maximum number of rows that any {@code ResultSet} can contain.
+ * If the number of rows exceeds this value, the additional rows are
+ * silently discarded.
*
* @param max
- * the maximum number of rows. 0 means "no limit".
+ * the maximum number of rows. {@code 0} means "no limit".
* @throws SQLException
- * if an error occurs accessing the database or if max <0.
+ * if an error occurs accessing the database or if max < {@code
+ * 0}.
*/
public void setMaxRows(int max) throws SQLException;
/**
* Sets the timeout, in seconds, for queries - how long the driver will
- * allow for completion of a Statement execution. If the timeout is
- * exceeded, the query will throw an SQLException.
+ * allow for completion of a statement execution. If the timeout is
+ * exceeded, the query will throw an {@code SQLException}.
*
* @param seconds
* timeout in seconds. 0 means no timeout ("wait forever")
* @throws SQLException
- * if an error occurs accessing the database or if seconds <0.
+ * if an error occurs accessing the database or if seconds <
+ * {@code 0}.
*/
public void setQueryTimeout(int seconds) throws SQLException;
}
Modified: harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/Struct.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/Struct.java?rev=770130&r1=770129&r2=770130&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/Struct.java (original)
+++ harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/Struct.java Thu Apr 30 09:45:40 2009
@@ -20,46 +20,48 @@
import java.util.Map;
/**
- * An interface which provides facilities for mapping an SQL structured type to
- * Java. The Struct object has a value for each attribute of the SQL structured
- * type
+ * An interface which provides facilities for manipulating an SQL structured type
+ * as a Java object. The {@code Struct} object has a value for each attribute of the SQL structured
+ * type.
*/
public interface Struct {
/**
- * Gets the SQL Type name of the SQL structured type that this Struct
- * represents
+ * Gets the SQL Type name of the SQL structured type that this {@code
+ * Struct} represents.
*
- * @return the fully qualified name of SQL structured type
+ * @return the fully qualified name of SQL structured type.
* @throws SQLException
- * if a database error occurs
+ * if a database error occurs.
*/
public String getSQLTypeName() throws SQLException;
/**
* Gets the values of the attributes of this SQL structured type. This
- * method uses the type map associated with the Connection for customized
- * type mappings. Where there is no entry in the Type Map which matches the
- * this structured type, the JDBC driver uses the standard mapping.
+ * method uses the type map associated with the {@link Connection} for
+ * customized type mappings. Where there is no entry in the type mapping
+ * which matches this structured type, the JDBC driver uses the standard
+ * mapping.
*
- * @return an Object array containing the attributes, in order
+ * @return an {@code Object} array containing the ordered attributes.
* @throws SQLException
- * if a database error occurs
+ * if a database error occurs.
*/
public Object[] getAttributes() throws SQLException;
/**
* Gets the values of the attributes of this SQL structured type. This
- * method uses the supplied type map for customized type mappings. Where
- * there is no entry in the Type Map which matches the this structured type,
- * the JDBC driver uses the default mapping. The Connection type map is
- * never utilized by this method.
+ * method uses the supplied type mapping to determine how to map SQL types
+ * to their corresponding Java objects. In the
+ * case where there is no entry in the type mapping which matches this
+ * structured type, the JDBC driver uses the default mapping. The {@code
+ * Connection} type map is <i>never</i> utilized by this method.
*
* @param theMap
* a Map describing how SQL Type names are mapped to classes.
- * @return an Object array containing the attributes, in order
+ * @return an Object array containing the ordered attributes,.
* @throws SQLException
- * if a database error occurs
+ * if a database error occurs.
*/
public Object[] getAttributes(Map<String, Class<?>> theMap)
throws SQLException;
Modified: harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/Time.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/Time.java?rev=770130&r1=770129&r2=770130&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/Time.java (original)
+++ harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/Time.java Thu Apr 30 09:45:40 2009
@@ -20,31 +20,32 @@
import java.util.Date;
/**
- * Java representation of an SQL TIME value. Provides functions to aid
- * generation and interpretation of JDBC escape format for time values.
- *
+ * Java representation of an SQL {@code TIME} value. Provides utilities to
+ * format and parse the time's representation as a String in JDBC escape format.
*/
public class Time extends Date {
private static final long serialVersionUID = 8397324403548013681L;
/**
- * @deprecated Please use the constructor Time( long ) Constructs a Time
- * object using the supplied values for Hour, Minute and Second.
- * The Year, Month and Day elements of the Time object are set
- * to 1970, January, 1 reflecting the Epoch (Time in
- * milliseconds = 0).
- * <p>
- * Any attempt to access the Year, Month or Day elements of a
- * Time object will result in an IllegalArgumentException.
- * <p>
- * Result is undefined if any argument is out of bounds.
+ * Constructs a {@code Time} object using the supplied values for <i>Hour</i>,
+ * <i>Minute</i> and <i>Second</i>. The <i>Year</i>, <i>Month</i> and
+ * <i>Day</i> elements of the {@code Time} object are set to the date
+ * of the Epoch (January 1, 1970).
+ * <p>
+ * Any attempt to access the <i>Year</i>, <i>Month</i> or <i>Day</i>
+ * elements of a {@code Time} object will result in an {@code
+ * IllegalArgumentException}.
+ * <p>
+ * The result is undefined if any argument is out of bounds.
+ *
+ * @deprecated Please use the constructor {@link #Time(long)}.
* @param theHour
- * a value from 0 - 23
+ * a value in the range {@code [0,23]}.
* @param theMinute
- * a value from 0 - 59
+ * a value in the range {@code [0,59]}.
* @param theSecond
- * a value from 0 - 59
+ * a value in the range {@code [0,59]}.
*/
@SuppressWarnings("deprecation")
@Deprecated
@@ -53,22 +54,23 @@
}
/**
- * Constructs a Time object using a supplied time specified in milliseconds
+ * Constructs a {@code Time} object using a supplied time specified in
+ * milliseconds.
*
* @param theTime
- * a Time specified in milliseconds since the Epoch (January 1st
- * 1970, 00:00:00.000)
+ * a {@code Time} specified in milliseconds since the
+ * <i>Epoch</i> (January 1st 1970, 00:00:00.000).
*/
public Time(long theTime) {
super(theTime);
}
/**
- * @deprecated This method is deprecated and must not be used. An SQL Time
- * object does not have a Date component.
- * @return does not return
+ * @deprecated This method is deprecated and must not be used. An SQL
+ * {@code Time} object does not have a {@code Date} component.
+ * @return does not return anything.
* @throws IllegalArgumentException
- * if this method is called
+ * if this method is called.
*/
@SuppressWarnings("deprecation")
@Deprecated
@@ -78,11 +80,11 @@
}
/**
- * @deprecated This method is deprecated and must not be used. An SQL Time
- * object does not have a Day component.
- * @return does not return
+ * @deprecated This method is deprecated and must not be used. An SQL
+ * {@code Time} object does not have a <i>Day</i> component.
+ * @return does not return anything.
* @throws IllegalArgumentException
- * if this method is called
+ * if this method is called.
*/
@SuppressWarnings("deprecation")
@Deprecated
@@ -92,11 +94,11 @@
}
/**
- * @deprecated This method is deprecated and must not be used. An SQL Time
- * object does not have a Month component.
- * @return does not return
+ * @deprecated This method is deprecated and must not be used. An SQL
+ * {@code Time} object does not have a <i>Month</i> component.
+ * @return does not return anything.
* @throws IllegalArgumentException
- * if this method is called
+ * if this method is called.
*/
@SuppressWarnings("deprecation")
@Deprecated
@@ -106,11 +108,11 @@
}
/**
- * @deprecated This method is deprecated and must not be used. An SQL Time
- * object does not have a Year component.
- * @return does not return
+ * @deprecated This method is deprecated and must not be used. An SQL
+ * {@code Time} object does not have a <i>Year</i> component.
+ * @return does not return anything.
* @throws IllegalArgumentException
- * if this method is called
+ * if this method is called.
*/
@SuppressWarnings("deprecation")
@Deprecated
@@ -120,10 +122,10 @@
}
/**
- * @deprecated This method is deprecated and must not be used. An SQL Time
- * object does not have a Date component.
+ * @deprecated This method is deprecated and must not be used. An SQL
+ * {@code Time} object does not have a {@code Date} component.
* @throws IllegalArgumentException
- * if this method is called
+ * if this method is called.
*/
@SuppressWarnings("deprecation")
@Deprecated
@@ -133,10 +135,10 @@
}
/**
- * @deprecated This method is deprecated and must not be used. An SQL Time
- * object does not have a Month component.
+ * @deprecated This method is deprecated and must not be used. An SQL
+ * {@code Time} object does not have a <i>Month</i> component.
* @throws IllegalArgumentException
- * if this method is called
+ * if this method is called.
*/
@SuppressWarnings("deprecation")
@Deprecated
@@ -146,10 +148,10 @@
}
/**
- * @deprecated This method is deprecated and must not be used. An SQL Time
- * object does not have a Year component.
+ * @deprecated This method is deprecated and must not be used. An SQL
+ * {@code Time} object does not have a <i>Year</i> component.
* @throws IllegalArgumentException
- * if this method is called
+ * if this method is called.
*/
@SuppressWarnings("deprecation")
@Deprecated
@@ -159,12 +161,13 @@
}
/**
- * Sets the time for this Time object to the supplied milliseconds value.
+ * Sets the time for this {@code Time} object to the supplied milliseconds
+ * value.
*
* @param time
- * A time value expressed as milliseconds since the Epoch.
+ * A time value expressed as milliseconds since the <i>Epoch</i>.
* Negative values are milliseconds before the Epoch. The Epoch
- * is January 1 1970, 00:00:00.000
+ * is January 1 1970, 00:00:00.000.
*/
@Override
public void setTime(long time) {
@@ -172,10 +175,11 @@
}
/**
- * Formats the Time as a String in JDBC escape format: hh:mm:ss
+ * Formats the {@code Time} as a String in JDBC escape format: {@code
+ * hh:mm:ss}.
*
- * @return A String representing the Time value in JDBC escape format:
- * HH:mm:ss
+ * @return A String representing the {@code Time} value in JDBC escape
+ * format: {@code HH:mm:ss}
*/
@Override
public String toString() {
@@ -204,16 +208,16 @@
}
/**
- * Creates a Time object from a String holding a time represented in JDBC
- * escape format: hh:mm:ss.
+ * Creates a {@code Time} object from a string holding a time represented in
+ * JDBC escape format: {@code hh:mm:ss}.
* <p>
- * An exception occurs if the input string is not in the form of a time in
- * JDBC escape format.
- *
+ * An exception occurs if the input string does not comply with this format.
+ *
* @param timeString
* A String representing the time value in JDBC escape format:
- * hh:mm:ss
- * @return The Time object set to a time corresponding to the given time
+ * {@code hh:mm:ss}.
+ * @return The {@code Time} object set to a time corresponding to the given
+ * time.
* @throws IllegalArgumentException
* if the supplied time string is not in JDBC escape format.
*/
Modified: harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/Timestamp.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/Timestamp.java?rev=770130&r1=770129&r2=770130&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/Timestamp.java (original)
+++ harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/Timestamp.java Thu Apr 30 09:45:40 2009
@@ -25,20 +25,23 @@
import org.apache.harmony.sql.internal.nls.Messages;
/**
- * A Java representation of the SQL TIMESTAMP type. It provides the capability
- * to represent the SQL TIMESTAMP nanosecond value, in addition to the regular
- * date/time value which has millisecond resolution.
+ * A Java representation of the SQL {@code TIMESTAMP} type. It provides the
+ * capability of representing the SQL {@code TIMESTAMP} nanosecond value, in
+ * addition to the regular date/time value which has millisecond resolution.
* <p>
- * The Timestamp class consists of a regular Date/Time value, where only the
- * integral seconds value is stored, plus a nanoseconds value where the
+ * The {@code Timestamp} class consists of a regular date/time value, where only
+ * the integral seconds value is stored, plus a nanoseconds value where the
* fractional seconds are stored.
* <p>
- * The addition of the nanosecond value field to the Timestamp object makes it
- * significantly different from the java.util.Date object which it extends.
- * Users should be cautious in their use of Timestamp objects and should not
- * assume that they are interchangeable with java.util.Date objects when used
- * outside the confines of the java.sql package.
- *
+ * The addition of the nanosecond value field to the {@code Timestamp} object
+ * makes it significantly different from the {@code java.util.Date} object which
+ * it extends. Users should be aware that {@code Timestamp} objects are not
+ * interchangable with {@code java.util.Date} objects when used outside the
+ * confines of the {@code java.sql} package.
+ *
+ * @see Date
+ * @see Time
+ * @see java.util.Date
*/
public class Timestamp extends Date {
@@ -48,27 +51,28 @@
private int nanos;
/**
- * @deprecated Please use the constructor Timestamp( long ) Returns a
- * Timestamp corresponding to the time specified by the supplied
- * values for Year, Month, Date, Hour, Minutes, Seconds and
- * Nanoseconds
+ * Returns a {@code Timestamp} corresponding to the time specified by the
+ * supplied values for <i>Year</i>, <i>Month</i>, <i>Date</i>, <i>Hour</i>,
+ * <i>Minutes</i>, <i>Seconds</i> and <i>Nanoseconds</i>.
+ *
+ * @deprecated Please use the constructor {@link #Timestamp(long)}.
* @param theYear
- * specified as the year minus 1900
+ * specified as the year minus 1900.
* @param theMonth
- * specified as an integer in the range 0 - 11
+ * specified as an integer in the range [0,11].
* @param theDate
- * specified as an integer in the range 1 - 31
+ * specified as an integer in the range [1,31].
* @param theHour
- * specified as an integer in the range 0 - 23
+ * specified as an integer in the range [0,23].
* @param theMinute
- * specified as an integer in the range 0 - 59
+ * specified as an integer in the range [0,59].
* @param theSecond
- * specified as an integer in the range 0 - 59
+ * specified as an integer in the range [0,59].
* @param theNano
* which defines the nanosecond value of the timestamp specified
- * as an integer in the range 0 - 999,999,999
+ * as an integer in the range [0,999'999'999]
* @throws IllegalArgumentException
- * if any of the parameters is out of range
+ * if any of the parameters is out of range.
*/
@SuppressWarnings("deprecation")
@Deprecated
@@ -83,12 +87,12 @@
}
/**
- * Returns a Timestamp object corresponding to the time represented by a
- * supplied time value.
+ * Returns a {@code Timestamp} object corresponding to the time represented
+ * by a supplied time value.
*
* @param theTime
* a time value in the format of milliseconds since the Epoch
- * (January 1 1970 00:00:00.000 GMT)
+ * (January 1 1970 00:00:00.000 GMT).
*/
public Timestamp(long theTime) {
super(theTime);
@@ -100,13 +104,13 @@
}
/**
- * Returns true if this timestamp object is later than the supplied
- * timestamp, otherwise returns false.
+ * Returns {@code true} if this timestamp object is later than the supplied
+ * timestamp, otherwise returns {@code false}.
*
* @param theTimestamp
- * the timestamp to compare with this timestamp object
- * @return true if this timestamp object is later than the supplied
- * timestamp, false otherwise
+ * the timestamp to compare with this timestamp object.
+ * @return {@code true} if this {@code Timestamp} object is later than the
+ * supplied timestamp, {@code false} otherwise.
*/
public boolean after(Timestamp theTimestamp) {
long thisTime = this.getTime();
@@ -132,13 +136,13 @@
}
/**
- * Returns true if this timestamp object is earlier than the supplied
- * timestamp, otherwise returns false.
+ * Returns {@code true} if this {@code Timestamp} object is earlier than the
+ * supplied timestamp, otherwise returns {@code false}.
*
* @param theTimestamp
- * the timestamp to compare with this timestamp object
- * @return true if this timestamp object is earlier than the supplied
- * timestamp, false otherwise
+ * the timestamp to compare with this {@code Timestamp} object.
+ * @return {@code true} if this {@code Timestamp} object is earlier than the
+ * supplied timestamp, {@code false} otherwise.
*/
public boolean before(Timestamp theTimestamp) {
long thisTime = this.getTime();
@@ -164,16 +168,27 @@
}
/**
- * Compares this Timestamp object with a supplied Timestamp object
+ * Compares this {@code Timestamp} object with a supplied {@code Timestamp}
+ * object.
*
* @param theObject
- * the timestamp to compare with this timestamp object, passed in
- * as an Object
- * @return 0 if the two Timestamp objects are equal in time, a value <0 if
- * this Timestamp object is before the supplied Timestamp and a
- * value >0 if this Timestamp object is after the supplied Timestamp
+ * the timestamp to compare with this {@code Timestamp} object,
+ * passed as an {@code Object}.
+ * @return <dd>
+ * <dl>
+ * {@code 0} if the two {@code Timestamp} objects are equal in time
+ * </dl>
+ * <dl>
+ * a value {@code < 0} if this {@code Timestamp} object is before
+ * the supplied {@code Timestamp} and a value
+ * </dl>
+ * <dl>
+ * {@code > 0} if this {@code Timestamp} object is after the
+ * supplied {@code Timestamp}
+ * </dl>
+ * </dd>
* @throws ClassCastException
- * if the supplied object is not a Timestamp object
+ * if the supplied object is not a {@code Timestamp} object.
*/
@Override
public int compareTo(Date theObject) throws ClassCastException {
@@ -181,14 +196,21 @@
}
/**
- * Compares this Timestamp object with a supplied Timestamp object
+ * Compares this {@code Timestamp} object with a supplied {@code Timestamp}
+ * object.
*
* @param theTimestamp
- * the timestamp to compare with this timestamp object, passed in
- * as a Timestamp
- * @return 0 if the two Timestamp objects are equal in time, a value <0 if
- * this Timestamp object is before the supplied Timestamp and a
- * value >0 if this Timestamp object is after the supplied Timestamp
+ * the timestamp to compare with this {@code Timestamp} object,
+ * passed in as a {@code Timestamp}.
+ * @return one of the following:
+ * <ul>
+ * <li>{@code 0}, if the two {@code Timestamp} objects are
+ * equal in time</li>
+ * <li>{@code < 0}, if this {@code Timestamp} object is before the
+ * supplied {@code Timestamp}</li>
+ * <li> {@code > 0}, if this {@code Timestamp} object is after the
+ * supplied {@code Timestamp}</li>
+ * </ul>
*/
public int compareTo(Timestamp theTimestamp) {
int result = super.compareTo(theTimestamp);
@@ -210,9 +232,11 @@
* Tests to see if this timestamp is equal to a supplied object.
*
* @param theObject
- * @return true if this Timestamp object is equal to the supplied Timestamp
- * object false if the object is not a Timestamp object or if the
- * object is a Timestamp but represents a different instant in time
+ * the object to which this timestamp is compared.
+ * @return {@code true} if this {@code Timestamp} object is equal to the
+ * supplied {@code Timestamp} object<br>{@code false} if the object
+ * is not a {@code Timestamp} object or if the object is a {@code
+ * Timestamp} but represents a different instant in time.
*/
@Override
public boolean equals(Object theObject) {
@@ -226,10 +250,10 @@
* Tests to see if this timestamp is equal to a supplied timestamp.
*
* @param theTimestamp
- * the timestamp to compare with this timestamp object, passed in
- * as an Object
- * @return true if this Timestamp object is equal to the supplied Timestamp
- * object
+ * the timestamp to compare with this {@code Timestamp} object,
+ * passed as an {@code Object}.
+ * @return {@code true} if this {@code Timestamp} object is equal to the
+ * supplied {@code Timestamp} object, {@code false} otherwise.
*/
public boolean equals(Timestamp theTimestamp) {
if (theTimestamp == null) {
@@ -240,19 +264,22 @@
}
/**
- * Gets this Timestamp's nanosecond value
+ * Gets this {@code Timestamp}'s nanosecond value
*
* @return The timestamp's nanosecond value, an integer between 0 and
- * 999,999,999
+ * 999,999,999.
*/
public int getNanos() {
return nanos;
}
/**
- * Returns the time represented by this Timestamp object, as a long value
- * containing the number of milliseconds since the Epoch (January 1 1970,
- * 00:00:00.000 GMT)
+ * Returns the time represented by this {@code Timestamp} object, as a long
+ * value containing the number of milliseconds since the Epoch (January 1
+ * 1970, 00:00:00.000 GMT).
+ *
+ * @return the number of milliseconds that have passed since January 1 1970,
+ * 00:00:00.000 GMT.
*/
@Override
public long getTime() {
@@ -262,7 +289,13 @@
}
/**
- * Sets the nanosecond value for this timestamp
+ * Sets the nanosecond value for this {@code Timestamp}.
+ *
+ * @param n
+ * number of nanoseconds.
+ * @throws IllegalArgumentException
+ * if number of nanoseconds smaller than 0 or greater than
+ * 999,999,999.
*/
public void setNanos(int n) throws IllegalArgumentException {
if ((n < 0) || (n > 999999999)) {
@@ -273,9 +306,13 @@
}
/**
- * Sets the time represented by this Timestamp object to the supplied time,
- * defined as the number of milliseconds since the Epoch (January 1 1970,
- * 00:00:00.000 GMT)
+ * Sets the time represented by this {@code Timestamp} object to the
+ * supplied time, defined as the number of milliseconds since the Epoch
+ * (January 1 1970, 00:00:00.000 GMT).
+ *
+ * @param theTime
+ * number of milliseconds since the Epoch (January 1 1970,
+ * 00:00:00.000 GMT).
*/
@Override
public void setTime(long theTime) {
@@ -305,10 +342,10 @@
/**
* Returns the timestamp formatted as a String in the JDBC Timestamp Escape
- * format, which is of the form "yyyy-mm-dd hh:mm:ss.nnnnnnnnn"
+ * format, which is {@code "yyyy-mm-dd hh:mm:ss.nnnnnnnnn"}.
*
- * @return A string representing the instant defined by the Timestamp, in
- * JDBC Timestamp escape format
+ * @return A string representing the instant defined by the {@code
+ * Timestamp}, in JDBC Timestamp escape format.
*/
@SuppressWarnings("deprecation")
@Override
@@ -353,14 +390,17 @@
}
/**
- * Creates a Timestamp object with a time value equal to the time specified
- * by a supplied String holding the time in JDBC timestamp escape format,
- * which is of the form "yyyy-mm-dd hh:mm:ss.nnnnnnnnn"
+ * Creates a {@code Timestamp} object with a time value equal to the time
+ * specified by a supplied String holding the time in JDBC timestamp escape
+ * format, which is {@code "yyyy-mm-dd hh:mm:ss.nnnnnnnnn}"
*
* @param s
- * the String containing a time in JDBC timestamp escape format
- * @return A timestamp object with time value as defined by the supplied
- * String
+ * the {@code String} containing a time in JDBC timestamp escape
+ * format.
+ * @return A {@code Timestamp} object with time value as defined by the
+ * supplied {@code String}.
+ * @throws IllegalArgumentException
+ * if the provided string is {@code null}.
*/
public static Timestamp valueOf(String s) throws IllegalArgumentException {
if (s == null) {
Modified: harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/Types.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/Types.java?rev=770130&r1=770129&r2=770130&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/Types.java (original)
+++ harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/Types.java Thu Apr 30 09:45:40 2009
@@ -19,7 +19,8 @@
/**
* A class which defines constants used to identify generic SQL types, also
- * called JDBC types. The type constant values are equivalent to those in XOPEN.
+ * called JDBC types. The type constant values are equivalent to those defined
+ * by X/OPEN.
*/
public class Types {
@@ -31,154 +32,154 @@
}
/**
- * The type code that identifies the SQL type ARRAY.
+ * The type code that identifies the SQL type {@code ARRAY}.
*/
public static final int ARRAY = 2003;
/**
- * The type code that identifies the SQL type BIGINT.
+ * The type code that identifies the SQL type {@code BIGINT}.
*/
public static final int BIGINT = -5;
/**
- * The type code that identifies the SQL type BINARY.
+ * The type code that identifies the SQL type {@code BINARY}.
*/
public static final int BINARY = -2;
/**
- * The type code that identifies the SQL type BIT.
+ * The type code that identifies the SQL type {@code BIT}.
*/
public static final int BIT = -7;
/**
- * The type code that identifies the SQL type BLOB.
+ * The type code that identifies the SQL type {@code BLOB}.
*/
public static final int BLOB = 2004;
/**
- * The type code that identifies the SQL type BOOLEAN.
+ * The type code that identifies the SQL type {@code BOOLEAN}.
*/
public static final int BOOLEAN = 16;
/**
- * The type code that identifies the SQL type CHAR.
+ * The type code that identifies the SQL type {@code CHAR}.
*/
public static final int CHAR = 1;
/**
- * The type code that identifies the SQL type CLOB.
+ * The type code that identifies the SQL type {@code CLOB}.
*/
public static final int CLOB = 2005;
/**
- * The type code that identifies the SQL type DATALINK.
+ * The type code that identifies the SQL type {@code DATALINK}.
*/
public static final int DATALINK = 70;
/**
- * The type code that identifies the SQL type DATE.
+ * The type code that identifies the SQL type {@code DATE}.
*/
public static final int DATE = 91;
/**
- * The type code that identifies the SQL type DECIMAL.
+ * The type code that identifies the SQL type {@code DECIMAL}.
*/
public static final int DECIMAL = 3;
/**
- * The type code that identifies the SQL type DISTINCT.
+ * The type code that identifies the SQL type {@code DISTINCT}.
*/
public static final int DISTINCT = 2001;
/**
- * The type code that identifies the SQL type DOUBLE.
+ * The type code that identifies the SQL type {@code DOUBLE}.
*/
public static final int DOUBLE = 8;
/**
- * The type code that identifies the SQL type FLOAT.
+ * The type code that identifies the SQL type {@code FLOAT}.
*/
public static final int FLOAT = 6;
/**
- * The type code that identifies the SQL type INTEGER.
+ * The type code that identifies the SQL type {@code INTEGER}.
*/
public static final int INTEGER = 4;
/**
- * The type code that identifies the SQL type JAVA_OBJECT.
+ * The type code that identifies the SQL type {@code JAVA_OBJECT}.
*/
public static final int JAVA_OBJECT = 2000;
/**
- * The type code that identifies the SQL type LONGVARBINARY.
+ * The type code that identifies the SQL type {@code LONGVARBINARY}.
*/
public static final int LONGVARBINARY = -4;
/**
- * The type code that identifies the SQL type LONGVARCHAR.
+ * The type code that identifies the SQL type {@code LONGVARCHAR}.
*/
public static final int LONGVARCHAR = -1;
/**
- * The type code that identifies the SQL type NULL.
+ * The type code that identifies the SQL type {@code NULL}.
*/
public static final int NULL = 0;
/**
- * The type code that identifies the SQL type NUMERIC.
+ * The type code that identifies the SQL type {@code NUMERIC}.
*/
public static final int NUMERIC = 2;
/**
* The type code that identifies that the SQL type is database specific and
* is mapped to a Java object, accessed via the methods
- * <code>getObject</code> and <code>setObject</code>.
+ * {@code getObject} and {@code setObject}.
*/
public static final int OTHER = 1111;
/**
- * The type code that identifies the SQL type REAL.
+ * The type code that identifies the SQL type {@code REAL}.
*/
public static final int REAL = 7;
/**
- * The type code that identifies the SQL type REF.
+ * The type code that identifies the SQL type {@code REF}.
*/
public static final int REF = 2006;
/**
- * The type code that identifies the SQL type SMALLINT.
+ * The type code that identifies the SQL type {@code SMALLINT}.
*/
public static final int SMALLINT = 5;
/**
- * The type code that identifies the SQL type STRUCT.
+ * The type code that identifies the SQL type {@code STRUCT}.
*/
public static final int STRUCT = 2002;
/**
- * The type code that identifies the SQL type TIME.
+ * The type code that identifies the SQL type {@code TIME}.
*/
public static final int TIME = 92;
/**
- * The type code that identifies the SQL type TIMESTAMP.
+ * The type code that identifies the SQL type {@code TIMESTAMP}.
*/
public static final int TIMESTAMP = 93;
/**
- * The type code that identifies the SQL type TINYINT.
+ * The type code that identifies the SQL type {@code TINYINT}.
*/
public static final int TINYINT = -6;
/**
- * The type code that identifies the SQL type VARBINARY.
+ * The type code that identifies the SQL type {@code VARBINARY}.
*/
public static final int VARBINARY = -3;
/**
- * The type code that identifies the SQL type VARCHAR.
+ * The type code that identifies the SQL type {@code VARCHAR}.
*/
public static final int VARCHAR = 12;
}
Modified: harmony/enhanced/classlib/trunk/modules/sql/src/main/java/javax/sql/ConnectionEvent.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/sql/src/main/java/javax/sql/ConnectionEvent.java?rev=770130&r1=770129&r2=770130&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/sql/src/main/java/javax/sql/ConnectionEvent.java (original)
+++ harmony/enhanced/classlib/trunk/modules/sql/src/main/java/javax/sql/ConnectionEvent.java Thu Apr 30 09:45:40 2009
@@ -22,9 +22,9 @@
import java.io.Serializable;
/**
- * An Event object which is sent when specific events happen on a
- * PooledConnection object. The events involved are when the application closing
- * the PooledConnection and when an error occurs in the PooledConnection.
+ * Sent when specific events happen on a {@link PooledConnection} object. These
+ * events are a facility to report when an application closes the pooled
+ * connection or when an error occurs in the pooled connection.
*/
public class ConnectionEvent extends EventObject implements Serializable {
@@ -33,25 +33,27 @@
private SQLException ex;
/**
- * Creates a connection event initialized with a supplied PooledConnection.
- *
+ * Creates a connection event initialized with the supplied {@code
+ * PooledConnection} reporting that the application has closed the
+ * connection.
+ *
* @param theConnection
- * the PooledConnection
+ * the connection for which this event is created.
*/
public ConnectionEvent(PooledConnection theConnection) {
super(theConnection);
}
/**
- * Creates a ConnectionEvent initialized with a supplied PooledConnection
- * and with a supplied SQLException indicating that an error has occurred
- * within the PooledConnection.
- *
+ * Creates a {@code ConnectionEvent} initialized with the supplied {@code
+ * PooledConnection} and with the supplied {@code SQLException} indicating
+ * that an error has occurred within the {@code PooledConnection}.
+ *
* @param theConnection
- * the PooledConnection
+ * the connection for which this event is created.
* @param theException
- * the SQLException holding information about the error that has
- * occurred, which is about to be returned to the application.
+ * information about the state of error that has occurred on the
+ * application side.
*/
public ConnectionEvent(PooledConnection theConnection,
SQLException theException) {
@@ -60,11 +62,11 @@
}
/**
- * Gets the SQLException which holds information about the error which
- * occurred in the PooledConnection.
- *
- * @return an SQLException containing information about the error. May be
- * null if no error has occurred.
+ * Gets the {@code SQLException} which holds information about the error
+ * which occurred in the {@code PooledConnection}.
+ *
+ * @return a {@code SQLException} containing information about the error.
+ * May be {@code null} if no error has occurred.
*/
public SQLException getSQLException() {
return ex;
Modified: harmony/enhanced/classlib/trunk/modules/sql/src/main/java/javax/sql/ConnectionEventListener.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/sql/src/main/java/javax/sql/ConnectionEventListener.java?rev=770130&r1=770129&r2=770130&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/sql/src/main/java/javax/sql/ConnectionEventListener.java (original)
+++ harmony/enhanced/classlib/trunk/modules/sql/src/main/java/javax/sql/ConnectionEventListener.java Thu Apr 30 09:45:40 2009
@@ -20,40 +20,38 @@
import java.util.EventListener;
/**
- * An interface used to receive events generated by a
- * <code>PooledConnection</code>.
+ * An interface used to receive events generated by a {@link PooledConnection}.
* <p>
- * This interface would typically be implemented by a component which implements
- * Connection Pooling (a Connection Pool Manager). A Connection will signal
- * events to a ConnectionEventListener either when the application closes a
- * Connection it has been using or when a significant error occurs while the
- * Connection is being used, where the Connection should not be used again.
+ * This interface would typically be implemented by a component which manages a
+ * connection pool (a connection pool manager). A connection triggers an event
+ * to a {@code ConnectionEventListener} either when the application closes a
+ * connection it has been using or when a significant error occurs while the
+ * connection is being used.
* <p>
- * The Connection Pool Manager can return closed Connections to the Pool for
+ * The connection pool manager can return closed connections to the pool for
* later reuse. Connections experiencing an error should be discarded.
- *
*/
public interface ConnectionEventListener extends EventListener {
/**
- * Notifies the ConnectionEventListener that an application has called the
- * <code>close</code> method on a pooled Connection.
+ * Notifies the {@code ConnectionEventListener} that an application has
+ * called the {@code close} method on a pooled connection.
*
* @param theEvent
- * a ConnectionEvent containing detail about the source of the
- * event.
+ * a {@code ConnectionEvent} containing details about the source
+ * of the event.
*/
public void connectionClosed(ConnectionEvent theEvent);
/**
- * Notifies the ConnectionEventListener that an error has occurred while a
- * PooledConnection was being used and that the PooledConnection can no
- * longer be used for work. This notification is done just before the
- * SQLException passed in the event message is thrown to the application.
+ * Notifies the {@code ConnectionEventListener} that an error has occurred
+ * on a {@code PooledConnection}. This notification is triggered <i>before</i> the
+ * {@code SQLException}, which is available through the event argument, is
+ * thrown.
*
* @param theEvent
- * a ConnectionEvent containing detail about the source of the
- * event and the SQLException that has occurred.
+ * a {@code ConnectionEvent} containing details about the source
+ * of the event and the {@code SQLException} that has occurred.
*/
public void connectionErrorOccurred(ConnectionEvent theEvent);
}