You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@harmony.apache.org by te...@apache.org on 2009/04/30 11:45:42 UTC
svn commit: r770130 [9/10] - in
/harmony/enhanced/classlib/trunk/modules/sql/src/main/java: java/sql/
javax/sql/
Modified: harmony/enhanced/classlib/trunk/modules/sql/src/main/java/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.
*/