harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From telli...@apache.org
Subject svn commit: r770130 [8/10] - in /harmony/enhanced/classlib/trunk/modules/sql/src/main/java: java/sql/ javax/sql/
Date Thu, 30 Apr 2009 09:45:42 GMT
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 &ge; 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 &lt; {@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);
 }



Mime
View raw message