harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From telli...@apache.org
Subject svn commit: r770130 [9/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/javax/sql/ConnectionPoolDataSource.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/sql/src/main/java/javax/sql/ConnectionPoolDataSource.java?rev=770130&r1=770129&r2=770130&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/sql/src/main/java/javax/sql/ConnectionPoolDataSource.java (original)
+++ harmony/enhanced/classlib/trunk/modules/sql/src/main/java/javax/sql/ConnectionPoolDataSource.java Thu Apr 30 09:45:40 2009
@@ -21,68 +21,70 @@
 import java.io.PrintWriter;
 
 /**
- * An interface for the creation of PooledConnection objects. Used internally
- * within the package.
+ * An interface for the creation of {@code ConnectionPoolDataSource} objects.
+ * Used internally within the package.
  * <p>
- * A class which implements the ConnectionPoolDataSource interface is typically
- * registered with a JNDI naming service directory and is retrieved from there
- * by name.
+ * A class which implements the {@code ConnectionPoolDataSource} interface is
+ * typically registered with a JNDI naming service directory and is retrieved
+ * from there by name.
  */
 public interface ConnectionPoolDataSource {
 
     /**
-     * Gets the Login Timeout value for this ConnectionPoolDataSource. The Login
-     * Timeout is the maximum time in seconds that the ConnectionPoolDataSource
-     * will wait when opening a connection to a database. A Timeout value of 0
-     * implies either the system default timeout value (if there is one) or that
-     * there is no timeout. The default value for the Login Timeout is 0.
+     * Gets the login timeout value for this {@code ConnectionPoolDataSource}.
+     * The login timeout is the maximum time in seconds that the {@code
+     * ConnectionPoolDataSource} will wait when opening a connection to a
+     * database. A timeout value of 0 implies either the system default timeout
+     * value (if there is one) or that there is no timeout. The default value
+     * for the login timeout is {@code 0}.
      * 
-     * @return the Login Timeout value in seconds.
+     * @return the login timeout value in seconds.
      * @throws SQLException
      *             if there is a problem accessing the database.
      */
     public int getLoginTimeout() throws SQLException;
 
     /**
-     * Gets the Log Writer for this ConnectionPoolDataSource.
+     * Gets the log writer for this {@code ConnectionPoolDataSource}.
      * <p>
-     * The Log Writer is a stream to which all log and trace messages are sent
-     * from this ConnectionPoolDataSource. The Log Writer can be null, in which
-     * case, log and trace capture is disabled. The default value for the Log
-     * Writer when an ConnectionPoolDataSource is created is null. Note that the
-     * Log Writer for an ConnectionPoolDataSource is not the same as the Log
-     * Writer used by a <code>DriverManager</code>.
-     * 
-     * @return a PrintWriter which is the Log Writer for this
-     *         ConnectionPoolDataSource. Can be null, in which case log writing
-     *         is disabled for this ConnectionPoolDataSource.
+     * The log writer is a stream to which all log and trace messages are sent
+     * from this {@code ConnectionPoolDataSource}. The log writer can be {@code
+     * null}, in which case the log and trace capture is disabled. The default
+     * value for the log writer when an {@code ConnectionPoolDataSource} is
+     * created is {@code null}. Note that the log writer for an {@code
+     * ConnectionPoolDataSource} is not the same as the log writer used by a
+     * {@code DriverManager}.
+     *
+     * @return a {@code PrintWriter} which is the log writer for this {@code
+     *         ConnectionPoolDataSource}. Can be {@code null}, in which case log
+     *         writing is disabled for this {@code ConnectionPoolDataSource}.
      * @throws SQLException
      *             if there is a problem accessing the database.
      */
     public PrintWriter getLogWriter() throws SQLException;
 
     /**
-     * Create a connection to a database which can then be used as a pooled
+     * Creates a connection to a database which can then be used as a pooled
      * connection.
      * 
-     * @return a PooledConnection which represents the connection to the
-     *         database
+     * @return a {@code PooledConnection} which represents the connection to the
+     *         database.
      * @throws SQLException
      *             if there is a problem accessing the database.
      */
     public PooledConnection getPooledConnection() throws SQLException;
 
     /**
-     * Create a connection to a database, using a supplied Username and
-     * Password, which can then be used as a pooled connection.
+     * Creates a connection to a database, using the supplied user name and
+     * password, which can then be used as a pooled connection.
      * 
      * @param theUser
-     *            a String containing a User Name for the database
+     *            the a user name for the database login.
      * @param thePassword
-     *            a String containing the Password for the user identified by
-     *            <code>theUser</code>
-     * @return a PooledConnection which represents the connection to the
-     *         database
+     *            the password associated with the user identified by {@code
+     *            theUser}.
+     * @return a {@code PooledConnection} object which represents the connection
+     *         to the database.
      * @throws SQLException
      *             if there is a problem accessing the database.
      */
@@ -90,32 +92,33 @@
             String thePassword) throws SQLException;
 
     /**
-     * Sets the Login Timeout value for this ConnectionPoolDataSource. The Login
-     * Timeout is the maximum time in seconds that the ConnectionPoolDataSource
-     * will wait when opening a connection to a database. A Timeout value of 0
-     * implies either the system default timeout value (if there is one) or that
-     * there is no timeout. The default value for the Login Timeout is 0.
+     * Sets the login timeout value for this {@code ConnectionPoolDataSource}.
+     * The login timeout is the maximum time in seconds that the {@code
+     * ConnectionPoolDataSource} will wait when opening a connection to a
+     * database. A timeout value of 0 implies either the system default timeout
+     * value (if there is one) or that there is no timeout. The default value
+     * for the login timeout is 0.
      * 
      * @param theTimeout
-     *            the new Login Timeout value in seconds.
+     *            the new login timeout value in seconds.
      * @throws SQLException
      *             if there is a problem accessing the database.
      */
     public void setLoginTimeout(int theTimeout) throws SQLException;
 
     /**
-     * Sets the Log Writer for this ConnectionPoolDataSource.
+     * Sets the log writer for this {@code ConnectionPoolDataSource}.
      * <p>
-     * The Log Writer is a stream to which all log and trace messages are sent
-     * from this ConnectionPoolDataSource. The Log Writer can be null, in which
-     * case, log and trace capture is disabled. The default value for the Log
-     * Writer when an ConnectionPoolDataSource is created is null. Note that the
-     * Log Writer for an ConnectionPoolDataSource is not the same as the Log
-     * Writer used by a <code>DriverManager</code>.
+     * The log writer is a stream to which all log and trace messages are sent
+     * from this {@code ConnectionPoolDataSource}. The log writer can be {@code
+     * null}, in which case log and trace capture is disabled. The default value
+     * for the log writer, when a {@code ConnectionPoolDataSource} is created,
+     * is {@code null}. Note that the log writer for a {@code
+     * ConnectionPoolDataSource} is not the same as the log writer used by a
+     * {@code DriverManager}.
      * 
      * @param theWriter
-     *            a PrintWriter to use as the Log Writer for this
-     *            ConnectionPoolDataSource.
+     *            is the log writer for this {@code ConnectionPoolDataSource}.
      * @throws SQLException
      *             if there is a problem accessing the database.
      */

Modified: harmony/enhanced/classlib/trunk/modules/sql/src/main/java/javax/sql/DataSource.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/sql/src/main/java/javax/sql/DataSource.java?rev=770130&r1=770129&r2=770130&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/sql/src/main/java/javax/sql/DataSource.java (original)
+++ harmony/enhanced/classlib/trunk/modules/sql/src/main/java/javax/sql/DataSource.java Thu Apr 30 09:45:40 2009
@@ -22,55 +22,58 @@
 import java.io.PrintWriter;
 
 /**
- * An interface for the creation of Connection objects which represent a
- * connection to a database. This interface is an alternative to the
- * <code>java.sql.DriverManager</code>.
+ * An interface for the creation of {@code Connection} objects which represent a
+ * connection to a database. This interface is an alternative to the {@code
+ * java.sql.DriverManager}.
  * <p>
- * A class which implements the DataSource interface is typically registered
- * with a JNDI naming service directory and is retrieved from there by name.
+ * A class which implements the {@code DataSource} interface is typically
+ * registered with a JNDI naming service directory and is retrieved from there
+ * by name.
  * <p>
- * The DataSource interface is typically implemented by the writer of a JDBC
- * driver. There are three variants of the DataSource interface, which produce
- * Connections with differing characteristics:
+ * The {@code DataSource} interface is typically implemented by the writer of a
+ * JDBC driver. There are three variants of the {@code DataSource} interface,
+ * which produce connections with different characteristics:
  * <ol>
- * <li>Standard DataSource, which produces standard Connection objects with no
- * special features.</li>
- * <li>Connection Pool DataSource, which produces PooledConnection objects
- * which are able to participate in connection pooling, typically involving a
- * connection pooling manager as an intermediary between applications and the
- * database.</li>
- * <li>Distributed transaction DataSource ("XADataSource"), which produces
- * XAConnection objects which can be used to handle distributed transactions and
- * which typically involve a transaction manager component in the system.
- * XAConnection objects also typically provide connection pooling capabilities
- * as well as distributed transaction capabilities. </li>
+ * <li><i>Standard {@code DataSource}</i>: produces standard {@code Connection}
+ * objects with no special features.</li>
+ * <li><i>Connection Pool {@code DataSource}</i>: produces {@code
+ * PooledConnection} objects which require a connection pool manager as an
+ * intermediary component.</li>
+ * <li><i>Distributed transaction {@code DataSource} ("XADataSource")</i>:
+ * produces {@code XAConnection} objects which can be used to handle distributed
+ * transactions which typically require an intermediary transaction manager
+ * component. {@code XAConnection} objects also provide connection pooling
+ * capabilities as well as distributed transaction capabilities.</li>
  * </ol>
  * <p>
- * Note that a JDBC driver which is accessed via the DataSource interface is
- * loaded via a JNDI lookup process. A driver loaded in this way does not
- * register itself with the <code>DriverManager</code>.
+ * Note that a JDBC driver which is accessed via the {@code DataSource}
+ * interface is loaded via a JNDI lookup process. A driver loaded in this way
+ * does not register itself with the {@code DriverManager}.
  */
 public interface DataSource {
 
     /**
-     * Creates a connection to the database represented by this DataSource.
+     * Creates a connection to the database represented by this {@code
+     * DataSource}.
      * 
-     * @return a Connection object which is a connection to the database.
+     * @return a {@code Connection} object which is a connection to the
+     *         database.
      * @throws SQLException
      *             if there is a problem accessing the database.
      */
     public Connection getConnection() throws SQLException;
 
     /**
-     * Creates a connection to the database represented by this DataSource,
-     * using a supplied Username and Password,.
+     * Creates a connection to the database represented by this {@code
+     * DataSource}, using the supplied user name and password.
      * 
      * @param theUsername
-     *            a String containing a User Name for the database
+     *            the a user name for the database login.
      * @param thePassword
-     *            a String containing the Password for the user identified by
-     *            <code>theUsername</code>
-     * @return a Connection object which is a connection to the database.
+     *            the password associated with the user identified by {@code
+     *            theUsername}.
+     * @return the {@code Connection} object which is the connection to the
+     *         database.
      * @throws SQLException
      *             if there is a problem accessing the database.
      */
@@ -78,59 +81,63 @@
             throws SQLException;
 
     /**
-     * Gets the Login Timeout value for this DataSource. The Login Timeout is
-     * the maximum time in seconds that the DataSource will wait when opening a
-     * connection to a database. A Timeout value of 0 implies either the system
-     * default timeout value (if there is one) or that there is no timeout. The
-     * default value for the Login Timeout is 0.
+     * Gets the login timeout value for this {@code DataSource}. The login
+     * timeout is the maximum time in seconds that the {@code DataSource} will
+     * wait when opening a connection to a database. A timeout value of 0
+     * implies either the system default timeout value (if there is one) or that
+     * there is no timeout. The default value for the login timeout is 0.
      * 
-     * @return the Login Timeout value in seconds.
+     * @return the login timeout value in seconds.
      * @throws SQLException
      *             if there is a problem accessing the database.
      */
     public int getLoginTimeout() throws SQLException;
 
     /**
-     * Gets the Log Writer for this DataSource.
+     * Gets the log writer for this {@code DataSource}.
      * <p>
-     * The Log Writer is a stream to which all log and trace messages are sent
-     * from this DataSource. The Log Writer can be null, in which case, log and
-     * trace capture is disabled. The default value for the Log Writer when an
-     * DataSource is created is null. Note that the Log Writer for an DataSource
-     * is not the same as the Log Writer used by a <code>DriverManager</code>.
-     * 
-     * @return a PrintWriter which is the Log Writer for this DataSource. Can be
-     *         null, in which case log writing is disabled for this DataSource.
+     * The log writer is a stream to which all log and trace messages are sent
+     * from this {@code DataSource}. The log writer can be {@code null}, in
+     * which case, log and trace capture is disabled. The default value for the
+     * log writer when an {@code DataSource} is created is {@code null}. Note
+     * that the log writer for a {@code DataSource} is not the same as the log
+     * writer used by a {@code DriverManager}.
+     *
+     * @return a {@code PrintWriter} which is the log writer for this {@code
+     *         DataSource}. Can be {@code null}, in which case log writing is
+     *         disabled for this {@code DataSource}.
      * @throws SQLException
      *             if there is a problem accessing the database.
      */
     public PrintWriter getLogWriter() throws SQLException;
 
     /**
-     * Sets the Login Timeout value for this DataSource. The Login Timeout is
-     * the maximum time in seconds that the DataSource will wait when opening a
-     * connection to a database. A Timeout value of 0 implies either the system
-     * default timeout value (if there is one) or that there is no timeout. The
-     * default value for the Login Timeout is 0.
+     * Sets the login timeout value for this {@code DataSource}. The login
+     * timeout is the maximum time in seconds that the {@code DataSource} will
+     * wait when opening a connection to a database. A timeout value of 0
+     * implies either the system default timeout value (if there is one) or that
+     * there is no timeout. The default value for the login timeout is 0.
      * 
      * @param theTimeout
-     *            the new Login Timeout value in seconds.
+     *            the new login timeout value in seconds.
      * @throws SQLException
      *             if there is a problem accessing the database.
      */
     public void setLoginTimeout(int theTimeout) throws SQLException;
 
     /**
-     * Sets the Log Writer for this DataSource.
+     * Sets the log writer for this {@code DataSource}.
      * <p>
-     * The Log Writer is a stream to which all log and trace messages are sent
-     * from this DataSource. The Log Writer can be null, in which case, log and
-     * trace capture is disabled. The default value for the Log Writer when an
-     * DataSource is created is null. Note that the Log Writer for an DataSource
-     * is not the same as the Log Writer used by a <code>DriverManager</code>.
+     * The log writer is a stream to which all log and trace messages are sent
+     * from this {@code DataSource}. The log writer can be {@code null}, in
+     * which case, log and trace capture is disabled. The default value for the
+     * log writer when a {@code DataSource} is created is {@code null}. Note
+     * that the log writer for a {@code DataSource} is not the same as the log
+     * writer used by a {@code DriverManager}.
      * 
      * @param theWriter
-     *            a PrintWriter to use as the Log Writer for this DataSource.
+     *            a {@code PrintWriter} to use as the log writer for this
+     *            {@code DataSource}.
      * @throws SQLException
      *             if there is a problem accessing the database.
      */

Modified: harmony/enhanced/classlib/trunk/modules/sql/src/main/java/javax/sql/PooledConnection.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/sql/src/main/java/javax/sql/PooledConnection.java?rev=770130&r1=770129&r2=770130&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/sql/src/main/java/javax/sql/PooledConnection.java (original)
+++ harmony/enhanced/classlib/trunk/modules/sql/src/main/java/javax/sql/PooledConnection.java Thu Apr 30 09:45:40 2009
@@ -24,58 +24,60 @@
  * An interface which provides facilities for handling connections to a database
  * which are pooled.
  * <p>
- * Typically, a PooledConnection is recycled when it is no longer required by an
- * application, rather than being closed and discarded. The reason for treating
- * connections in this way is that it can be an expensive process both to
- * establish a connection to a database and to destroy the connection. Reusing
- * connections through a pool is a way of improving system performance and
- * reducing overhead.
+ * Typically, a {@code PooledConnection} is recycled when it is no longer
+ * required by an application, rather than being closed and discarded. The
+ * reason for treating connections in this way is that it can be an expensive
+ * process both to establish a connection to a database and to destroy the
+ * connection. Reusing connections through a pool is a way of improving system
+ * performance and reducing overhead.
  * <p>
- * It is not intended that an application use the PooledConnection interface
- * directly. The PooledConnection interface is intended for use by a component
- * called a Connection Pool Manager, typically part of the infrastructure that
- * supports use of the database by applications.
+ * It is not intended that an application uses the {@code PooledConnection}
+ * interface directly. The {@code PooledConnection} interface is intended for
+ * use by a component called a connection pool manager, typically part of the
+ * infrastructure that supports use of the database by applications.
  * <p>
  * Applications obtain connections to the database by calling the
- * <code>DataSource.getConnection</code> method. Under the covers, the
- * Connection Pool Manager will get a PooledConnection object from its
- * connection pool and passes back a Connection object that wraps or references
- * the PooledConnection object. A new PooledConnection object will only be
+ * {@link DataSource#getConnection} method. Behind the scenes, the connection
+ * pool manager will get a {@code PooledConnection} object from its connection
+ * pool and passes back a connection object that wraps or references the {@code
+ * PooledConnection} object. A new {@code PooledConnection} object will only be
  * created if the pool is empty.
  * <p>
- * When the application is finished using a PooledConnection, the application
- * calls the <code>Connection.close</code> method. The Connection Pool Manager
- * is notified via a ConnectionEvent from the Connection that this has happened
- * (the Pool Manager registers itself with the Connection before the Connection
- * is given to the application). The Pool Manager removes the underlying
- * PooledConnection object from the Connection and returns it to the pool for
- * reuse - the PooledConnection is thus recycled rather than being destroyed.
+ * When the application is finished using a {@code PooledConnection}, the
+ * application calls the {@link Connection#close} method. The connection pool
+ * manager is notified via a {@link ConnectionEvent} from the connection that
+ * this has happened (the pool manager registers itself with the connection
+ * before the connection is given to the application). The pool manager removes
+ * the underlying {@code PooledConnection} object from the connection and
+ * returns it to the pool for reuse - the {@code PooledConnection} is thus
+ * recycled rather than being destroyed.
  * <p>
- * The connection to the database represented by the PooledConnection is kept
- * open until the PooledConnection object itself is deactivated by the
- * Connection Pool Manager, which calls the <code>PooledConnection.close</code>
- * method. This is typically done if there are too many inactive connections in
- * the pool, if the PooledConnection encounters a problem that makes it unusable
- * or if the whole system is being shut down.
- * 
+ * The connection to the database represented by the {@code PooledConnection} is
+ * kept open until the {@code PooledConnection} object itself is deactivated by
+ * the connection pool manager, which calls {@code PooledConnection.close()}.
+ * This is typically done if there are too many inactive connections in the
+ * pool, if the {@code PooledConnection} encounters a problem that makes it
+ * unusable or if the whole system is being shut down.
  */
 public interface PooledConnection {
 
     /**
-     * Registers the supplied ConnectionEventListener with this
-     * PooledConnection. Once registered, the ConnectionEventListener will
-     * receive ConnectionEvent events when they occur in the PooledConnection.
+     * Registers the supplied {@code ConnectionEventListener} with this {@code
+     * PooledConnection}. Once registered, the {@code ConnectionEventListener}
+     * will receive {@link ConnectionEvent} events when they occur in the
+     * {@code PooledConnection}.
      * 
      * @param theListener
-     *            an object which implements the ConnectionEventListener
+     *            an object which implements the {@code ConnectionEventListener}
      *            interface.
      */
     public void addConnectionEventListener(ConnectionEventListener theListener);
 
     /**
-     * Closes the connection to the database held by this PooledConnection. This
-     * method should not be called directly by application code - it is intended
-     * for use by the Connection Pool manager component.
+     * Closes the connection to the database held by this {@code
+     * PooledConnection}. This method should not be called directly by
+     * application code - it is intended only for the connection pool manager
+     * component.
      * 
      * @throws SQLException
      *             if there is a problem accessing the database.
@@ -84,27 +86,26 @@
 
     /**
      * Creates a connection to the database. This method is typically called by
-     * the Connection Pool manager when an application invokes the method
-     * <code>DataSource.getConnection</code> and there are no PooledConnection
-     * objects available in the connection pool.
+     * the connection pool manager when an application invokes the method
+     * {@code DataSource.getConnection()} and there are no {@code
+     * PooledConnection} objects available in the connection pool.
      * 
-     * @return a Connection object that is a handle to this PooledConnection
-     *         object.
+     * @return a {@code Connection} object.
      * @throws SQLException
      *             if there is a problem accessing the database.
      */
     public Connection getConnection() throws SQLException;
 
     /**
-     * Deregister the supplied ConnectionEventListener from this
-     * PooledConnection. Once deregistered, the ConnectionEventListener will not
-     * longer receive events occurring in the PooledConnection.
+     * Unregisters the supplied {@code ConnectionEventListener} from this {@code
+     * PooledConnection}. Once unregistered, the {@code ConnectionEventListener}
+     * will no longer receive events occurring in the {@code PooledConnection}.
      * 
      * @param theListener
-     *            an object which implements the ConnectionEventListener
+     *            an object which implements the {@code ConnectionEventListener}
      *            interface. This object should have previously been registered
-     *            with the PooledConnection using the
-     *            <code>addConnectionEventListener</code> method.
+     *            with the {@code PooledConnection} using the {@code
+     *            addConnectionEventListener} method.
      */
     public void removeConnectionEventListener(
             ConnectionEventListener theListener);

Modified: harmony/enhanced/classlib/trunk/modules/sql/src/main/java/javax/sql/RowSet.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/sql/src/main/java/javax/sql/RowSet.java?rev=770130&r1=770129&r2=770130&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/sql/src/main/java/javax/sql/RowSet.java (original)
+++ harmony/enhanced/classlib/trunk/modules/sql/src/main/java/javax/sql/RowSet.java Thu Apr 30 09:45:40 2009
@@ -33,171 +33,191 @@
 import java.math.BigDecimal;
 
 /**
- * A RowSet is an interface which provides access to data being sent from/to a
- * database and which extends the functionality of ResultSet into a form that
- * can be used as a JavaBeans component, perhaps being used in a visual
- * programming environment.
+ * An interface which provides means to access data which
+ * persists on a database. It extends the functionality of
+ * {@link java.sql.ResultSet ResultSet} into a form that it can be used as a
+ * JavaBean component, suited for a visual programming environment.
  * <p>
- * Facilities are provided for get/set of properties relating to the Database
- * and the SQL Command and for getting/setting data within the Rows represented
- * by the RowSet. The RowSet supports JavaBeans events so that other components
- * in an application can be informed when various changes happen to the RowSet,
- * such as changes in data values.
+ * {@code RowSet} provides getters and setters for properties relating to the
+ * general database environment together with the getters and setters for
+ * distinct data values which constitute the row set. The {@code RowSet} class
+ * supports JavaBean events so that other components in an application can be
+ * informed when changes happen such as changes in data values.
  * <p>
- * RowSet is implemented as a layer on top of the remainder of the JDBC API. A
- * RowSet may be <i>connected</i> where it maintains a connection to the
- * database throughout its lifecycle. A RowSet may be <i>disconnected</i> where
- * it establishes a connection to the database, gets data and then closes the
- * connection. Updates to a disconnected RowSet can be made and later send back
- * the changes to the database, but this requires the RowSet to first reconnect
- * to the database before the changes are sent back.
+ * {@code RowSet} is a facility implemented on top of the remainder of the JDBC
+ * API. It may be <i>connected</i>, maintaining a connection to the database
+ * throughout its lifecycle. The changes made on a <i>disconnected</i> {@code
+ * RowSet} on the other hand can be persisted only establishing a new connection
+ * with the database each time.
  * <p>
- * Disconnected RowSets may make use of RowSetReaders to populate the RowSet
- * with data, possibly from a non-relational database source. Disconnected
- * RowSets may also use RowSetWriters to send data back to the underlying data
- * store. There is considerable freedom in the way that RowSetReaders and
- * RowSetWriters are implemented to get and store data.
+ * Disconnected {@code RowSets} make use of {@code RowSetReaders} to populate
+ * the {@code RowSet} with data, possibly from a non-relational database source.
+ * They may also use {@code RowSetWriters} to send data back to the underlying
+ * data store. There is considerable freedom in the way that {@code
+ * RowSetReaders} and {@code RowSetWriters} may be implemented to retrieve and
+ * store data.
+ *
+ * @see RowSetReader
+ * @see RowSetWriter
  */
 public interface RowSet extends ResultSet {
 
     /**
-     * Registers a supplied RowSetListener with this RowSet. Once registered,
-     * the RowSetListener is notified of events generated by the RowSet.
+     * Registers the supplied {@link RowSetListener} with this {@code RowSet}.
+     * Once registered, the {@link RowSetListener} is notified of events
+     * generated by the {@code RowSet}.
      * 
      * @param theListener
-     *            an object which implements the <code>rowSetListener</code>
+     *            an object which implements the {@code rowSetListener}
      *            interface.
      */
     public void addRowSetListener(RowSetListener theListener);
 
     /**
-     * Clears the parameters previously set for this RowSet.
+     * Clears the parameters previously set for this {@code RowSet}.
      * <p>
-     * Parameter values apply to repeated use of a RowSet object. Setting a new
-     * value for a parameter clears its previous value.
-     * <code>clearParameters</code> clears the values for all parameters with
-     * one method call.
-     * 
+     * The {@code RowSet} object retains its value until either a new value for
+     * a parameter is set or its value is actively reset. {@code
+     * clearParameters} provides a facility to clear the values for all
+     * parameters with one method call.
+     *
      * @throws SQLException
-     *             if a problem occurs accessing the database
+     *             if a problem occurs accessing the database.
      */
     public void clearParameters() throws SQLException;
 
     /**
-     * Fetches data for this RowSet. If successful, any existing data for the
-     * RowSet is discarded and the metadata for the rowset is set.
+     * Fetches data for this {@code RowSet} from the database. If successful,
+     * any existing data for the {@code RowSet} is discarded and its metadata is
+     * overwritten.
      * <p>
-     * Data is retrieved connects to the database and executes a Command. This
-     * requires some or all of the following properties to be set: url, data
-     * source name, user name, password, transaction isolation, type map ; plus
-     * some or all of the properties: command, read only, maximum field size,
-     * maximum rows, escape processing, and query timeout.
+     * Data is retrieved connecting to the database and executing an
+     * according SQL statement. This requires some or all of the following
+     * properties to be set: URL, database name, user name, password,
+     * transaction isolation, type map; plus some or all of the properties:
+     * command, read only, maximum field size, maximum rows, escape processing,
+     * and query timeout.
      * <p>
-     * The RowSet may use a RowSetReader to access the database - in this case a
-     * reader must be registered with the RowSet and the RowSet will then invoke
-     * the <code>readData</code> method on the reader to fetch the data.
-     * 
+     * The {@code RowSet} may use a {@code RowSetReader} to access the database
+     * it will then invoke the {@link RowSetReader#readData} method on the
+     * reader to fetch the data. When the new data is fetched all the listeners
+     * are notified to take appropriate measures.
+     *
      * @throws SQLException
      *             if a problem occurs accessing the database or if the
-     *             properties needed to access the database have not been set
+     *             properties needed to access the database have not been set.
+     * @see RowSetMetaData
+     * @see RowSetReader
      */
     public void execute() throws SQLException;
 
     /**
-     * Gets the RowSet's Command property.
+     * Gets the {@code RowSet}'s command property.
      * 
-     * @return a string containing the RowSet's Command property - this is an
-     *         SQL Query which can be executed to fetch data into the RowSet.
+     * @return a string containing the {@code RowSet}'s command property. A
+     *         command is a SQL statement which is executed to fetch required
+     *         data into the {@code RowSet}.
      */
     public String getCommand();
 
     /**
-     * Gets the name of the datasource for this RowSet.
+     * Gets the ODBC Data Source Name property associated with this {@code
+     * RowSet}. The database name can be used to find a {@link DataSource}
+     * which has been registered with a naming service - the {@link DataSource}
+     * can then be used to create a connection to the database.
      * 
-     * @return a String containing the name of the datasource.
+     * @return the name of the database.
      */
     public String getDataSourceName();
 
     /**
-     * Reports if escape processing is enabled for this RowSet.
-     * <p>
-     * If <code>true</code> (the default) the driver will automatically
-     * perform escape code processing on SQL statements prior to them being sent
-     * to the database.
+     * Reports if escape processing is enabled for this {@code RowSet}. If
+     * escape processing is on, the driver performs a substitution of the escape
+     * syntax with the applicable code before sending an SQL command to the
+     * database. The default value for escape processing is {@code true}.
      * 
-     * @return true if escape processing is enabled, false otherwise.
+     * @return {@code true} if escape processing is enabled, {@code
+     *         false} otherwise.
      * @throws SQLException
-     *             if a problem occurs accessing the database
+     *             if a problem occurs accessing the database.
      */
     public boolean getEscapeProcessing() throws SQLException;
 
     /**
      * Gets the maximum number of bytes that can be returned for column values
-     * which are of types BINARY, VARBINARY, LONGVARBINARYBINARY, CHAR, VARCHAR,
-     * or LONGVARCHAR. Excess data is silently discarded if the number is
+     * which are of type {@code BINARY}, {@code VARBINARY}, {@code
+     * LONGVARBINARYBINARY}, {@code CHAR}, {@code VARCHAR}, or {@code
+     * LONGVARCHAR}. Excess data is silently discarded if the number is
      * exceeded.
      * 
-     * @return the current maximum size in bytes. 0 means no limit
+     * @return the current maximum size in bytes. 0 implies no size limit.
      * @throws SQLException
-     *             if a problem occurs accessing the database
+     *             if a problem occurs accessing the database.
      */
     public int getMaxFieldSize() throws SQLException;
 
     /**
-     * Gets the maximum number of rows for this RowSet. Excess rows are
+     * Gets the maximum number of rows for this {@code RowSet}. Excess rows are
      * discarded silently if the limit is exceeded.
      * 
-     * @return the previous maximum number of rows. 0 implies no limit.
+     * @return the previous maximum number of rows. 0 implies no row limit.
      * @throws SQLException
-     *             if a problem occurs accessing the database
+     *             if a problem occurs accessing the database.
      */
     public int getMaxRows() throws SQLException;
 
     /**
-     * Gets the value of the password property for this RowSet. This property is
-     * used when making a connection to the database and should be set before
-     * invoking the <code>execute</code> method.
+     * Gets the value of the password property for this {@code RowSet}. This
+     * property is used when a connection to the database is established.
+     * Therefore it should be set prior to invoking the {@link #execute} method.
      * 
-     * @return a String containing the value of the password property.
+     * @return the value of the password property.
      */
     public String getPassword();
 
     /**
-     * Gets the Timeout for the driver when executing a Query operation.
-     * <p>
-     * If a Query takes longer than the Timeout, an exception is thrown.
+     * Gets the timeout for the driver when a query operation is executed. If a
+     * query takes longer than the timeout then a {@code SQLException} is
+     * thrown.
      * 
-     * @return the Timeout value in seconds.
+     * @return the timeout value in seconds.
      * @throws SQLException
      *             if an error occurs accessing the database.
      */
     public int getQueryTimeout() throws SQLException;
 
     /**
-     * Gets the transaction isolation property setting for this RowSet.
-     * 
-     * @return an integer holding the current transaction isolation setting. One
-     *         of: one of Connection.TRANSACTION_READ_UNCOMMITTED,
-     *         Connection.TRANSACTION_READ_COMMITTED,
-     *         Connection.TRANSACTION_REPEATABLE_READ,
-     *         Connection.TRANSACTION_SERIALIZABLE
+     * Gets the transaction isolation level property set for this 
+     * {@code RowSet}. The transaction isolation level defines the 
+     * policy implemented on the database for maintaining the data 
+     * values consistent.
+     * 
+     * @return the current transaction isolation level. Must be one of:
+     *         <ul>
+     *         <li>{@code Connection.TRANSACTION_READ_UNCOMMITTED}</li>
+     *         <li>{@code Connection.TRANSACTION_READ_COMMITTED}</li>
+     *         <li>{@code Connection.TRANSACTION_REPEATABLE_READ}</li>
+     *         <li>{@code Connection.TRANSACTION_SERIALIZABLE}</li>
+     *         </ul>
+     * @see java.sql.Connection
      */
     public int getTransactionIsolation();
 
     /**
-     * Gets the custom mapping of SQL types for this RowSet, if any.
+     * Gets the custom mapping of SQL User-Defined Types (UDTs) and Java classes
+     * for this {@code RowSet}, if applicable.
      * 
-     * @return a Map holding the custom mappings of SQL types to Java classes
-     *         for this RowSet. By default, the Map is empty.
+     * @return the custom mappings of SQL types to Java classes.
      * @throws SQLException
      *             if an error occurs accessing the database.
      */
     public Map<String, Class<?>> getTypeMap() throws SQLException;
 
     /**
-     * Gets the URL property value for this RowSet. If there is no DataSource
-     * object specified, the RowSet uses the URL to establish a connection to
-     * the database. The default value for the URL is null.
+     * Gets the URL property value for this {@code RowSet}. If there is no
+     * {@code DataSource} object specified, the {@code RowSet} uses the URL to
+     * establish a connection to the database. The default value for the URL is
+     * {@code null}.
      * 
      * @return a String holding the value of the URL property.
      * @throws SQLException
@@ -206,40 +226,42 @@
     public String getUrl() throws SQLException;
 
     /**
-     * Gets the value of the Username property for this RowSet. The Username is
-     * used when establishing a connection to the database and should be set
-     * before the <code>execute</code> method is invoked.
+     * Gets the value of the {@code username} property for this {@code RowSet}.
+     * The {@code username} is used when establishing a connection to the
+     * database and should be set before the {@code execute} method is invoked.
      * 
-     * @return a String holing the value of the Username property.
+     * @return a {@code String} holding the value of the {@code username}
+     *         property.
      */
     public String getUsername();
 
     /**
-     * Reports if this RowSet is read only.
+     * Indicates if this {@code RowSet} is read-only.
      * 
-     * @return true if this RowSet is read only, false if it is updateable.
+     * @return {@code true} if this {@code RowSet} is read-only, {@code false}
+     *         if it is updatable.
      */
     public boolean isReadOnly();
 
     /**
-     * Removes a specified RowSetListener object from the set of listeners which
-     * will be notified of events by this RowSet.
+     * Removes a specified {@link RowSetListener} object from the set of
+     * listeners which will be notified of events by this {@code RowSet}.
      * 
      * @param theListener
-     *            the RowSetListener to remove from the set of listeners for
-     *            this RowSet.
+     *            the {@link RowSetListener} to remove from the set of listeners
+     *            for this {@code RowSet}.
      */
     public void removeRowSetListener(RowSetListener theListener);
 
     /**
-     * Sets the specified ARRAY parameter in the RowSet command with the
-     * supplied java.sql.Array value.
+     * Sets the specified {@code ARRAY} parameter in the {@code RowSet} command
+     * with the supplied {@code java.sql.Array} value.
      * 
      * @param parameterIndex
-     *            index of the parameter to set, where the first parameter has
-     *            index = 1.
+     *            the index of the parameter to set; the first parameter's index
+     *            is 1.
      * @param theArray
-     *            the java.sql.Array value to set
+     *            the {@code Array} data value to which the parameter is set.
      * @throws SQLException
      *             if an error occurs accessing the database.
      */
@@ -247,18 +269,17 @@
             throws SQLException;
 
     /**
-     * Sets the value of the specified parameter in the RowSet command with the
-     * ASCII data in the supplied java.io.InputStream value. Data is read from
-     * the InputStream until end-of-file is reached.
+     * Sets the value of the specified parameter in the {@code RowSet} command
+     * with the ASCII data in the supplied {@code java.io.InputStream} value.
+     * Data is read from the {@code InputStream} until end-of-file is reached.
      * 
      * @param parameterIndex
-     *            index of the parameter to set, where the first parameter has
-     *            index = 1.
+     *            the index of the parameter to set; the first parameter's index
+     *            is 1.
      * @param theInputStream
-     *            an InputStream containing the ASCII data to set into the
-     *            parameter value
+     *            the ASCII data value to which the parameter is set.
      * @param length
-     *            the length of the data in bytes
+     *            the length of the data in bytes.
      * @throws SQLException
      *             if an error occurs accessing the database.
      */
@@ -266,14 +287,15 @@
             int length) throws SQLException;
 
     /**
-     * Sets the value of the specified SQL NUMERIC parameter in the RowSet
-     * command with the data in the supplied java.math.BigDecimal value.
+     * Sets the value of the specified SQL {@code NUMERIC} parameter in the
+     * {@code RowSet} command with the data in the supplied {@code
+     * java.math.BigDecimal} value.
      * 
      * @param parameterIndex
-     *            index of the parameter to set, where the first parameter has
-     *            index = 1.
+     *            the index of the parameter to set; the first parameter's index
+     *            is 1.
      * @param theBigDecimal
-     *            the BigDecimal containing the value
+     *            the big decimal value to which the parameter is set.
      * @throws SQLException
      *             if an error occurs accessing the database.
      */
@@ -281,18 +303,17 @@
             throws SQLException;
 
     /**
-     * Sets the value of the specified parameter in the RowSet command with the
-     * binary data in the supplied java.io.InputStream value. Data is read from
-     * the InputStream until end-of-file is reached.
+     * Sets the value of the specified parameter in the {@code RowSet} command
+     * to the binary data in the supplied input stream. Data is read from the
+     * input stream until end-of-file is reached.
      * 
      * @param parameterIndex
-     *            index of the parameter to set, where the first parameter has
-     *            index = 1.
+     *            the index of the parameter to set; the first parameter's index
+     *            is 1.
      * @param theInputStream
-     *            an InputStream containing the binary data to set into the
-     *            parameter value
+     *            the binary data stream to which the parameter is set.
      * @param length
-     *            the length of the data in bytes
+     *            the length of the data in bytes.
      * @throws SQLException
      *             if an error occurs accessing the database.
      */
@@ -300,28 +321,28 @@
             int length) throws SQLException;
 
     /**
-     * Sets the value of the specified parameter in the RowSet command with the
-     * value of a supplied java.sql.Blob.
+     * Sets the value of the specified parameter in the {@code RowSet} command
+     * to the supplied {@code Blob} value.
      * 
      * @param parameterIndex
-     *            index of the parameter to set, where the first parameter has
-     *            index = 1.
+     *            the index of the parameter to set; the first parameter's index
+     *            is 1.
      * @param theBlob
-     *            the Blob value to set
+     *            the {@code Blob} value to which the parameter is set.
      * @throws SQLException
      *             if an error occurs accessing the database.
      */
     public void setBlob(int parameterIndex, Blob theBlob) throws SQLException;
 
     /**
-     * Sets the value of the specified parameter in the RowSet command to the
-     * supplied boolean.
+     * Sets the value of the specified parameter in the {@code RowSet} command
+     * to the supplied boolean.
      * 
      * @param parameterIndex
-     *            index of the parameter to set, where the first parameter has
-     *            index = 1.
+     *            the index of the parameter to set; the first parameter's index
+     *            is 1.
      * @param theBoolean
-     *            the boolean value to set
+     *            the {@code boolean} value to which the parameter is set.
      * @throws SQLException
      *             if an error occurs accessing the database.
      */
@@ -329,28 +350,28 @@
             throws SQLException;
 
     /**
-     * Sets the value of the specified parameter in the RowSet command to the
-     * supplied byte value.
+     * Sets the value of the specified parameter in the {@code RowSet} command
+     * to the supplied byte value.
      * 
      * @param parameterIndex
-     *            index of the parameter to set, where the first parameter has
-     *            index = 1.
+     *            the index of the parameter to set; the first parameter's index
+     *            is 1.
      * @param theByte
-     *            the byte value to set
+     *            the {@code byte} value to which the parameter is set.
      * @throws SQLException
      *             if an error occurs accessing the database.
      */
     public void setByte(int parameterIndex, byte theByte) throws SQLException;
 
     /**
-     * Sets the value of the specified parameter in the RowSet command to the
-     * supplied byte array value.
+     * Sets the value of the specified parameter in the {@code RowSet} command
+     * to the supplied byte array value.
      * 
      * @param parameterIndex
-     *            index of the parameter to set, where the first parameter has
-     *            index = 1.
+     *            the index of the parameter to set; the first parameter's index
+     *            is 1.
      * @param theByteArray
-     *            the array of bytes to set into the parameter.
+     *            the {@code Array} of {@code bytes} to which the parameter is set.
      * @throws SQLException
      *             if an error occurs accessing the database.
      */
@@ -358,17 +379,18 @@
             throws SQLException;
 
     /**
-     * Sets the value of the specified parameter in the RowSet command to the
-     * sequence of Unicode characters carried by the supplied java.io.Reader.
+     * Sets the value of the specified parameter in the {@code RowSet} command
+     * to the sequence of Unicode characters carried by the supplied {@code
+     * java.io.Reader}.
      * 
      * @param parameterIndex
-     *            index of the parameter to set, where the first parameter has
-     *            index = 1.
+     *            the index of the parameter to set; the first parameter's index
+     *            is 1.
      * @param theReader
-     *            the Reader which contains the Unicode data to set into the
-     *            parameter
+     *            the {@code Reader} which contains the Unicode data to set the
+     *            parameter.
      * @param length
-     *            the length of the data in the Reader in characters
+     *            the length of the data in the {@code Reader} in characters.
      * @throws SQLException
      *             if an error occurs accessing the database.
      */
@@ -376,84 +398,89 @@
             int length) throws SQLException;
 
     /**
-     * Sets the value of the specified parameter in the RowSet command with the
-     * value of a supplied java.sql.Clob.
+     * Sets the value of the specified parameter in the {@code RowSet} command
+     * with the value of a supplied {@code java.sql.Clob}.
      * 
      * @param parameterIndex
-     *            index of the parameter to set, where the first parameter has
-     *            index = 1.
+     *            the index of the parameter to set; the first parameter's index
+     *            is 1.
      * @param theClob
-     *            the Clob value to set
+     *            the {@code Clob} value to which the parameter is set.
      * @throws SQLException
      *             if an error occurs accessing the database.
      */
     public void setClob(int parameterIndex, Clob theClob) throws SQLException;
 
     /**
-     * Sets the Command property for this RowSet - the command is an SQL Query
-     * which runs when the <code>execute</code> method is invoked. This
-     * property is optional for datasources that do not support commands.
+     * Sets the Command property for this {@code RowSet} - the command is an SQL
+     * query which runs when the {@code execute} method is invoked. This
+     * property is optional for databases that do not support commands.
      * 
      * @param cmd
-     *            a String containing the SQL Query. Can be null.
+     *            the SQL query. Can be {@code null}.
      * @throws SQLException
      *             if an error occurs accessing the database.
      */
     public void setCommand(String cmd) throws SQLException;
 
     /**
-     * Sets the concurrency property of this RowSet. The default value is
-     * ResultSet.CONCUR_READ_ONLY.
+     * Sets the concurrency property of this {@code RowSet}. The default value
+     * is {@code ResultSet.CONCUR_READ_ONLY}.
      * 
      * @param concurrency
-     *            the new concurrency value - one of: ResultSet.CONCUR_READ_ONLY
-     *            or ResultSet.CONCUR_UPDATABLE
+     *            the concurrency value. One of:
+     *            <ul>
+     *            <li>{@code ResultSet.CONCUR_READ_ONLY}</li>
+     *            <li>{@code ResultSet.CONCUR_UPDATABLE}</li>
+     *            </ul>
      * @throws SQLException
      *             if an error occurs accessing the database.
+     * @see java.sql.ResultSet
      */
     public void setConcurrency(int concurrency) throws SQLException;
 
     /**
-     * Sets the Data Source Name property for the RowSet.
+     * Sets the database name property for the {@code RowSet}.
      * <p>
-     * The Data Source Name can be used to find a <code>DataSource</code>
-     * which has been registered with a naming service - the DataSource can then
-     * be used to create a connection to the database.
-     * 
+     * The database name can be used to find a {@link DataSource} which has been
+     * registered with a naming service - the {@link DataSource} can then be
+     * used to create a connection to the database.
+     *
      * @param name
-     *            a String with the new Data Source Name.
+     *            the database name.
      * @throws SQLException
      *             if an error occurs accessing the database.
      */
     public void setDataSourceName(String name) throws SQLException;
 
     /**
-     * Sets the value of the specified parameter in the RowSet command with the
-     * value of a supplied java.sql.Date.
+     * Sets the value of the specified parameter in the {@code RowSet} command
+     * with the value of a supplied {@code java.sql.Date}.
      * 
      * @param parameterIndex
-     *            index of the parameter to set, where the first parameter has
-     *            index = 1.
+     *            the index of the parameter to set; the first parameter's index
+     *            is 1.
      * @param theDate
-     *            the Date to use
+     *            the date value to which the parameter is set.
      * @throws SQLException
      *             if an error occurs accessing the database.
      */
     public void setDate(int parameterIndex, Date theDate) throws SQLException;
 
     /**
-     * Sets the value of the specified parameter in the RowSet command with the
-     * value of a supplied java.sql.Date, where the conversion of the Date to an
-     * SQL DATE value is calculated using a supplied Calendar.
+     * Sets the value of the specified parameter in the {@code RowSet} command
+     * with the value of a supplied {@code java.sql.Date}, where the conversion
+     * of the date to an SQL {@code DATE} value is calculated using a supplied
+     * {@code Calendar}.
      * 
      * @param parameterIndex
-     *            index of the parameter to set, where the first parameter has
-     *            index = 1.
+     *            the index of the parameter to set; the first parameter's index
+     *            is 1.
      * @param theDate
-     *            the Date to use
+     *            the date to which the parameter is set.
      * @param theCalendar
-     *            the Calendar to use in converting the Date to an SQL DATE
-     *            value
+     *            the {@code Calendar} to use in converting the Date to an SQL
+     *            {@code DATE} value.
      * @throws SQLException
      *             if an error occurs accessing the database.
      */
@@ -461,14 +488,14 @@
             throws SQLException;
 
     /**
-     * Sets the value of the specified parameter in the RowSet command with the
-     * supplied double.
+     * Sets the value of the specified parameter in the {@code RowSet} command
+     * with the supplied {@code double}.
      * 
      * @param parameterIndex
-     *            index of the parameter to set, where the first parameter has
-     *            index = 1.
+     *            the index of the parameter to set; the first parameter's index
+     *            is 1.
      * @param theDouble
-     *            the double value to set
+     *            the {@code double} value to which the parameter is set.
      * @throws SQLException
      *             if an error occurs accessing the database.
      */
@@ -476,26 +503,28 @@
             throws SQLException;
 
     /**
-     * Sets the Escape Processing status for this RowSet. If escape processing
-     * is on, the driver performs escape substitution before sending an SQL
-     * command to the database. The default value for escape processing is on.
+     * Sets the escape processing status for this {@code RowSet}. If escape
+     * processing is on, the driver performs a substitution of the escape syntax
+     * with the applicable code before sending an SQL command to the database.
+     * The default value for escape processing is {@code true}.
      * 
      * @param enable
-     *            true to enable Escape Processing, false to turn it off.
+     *            {@code true} to enable escape processing, {@code false} to
+     *            turn it off.
      * @throws SQLException
      *             if an error occurs accessing the database.
      */
     public void setEscapeProcessing(boolean enable) throws SQLException;
 
     /**
-     * Sets the value of the specified parameter in the RowSet command with the
-     * supplied float.
+     * Sets the value of the specified parameter in the {@code RowSet} command
+     * with the supplied {@code float}.
      * 
      * @param parameterIndex
-     *            index of the parameter to set, where the first parameter has
-     *            index = 1.
+     *            the index of the parameter to set; the first parameter's index
+     *            is 1.
      * @param theFloat
-     *            the float value to set
+     *            the {@code float} value to which the parameter is set.
      * @throws SQLException
      *             if an error occurs accessing the database.
      */
@@ -503,28 +532,28 @@
             throws SQLException;
 
     /**
-     * Sets the value of the specified parameter in the RowSet command with the
-     * supplied integer.
+     * Sets the value of the specified parameter in the {@code RowSet} command
+     * with the supplied {@code integer}.
      * 
      * @param parameterIndex
-     *            index of the parameter to set, where the first parameter has
-     *            index = 1.
+     *            the index of the parameter to set; the first parameter's index
+     *            is 1.
      * @param theInteger
-     *            the integer value to set
+     *            the {@code integer} value to which the parameter is set.
      * @throws SQLException
      *             if an error occurs accessing the database.
      */
     public void setInt(int parameterIndex, int theInteger) throws SQLException;
 
     /**
-     * Sets the value of the specified parameter in the RowSet command with the
-     * supplied long.
+     * Sets the value of the specified parameter in the {@code RowSet} command
+     * with the supplied {@code long}.
      * 
      * @param parameterIndex
-     *            index of the parameter to set, where the first parameter has
-     *            index = 1.
+     *            the index of the parameter to set; the first parameter's index
+     *            is 1.
      * @param theLong
-     *            the long value to set
+     *            the {@code long} value value to which the parameter is set.
      * @throws SQLException
      *             if an error occurs accessing the database.
      */
@@ -532,58 +561,61 @@
 
     /**
      * Sets the maximum number of bytes which can be returned for a column value
-     * where the column type BINARY, VARBINARY, LONGVARBINARYBINARY, CHAR,
-     * VARCHAR, or LONGVARCHAR. Data which exceeds this limit is silently
-     * discarded. For portability, a value greater than 256 is recommended.
+     * where the column type is one of {@code BINARY}, {@code VARBINARY},
+     * {@code LONGVARBINARYBINARY}, {@code CHAR}, {@code VARCHAR}, or {@code
+     * LONGVARCHAR}. Data which exceeds this limit is silently discarded. For
+     * portability, a value greater than 256 is recommended.
      * 
      * @param max
      *            the maximum size of the returned column value in bytes. 0
-     *            means unlimited.
+     *            implies no size limit.
      * @throws SQLException
      *             if an error occurs accessing the database.
      */
     public void setMaxFieldSize(int max) throws SQLException;
 
     /**
-     * Sets the maximum number of rows which can be held by the RowSet. Any
-     * additional rows are silently discarded.
+     * Sets the maximum number of rows which can be held by the {@code RowSet}.
+     * Any additional rows are silently discarded.
      * 
      * @param max
-     *            the maximum number of rows which can be held in the RowSet. 0
-     *            means no limit.
+     *            the maximum number of rows which can be held in the {@code
+     *            RowSet}. 0 means no limit.
      * @throws SQLException
      *             if an error occurs accessing the database.
      */
     public void setMaxRows(int max) throws SQLException;
 
     /**
-     * Sets the value of the specified parameter in the RowSet command to SQL
-     * NULL.
+     * Sets the value of the specified parameter in the {@code RowSet} command
+     * to SQL {@code NULL}.
      * 
      * @param parameterIndex
-     *            index of the parameter to set, where the first parameter has
-     *            index = 1.
+     *            the index of the parameter to set; the first parameter's index
+     *            is 1.
      * @param sqlType
-     *            the type of the parameter, as defined by java.sql.Types.
+     *            the type of the parameter, as defined by {@code
+     *            java.sql.Types}.
      * @throws SQLException
      *             if an error occurs accessing the database.
      */
     public void setNull(int parameterIndex, int sqlType) throws SQLException;
 
     /**
-     * Sets the value of the specified parameter in the RowSet command to SQL
-     * NULL. This form of the <code>setNull</code> method should be used for
-     * User Defined Types and REF parameters.
+     * Sets the value of the specified parameter in the {@code RowSet} command
+     * to SQL {@code NULL}. This form of the {@code setNull} method should be
+     * used for User Defined Types and {@code REF} parameters.
      * 
      * @param parameterIndex
-     *            index of the parameter to set, where the first parameter has
-     *            index = 1.
+     *            the index of the parameter to set; the first parameter's index
+     *            is 1.
      * @param sqlType
-     *            the type of the parameter, as defined by java.sql.Types.
+     *            the type of the parameter, as defined by {@code
+     *            java.sql.Types}.
      * @param typeName
-     *            the fully qualified name of an SQL User Defined Type or the
-     *            name of the SQL structured type referenced by a REF type.
-     *            Ignored if the sqlType is not a UDT or REF type.
+     *            the fully qualified name of an SQL user defined type or the
+     *            name of the SQL structured type referenced by a {@code REF}
+     *            type. Ignored if the sqlType is not a UDT or REF type.
      * @throws SQLException
      *             if an error occurs accessing the database.
      */
@@ -591,18 +623,19 @@
             throws SQLException;
 
     /**
-     * Sets the value of the specified parameter in the RowSet command to a
-     * supplied Java object.
+     * Sets the value of the specified parameter in the {@code RowSet} command
+     * to a supplied Java object.
      * <p>
      * The JDBC specification provides a standard mapping for Java objects to
      * SQL data types. Database specific types can be mapped by JDBC driver
      * specific Java types.
-     * 
+     *
      * @param parameterIndex
-     *            index of the parameter to set, where the first parameter has
-     *            index = 1.
+     *            the index of the parameter to set; the first parameter's index
+     *            is 1.
      * @param theObject
-     *            the Java object containing the data value.
+     *            the Java object containing the data value to which the
+     *            parameter is set.
      * @throws SQLException
      *             if an error occurs accessing the database.
      */
@@ -610,17 +643,17 @@
             throws SQLException;
 
     /**
-     * Sets the value of the specified parameter in the RowSet command to a
-     * supplied Java object.
+     * Sets the value of the specified parameter in the {@code RowSet} command
+     * to a supplied Java object.
      * 
      * @param parameterIndex
-     *            index of the parameter to set, where the first parameter has
-     *            index = 1.
+     *            the index of the parameter to set; the first parameter's index
+     *            is 1.
      * @param theObject
      *            the Java object containing the data value.
      * @param targetSqlType
-     *            the SQL type to send to the database, as defined in
-     *            java.sql.Types.
+     *            the SQL type to send to the database, as defined in {@code
+     *            java.sql.Types}.
      * @throws SQLException
      *             if an error occurs accessing the database.
      */
@@ -628,21 +661,21 @@
             int targetSqlType) throws SQLException;
 
     /**
-     * Sets the value of the specified parameter in the RowSet command to a
-     * supplied Java object.
+     * Sets the value of the specified parameter in the {@code RowSet} command
+     * to a supplied Java object.
      * 
      * @param parameterIndex
-     *            index of the parameter to set, where the first parameter has
-     *            index = 1.
+     *            the index of the parameter to set; the first parameter's index
+     *            is 1.
      * @param theObject
      *            the Java object containing the data value.
      * @param targetSqlType
-     *            the SQL type to send to the database, as defined in
-     *            java.sql.Types.
+     *            the SQL type to send to the database, as defined in {@code
+     *            java.sql.Types}.
      * @param scale
-     *            the number of digits after the decimal point, for
-     *            java.sql.Types.DECIMAL and java.sql.Types.NUMERIC types.
-     *            Ignored for all other types.
+     *            the number of digits after the decimal point, for {@code
+     *            java.sql.Types.DECIMAL} and {@code java.sql.Types.NUMERIC}
+     *            types. Ignored for all other types.
      * @throws SQLException
      *             if an error occurs accessing the database.
      */
@@ -650,61 +683,64 @@
             int targetSqlType, int scale) throws SQLException;
 
     /**
-     * Sets the database Password for this RowSet.
+     * Sets the database Password for this {@code RowSet}. This property is used
+     * when a connection to the database is established. Therefore it should be
+     * set prior to invoking the {@link #execute} method.
      * 
      * @param password
-     *            a string holding the new password
+     *            a {@code String} holding the password.
      * @throws SQLException
      *             if an error occurs accessing the database.
      */
     public void setPassword(String password) throws SQLException;
 
     /**
-     * Sets the Timeout value for this RowSet. The timeout is the maximum time
-     * that the driver will wait while executing a command - after this time, an
-     * SQLException is thrown.
+     * Gets the timeout for the driver when a query operation is executed. If a
+     * query takes longer than the timeout, a {@code SQLException} is thrown.
      * 
      * @param seconds
-     *            the number of seconds for the Timeout.
+     *            the number of seconds for the timeout.
      * @throws SQLException
      *             if an error occurs accessing the database.
      */
     public void setQueryTimeout(int seconds) throws SQLException;
 
     /**
-     * Sets whether the RowSet is read only or is updateable.
+     * Sets whether the {@code RowSet} is read-only or updatable.
      * 
      * @param readOnly
-     *            true to set the RowSet to readonly state, false to allow
-     *            updates.
+     *            {@code true} to set the {@code RowSet} to read-only state,
+     *            {@code false} to allow updates.
      * @throws SQLException
      *             if an error occurs accessing the database.
      */
     public void setReadOnly(boolean readOnly) throws SQLException;
 
     /**
-     * Sets the value of the specified parameter in the RowSet command to a
-     * supplied java.sql.Ref. This is sent to the database as an SQL REF value.
+     * Sets the value of the specified parameter in the {@code RowSet} command
+     * to a supplied {@code java.sql.Ref}. This is sent to the database as an
+     * SQL {@code REF} value.
      * 
      * @param parameterIndex
-     *            index of the parameter to set, where the first parameter has
-     *            index = 1.
+     *            the index of the parameter to set; the first parameter's index
+     *            is 1.
      * @param theRef
-     *            the Ref value to set
+     *            the value to which the parameter is set.
      * @throws SQLException
      *             if an error occurs accessing the database.
+     * @see java.sql.Ref
      */
     public void setRef(int parameterIndex, Ref theRef) throws SQLException;
 
     /**
-     * Sets the value of the specified parameter in the RowSet command to a
-     * supplied short integer.
+     * Sets the value of the specified parameter in the {@code RowSet} command
+     * to a supplied {@code short integer}.
      * 
      * @param parameterIndex
-     *            index of the parameter to set, where the first parameter has
-     *            index = 1.
+     *            the index of the parameter to set; the first parameter's index
+     *            is 1.
      * @param theShort
-     *            the short value to set
+     *            the value to which the parameter is set.
      * @throws SQLException
      *             if an error occurs accessing the database.
      */
@@ -712,15 +748,16 @@
             throws SQLException;
 
     /**
-     * Sets the value of the specified parameter in the RowSet command to a
-     * supplied String. The String is placed into the database as a VARCHAR or
-     * LONGVARCHAR SQL value, depending on the database limits for the length of
-     * VARCHAR values.
+     * Sets the value of the specified parameter in the {@code RowSet} command
+     * to a supplied {@code String}. The string is placed into the database as a
+     * {@code VARCHAR} or {@code LONGVARCHAR} SQL value, depending on the
+     * database limits for the length of {@code VARCHAR} values.
      * 
      * @param parameterIndex
-     *            index of the parameter to set, where the first parameter has
-     *            index = 1.
+     *            the index of the parameter to set; the first parameter's index
+     *            is 1.
      * @param theString
+     *            the value to which the parameter is set.
      * @throws SQLException
      *             if an error occurs accessing the database.
      */
@@ -728,104 +765,127 @@
             throws SQLException;
 
     /**
-     * Sets the value of the specified parameter in the RowSet command to a
-     * supplied java.sql.Time, converting to an SQL TIME value using the system
-     * default Calendar.
+     * Sets the value of the specified parameter in the {@code RowSet} command
+     * to a supplied {@code java.sql.Time}, converting it to an SQL {@code TIME}
+     * value using the system default {@code Calendar}.
      * 
      * @param parameterIndex
-     *            index of the parameter to set, where the first parameter has
-     *            index = 1.
+     *            the index of the parameter to set; the first parameter's index
+     *            is 1.
      * @param theTime
-     *            the Time value to set
+     *            the value to which the parameter is set.
      * @throws SQLException
      *             if an error occurs accessing the database.
+     * @see java.util.Calendar
+     * @see java.sql.Time
      */
     public void setTime(int parameterIndex, Time theTime) throws SQLException;
 
     /**
-     * Sets the value of the specified parameter in the RowSet command to a
-     * supplied java.sql.Time, converting to an SQL TIME value using a supplied
-     * Calendar.
+     * Sets the value of the specified parameter in the {@code RowSet} command
+     * to a supplied {@code java.sql.Time}, converting it to an SQL {@code TIME}
+     * value using a supplied {@code Calendar}.
      * 
      * @param parameterIndex
-     *            index of the parameter to set, where the first parameter has
-     *            index = 1.
+     *            the index of the parameter to set; the first parameter's index
+     *            is 1.
      * @param theTime
-     *            the Time value to set
+     *            the value to which the parameter is set.
      * @param theCalendar
-     *            the Calendar to use in the conversion operation
+     *            the {@code Calendar} to use in the conversion operation.
      * @throws SQLException
      *             if an error occurs accessing the database.
+     * @see java.util.Calendar
+     * @see java.sql.Time
      */
     public void setTime(int parameterIndex, Time theTime, Calendar theCalendar)
             throws SQLException;
 
     /**
-     * Sets the value of the specified parameter in the RowSet command to a
-     * supplied java.sql.Timestamp, converting to an SQL TIMESTAMP value using
-     * the system default Calendar.
+     * Sets the value of the specified parameter in the {@code RowSet} command
+     * to a supplied {@code java.sql.Timestamp}, converting it to an SQL {@code
+     * TIMESTAMP} value using the system default {@code Calendar}.
      * 
      * @param parameterIndex
-     *            index of the parameter to set, where the first parameter has
-     *            index = 1.
+     *            the index of the parameter to set; the first parameter's index
+     *            is 1.
      * @param theTimestamp
+     *            the value to which the parameter is set.
      * @throws SQLException
      *             if an error occurs accessing the database.
+     * @see java.util.Calendar
+     * @see java.sql.Timestamp
      */
     public void setTimestamp(int parameterIndex, Timestamp theTimestamp)
             throws SQLException;
 
     /**
-     * Sets the value of the specified parameter in the RowSet command to a
-     * supplied java.sql.Timestamp converting to an SQL TIMESTAMP value using a
-     * supplied Calendar.
+     * Sets the value of the specified parameter in the {@code RowSet} command
+     * to a supplied {@code java.sql.Timestamp}, converting it to an SQL {@code
+     * TIMESTAMP} value using a supplied {@code Calendar}.
      * 
      * @param parameterIndex
-     *            index of the parameter to set, where the first parameter has
-     *            index = 1.
+     *            the index of the parameter to set; the first parameter's index
+     *            is 1.
      * @param theTimestamp
+     *            the value to which the parameter is set.
      * @param theCalendar
-     *            the Calendar to use in the conversion operation
+     *            the {@code Calendar} to use in the conversion operation
      * @throws SQLException
      *             if an error occurs accessing the database.
+     * @see java.util.Calendar
+     * @see java.sql.Timestamp
      */
     public void setTimestamp(int parameterIndex, Timestamp theTimestamp,
             Calendar theCalendar) throws SQLException;
 
     /**
-     * Updates the target instance's transaction isolation level to one of a
-     * discrete set of possible values.
-     * 
+     * Sets the target instance's transaction isolation level to one of a
+     * discrete set of possible values. The transaction isolation level defines
+     * the policy implemented on the database for maintaining the data values
+     * consistent.
+     * <p>
+     * Keep in mind that setting a transaction isolation level has no effect
+     * unless your driver and DBMS support it.
+     *
      * @param level
-     *            the new transaction isolation level. One of:
-     *            Connection.TRANSACTION_READ_UNCOMMITTED,
-     *            Connection.TRANSACTION_READ_COMMITTED,
-     *            Connection.TRANSACTION_REPEATABLE_READ, or
-     *            Connection.TRANSACTION_SERIALIZABLE
+     *            the transaction isolation level. One of:
+     *            <ul>
+     *            <li>{@code Connection.TRANSACTION_READ_UNCOMMITTED}</li> 
+     *            <li>{@code Connection.TRANSACTION_READ_COMMITTED}</li> 
+     *            <li>{@code Connection.TRANSACTION_REPEATABLE_READ}</li> 
+     *            <li>{@code Connection.TRANSACTION_SERIALIZABLE}</li>
+     *            </ul>
      * @throws SQLException
      *             if an error occurs accessing the database.
+     * @see java.sql.Connection
      */
     public void setTransactionIsolation(int level) throws SQLException;
 
     /**
-     * Sets the type of this RowSet. By default, the type is non-scrollable.
+     * Sets the type of this {@code RowSet}. By default, the type is
+     * non-scrollable.
      * 
      * @param type
-     *            the new type for the RowSet. One of:
-     *            ResultSet.TYPE_FORWARD_ONLY,
-     *            ResultSet.TYPE_SCROLL_INSENSITIVE, or
-     *            ResultSet.TYPE_SCROLL_SENSITIVE
+     *            the type for the {@code RowSet}. One of:
+     *            <ul>
+     *            <li>{@code ResultSet.TYPE_FORWARD_ONLY}</li> 
+     *            <li>{@code ResultSet.TYPE_SCROLL_INSENSITIVE}</li> 
+     *            <li>{@code ResultSet.TYPE_SCROLL_SENSITIVE}</li>
+     *            </ul>
      * @throws SQLException
      *             if an error occurs accessing the database.
      */
     public void setType(int type) throws SQLException;
 
     /**
-     * Sets the Map used to map SQL User Defined Types to Java classes.
+     * Sets the mapping of SQL User Defined Types (UDTs) to Java classes. The
+     * Java classes must all implement the {@link java.sql.SQLData SQLData}
+     * interface.
      * 
      * @param theTypeMap
-     *            a Map which defines the names of SQL UDTs and the Java classes
-     *            to which they are mapped.
+     *            the names of SQL UDTs and the Java classes to which they are
+     *            mapped.
      * @throws SQLException
      *             if an error occurs accessing the database.
      */
@@ -833,23 +893,23 @@
             throws SQLException;
 
     /**
-     * Sets the URL used by this RowSet to access the database via a
-     * <code>DriverManager</code>. The URL is optional - an alternative is to
-     * use a Data Source Name to create a connection.
+     * Sets the URL used by this {@code RowSet} to access the database via a
+     * {@code DriverManager}. The URL is optional - an alternative is to use a
+     * database name to create a connection.
      * 
      * @param theURL
-     *            a String containing the URL for the database. Can be null.
+     *            the URL for the database. Can be {@code null}.
      * @throws SQLException
      *             if an error occurs accessing the database.
      */
     public void setUrl(String theURL) throws SQLException;
 
     /**
-     * Sets the Username property for the RowSet, used to authenticate a
-     * connection to the database.
+     * Sets the {@code Username} property for the {@code RowSet}, used to
+     * authenticate a connection to the database.
      * 
      * @param theUsername
-     *            a String containing the User Name
+     *            the new user name for this row set.
      * @throws SQLException
      *             if an error occurs accessing the database.
      */

Modified: harmony/enhanced/classlib/trunk/modules/sql/src/main/java/javax/sql/RowSetEvent.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/sql/src/main/java/javax/sql/RowSetEvent.java?rev=770130&r1=770129&r2=770130&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/sql/src/main/java/javax/sql/RowSetEvent.java (original)
+++ harmony/enhanced/classlib/trunk/modules/sql/src/main/java/javax/sql/RowSetEvent.java Thu Apr 30 09:45:40 2009
@@ -21,31 +21,32 @@
 import java.io.Serializable;
 
 /**
- * An event which is sent when specific events happen to a RowSet object. The
- * events are sent to inform registered listeners that changes have occurred to
- * the RowSet. The events covered are:
+ * An event which is sent when specific events happen to a {@link RowSet}
+ * object. The events are sent to inform registered listeners that changes have
+ * occurred to the {@code RowSet}. The events covered are:
  * <ol>
- * <li>A single row in the RowSet changes</li>
- * <li>The whole set of data in the RowSet changes</li>
- * <li>The RowSet cursor position changes</li>
+ * <li>A single row in the {@code RowSet} changes.</li>
+ * <li>The whole set of data in the {@code RowSet} changes.</li>
+ * <li>The {@code RowSet} cursor position changes.</li>
  * </ol>
- * The event contains a reference to the RowSet object which generated the
- * message so that the listeners can extract whatever information they need from
- * that reference.
- * 
+ * <p>
+ * The event contains a reference to the {@code RowSet} object which generated
+ * the message so that the listeners can extract whatever information they need
+ * from that reference.
  */
 public class RowSetEvent extends EventObject implements Serializable {
 
     private static final long serialVersionUID = -1875450876546332005L;
 
     /**
-     * Creates a RowSetEvent object containing a reference to the RowSet object
-     * that generated the event. Information about the changes that have
-     * occurred to the RowSet can be extracted from the RowSet using one or more
-     * of the query methods available on the RowSet.
+     * Creates a {@code RowSetEvent} object containing a reference to the
+     * {@link RowSet} object that generated the event. Information about the
+     * changes that have occurred to the {@code RowSet} can be extracted from
+     * the {@code RowSet} using one or more of the query methods available on
+     * the {@code RowSet}.
      * 
      * @param theSource
-     *            the RowSet which generated the event
+     *            the {@code RowSet} which generated the event.
      */
     public RowSetEvent(RowSet theSource) {
         super(theSource);

Modified: harmony/enhanced/classlib/trunk/modules/sql/src/main/java/javax/sql/RowSetInternal.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/sql/src/main/java/javax/sql/RowSetInternal.java?rev=770130&r1=770129&r2=770130&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/sql/src/main/java/javax/sql/RowSetInternal.java (original)
+++ harmony/enhanced/classlib/trunk/modules/sql/src/main/java/javax/sql/RowSetInternal.java Thu Apr 30 09:45:40 2009
@@ -22,29 +22,30 @@
 import java.sql.ResultSet;
 
 /**
- * An interface provided by a RowSet object to either a RowSetReader or a
- * RowSetWriter, providing facilities to read and update the internal state of
- * the RowSet.
+ * An interface provided by a {@code RowSet} object to let either a {@code
+ * RowSetReader} or a {@code RowSetWriter} access its internal state, thereby
+ * providing facilities to read and update the state of the {@code RowSet}.
  */
 public interface RowSetInternal {
 
     /**
-     * Gets the Connection associated with this RowSet object.
+     * Gets the connection associated with this {@code RowSet} object.
      * 
-     * @return the Connection
+     * @return the connection or {@code null}.
      * @throws SQLException
      *             if there is a problem accessing the database.
      */
     public Connection getConnection() throws SQLException;
 
     /**
-     * Gets the ResultSet that was the original (unmodified) content of the
-     * RowSet.
+     * Gets the {@code ResultSet} that was the original (unmodified) content of
+     * the {@code RowSet}.
      * <p>
-     * The ResultSet cursor is positioned before the first row of data
+     * The {@code ResultSet}'s cursor is positioned before the first row of
+     * data.
      * 
-     * @return the ResultSet that contained the original data value of the
-     *         RowSet
+     * @return the {@code ResultSet} that contained the original data value of
+     *         the {@code RowSet}.
      * @throws SQLException
      *             if there is a problem accessing the database.
      */
@@ -54,31 +55,31 @@
      * Gets the original value of the current row only. If the current row did
      * not have an original value, then an empty value is returned.
      * 
-     * @return a ResultSet containing the value of the current row only.
+     * @return a {@code ResultSet} containing the value of the current row only.
      * @throws SQLException
      *             if there is a problem accessing the database, or if the
-     *             cursor is not on a valid row (before first, after last or
-     *             pointing to the insert row).
+     *             cursor is not on a valid row (before the first row, after the
+     *             last one or pointing to the insert row).
      */
     public ResultSet getOriginalRow() throws SQLException;
 
     /**
-     * Gets the parameter values that have been set for this RowSet's command.
+     * Gets the parameter values that have been set for this {@code RowSet}'s
+     * command.
      * 
-     * @return an Object array containing the values of parameters that have
-     *         been set.
+     * @return the values of parameters that have been set.
      * @throws SQLException
      *             if there is a problem accessing the database.
      */
     public Object[] getParams() throws SQLException;
 
     /**
-     * Sets RowSetMetaData for this RowSet. The RowSetMetaData is used by a
-     * RowSetReader to set values giving information about the RowSet's columns.
+     * Sets {@code RowSetMetaData} for this {@code RowSet}. The {@code
+     * RowSetMetaData} is used by a {@code RowSetReader} to set values giving
+     * information about the {@code RowSet}'s columns.
      * 
      * @param theMetaData
-     *            a RowSetMetaData holding the metadata about the RowSet's
-     *            columns.
+     *            holds the metadata about the {@code RowSet}'s columns.
      * @throws SQLException
      *             if there is a problem accessing the database.
      */



Mime
View raw message