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 [3/10] - in
/harmony/enhanced/classlib/trunk/modules/sql/src/main/java: java/sql/
javax/sql/
Modified: harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/Clob.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/Clob.java?rev=770130&r1=770129&r2=770130&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/Clob.java (original)
+++ harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/Clob.java Thu Apr 30 09:45:40 2009
@@ -25,150 +25,155 @@
/**
* A Java interface mapping for the SQL CLOB type.
* <p>
- * An SQL CLOB type stores a large array of characters as the value in a column
- * of a database.
+ * An SQL {@code CLOB} type stores a large array of characters as the value in a
+ * column of a database.
* <p>
- * The java.sql.Clob interface provides methods for setting and retrieving data
- * in the Clob, for querying Clob data length, for searching for data within the
- * Clob.
+ * The {@code java.sql.Clob} interface provides methods for setting and
+ * retrieving data in the {@code Clob}, for querying {@code Clob} data length,
+ * for searching for data within the {@code Clob}.
*/
public interface Clob {
/**
- * Gets the value of this Clob object as an ASCII stream.
+ * Gets the value of this {@code Clob} object as an ASCII stream.
*
- * @return an ASCII InputStream giving access to the Clob data
+ * @return an ASCII {@code InputStream} giving access to the
+ * {@code Clob} data.
* @throws SQLException
- * if an error occurs accessing the Clob
+ * if an error occurs accessing the {@code Clob}.
*/
public InputStream getAsciiStream() throws SQLException;
/**
- * Gets the value of this Clob object as a java.io.Reader.
+ * Gets the data of this {@code Clob} object in a {@code java.io.Reader}.
*
- * @return a character stream Reader object giving access to the Clob data
+ * @return a character stream Reader object giving access to the {@code
+ * Clob} data.
* @throws SQLException
- * if an error occurs accessing the Clob
+ * if an error occurs accessing the {@code Clob}.
*/
public Reader getCharacterStream() throws SQLException;
/**
- * Gets a copy of a specified substring in this Clob.
+ * Gets a copy of a specified substring in this {@code Clob}.
*
* @param pos
- * the index of the start of the substring in the Clob
+ * the index of the start of the substring in the {@code Clob}.
* @param length
- * the length of the data to retrieve
- * @return A String containing the requested data
+ * the length of the data to retrieve.
+ * @return A string containing the requested data.
* @throws SQLException
- * if an error occurs accessing the Clob
+ * if an error occurs accessing the {@code Clob}.
*/
public String getSubString(long pos, int length) throws SQLException;
/**
- * Retrieves the number of characters in this Clob object.
+ * Retrieves the number of characters in this {@code Clob} object.
*
- * @return a long value with the number of character in this Clob.
+ * @return a long value with the number of character in this {@code Clob}.
* @throws SQLException
- * if an error occurs accessing the Clob
+ * if an error occurs accessing the {@code Clob}.
*/
public long length() throws SQLException;
/**
- * Retrieves the character position at which a specified Clob object appears
- * in this Clob object.
+ * Retrieves the character position at which a specified {@code Clob} object
+ * appears in this {@code Clob} object.
*
* @param searchstr
- * the specified Clob to search for
+ * the specified {@code Clob} to search for.
* @param start
- * the position within this Clob to start the search
- * @return a long value with the position at which the specified Clob occurs
- * within this Clob.
+ * the position within this {@code Clob} to start the search
+ * @return a long value with the position at which the specified {@code
+ * Clob} occurs within this {@code Clob}.
* @throws SQLException
- * if an error occurs accessing the Clob
+ * if an error occurs accessing the {@code Clob}.
*/
public long position(Clob searchstr, long start) throws SQLException;
/**
* Retrieves the character position at which a specified substring appears
- * in this Clob object.
+ * in this {@code Clob} object.
*
* @param searchstr
- * th String to search for
+ * the string to search for.
* @param start
- * the position at which to start the search within this Clob.
- * @return a long value with the position at which the specified String
- * occurs within this Clob.
+ * the position at which to start the search within this {@code
+ * Clob}.
+ * @return a long value with the position at which the specified string
+ * occurs within this {@code Clob}.
* @throws SQLException
- * if an error occurs accessing the Clob
+ * if an error occurs accessing the {@code Clob}.
*/
public long position(String searchstr, long start) throws SQLException;
/**
* Retrieves a stream which can be used to write Ascii characters to this
- * Clob object, starting at specified position.
+ * {@code Clob} object, starting at specified position.
*
* @param pos
- * the position at which to start the writing
+ * the position at which to start the writing.
* @return an OutputStream which can be used to write ASCII characters to
- * this Clob.
+ * this {@code Clob}.
* @throws SQLException
- * if an error occurs accessing the Clob
+ * if an error occurs accessing the {@code Clob}.
*/
public OutputStream setAsciiStream(long pos) throws SQLException;
/**
- * Retrieves a stream which can be used to write a stream of Unicode
- * characters to this Clob object, at a specified position.
+ * Retrieves a stream which can be used to write a stream of unicode
+ * characters to this {@code Clob} object, at a specified position.
*
* @param pos
- * the position at which to start the writing
- * @return a Writer which can be used to write Unicode characters to this
- * Clob.
+ * the position at which to start the writing.
+ * @return a Writer which can be used to write unicode characters to this
+ * {@code Clob}.
* @throws SQLException
- * if an error occurs accessing the Clob
+ * if an error occurs accessing the {@code Clob}.
*/
public Writer setCharacterStream(long pos) throws SQLException;
/**
- * Writes a given Java String to this Clob object at a specified position.
+ * Writes a given Java String to this {@code Clob} object at a specified
+ * position.
*
* @param pos
- * the position at which to start the writing
+ * the position at which to start the writing.
* @param str
- * the String to write
- * @return the number of characters written
+ * the string to write.
+ * @return the number of characters written.
* @throws SQLException
- * if an error occurs accessing the Clob
+ * if an error occurs accessing the {@code Clob}.
*/
public int setString(long pos, String str) throws SQLException;
/**
- * Writes len characters of String, starting at a specified character
- * offset, to this Clob.
+ * Writes {@code len} characters of a string, starting at a specified
+ * character offset, to this {@code Clob}.
*
* @param pos
- * the position at which to start the writing
+ * the position at which to start the writing.
* @param str
- * the String to write
+ * the String to write.
* @param offset
- * the offset within str to start writing from
+ * the offset within {@code str} to start writing from.
* @param len
- * the number of characters to write
- * @return the number of characters written
+ * the number of characters to write.
+ * @return the number of characters written.
* @throws SQLException
- * if an error occurs accessing the Clob
+ * if an error occurs accessing the {@code Clob}.
*/
public int setString(long pos, String str, int offset, int len)
throws SQLException;
/**
- * Truncates this Clob to have a specified length of characters.
+ * Truncates this {@code Clob} after the specified number of characters.
*
* @param len
- * the length in characters to truncate this Clob
+ * the length in characters giving the place to
+ * truncate this {@code Clob}.
* @throws SQLException
- * if an error occurs accessing the Clob
+ * if an error occurs accessing the {@code Clob}.
*/
public void truncate(long len) throws SQLException;
}
Modified: harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/Connection.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/Connection.java?rev=770130&r1=770129&r2=770130&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/Connection.java (original)
+++ harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/Connection.java Thu Apr 30 09:45:40 2009
@@ -20,9 +20,24 @@
import java.util.Map;
/**
- * A Connection represents a link from a Java application to a database. All SQL
+ * A connection represents a link from a Java application to a database. All SQL
* statements and results are returned within the context of a connection.
- *
+ * Database statements that are executed within this context form a
+ * database session which forms one or more closed transactions. Especially in
+ * distributed applications, multiple concurrent connections may exist accessing
+ * the same values of the database. which may lead to the following phenomena
+ * (referred to as <i>transaction isolation levels</i>):
+ * <ul>
+ * <li><i>dirty reads</i>:<br>
+ * reading values from table rows that are not committed.</br></li>
+ * <li><i>non-repeatable reads</i>:<br>
+ * reading table rows more than once in a transaction but getting back different
+ * data because other transactions have altered the rows between the reads.</br></li>
+ * <li><i>phantom reads</i>:<br>
+ * retrieving additional "phantom" rows in the course of repeated table reads
+ * because other transactions have inserted additional rows that satisfy an
+ * SQL {@code WHERE} clause</br></li>
+ * </ul>
*/
public interface Connection {
@@ -32,71 +47,72 @@
public static final int TRANSACTION_NONE = 0;
/**
- * No dirty reads are permitted. Transactions may not read a row containing
- * changes that have not yet been committed.
+ * No <i>dirty reads</i> are permitted, therefore transactions may not read
+ * a row containing uncommitted values - but does not prevent an application
+ * from <i>non-repeatable reads</i> and <i>phantom reads</i>.
*/
public static final int TRANSACTION_READ_COMMITTED = 2;
/**
- * Dirty reads (reading from table rows containing changes that have not yet
- * been committed), non-repeatable reads (reading table rows more than once
- * in a transaction but getting back different data because other
- * transactions may have altered rows between reads), and phantom reads
- * (retrieving additional "phantom" rows in the course of repeated table
- * reads because other transactions may have inserted additional rows that
- * satisfy an SQL <code>WHERE</code> clause) are <b>all permitted</b>.
+ * In the case that reading uncommitted values is allowed, the following
+ * incidents may happen which may lead to an invalid results:
+ * <ul>
+ * <li><i>dirty reads</i></li>
+ * <li><i>non-repeatable reads</i></li>
+ * <li><i>phantom reads</i></li>
+ * </ul>
*/
public static final int TRANSACTION_READ_UNCOMMITTED = 1;
/**
- * A constant indicating that dirty reads and non-repeatable reads are
- * prevented; phantom reads can occur.
+ * A constant indicating that <i>dirty reads</i> and <i>non-repeatable
+ * reads</i> are <b>prevented</b> but <i>phantom reads</i> can occur.
*/
public static final int TRANSACTION_REPEATABLE_READ = 4;
/**
- * Dirty reads (reading from table rows containing changes that have not yet
- * been committed), non-repeatable reads (reading table rows more than once
- * in a transaction but getting back different data because other
- * transactions may have altered rows between reads), and phantom reads
- * (retrieving additional "phantom" rows in the course of repeated table
- * reads because other transactions may have inserted additional rows that
- * satisfy an SQL <code>WHERE</code> clause) are <b>all prevented</b>.
+ * The constant that indicates that the following incidents are <b>all
+ * prevented</b> (the opposite of {@link #TRANSACTION_READ_UNCOMMITTED}):
+ * <ul>
+ * <li><i>dirty reads</i></li>
+ * <li><i>non-repeatable reads</i></li>
+ * <li><i>phantom reads</i></li>
+ * </ul>
*/
public static final int TRANSACTION_SERIALIZABLE = 8;
/**
- * Throws away any warnings that may have arisen for this connection.
- * Subsequent calls to {@link #getWarnings()} will return <code>null</code>
- * up until a brand new warning condition occurs.
+ * Discards all warnings that may have arisen for this connection.
+ * Subsequent calls to {@link #getWarnings()} will return {@code null}
+ * up until a new warning condition occurs.
*
* @throws SQLException
- * if there is a problem accessing the database
+ * if there is a problem accessing the database.
*/
public void clearWarnings() throws SQLException;
/**
* Causes the instant release of all database and driver connection
* resources associated with this object. Any subsequent invocations of this
- * method will have no effect.
+ * method have no effect.
* <p>
- * It is strongly recommended that all Connections are closed before they
- * are dereferenced by the application ready for garbage collection. While
- * the finalize method of the Connection will close the Connection before
- * garbage collection takes place, it is not advisable to leave the close
- * operation to take place in this way. Unpredictable performance may result
- * from closing Connections in the finalizer.
- *
+ * It is strongly recommended that all connections are closed before they
+ * are dereferenced by the application ready for garbage collection.
+ * Although the {@code finalize} method of the connection closes the
+ * connection before garbage collection takes place, it is not advisable to
+ * leave the {@code close} operation to take place in this way. Mainly
+ * because undesired side-effects may appear.
+ *
* @throws SQLException
- * if there is a problem accessing the database
+ * if there is a problem accessing the database.
*/
public void close() throws SQLException;
/**
- * Commits all of the changes made subsequent to the last commit or rollback
- * of the associated transaction. All locks in the database held by this
- * connection are also relinquished. Calling this operation on connection
- * objects in auto-commit mode is an error.
+ * Commits all of the changes made since the last {@code commit} or
+ * {@code rollback} of the associated transaction. All locks in the database
+ * held by this connection are also relinquished. Calling this operation on
+ * connection objects in {@code auto-commit} mode leads to an error.
*
* @throws SQLException
* if there is a problem accessing the database or if the target
@@ -105,41 +121,41 @@
public void commit() throws SQLException;
/**
- * Returns a new instance of <code>Statement</code> for issuing SQL
- * commands to the remote database.
+ * Returns a new instance of {@code Statement} for issuing SQL commands to
+ * the remote database.
* <p>
- * ResultSets generated by the returned Statement will default to type
- * <code>TYPE_FORWARD_ONLY</code> and concurrency level
- * <code>CONCUR_READ_ONLY</code>.
+ * {@code ResultSets} generated by the returned statement will default to
+ * type {@code ResultSet.TYPE_FORWARD_ONLY} and concurrency level {@code
+ * ResultSet.CONCUR_READ_ONLY}.
*
- * @return a <code>Statement</code> object with default settings.
+ * @return a {@code Statement} object with default settings.
* @throws SQLException
- * if there is a problem accessing the database
+ * if there is a problem accessing the database.
+ * @see ResultSet
*/
public Statement createStatement() throws SQLException;
/**
- * Returns a new instance of <code>Statement</code> whose associated
- * <code>ResultSet</code>s will have the characteristics specified in the
- * type, concurrency and holdability arguments.
+ * Returns a new instance of {@code Statement} whose associated {@code
+ * ResultSet}s have the characteristics specified in the type and
+ * concurrency arguments.
*
* @param resultSetType
- * one of :
+ * one of the following type specifiers:
* <ul>
- * <li>{@link ResultSet#TYPE_SCROLL_SENSITIVE}
- * <li>{@link ResultSet#TYPE_SCROLL_INSENSITIVE}
- * <li>{@link ResultSet#TYPE_FORWARD_ONLY}
+ * <li>{@link ResultSet#TYPE_SCROLL_SENSITIVE} </li> <li>
+ * {@link ResultSet#TYPE_SCROLL_INSENSITIVE} </li> <li>
+ * {@link ResultSet#TYPE_FORWARD_ONLY}</li>
* </ul>
* @param resultSetConcurrency
- * one of :
+ * one of the following concurrency mode specifiers:
* <ul>
- * <li>{@link ResultSet#CONCUR_UPDATABLE}
- * <li>{@link ResultSet#CONCUR_READ_ONLY}
+ * <li>{@link ResultSet#CONCUR_UPDATABLE}</li> <li>
+ * {@link ResultSet#CONCUR_READ_ONLY}</li>
* </ul>
- * @return a new instance of <code>Statement</code> capable of
- * manufacturing <code>ResultSet</code>s that satisfy the
- * specified <code>resultSetType</code> and
- * <code>resultSetConcurrency</code> values.
+ * @return a new instance of {@code Statement} capable of manufacturing
+ * {@code ResultSet}s that satisfy the specified {@code
+ * resultSetType} and {@code resultSetConcurrency} values.
* @throws SQLException
* if there is a problem accessing the database
*/
@@ -147,95 +163,94 @@
throws SQLException;
/**
- * Returns a new instance of <code>Statement</code> whose associated
- * <code>ResultSet</code>s will have the characteristics specified in the
+ * Returns a new instance of {@code Statement} whose associated
+ * {@code ResultSet}s will have the characteristics specified in the
* type, concurrency and holdability arguments.
*
* @param resultSetType
- * one of :
+ * one of the following type specifiers:
* <ul>
- * <li>{@link ResultSet#TYPE_SCROLL_SENSITIVE}
- * <li>{@link ResultSet#TYPE_SCROLL_INSENSITIVE}
- * <li>{@link ResultSet#TYPE_FORWARD_ONLY}
+ * <li>{@link ResultSet#TYPE_SCROLL_SENSITIVE}</li>
+ * <li>{@link ResultSet#TYPE_SCROLL_INSENSITIVE}</li>
+ * <li>{@link ResultSet#TYPE_FORWARD_ONLY}</li>
* </ul>
* @param resultSetConcurrency
- * one of :
+ * one of the following concurrency mode specifiers:
* <ul>
- * <li>{@link ResultSet#CONCUR_UPDATABLE}
- * <li>{@link ResultSet#CONCUR_READ_ONLY}
+ * <li>{@link ResultSet#CONCUR_UPDATABLE}</li>
+ * <li>{@link ResultSet#CONCUR_READ_ONLY}</li>
* </ul>
* @param resultSetHoldability
- * one of :
+ * one of the following holdability mode specifiers:
* <ul>
- * <li>{@link ResultSet#HOLD_CURSORS_OVER_COMMIT}
- * <li>{@link ResultSet#CLOSE_CURSORS_AT_COMMIT}
+ * <li>{@link ResultSet#HOLD_CURSORS_OVER_COMMIT}</li>
+ * <li>{@link ResultSet#CLOSE_CURSORS_AT_COMMIT}</li>
* </ul>
- * @return a new instance of <code>Statement</code> capable of
- * manufacturing <code>ResultSet</code>s that satisfy the
- * specified <code>resultSetType</code>,
- * <code>resultSetConcurrency</code> and
- * <code>resultSetHoldability</code> values.
+ * @return a new instance of {@code Statement} capable of
+ * manufacturing {@code ResultSet}s that satisfy the
+ * specified {@code resultSetType},
+ * {@code resultSetConcurrency} and
+ * {@code resultSetHoldability} values.
* @throws SQLException
- * if there is a problem accessing the database
+ * if there is a problem accessing the database.
*/
public Statement createStatement(int resultSetType,
int resultSetConcurrency, int resultSetHoldability)
throws SQLException;
/**
- * Returns a boolean indication of whether or not this connection is in the
- * auto-commit operating mode.
+ * Returns a {@code boolean} indicating whether or not this connection is in
+ * the {@code auto-commit} operating mode.
*
- * @return <code>true</code> if auto-commit is on, otherwise
- * <code>false</code>
+ * @return {@code true} if {@code auto-commit} is on, otherwise {@code
+ * false}.
* @throws SQLException
- * if there is a problem accessing the database
+ * if there is a problem accessing the database.
*/
public boolean getAutoCommit() throws SQLException;
/**
- * Gets this Connection object's current catalog name.
+ * Gets this {@code Connection} object's current catalog name.
*
- * @return the catalog name. <code>null</code> if there is no catalog
+ * @return the catalog name. {@code null} if there is no catalog
* name.
* @throws SQLException
- * if there is a problem accessing the database
+ * if there is a problem accessing the database.
*/
public String getCatalog() throws SQLException;
/**
- * Returns the kind of holdability that any <code>ResultSet</code>s made
- * from this instance will have.
+ * Returns the holdability property that any {@code ResultSet} produced by
+ * this instance will have.
*
- * @return one of :
+ * @return one of the following holdability mode specifiers:
* <ul>
- * <li>{@link ResultSet#HOLD_CURSORS_OVER_COMMIT}
- * <li>{@link ResultSet#CLOSE_CURSORS_AT_COMMIT}
+ * <li>{@link ResultSet#HOLD_CURSORS_OVER_COMMIT}</li> <li>
+ * {@link ResultSet#CLOSE_CURSORS_AT_COMMIT}</li>
* </ul>
* @throws SQLException
- * if there is a problem accessing the a database
+ * if there is a problem accessing the a database.
*/
public int getHoldability() throws SQLException;
/**
* Gets the metadata about the database referenced by this connection. The
- * returned <code>DatabaseMetaData</code> describes the database
- * topography, available stored procedures, SQL syntax and so on.
+ * returned {@code DatabaseMetaData} describes the database topography,
+ * available stored procedures, SQL syntax and so on.
*
- * @return a <code>DatabaseMetaData</code> object containing the database
- * description
+ * @return a {@code DatabaseMetaData} object containing the database
+ * description.
* @throws SQLException
- * if there is a problem accessing the a database
+ * if there is a problem accessing the a database.
*/
public DatabaseMetaData getMetaData() throws SQLException;
/**
- * Returns the present value of transaction isolation for this Connection
- * instance.
+ * Returns the transaction isolation level for this connection.
*
- * @return the transaction isolation value
+ * @return the transaction isolation value.
* @throws SQLException
- * if there is a problem accessing the database
+ * if there is a problem accessing the database.
* @see #TRANSACTION_NONE
* @see #TRANSACTION_READ_COMMITTED
* @see #TRANSACTION_READ_UNCOMMITTED
@@ -245,27 +260,26 @@
public int getTransactionIsolation() throws SQLException;
/**
- * Returns the Type Map associated with this Connection object. The type map
- * will be empty unless the application has added at least one entry.
+ * Returns the type mapping associated with this {@code Connection} object.
+ * The type mapping must be set on the application level.
*
- * @return the Type Map as a <code>java.util.Map</code>
+ * @return the Type Map as a {@code java.util.Map}.
* @throws SQLException
- * if there is a problem accessing the database
+ * if there is a problem accessing the database.
*/
public Map<String, Class<?>> getTypeMap() throws SQLException;
/**
- * Gets the first instance of any <code>SQLWarning</code> objects that may
- * have been created in the use of this connection. If at least one warning
- * has occurred then this operation returns the first one reported. A
- * <code>null</code> indicates that no warnings have occurred.
+ * Gets the first instance of any {@code SQLWarning} objects that may have
+ * been created in the use of this connection. If at least one warning has
+ * occurred then this operation returns the first one reported. A {@code
+ * null} indicates that no warnings have occurred.
* <p>
* By invoking the {@link SQLWarning#getNextWarning()} method of the
- * returned <code>SQLWarning</code> object it is possible to obtain all
- * warning objects.
- *
- * @return the first warning as an SQLWarning object (may be
- * <code>null</code>)
+ * returned {@code SQLWarning} object it is possible to obtain all of
+ * this connection's warning objects.
+ *
+ * @return the first warning as an SQLWarning object (may be {@code null}).
* @throws SQLException
* if there is a problem accessing the database or if the call
* has been made on a connection which has been previously
@@ -274,31 +288,31 @@
public SQLWarning getWarnings() throws SQLException;
/**
- * Returns a boolean indication of whether or not this connection is in the
- * closed state. The closed state may be entered into as a consequence of a
- * successful invocation of the {@link #close()} method or else if an error
- * has occurred that prevents the connection from functioning normally.
+ * Returns a {@code boolean} indicating whether or not this connection is in
+ * the {@code closed} state. The {@code closed} state may be entered into as
+ * a consequence of a successful invocation of the {@link #close()} method
+ * or else if an error has occurred that prevents the connection from
+ * functioning normally.
*
- * @return <code>true</code> if closed, otherwise <code>false</code>
+ * @return {@code true} if closed, otherwise {@code false}.
* @throws SQLException
- * if there is a problem accessing the database
+ * if there is a problem accessing the database.
*/
public boolean isClosed() throws SQLException;
/**
- * Returns a boolean indication of whether or not this connection is
- * currently in read-only state.
+ * Returns a {@code boolean} indicating whether or not this connection is
+ * currently in the {@code read-only} state.
*
- * @return <code>true</code> if in read-only state, otherwise
- * <code>false</code>.
+ * @return {@code true} if in read-only state, otherwise {@code false}.
* @throws SQLException
- * if there is a problem accessing the database
+ * if there is a problem accessing the database.
*/
public boolean isReadOnly() throws SQLException;
/**
* Returns a string representation of the input SQL statement
- * <code>sql</code> expressed in the underlying system's native SQL
+ * {@code sql} expressed in the underlying system's native SQL
* syntax.
*
* @param sql
@@ -310,49 +324,46 @@
public String nativeSQL(String sql) throws SQLException;
/**
- * Returns a new instance of <code>CallableStatement</code> that may be
- * used for making stored procedure calls to the database.
+ * Returns a new instance of {@code CallableStatement} that may be used for
+ * making stored procedure calls to the database.
*
* @param sql
* the SQL statement that calls the stored function
- * @return a new instance of <code>CallableStatement</code> representing
- * the SQL statement. <code>ResultSet</code>s emitted from this
- * <code>CallableStatement</code> will default to type
+ * @return a new instance of {@code CallableStatement} representing the SQL
+ * statement. {@code ResultSet}s emitted from this {@code
+ * CallableStatement} will default to type
* {@link ResultSet#TYPE_FORWARD_ONLY} and concurrency
* {@link ResultSet#CONCUR_READ_ONLY}.
* @throws SQLException
- * if a problem occurs accessing the database
+ * if a problem occurs accessing the database.
*/
public CallableStatement prepareCall(String sql) throws SQLException;
/**
- * Returns a new instance of <code>CallableStatement</code> that may be
- * used for making stored procedure calls to the database.
- * <code>ResultSet</code>s emitted from this
- * <code>CallableStatement</code> will satisfy the specified
- * <code>resultSetType</code> and <code>resultSetConcurrency</code>
- * values.
+ * Returns a new instance of {@code CallableStatement} that may be used for
+ * making stored procedure calls to the database. {@code ResultSet}s emitted
+ * from this {@code CallableStatement} will satisfy the specified {@code
+ * resultSetType} and {@code resultSetConcurrency} values.
*
* @param sql
* the SQL statement
* @param resultSetType
- * one of :
+ * one of the following type specifiers:
* <ul>
- * <li>{@link ResultSet#TYPE_SCROLL_SENSITIVE}
- * <li>{@link ResultSet#TYPE_SCROLL_INSENSITIVE}
- * <li>{@link ResultSet#TYPE_FORWARD_ONLY}
+ * <li>{@link ResultSet#TYPE_SCROLL_SENSITIVE}</li>
+ * <li>{@link ResultSet#TYPE_SCROLL_INSENSITIVE}</li>
+ * <li>{@link ResultSet#TYPE_FORWARD_ONLY}</li>
* </ul>
* @param resultSetConcurrency
- * one of :
+ * one of the following concurrency mode specifiers:
* <ul>
- * <li>{@link ResultSet#CONCUR_READ_ONLY}
- * <li>{@link ResultSet#CONCUR_UPDATABLE}
+ * <li>{@link ResultSet#CONCUR_READ_ONLY}</li>
+ * <li>{@link ResultSet#CONCUR_UPDATABLE}</li>
* </ul>
- * @return a new instance of <code>CallableStatement</code> representing
- * the precompiled SQL statement. <code>ResultSet</code>s emitted
- * from this <code>CallableStatement</code> will satisfy the
- * specified <code>resultSetType</code> and
- * <code>resultSetConcurrency</code> values.
+ * @return a new instance of {@code CallableStatement} representing the
+ * precompiled SQL statement. {@code ResultSet}s emitted from this
+ * {@code CallableStatement} will satisfy the specified {@code
+ * resultSetType} and {@code resultSetConcurrency} values.
* @throws SQLException
* if a problem occurs accessing the database
*/
@@ -360,258 +371,252 @@
int resultSetConcurrency) throws SQLException;
/**
- * Returns a new instance of <code>CallableStatement</code> that may be
- * used for making stored procedure calls to the database. ResultSets
- * created from this <code>CallableStatement</code> will have
- * characteristics determined by the specified type, concurrency and
- * holdability arguments.
+ * Returns a new instance of {@code CallableStatement} that may be used for
+ * making stored procedure calls to the database. {@code ResultSet}s created
+ * from this {@code CallableStatement} will have characteristics determined
+ * by the specified type, concurrency and holdability arguments.
*
* @param sql
* the SQL statement
* @param resultSetType
- * one of :
+ * one of the following type specifiers:
* <ul>
- * <li>{@link ResultSet#TYPE_SCROLL_SENSITIVE}
- * <li>{@link ResultSet#TYPE_SCROLL_INSENSITIVE}
- * <li>{@link ResultSet#TYPE_FORWARD_ONLY}
+ * <li>{@link ResultSet#TYPE_SCROLL_SENSITIVE}</li>
+ * <li>{@link ResultSet#TYPE_SCROLL_INSENSITIVE}</li>
+ * <li>{@link ResultSet#TYPE_FORWARD_ONLY}</li>
* </ul>
* @param resultSetConcurrency
- * one of :
+ * one of the following concurrency mode specifiers:
* <ul>
- * <li>{@link ResultSet#CONCUR_READ_ONLY}
- * <li>{@link ResultSet#CONCUR_UPDATABLE}
+ * <li>{@link ResultSet#CONCUR_READ_ONLY}</li>
+ * <li>{@link ResultSet#CONCUR_UPDATABLE}</li>
* </ul>
* @param resultSetHoldability
- * one of :
+ * one of the following holdability mode specifiers:
* <ul>
- * <li>{@link ResultSet#HOLD_CURSORS_OVER_COMMIT}
- * <li>{@link ResultSet#CLOSE_CURSORS_AT_COMMIT}
+ * <li>{@link ResultSet#HOLD_CURSORS_OVER_COMMIT}</li>
+ * <li>{@link ResultSet#CLOSE_CURSORS_AT_COMMIT}</li>
* </ul>
- * @return a new instance of <code>CallableStatement</code> representing
- * the precompiled SQL statement. <code>ResultSet</code>s emitted
- * from this <code>CallableStatement</code> will satisfy the
- * specified <code>resultSetType</code>,
- * <code>resultSetConcurrency</code> and
- * <code>resultSetHoldability</code> values.
+ * @return a new instance of {@code CallableStatement} representing the
+ * precompiled SQL statement. {@code ResultSet}s emitted from this
+ * {@code CallableStatement} will satisfy the specified {@code
+ * resultSetType}, {@code resultSetConcurrency} and {@code
+ * resultSetHoldability} values.
* @throws SQLException
- * if a problem occurs accessing the database
+ * if a problem occurs accessing the database.
*/
public CallableStatement prepareCall(String sql, int resultSetType,
int resultSetConcurrency, int resultSetHoldability)
throws SQLException;
/**
- * Returns a new instance of <code>PreparedStatement</code> that may be
- * used any number of times to execute parameterized requests on the
- * database server.
+ * Returns a new instance of {@code PreparedStatement} that may be used any
+ * number of times to execute parameterized requests on the database server.
* <p>
* Subject to JDBC driver support, this operation will attempt to send the
- * precompiled version of the statement to the database. Alternatively, if
- * the driver is not capable of flowing precompiled statements, the
- * statement will not reach the database server until it is executed. This
- * will have a bearing on precisely when <code>SQLException</code>
- * instances get raised.
+ * precompiled version of the statement to the database. If
+ * the driver does not support precompiled statements, the statement will
+ * not reach the database server until it is executed. This distinction
+ * determines the moment when {@code SQLException}s get raised.
* <p>
- * By default, ResultSets from the returned object will be
+ * By default, {@code ResultSet}s from the returned object will be
* {@link ResultSet#TYPE_FORWARD_ONLY} type with a
* {@link ResultSet#CONCUR_READ_ONLY} mode of concurrency.
*
* @param sql
* the SQL statement.
- * @return the PreparedStatement containing the supplied SQL statement
+ * @return the {@code PreparedStatement} containing the supplied SQL
+ * statement.
* @throws SQLException
- * if there is a problem accessing the database
+ * if there is a problem accessing the database.
*/
public PreparedStatement prepareStatement(String sql) throws SQLException;
/**
- * Creates a default PreparedStatement that can retrieve automatically
- * generated keys. Parameter <code>autoGeneratedKeys</code> may be used to
- * specify to the driver if such keys should be made accessible. This is
- * only the case when <code>sql</code> is an insert statement.
- * <p>
- * An SQL statement which may have IN parameters can be stored and
- * precompiled in a PreparedStatement. The PreparedStatement can then be
- * used to execute the statement multiple times in an efficient way.
+ * Creates a default {@code PreparedStatement} that can retrieve
+ * automatically generated keys. Parameter {@code autoGeneratedKeys} may be
+ * used to tell the driver whether such keys should be made accessible.
+ * This is only relevant when the {@code sql} statement is an {@code insert}
+ * statement.
+ * <p>
+ * An SQL statement which may have {@code IN} parameters can be stored and
+ * precompiled in a {@code PreparedStatement}. The {@code PreparedStatement}
+ * can then be then be used to execute the statement multiple times in an
+ * efficient way.
* <p>
* Subject to JDBC driver support, this operation will attempt to send the
- * precompiled version of the statement to the database. Alternatively, if
- * the driver is not capable of flowing precompiled statements, the
- * statement will not reach the database server until it is executed. This
- * will have a bearing on precisely when <code>SQLException</code>
- * instances get raised.
+ * precompiled version of the statement to the database. If
+ * the driver does not support precompiled statements, the statement will
+ * not reach the database server until it is executed. This distinction
+ * determines the moment when {@code SQLException}s get raised.
* <p>
- * By default, ResultSets from the returned object will be
+ * By default, {@code ResultSet}s from the returned object will be
* {@link ResultSet#TYPE_FORWARD_ONLY} type with a
* {@link ResultSet#CONCUR_READ_ONLY} mode of concurrency.
- *
+ *
* @param sql
* the SQL statement.
* @param autoGeneratedKeys
- * one of :
+ * one of the following generated key options:
* <ul>
- * <li>{@link Statement#RETURN_GENERATED_KEYS}
- * <li>{@link Statement#NO_GENERATED_KEYS}
+ * <li>{@link Statement#RETURN_GENERATED_KEYS}</li>
+ * <li>{@link Statement#NO_GENERATED_KEYS}</li>
* </ul>
- * @return a new <code>PreparedStatement</code> instance representing the
- * input SQL statement.
+ * @return a new {@code PreparedStatement} instance representing the input
+ * SQL statement.
* @throws SQLException
- * if there is a problem accessing the database
+ * if there is a problem accessing the database.
*/
public PreparedStatement prepareStatement(String sql, int autoGeneratedKeys)
throws SQLException;
/**
- * Creates a default PreparedStatement that can retrieve the auto-generated
- * keys designated by a supplied array. If <code>sql</code> is an SQL
- * <code>INSERT</code> statement, parameter <code>columnIndexes</code>
- * is expected to hold the index values for each column in the statement's
- * intended database table containing the autogenerated-keys of interest.
- * Otherwise <code>columnIndexes</code> is ignored.
+ * Creates a default {@code PreparedStatement} that can retrieve the
+ * auto-generated keys designated by a supplied array. If {@code sql} is an
+ * SQL {@code INSERT} statement, the parameter {@code columnIndexes} is expected
+ * to hold the index values for each column in the statement's intended
+ * database table containing the autogenerated-keys of interest. Otherwise
+ * {@code columnIndexes} is ignored.
* <p>
* Subject to JDBC driver support, this operation will attempt to send the
- * precompiled version of the statement to the database. Alternatively, if
- * the driver is not capable of flowing precompiled statements, the
- * statement will not reach the database server until it is executed. This
- * will have a bearing on precisely when <code>SQLException</code>
- * instances get raised.
+ * precompiled version of the statement to the database. If
+ * the driver does not support precompiled statements, the statement will
+ * not reach the database server until it is executed. This distinction
+ * determines the moment when {@code SQLException}s get raised.
* <p>
- * By default, ResultSets from the returned object will be
+ * By default, {@code ResultSet}s from the returned object will be
* {@link ResultSet#TYPE_FORWARD_ONLY} type with a
- * {@link ResultSet#CONCUR_READ_ONLY} mode of concurrency.
- *
+ * {@link ResultSet#CONCUR_READ_ONLY} concurrency mode.
+ *
* @param sql
* the SQL statement.
* @param columnIndexes
* the indexes of the columns for which auto-generated keys
* should be made available.
- * @return the PreparedStatement containing the supplied SQL statement
+ * @return the PreparedStatement containing the supplied SQL statement.
* @throws SQLException
- * if a problem occurs accessing the database
+ * if a problem occurs accessing the database.
*/
public PreparedStatement prepareStatement(String sql, int[] columnIndexes)
throws SQLException;
/**
- * Creates a PreparedStatement that generates ResultSets with the specified
- * values of <code>resultSetType</code> and
- * <code>resultSetConcurrency</code>.
+ * Creates a {@code PreparedStatement} that generates {@code ResultSet}s
+ * with the specified values of {@code resultSetType} and {@code
+ * resultSetConcurrency}.
*
* @param sql
- * the SQL statement. It can contain one or more '?' IN parameter
- * placeholders
+ * the SQL statement. It can contain one or more {@code '?'}
+ * {@code IN} parameter placeholders.
* @param resultSetType
- * one of :
+ * one of the following type specifiers:
* <ul>
- * <li>{@link ResultSet#TYPE_SCROLL_SENSITIVE}
- * <li>{@link ResultSet#TYPE_SCROLL_INSENSITIVE}
- * <li>{@link ResultSet#TYPE_FORWARD_ONLY}
+ * <li>{@link ResultSet#TYPE_SCROLL_SENSITIVE}</li>
+ * <li>{@link ResultSet#TYPE_SCROLL_INSENSITIVE}</li>
+ * <li>{@link ResultSet#TYPE_FORWARD_ONLY}</li>
* </ul>
* @param resultSetConcurrency
- * one of :
+ * one of the following concurrency mode specifiers:
* <ul>
- * <li>{@link ResultSet#CONCUR_READ_ONLY}
- * <li>{@link ResultSet#CONCUR_UPDATABLE}
+ * <li>{@link ResultSet#CONCUR_READ_ONLY}</li>
+ * <li>{@link ResultSet#CONCUR_UPDATABLE}</li>
* </ul>
- * @return a new instance of <code>PreparedStatement</code> containing the
- * SQL statement <code>sql</code>. <code>ResultSet</code>s
- * emitted from this <code>PreparedStatement</code> will satisfy
- * the specified <code>resultSetType</code> and
- * <code>resultSetConcurrency</code> values.
+ * @return a new instance of {@code PreparedStatement} containing the SQL
+ * statement {@code sql}. {@code ResultSet}s emitted from this
+ * {@code PreparedStatement} will satisfy the specified {@code
+ * resultSetType} and {@code resultSetConcurrency} values.
* @throws SQLException
- * if a problem occurs accessing the database
+ * if a problem occurs accessing the database.
*/
public PreparedStatement prepareStatement(String sql, int resultSetType,
int resultSetConcurrency) throws SQLException;
/**
- * Creates a PreparedStatement that generates ResultSets with the specified
- * type, concurrency and holdability
+ * Creates a {@code PreparedStatement} that generates {@code ResultSet}s
+ * with the specified type, concurrency and holdability
*
* @param sql
- * the SQL statement. It can contain one or more '?' IN parameter
- * placeholders
+ * the SQL statement. It can contain one or more {@code '?' IN}
+ * parameter placeholders.
* @param resultSetType
- * one of :
+ * one of the following type specifiers:
* <ul>
- * <li>{@link ResultSet#TYPE_SCROLL_SENSITIVE}
- * <li>{@link ResultSet#TYPE_SCROLL_INSENSITIVE}
- * <li>{@link ResultSet#TYPE_FORWARD_ONLY}
+ * <li>{@link ResultSet#TYPE_SCROLL_SENSITIVE}</li>
+ * <li>{@link ResultSet#TYPE_SCROLL_INSENSITIVE}</li>
+ * <li>{@link ResultSet#TYPE_FORWARD_ONLY}</li>
* </ul>
* @param resultSetConcurrency
- * one of :
+ * one of the following concurrency mode specifiers:
* <ul>
- * <li>{@link ResultSet#CONCUR_READ_ONLY}
- * <li>{@link ResultSet#CONCUR_UPDATABLE}
+ * <li>{@link ResultSet#CONCUR_READ_ONLY}</li>
+ * <li>{@link ResultSet#CONCUR_UPDATABLE}</li>
* </ul>
* @param resultSetHoldability
- * one of :
+ * one of the following holdability mode specifiers:
* <ul>
- * <li>{@link ResultSet#HOLD_CURSORS_OVER_COMMIT}
- * <li>{@link ResultSet#CLOSE_CURSORS_AT_COMMIT}
+ * <li>{@link ResultSet#HOLD_CURSORS_OVER_COMMIT}</li>
+ * <li>{@link ResultSet#CLOSE_CURSORS_AT_COMMIT}</li>
* </ul>
- *
- * @return a new instance of <code>PreparedStatement</code> containing the
- * SQL statement <code>sql</code>. <code>ResultSet</code>s
- * emitted from this <code>PreparedStatement</code> will satisfy
- * the specified <code>resultSetType</code>,
- * <code>resultSetConcurrency</code> and
- * <code>resultSetHoldability</code> values.
+ * @return a new instance of {@code PreparedStatement} containing the SQL
+ * statement {@code sql}. {@code ResultSet}s emitted from this
+ * {@code PreparedStatement} will satisfy the specified {@code
+ * resultSetType}, {@code resultSetConcurrency} and {@code
+ * resultSetHoldability} values.
* @throws SQLException
- * if a problem occurs accessing the database
+ * if a problem occurs accessing the database.
*/
public PreparedStatement prepareStatement(String sql, int resultSetType,
int resultSetConcurrency, int resultSetHoldability)
throws SQLException;
/**
- * Creates a default PreparedStatement that can retrieve the auto-generated
- * keys designated by a supplied array. If <code>sql</code> is an SQL
- * <code>INSERT</code> statement, <code>columnNames</code> is expected
- * to hold the names of each column in the statement's associated database
- * table containing the autogenerated-keys of interest. Otherwise
- * <code>columnNames</code> is ignored.
+ * Creates a default {@code PreparedStatement} that can retrieve the
+ * auto-generated keys designated by a supplied array. If {@code sql} is an
+ * SQL {@code INSERT} statement, {@code columnNames} is expected to hold the
+ * names of each column in the statement's associated database table
+ * containing the autogenerated-keys of interest. Otherwise {@code
+ * columnNames} is ignored.
* <p>
* Subject to JDBC driver support, this operation will attempt to send the
* precompiled version of the statement to the database. Alternatively, if
- * the driver is not capable of flowing precompiled statements, the
+ * the driver is not capable of handling precompiled statements, the
* statement will not reach the database server until it is executed. This
- * will have a bearing on precisely when <code>SQLException</code>
+ * will have a bearing on precisely <i>when</i> {@code SQLException}
* instances get raised.
* <p>
* By default, ResultSets from the returned object will be
* {@link ResultSet#TYPE_FORWARD_ONLY} type with a
- * {@link ResultSet#CONCUR_READ_ONLY} mode of concurrency.
- *
+ * {@link ResultSet#CONCUR_READ_ONLY} concurrency mode.
+ *
* @param sql
* the SQL statement.
* @param columnNames
* the names of the columns for which auto-generated keys should
* be made available.
- * @return the PreparedStatement containing the supplied SQL statement
+ * @return the PreparedStatement containing the supplied SQL statement.
* @throws SQLException
- * if a problem occurs accessing the database
+ * if a problem occurs accessing the database.
*/
public PreparedStatement prepareStatement(String sql, String[] columnNames)
throws SQLException;
/**
- * Releases <code>savepoint</code> from the present transaction. Once
- * removed, the <code>Savepoint</code> is considered invalid and should
- * not be referenced further.
+ * Releases the specified {@code savepoint} from the present transaction. Once removed,
+ * the {@code Savepoint} is considered invalid and should not be referenced
+ * further.
*
* @param savepoint
- * the object targeted for removal
+ * the object targeted for removal.
* @throws SQLException
* if there is a problem with accessing the database or if
- * <code>savepoint</code> is considered not valid in this
+ * {@code savepoint} is considered not valid in this
* transaction.
*/
public void releaseSavepoint(Savepoint savepoint) throws SQLException;
/**
- * Rolls back all updates made so far in this transaction as well as
- * relinquishing all acquired database locks. It is an error to invoke this
+ * Rolls back all updates made so far in this transaction and
+ * relinquishes all acquired database locks. It is an error to invoke this
* operation when in auto-commit mode.
*
* @throws SQLException
@@ -621,22 +626,22 @@
public void rollback() throws SQLException;
/**
- * Undoes all changes made after the supplied Savepoint object was set. This
- * method should only be used when auto-commit mode is disabled.
+ * Undoes all changes made after the supplied {@code Savepoint} object was
+ * set. This method should only be used when auto-commit mode is disabled.
*
* @param savepoint
* the Savepoint to roll back to
* @throws SQLException
- * if there is a problem accessing the database
+ * if there is a problem accessing the database.
*/
public void rollback(Savepoint savepoint) throws SQLException;
/**
- * Sets this connection's auto-commit mode on or off.
+ * Sets this connection's auto-commit mode {@code on} or {@code off}.
* <p>
* Putting a Connection into auto-commit mode means that all associated SQL
- * statements will be run and committed in their own separate transactions.
- * Alternatively, auto-commit set to off means that associated SQL
+ * statements are run and committed as separate transactions.
+ * By contrast, setting auto-commit to {@code off} means that associated SQL
* statements get grouped into transactions that need to be completed by
* explicit calls to either the {@link #commit()} or {@link #rollback()}
* methods.
@@ -645,19 +650,18 @@
* <p>
* When in this mode, commits will automatically occur upon successful SQL
* statement completion or upon successful completion of an execute.
- * Statements are not considered successfully complete until all associated
- * <code>ResultSet</code>s and output parameters have been obtained or
- * closed.
+ * Statements are not considered successfully completed until all associated
+ * {@code ResultSet}s and output parameters have been obtained or closed.
* <p>
* Calling this operation during an uncommitted transaction will result in
* it being committed.
- *
+ *
* @param autoCommit
- * boolean indication of whether to put the target connection
- * into auto-commit mode (<code>true</code>) or not (<code>false</code>)
- *
+ * {@code boolean} indication of whether to put the target
+ * connection into auto-commit mode ({@code true}) or not (
+ * {@code false}).
* @throws SQLException
- * if there is a problem accessing the database
+ * if there is a problem accessing the database.
*/
public void setAutoCommit(boolean autoCommit) throws SQLException;
@@ -669,18 +673,18 @@
* @param catalog
* the catalog name to use.
* @throws SQLException
- * if there is a problem accessing the database
+ * if there is a problem accessing the database.
*/
public void setCatalog(String catalog) throws SQLException;
/**
- * Sets the holdability of ResultSets created by this Connection.
+ * Sets the holdability of the {@code ResultSet}s created by this Connection.
*
* @param holdability
- * one of :
+ * one of the following holdability mode specifiers:
* <ul>
- * <li>{@link ResultSet#CLOSE_CURSORS_AT_COMMIT}
- * <li>{@link ResultSet#HOLD_CURSORS_OVER_COMMIT}
+ * <li>{@link ResultSet#CLOSE_CURSORS_AT_COMMIT}</li>
+ * <li>{@link ResultSet#HOLD_CURSORS_OVER_COMMIT}</li>
* <li>
* </ul>
* @throws SQLException
@@ -693,32 +697,32 @@
* <p>
* This serves as a hint to the driver, which can enable database
* optimizations.
- *
+ *
* @param readOnly
- * true to set the Connection to read only mode. false disables
- * read-only mode
+ * {@code true} to set the Connection to read only mode. {@code
+ * false} disables read-only mode.
* @throws SQLException
- * if there is a problem accessing the database
+ * if there is a problem accessing the database.
*/
public void setReadOnly(boolean readOnly) throws SQLException;
/**
- * Creates an unnamed Savepoint in the current transaction.
+ * Creates an unnamed {@code Savepoint} in the current transaction.
*
- * @return a Savepoint object for this savepoint.
+ * @return a {@code Savepoint} object for this savepoint.
* @throws SQLException
- * if there is a problem accessing the database
+ * if there is a problem accessing the database.
*/
public Savepoint setSavepoint() throws SQLException;
/**
- * Creates a named Savepoint in the current transaction.
+ * Creates a named {@code Savepoint} in the current transaction.
*
* @param name
- * the name to use for the new Savepoint.
- * @return a Savepoint object for this savepoint.
+ * the name to use for the new {@code Savepoint}.
+ * @return a {@code Savepoint} object for this savepoint.
* @throws SQLException
- * if there is a problem accessing the database
+ * if there is a problem accessing the database.
*/
public Savepoint setSavepoint(String name) throws SQLException;
@@ -727,10 +731,10 @@
* <p>
* If this method is called during a transaction, the results are
* implementation defined.
- *
+ *
* @param level
* the new transaction isolation level to use from the following
- * list of possible values :
+ * list of possible values:
* <ul>
* <li>{@link #TRANSACTION_READ_COMMITTED}
* <li>{@link #TRANSACTION_READ_UNCOMMITTED}
@@ -739,21 +743,19 @@
* </ul>
* @throws SQLException
* if there is a problem with the database or if the value of
- * <code>level</code> is not one of the expected constant
- * values.
+ * {@code level} is not one of the expected constant values.
*/
public void setTransactionIsolation(int level) throws SQLException;
/**
- * Sets the <code>TypeMap</code> for this connection. The input
- * <code>map</code> should contain mappings between complex Java and SQL
- * types.
+ * Sets the {@code TypeMap} for this connection. The input {@code map}
+ * should contain mappings between complex Java and SQL types.
*
* @param map
- * the new type map
+ * the new type map.
* @throws SQLException
- * if there is a problem accessing the database or if
- * <code>map</code> is not an instance of {@link Map}.
+ * if there is a problem accessing the database or if {@code
+ * map} is not an instance of {@link Map}.
*/
public void setTypeMap(Map<String, Class<?>> map) throws SQLException;
}
Modified: harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/DataTruncation.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/DataTruncation.java?rev=770130&r1=770129&r2=770130&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/DataTruncation.java (original)
+++ harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/DataTruncation.java Thu Apr 30 09:45:40 2009
@@ -21,9 +21,9 @@
/**
* An exception which is thrown when a JDBC driver unexpectedly truncates a data
- * value either when reading or when writing data.
- *
- * The SQLState value for a <code>DataTruncation</code> is <code>01004</code>.
+ * value either when reading (resulting in warning), or when writing data
+ * (resulting in an error). The {@code SQLState} error code for truncated data
+ * is {@code 01004}.
*/
public class DataTruncation extends SQLWarning implements Serializable {
@@ -46,23 +46,24 @@
private static final int THE_ERROR_CODE = 0;
/**
- * Creates a DataTruncation. The Reason is set to "Data truncation", the
- * ErrorCode is set to the SQLException default value and other fields are
- * set to the values supplied on this method.
+ * Creates the {@code DataTruncation} object. The reason is set to {@code
+ * "Data truncation"}, the {@code ErrorCode} is set to the {@code
+ * SQLException} default value, and the other fields are set to the values
+ * supplied as arguments.
*
* @param index
* the Index value of the column value or parameter that was
- * truncated
+ * truncated.
* @param parameter
- * true if it was a Parameter value that was truncated, false
- * otherwise
+ * {@code true} if it was a parameter value that was truncated,
+ * {@code false} otherwise.
* @param read
- * true if the truncation occurred on a read operation, false
- * otherwise
+ * {@code true} if the truncation occurred on a read operation,
+ * {@code false} otherwise.
* @param dataSize
- * the original size of the truncated data
+ * the original size of the truncated data.
* @param transferSize
- * the size of the data after truncation
+ * the size of the data after truncation.
*/
public DataTruncation(int index, boolean parameter, boolean read,
int dataSize, int transferSize) {
@@ -78,7 +79,7 @@
* Gets the number of bytes of data that should have been read/written.
*
* @return the number of bytes that should have been read or written. The
- * value may be set to -1 if the size is unknown.
+ * value is set to {@code -1} if the size is unknown.
*/
public int getDataSize() {
return dataSize;
@@ -96,8 +97,8 @@
/**
* Gets whether the value truncated was a parameter value or a column value.
*
- * @return true if the value truncated was a Parameter value, false if it
- * was a column value
+ * @return {@code true} if the value truncated was a parameter value,
+ * {@code false} if it was a column value.
*/
public boolean getParameter() {
return parameter;
@@ -107,18 +108,18 @@
* Gets whether the value was truncated on a read operation or a write
* operation
*
- * @return true if the value was truncated on a read operation, false
- * otherwise.
+ * @return {@code true} if the value was truncated on a read operation,
+ * {@code false} otherwise.
*/
public boolean getRead() {
return read;
}
/**
- * Gets the number of bytes of data that was actually read or written
+ * Gets the number of bytes of data that was actually read or written.
*
* @return the number of bytes actually read/written. The value may be set
- * to -1 if the size is unknown.
+ * to {@code -1} if the size is unknown.
*/
public int getTransferSize() {
return transferSize;