harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From telli...@apache.org
Subject svn commit: r770130 [7/10] - in /harmony/enhanced/classlib/trunk/modules/sql/src/main/java: java/sql/ javax/sql/
Date Thu, 30 Apr 2009 09:45:42 GMT
Modified: harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/ResultSetMetaData.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/ResultSetMetaData.java?rev=770130&r1=770129&r2=770130&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/ResultSetMetaData.java (original)
+++ harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/ResultSetMetaData.java Thu Apr 30 09:45:40 2009
@@ -18,54 +18,55 @@
 package java.sql;
 
 /**
- * Provides information about the columns in a ResultSet.
+ * Provides information about the columns returned in a {@code ResultSet}.
  */
 public interface ResultSetMetaData {
 
     /**
-     * Indicates that a column cannot contain NULL values
+     * Indicates that a column cannot contain {@code NULL} values.
      */
     public static final int columnNoNulls = 0;
 
     /**
-     * Indicates that a column can contain NULL values
+     * Indicates that a column can contain {@code NULL} values.
      */
     public static final int columnNullable = 1;
 
     /**
-     * Indicates that it is unknown whether a column can contain NULLs or not
+     * Indicates that it is unknown whether a column can contain {@code NULL}s or not.
      */
     public static final int columnNullableUnknown = 2;
 
     /**
-     * Returns the title of indexed columns catalog
+     * Returns the title of an indexed column's catalog.
      * 
      * @param column
-     *            the column index, starting at 1
-     * @return the catalog title
+     *            the column index, starting at 1.
+     * @return the catalog title.
      * @throws SQLException
-     *             if there is a database error
+     *             if there is a database error.
      */
     public String getCatalogName(int column) throws SQLException;
 
     /**
      * Returns the fully-qualified type of the class that is produced when
-     * invoking ResultSet.getObject to recover this columns value.
+     * invoking {@code ResultSet.getObject} to recover this column's value.
      * 
      * @param column
-     *            the column index, starting at 1
-     * @return the fully-qualified class name
+     *            the column index, starting at 1.
+     * @return the fully-qualified class name.
      * @throws SQLException
-     *             if there is a database error
+     *             if there is a database error.
+     * @see ResultSet#getObject
      */
     public String getColumnClassName(int column) throws SQLException;
 
     /**
-     * Returns a count of the columns in this set of results.
+     * Returns number of columns contained in the associated result set.
      * 
-     * @return the column count
+     * @return the column count.
      * @throws SQLException
-     *             if there is a database error
+     *             if there is a database error.
      */
     public int getColumnCount() throws SQLException;
 
@@ -74,10 +75,10 @@
      * of characters.
      * 
      * @param column
-     *            the column index, starting at 1
-     * @return the column's max width
+     *            the column index, starting at 1.
+     * @return the column's max width.
      * @throws SQLException
-     *             if there is a database error
+     *             if there is a database error.
      */
     public int getColumnDisplaySize(int column) throws SQLException;
 
@@ -86,76 +87,78 @@
      * title needs to be displayed.
      * 
      * @param column
-     *            the column index, starting at 1
-     * @return the column's title
+     *            the column index, starting at 1.
+     * @return the column's title.
      * @throws SQLException
-     *             if there is a database error
+     *             if there is a database error.
      */
     public String getColumnLabel(int column) throws SQLException;
 
     /**
-     * Returns the title of the indexed column
+     * Returns the title of the indexed column.
      * 
      * @param column
-     *            the column index, starting at 1
-     * @return the column title
+     *            the column index, starting at 1.
+     * @return the column title.
      * @throws SQLException
-     *             if there is a database error
+     *             if there is a database error.
      */
     public String getColumnName(int column) throws SQLException;
 
     /**
-     * Returns the type of the indexed column
+     * Returns the type of the indexed column as SQL type code.
      * 
      * @param column
-     *            the column index, starting at 1
-     * @return the column type
+     *            the column index, starting at 1.
+     * @return the column type code.
      * @throws SQLException
-     *             if there is a database error
+     *             if there is a database error.
+     * @see Types
      */
     public int getColumnType(int column) throws SQLException;
 
     /**
-     * Returns the type name of the indexed column
+     * Returns the type name of the indexed column.
      * 
      * @param column
-     *            the column index, starting at 1
-     * @return the type name
+     *            the column index, starting at 1.
+     * @return the type name.
      * @throws SQLException
-     *             if there is a database error
+     *             if there is a database error.
      */
     public String getColumnTypeName(int column) throws SQLException;
 
     /**
-     * Returns the decimal precision of the indexed column
+     * Returns the decimal precision of the indexed column.
      * 
      * @param column
-     *            the column index, starting at 1
-     * @return the precision
+     *            the column index, starting at 1.
+     * @return the precision.
      * @throws SQLException
-     *             if there is a database error
+     *             if there is a database error.
      */
     public int getPrecision(int column) throws SQLException;
 
     /**
-     * Returns the number of decimal places in the indexed column.
+     * Returns the number of digits to the right of the decimal point of the
+     * indexed column.
      * 
      * @param column
-     *            the column index, starting at 1
-     * @return number of decimal places
+     *            the column index, starting at 1.
+     * @return number of decimal places.
      * @throws SQLException
-     *             if there is a database error
+     *             if there is a database error.
      */
     public int getScale(int column) throws SQLException;
 
     /**
-     * Returns the name of the indexed columns schema
+     * Returns the name of the indexed columns schema.
      * 
      * @param column
-     *            the column index, starting at 1
-     * @return the name of the columns schema
+     *            the column index, starting at 1.
+     * @return the name of the columns schema.
      * @throws SQLException
-     *             if there is a database error
+     *             if there is a database error.
      */
     public String getSchemaName(int column) throws SQLException;
 
@@ -163,57 +166,58 @@
      * Returns the title of the indexed columns table.
      * 
      * @param column
-     *            the column index, starting at 1
-     * @return the table title
+     *            the column index, starting at 1.
+     * @return the table title.
      * @throws SQLException
-     *             if there is a database error
+     *             if there is a database error.
      */
     public String getTableName(int column) throws SQLException;
 
     /**
-     * Returns and indication of whether the indexed column has automatic
-     * numbering and is therefore read-only
+     * Returns an indication of whether the indexed column is automatically
+     * incremented and is therefore read-only.
      * 
      * @param column
-     *            the column index, starting at 1
-     * @return true if it is automatically numbered, false otherwise
+     *            the column index, starting at 1.
+     * @return {@code true} if it is automatically numbered, {@code false}
+     *         otherwise.
      * @throws SQLException
-     *             if there is a database error
+     *             if there is a database error.
      */
     public boolean isAutoIncrement(int column) throws SQLException;
 
     /**
-     * Returns an indicator of whether the case of the indexed column is
-     * important
+     * Returns an indication of whether the case of the indexed column is
+     * important.
      * 
      * @param column
-     *            the column index, starting at 1
-     * @return true if case matters, false otherwise
+     *            the column index, starting at 1.
+     * @return {@code true} if case matters, {@code false} otherwise.
      * @throws SQLException
-     *             if there is a database error
+     *             if there is a database error.
      */
     public boolean isCaseSensitive(int column) throws SQLException;
 
     /**
-     * Returns if the indexed column contains a monetary amount.
+     * Returns whether the indexed column contains a monetary amount.
      * 
      * @param column
-     *            the column index, starting at 1
-     * @return true if it is a monetary value, false otherwise
+     *            the column index, starting at 1.
+     * @return {@code true} if it is a monetary value, {@code false} otherwise.
      * @throws SQLException
-     *             if there is a database error
+     *             if there is a database error.
      */
     public boolean isCurrency(int column) throws SQLException;
 
     /**
      * Returns an indication of whether writing to the indexed column is
-     * guaranteed to be successful
+     * guaranteed to be successful.
      * 
      * @param column
-     *            the column index, starting at 1
-     * @return true if the write is guaranteed, false otherwise
+     *            the column index, starting at 1.
+     * @return {@code true} if the write is guaranteed, {@code false} otherwise.
      * @throws SQLException
-     *             if there is a database error
+     *             if there is a database error.
      */
     public boolean isDefinitelyWritable(int column) throws SQLException;
 
@@ -221,22 +225,22 @@
      * Returns whether the indexed column is nullable.
      * 
      * @param column
-     *            the column index, starting at 1
-     * @return true if it is nullable, false otherwise
+     *            the column index, starting at 1.
+     * @return {@code true} if it is nullable, {@code false} otherwise.
      * @throws SQLException
-     *             if there is a database error
+     *             if there is a database error.
      */
     public int isNullable(int column) throws SQLException;
 
     /**
      * Returns an indication of whether writing to the indexed column is
-     * guaranteed to be unsuccessful
+     * guaranteed to be unsuccessful.
      * 
      * @param column
-     *            the column index, starting at 1
-     * @return true if the column is read-only, false otherwise
+     *            the column index, starting at 1.
+     * @return {@code true} if the column is read-only, {@code false} otherwise.
      * @throws SQLException
-     *             if there is a database error
+     *             if there is a database error.
      */
     public boolean isReadOnly(int column) throws SQLException;
 
@@ -244,22 +248,23 @@
      * Returns an indication of whether the indexed column is searchable.
      * 
      * @param column
-     *            the column index, starting at 1
-     * @return true if the indexed column is searchable, false otherwise.
+     *            the column index, starting at 1.
+     * @return {@code true} if the indexed column is searchable, {@code false}
+     *         otherwise.
      * @throws SQLException
-     *             if there is a database error
+     *             if there is a database error.
      */
     public boolean isSearchable(int column) throws SQLException;
 
     /**
-     * Returns an indicator of whether the values contained in the indexed
+     * Returns an indication of whether the values contained in the indexed
      * column are signed.
      * 
      * @param column
-     *            the column index, starting at 1
-     * @return true if they are signed, false otherwise
+     *            the column index, starting at 1.
+     * @return {@code true} if they are signed, {@code false} otherwise.
      * @throws SQLException
-     *             if there is a database error
+     *             if there is a database error.
      */
     public boolean isSigned(int column) throws SQLException;
 
@@ -268,10 +273,10 @@
      * possible.
      * 
      * @param column
-     *            the column index, starting at 1
-     * @return true if it is possible to write, false otherwise
+     *            the column index, starting at 1.
+     * @return {@code true} if it is possible to write, {@code false} otherwise.
      * @throws SQLException
-     *             if there is a database error
+     *             if there is a database error.
      */
     public boolean isWritable(int column) throws SQLException;
 }

Modified: harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/SQLData.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/SQLData.java?rev=770130&r1=770129&r2=770130&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/SQLData.java (original)
+++ harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/SQLData.java Thu Apr 30 09:45:40 2009
@@ -18,89 +18,97 @@
 package java.sql;
 
 /**
- * An interface for the custom mapping of an SQL User Defined Type (UDT) to a
- * Java Class. The Java Class object will be added to the Connection's type map
- * with the SQL Name of the UDT which it maps.
+ * An interface for the custom mapping of an SQL <i>User Defined Type</i> (UDT)
+ * to a Java class. The Java class object is added to the connection's type map
+ * paired with the SQL name of the corresponding UDT.
  * <p>
- * Usually within an implementation of SQLData, there is a corresponding field
- * for every attribute of an SQL type, or only one field if the type is SQL
- * DISTINCT. When the UDT is returned within a ResultSet, it is accessed with
- * the ResultSet.getObject method and is returned as an Object which is an
- * instance of the class defined by the SQLData mapping. The application can use
- * this object just like any other Java object and can store changes back into
- * the database using the PreparedStatement.setObject method which performs the
- * reverse mapping into the SQL UDT.
+ * Usually within an implementation of {@code SQLData}, there is a corresponding
+ * field for every attribute of an SQL type, but only one field, if the type is
+ * SQL {@code DISTINCT}. When the UDT is returned within a {@code ResultSet}, it
+ * is accessed with the {@link ResultSet#getObject} method and is returned as an
+ * object which is an instance of the class defined by the {@code SQLData}
+ * mapping. The application can use this object just like any other Java object
+ * and can store changes back into the database using the
+ * {@link PreparedStatement#setObject} method which performs the reverse mapping
+ * into the SQL {@code UDT}.
  * <p>
- * It is standard for an implementation for a custom mapping to be generated by
- * a tool. The tool usually requires the name of the SQL UDT, the name of the
- * class which it is going to be mapped to, and the field names to which the UDT
- * attributes will be mapped. The tool can then implement the SQLData readSQL
- * and writeSQL methods. readSQL reads attributes from an SQLInput object, and
- * writeSQL writes them. This is done via SQLInput and SQLOutput method calls
- * respectively
+ * Normally the implementation of a custom mapping is generated by
+ * a tool requiring the name of the SQL {@code UDT}, the name
+ * of the class which it is going to be mapped to, and the field names to which
+ * the UDT attributes are mapped. The tool can then implement the {@code
+ * SQLData}, {@code readSQL}, and {@code writeSQL} methods. {@code readSQL} reads
+ * attributes from an {@code SQLInput} object, and {@code writeSQL} writes them.
+ * This is done via {@code SQLInput} and {@code SQLOutput} method calls
+ * respectively.
  * <p>
- * Ordinarily a programmer would not call SQLData methods directly. Similarly
- * SQLInput and SQLOutput methods are not usually called directly.
+ * Ordinarily an application would not call {@code SQLData} methods directly.
+ * Similarly {@code SQLInput} and {@code SQLOutput} methods are not usually
+ * called directly.
  */
 public interface SQLData {
 
     /**
-     * Gets the SQL name of the User Defined Type (UDT) that this object
+     * Gets the SQL name of the <i>User Defined Type</i> (UDT) that this object
      * represents. This method, usually invoked by the JDBC driver, retrieves
-     * the name of the UDT instance associated with this SQLData object.
+     * the name of the UDT instance associated with this {@code SQLData} object.
      * 
      * @return a string with UDT type name for this object mapping, passed to
-     *         readSQL when the object was created
+     *         {@code readSQL} when the object was created.
      * @throws SQLException
-     *             if a database error occurs
+     *             if a database error occurs.
      */
     public String getSQLTypeName() throws SQLException;
 
     /**
      * Reads data from the database into this object. This method follows these
      * steps:
+     * <p>
      * <ul>
      * <li>Utilize the passed input stream to read the attributes or entries of
      * the SQL type</li>
      * <li>This is carried out by reading each entry from the input stream,
-     * ordered as the are the SQL definition.</li>
+     * ordered as they are in the SQL definition.</li>
      * <li>Assign the data to the appropriate fields or elements. This is done
-     * by calling the relevant reader method for the type involved (eg.
-     * SQLInput.readString, SQLInputreadBigDecimal). If the type is distinct,
-     * then read its only data entry. For structured types, read every entry.</li>
+     * by calling the relevant reader method for the type involved (e.g. {@code
+     * SQLInput.readString}, {@code SQLInputreadBigDecimal}). If the type is
+     * distinct, then read its only data entry. For structured types, read every
+     * entry.</li>
      * </ul>
+     * <p>
      * The supplied input stream is typically initialized by the calling JDBC
-     * driver with the type map before readSQL is called.
-     * 
+     * driver with the type map before {@code readSQL} is called.
+     *
      * @param stream
-     *            the SQLInput stream from which the type map data is read for
-     *            the custom mapping
+     *            the {@code SQLInput} stream from which the type map data is
+     *            read for the custom mapping.
      * @param typeName
-     *            the SQL Type name for the type which is being mapped
+     *            the SQL type name for the type which is being mapped.
      * @throws SQLException
-     *             if a database error occurs
+     *             if a database error occurs.
+     * @see SQLInput
      */
     public void readSQL(SQLInput stream, String typeName) throws SQLException;
 
     /**
-     * Writes the object to a supplied SQLOutput data stream, writing it out as
-     * an SQL value to the data source.
+     * Writes the object to a supplied {@code SQLOutput} data stream, writing it
+     * out as an SQL value to the data source.
      * <p>
      * This method follows the following steps:
      * <ul>
      * <li>Write each attribute of the SQL type to the output stream.</li>
      * <li>Write each item by calling a method on the output stream, in the
      * order they appear in the SQL definition of the type. Use the appropriate
-     * SQLOutput methods (eg. writeInt, writeString). Write a single data
-     * element for a Distinct type. For a Structured type, write a value for
-     * each attribute of the the SQL type.</li>
+     * {@code SQLOutput} methods (e.g. {@code writeInt}, {@code writeString}).
+     * Write a single data element for a distinct type. For a structured type,
+     * write a value for each attribute of the the SQL type.</li>
      * </ul>
      * 
      * @param stream
-     *            the SQLOutput stream to use to write out the data for the
-     *            custom mapping
+     *            the {@code SQLOutput} stream to use to write out the data for
+     *            the custom mapping.
      * @throws SQLException
-     *             if a database error occurs
+     *             if a database error occurs.
+     * @see SQLOutput
      */
     public void writeSQL(SQLOutput stream) throws SQLException;
 }

Modified: harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/SQLException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/SQLException.java?rev=770130&r1=770129&r2=770130&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/SQLException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/SQLException.java Thu Apr 30 09:45:40 2009
@@ -20,25 +20,26 @@
 import java.io.Serializable;
 
 /**
- * An Exception class that is used in conjunction with JDBC operations. It
- * provides information about problems encountered with Database access and
+ * An {@code Exception} class that is used in conjunction with JDBC operations.
+ * It provides information about problems encountered with database access and
  * other problems related to JDBC
  * <p>
- * The SQLException class provides the following information:
+ * The {@code SQLException} class provides the following information:
  * <ul>
- * <li>A standard Java exception message, as a String
- * <li>An SQLState string. This is an error description string which follows
- * either the SQL 99 conventions or the XOPEN SQLstate conventions. The
- * potential values of the SQLState string are described in each of the
- * specifications. Which of the conventions is being used by the SQLState string
- * can be discovered by using the getSQLStateType method of the DatabaseMetaData
- * interface.
- * <li>An Error Code, an an integer. The error code is specific to each
- * database vendor and is typically the error code returned by the database
- * itself.
- * <li>A chain to a next Exception, if relevant, which can give access to
- * additional error information.
+ * <li>A standard Java exception message, as a {@code String}</li>
+ * <li>An {@code SQLState} string. This is an error description string which
+ * follows either the SQL 99 conventions or the X/OPEN {@code SQLstate}
+ * conventions. The potential values of the {@code SQLState} string are
+ * described in each of the specifications. Which of the conventions is being
+ * used by the {@code SQLState} string can be discovered by using the {@code
+ * getSQLStateType} method of the {@code DatabaseMetaData} interface.</li>
+ * <li>An error code, an an integer. The error code is specific to each database
+ * vendor and is typically the error code returned by the database itself.</li>
+ * <li>A chain to a next {@code Exception}, if relevant, which can give access
+ * to additional error information.</li>
  * </ul>
+ * 
+ * @see DatabaseMetaData
  */
 public class SQLException extends Exception implements Serializable {
 
@@ -51,16 +52,17 @@
     private SQLException next = null;
 
     /**
-     * Creates an SQLException object. The Reason string is set to null, the
-     * SQLState string is set to null and the Error Code is set to 0.
+     * Creates an {@code SQLException} object. The reason string is set to
+     * {@code null}, the {@code SQLState} string is set to {@code null} and the
+     * error code is set to 0.
      */
     public SQLException() {
         super();
     }
 
     /**
-     * Creates an SQLException object. The Reason string is set to the given
-     * reason string, the SQLState string is set to null and the Error Code is
+     * Creates an {@code SQLException} object. The reason string is set to the given
+     * reason string, the {@code SQLState} string is set to {@code null} and the error code is
      * set to 0.
      * 
      * @param theReason
@@ -71,30 +73,31 @@
     }
 
     /**
-     * Creates an SQLException object. The Reason string is set to the given
-     * reason string, the SQLState string is set to the given SQLState string
-     * and the Error Code is set to 0.
+     * Creates an {@code SQLException} object. The reason string is set to the
+     * given reason string, the {@code SQLState} string is set to the given
+     * {@code SQLState} string and the error code is set to 0.
      * 
      * @param theReason
-     *            the string to use as the Reason string
+     *            the string to use as the reason string.
      * @param theSQLState
-     *            the string to use as the SQLState string
+     *            the string to use as the {@code SQLState} string.
      */
     public SQLException(String theReason, String theSQLState) {
         this(theReason, theSQLState, 0);
     }
 
     /**
-     * Creates an SQLException object. The Reason string is set to the given
-     * reason string, the SQLState string is set to the given SQLState string
-     * and the Error Code is set to the given error code value.
+     * Creates an {@code SQLException} object. The reason string is set to the
+     * given reason string, the {@code SQLState} string is set to the given
+     * {@code SQLState} string and the error code is set to the given error code
+     * value.
      * 
      * @param theReason
-     *            the string to use as the Reason string
+     *            the string to use as the reason string.
      * @param theSQLState
-     *            the string to use as the SQLState string
+     *            the string to use as the {@code SQLState} string.
      * @param theErrorCode
-     *            the integer value for the error code
+     *            the integer value for the error code.
      */
     public SQLException(String theReason, String theSQLState, int theErrorCode) {
         super(theReason);
@@ -103,47 +106,52 @@
     }
 
     /**
-     * Returns the integer error code for this SQLException
+     * Returns the integer error code for this {@code SQLException}.
      * 
-     * @return The integer error code for this SQLException. The meaning of the
-     *         code is specific to the vendor of the database.
+     * @return The integer error code for this {@code SQLException}. The meaning
+     *         of the code is specific to the vendor of the database.
      */
     public int getErrorCode() {
         return vendorCode;
     }
 
     /**
-     * Retrieves the SQLException chained to this SQLException, if any.
+     * Retrieves the {@code SQLException} chained to this {@code SQLException},
+     * if any.
      * 
-     * @return The SQLException chained to this SQLException. null if there is
-     *         no SQLException chained to this SQLException.
+     * @return The {@code SQLException} chained to this {@code SQLException}.
+     *         {@code null} if there is no {@code SQLException} chained to this
+     *         {@code SQLException}.
      */
     public SQLException getNextException() {
         return next;
     }
 
     /**
-     * Retrieves the SQLState description string for this SQLException object
+     * Retrieves the {@code SQLState} description string for this {@code
+     * SQLException} object.
      * 
-     * @return The SQLState string for this SQLException object. This is an
-     *         error description string which follows either the SQL 99
-     *         conventions or the XOPEN SQLstate conventions. The potential
-     *         values of the SQLState string are described in each of the
-     *         specifications. Which of the conventions is being used by the
-     *         SQLState string can be discovered by using the getSQLStateType
-     *         method of the DatabaseMetaData interface.
+     * @return The {@code SQLState} string for this {@code SQLException} object.
+     *         This is an error description string which follows either the SQL
+     *         99 conventions or the X/OPEN {@code SQLstate} conventions. The
+     *         potential values of the {@code SQLState} string are described in
+     *         each of the specifications. Which of the conventions is being
+     *         used by the {@code SQLState} string can be discovered by using
+     *         the {@code getSQLStateType} method of the {@code
+     *         DatabaseMetaData} interface.
      */
     public String getSQLState() {
         return SQLState;
     }
 
     /**
-     * Adds the SQLException to the end of this SQLException chain.
+     * Adds the SQLException to the end of this {@code SQLException} chain.
      * 
      * @param ex
-     *            the new SQLException to be added to the end of the chain
+     *            the new {@code SQLException} to be added to the end of the
+     *            chain.
      */
-    public void setNextException(SQLException ex) {
+    public void setNextException(SQLException ex) {    
         if (next != null) {
             next.setNextException(ex);
         } else {

Modified: harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/SQLInput.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/SQLInput.java?rev=770130&r1=770129&r2=770130&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/SQLInput.java (original)
+++ harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/SQLInput.java Thu Apr 30 09:45:40 2009
@@ -23,258 +23,291 @@
 import java.net.URL;
 
 /**
- * The SQLInput interface defines operations which apply to a type of input
- * stream which carries a series of values which represent an instance of an SQL
- * structured type or SQL distinct type.
+ * The {@code SQLInput} interface defines operations which apply to a type of
+ * input stream which carries a series of values representing an instance of
+ * an SQL structured type or SQL distinct type.
  * <p>
- * SQLInput interface is used for custom mapping of SQL User Defined Types
- * (UDTs)to Java classes. It is used by JDBC drivers below the level of the
- * public interfaces and application programs do not normally use the SQLInput
- * methods directly. Reader methods such as readLong and readBytes provide means
- * to read values from an SQLInput stream.
+ * This interface is used to define custom mappings of SQL <i>User Defined
+ * Types</i> (UDTs) to Java classes. It is used by JDBC drivers, therefore
+ * application programmers do not normally use the {@code SQLInput} methods
+ * directly. Reader methods such as {@code readLong} and {@code readBytes}
+ * provide means to read values from an {@code SQLInput} stream.
  * <p>
- * When the getObject method is called with an object which implements the
- * SQLData interface, the JDBC driver determines the SQL type of the UDT being
- * mapped by calling the SQLData.getSQLType method. The driver creates an
- * instance of an SQLInput stream, filling the stream with the attributes of the
- * UDT. The SQLInput stream is passed to the SQLData.readSQL method which then
- * calls the SQLInput reader methods to read the attributes.
+ * When the {@code getObject} method is called with an object which implements
+ * the {@code SQLData} interface, the JDBC driver determines the SQL type of the
+ * UDT being mapped by calling the {@code SQLData.getSQLType} method. The driver
+ * creates an instance of an {@code SQLInput} stream, filling the stream with
+ * the attributes of the UDT. The {@code SQLInput} stream is passed to the
+ * {@code SQLData.readSQL} method which then calls the {@code SQLInput} reader
+ * methods to read the attributes.
+ *
+ * @see SQLData
  */
 public interface SQLInput {
 
     /**
-     * Returns the next attribute in the stream in the form of a String.
+     * Returns the next attribute in the stream in the form of a {@code String}.
+     * 
+     * @return the next attribute. {@code null} if the value is SQL {@code NULL}.
      * 
-     * @return the next attribute as a String. null if the value is SQL NULL.
      * @throws SQLException
-     *             if there is a database error
+     *             if there is a database error.
      */
     public String readString() throws SQLException;
 
     /**
-     * Returns the next attribute in the stream in the form of a boolean.
+     * Returns the next attribute in the stream in the form of a {@code boolean}
+     * .
      * 
-     * @return the next attribute as a boolean. false if the value is SQL NULL.
+     * @return the next attribute as a {@code boolean}. {@code false} if the
+     *         value is SQL {@code NULL}.
      * @throws SQLException
-     *             if there is a database error
+     *             if there is a database error.
      */
     public boolean readBoolean() throws SQLException;
 
     /**
-     * Returns the next attribute in the stream in the form of a byte.
+     * Returns the next attribute in the stream in the form of a {@code byte}.
      * 
-     * @return the next attribute as a byte. 0 if the value is SQL NULL.
+     * @return the next attribute as a {@code byte}. 0 if the value is SQL
+     *         {@code NULL}.
      * @throws SQLException
-     *             if there is a database error
+     *             if there is a database error.
      */
     public byte readByte() throws SQLException;
 
     /**
-     * Returns the next attribute in the stream in the form of a short.
+     * Returns the next attribute in the stream in the form of a {@code short}.
      * 
-     * @return the next attribute as a short. 0 if the value is SQL NULL.
+     * @return the next attribute as a {@code short}. 0 if the value is SQL
+     *         {@code NULL}.
      * @throws SQLException
-     *             if there is a database error
+     *             if there is a database error.
      */
     public short readShort() throws SQLException;
 
     /**
-     * Returns the next attribute in the stream in the form of an int.
+     * Returns the next attribute in the stream in the form of an {@code int}.
      * 
-     * @return the next attribute as an int. 0 if the value is SQL NULL.
+     * @return the next attribute as an {@code int}. 0 if the value is SQL
+     *         {@code NULL}.
      * @throws SQLException
-     *             if there is a database error
+     *             if there is a database error.
      */
     public int readInt() throws SQLException;
 
     /**
-     * Returns the next attribute in the stream in the form of a long.
+     * Returns the next attribute in the stream in the form of a {@code long}.
      * 
-     * @return the next attribute as a long. 0 if the value is SQL NULL.
+     * @return the next attribute as a {@code long}. 0 if the value is SQL
+     *         {@code NULL}.
      * @throws SQLException
-     *             if there is a database error
+     *             if there is a database error.
      */
     public long readLong() throws SQLException;
 
     /**
-     * Returns the next attribute in the stream in the form of a float.
+     * Returns the next attribute in the stream in the form of a {@code float}.
      * 
-     * @return the next attribute as a float. 0 if the value is SQL NULL.
+     * @return the next attribute as a {@code float}. 0 if the value is SQL
+     *         {@code NULL}.
      * @throws SQLException
-     *             if there is a database error
+     *             if there is a database error.
      */
     public float readFloat() throws SQLException;
 
     /**
-     * Returns the next attribute in the stream in the form of a double.
+     * Returns the next attribute in the stream in the form of a {@code double}.
      * 
-     * @return the next attribute as a double. 0 if the value is SQL NULL.
+     * @return the next attribute as a {@code double}. 0 if the value is SQL
+     *         {@code NULL}.
      * @throws SQLException
-     *             if there is a database error
+     *             if there is a database error.
      */
     public double readDouble() throws SQLException;
 
     /**
-     * Returns the next attribute in the stream in the form of a
-     * java.math.BigDecimal.
+     * Returns the next attribute in the stream in the form of a {@code
+     * java.math.BigDecimal}.
      * 
-     * @return the attribute as a java.math.BigDecimal. null if the read returns
-     *         SQL NULL.
+     * @return the attribute as a {@code java.math.BigDecimal}. {@code null} if
+     *         the read returns SQL {@code NULL}.
      * @throws SQLException
-     *             if there is a database error
+     *             if there is a database error.
+     * @see java.math.BigDecimal
      */
     public BigDecimal readBigDecimal() throws SQLException;
 
     /**
      * Returns the next attribute in the stream in the form of a byte array.
      * 
-     * @return the attribute as a byte array. null if the read returns SQL NULL.
+     * @return the attribute as a byte array. {@code null} if the read returns
+     *         SQL {@code NULL}.
      * @throws SQLException
-     *             if there is a database error
+     *             if there is a database error.
      */
     public byte[] readBytes() throws SQLException;
 
     /**
-     * Returns the next attribute in the stream in the form of a java.sql.Date.
+     * Returns the next attribute in the stream in the form of a {@code
+     * java.sql.Date}.
      * 
-     * @return the next attribute as a java.sql.Date. null if the value is SQL
-     *         NULL.
+     * @return the next attribute as a {@code java.sql.Date}. {@code null} if
+     *         the value is SQL {@code NULL}.
      * @throws SQLException
-     *             if there is a database error
+     *             if there is a database error.
+     * @see Date
      */
     public Date readDate() throws SQLException;
 
     /**
-     * Returns the next attribute in the stream in the form of a java.sql.Time.
+     * Returns the next attribute in the stream in the form of a {@code
+     * java.sql.Time}.
      * 
-     * @return the attribute as a java.sql.Time. null if the read returns SQL
-     *         NULL.
+     * @return the attribute as a {@code java.sql.Time}. {@code null} if the
+     *         read returns SQL {@code NULL}.
      * @throws SQLException
-     *             if there is a database error
+     *             if there is a database error.
+     * @see Time
      */
     public Time readTime() throws SQLException;
 
     /**
-     * Returns the next attribute in the stream in the form of a
-     * java.sql.Timestamp.
+     * Returns the next attribute in the stream in the form of a {@code
+     * java.sql.Timestamp}.
      * 
-     * @return the attribute as a java.sql.Timestamp. null if the read returns
-     *         SQL NULL.
+     * @return the attribute as a {@code java.sql.Timestamp}. {@code null} if
+     *         the read returns SQL {@code NULL}.
      * @throws SQLException
-     *             if there is a database error
+     *             if there is a database error.
+     * @see Timestamp
      */
     public Timestamp readTimestamp() throws SQLException;
 
     /**
      * Returns the next attribute in the stream in the form of a Unicode
-     * character stream embodied as a java.io.Reader.
+     * character stream embodied as a {@code java.io.Reader}.
      * 
-     * @return the next attribute as a java.io.Reader. null if the value is SQL
-     *         NULL.
+     * @return the next attribute as a {@code java.io.Reader}. {@code null} if
+     *         the value is SQL {@code NULL}.
      * @throws SQLException
-     *             if there is a database error
+     *             if there is a database error.
+     * @see java.io.Reader
      */
     public Reader readCharacterStream() throws SQLException;
 
     /**
      * Returns the next attribute in the stream in the form of an ASCII
-     * character stream embodied as a java.io.InputStream.
+     * character stream embodied as a {@code java.io.InputStream}.
      * 
-     * @return the next attribute as a java.io.InputStream. null if the value is
-     *         SQL NULL.
+     * @return the next attribute as a {@code java.io.InputStream}. {@code null}
+     *         if the value is SQL {@code NULL}.
      * @throws SQLException
-     *             if there is a database error
+     *             if there is a database error.
+     * @see java.io.InputStream
      */
     public InputStream readAsciiStream() throws SQLException;
 
     /**
      * Returns the next attribute in the stream in the form of a stream of bytes
-     * embodied as a java.io.InputStream.
+     * embodied as a {@code java.io.InputStream}.
      * 
-     * @return the next attribute as a java.io.InputStream. null if the value is
-     *         SQL NULL.
+     * @return the next attribute as a {@code java.io.InputStream}. {@code null}
+     *         if the value is SQL {@code NULL}.
      * @throws SQLException
-     *             if there is a database error
+     *             if there is a database error.
+     * @see java.io.InputStream
      */
     public InputStream readBinaryStream() throws SQLException;
 
     /**
-     * Returns the next attribute in the stream in the form of a
-     * java.lang.Object.
+     * Returns the next attribute in the stream in the form of a {@code
+     * java.lang.Object}.
      * <p>
-     * The type of the Object returned is determined by the type mapping for
-     * this JDBC driver, including any customized mappings in force. A type map
-     * is given to the SQLInput by the JDBC driver before the SQLInput is given
-     * to the application.
+     * The type of the {@code Object} returned is determined by the type mapping
+     * for this JDBC driver, including any customized mappings, if present. A
+     * type map is given to the {@code SQLInput} by the JDBC driver before the
+     * {@code SQLInput} is given to the application.
      * <p>
      * If the attribute is an SQL structured or distinct type, its SQL type is
-     * determined. If the streams type map contains an element for that SQL
-     * type, the driver creates an object of relevant type and invokes the
-     * method SQLData.readSQL on it, which reads supplementary data from the
-     * stream using whichever protocol is defined for that method.
+     * determined. If the stream's type map contains an element for that SQL
+     * type, the driver creates an object for the relevant type and invokes the
+     * method {@code SQLData.readSQL} on it, which reads supplementary data from
+     * the stream using whichever protocol is defined for that method.
      * 
-     * @return the next attribute as an Object. null if the value is SQL NULL.
+     * @return the next attribute as an Object. {@code null} if the value is SQL
+     *         {@code NULL}.
      * @throws SQLException
-     *             if there is a database error
+     *             if there is a database error.
      */
     public Object readObject() throws SQLException;
 
     /**
-     * Returns the next attribute in the stream in the form of a java.sql.Ref.
+     * Returns the next attribute in the stream in the form of a {@code
+     * java.sql.Ref}.
      * 
-     * @return the next attribute as a java.sql.Ref. null if the value is SQL
-     *         NULL.
+     * @return the next attribute as a {@code java.sql.Ref}. {@code null} if the
+     *         value is SQL {@code NULL}.
      * @throws SQLException
-     *             if there is a database error
+     *             if there is a database error.
+     * @see Ref
      */
     public Ref readRef() throws SQLException;
 
     /**
-     * Returns the next attribute in the stream in the form of a java.sql.Blob.
+     * Returns the next attribute in the stream in the form of a {@code
+     * java.sql.Blob}.
      * 
-     * @return the next attribute as a java.sql.Blob. null if the value is SQL
-     *         NULL.
+     * @return the next attribute as a {@code java.sql.Blob}. {@code null} if
+     *         the value is SQL {@code NULL}.
      * @throws SQLException
-     *             if there is a database error
+     *             if there is a database error.
      */
     public Blob readBlob() throws SQLException;
 
     /**
-     * Returns the next attribute in the stream in the form of a java.sql.Clob.
+     * Returns the next attribute in the stream in the form of a {@code
+     * java.sql.Clob}.
      * 
-     * @return the next attribute as a java.sql.Clob. null if the value is SQL
-     *         NULL.
+     * @return the next attribute as a {@code java.sql.Clob}. {@code null} if
+     *         the value is SQL {@code NULL}.
      * @throws SQLException
-     *             if there is a database error
+     *             if there is a database error.
+     * @see Clob
      */
     public Clob readClob() throws SQLException;
 
     /**
-     * Returns the next attribute in the stream in the form of a java.sql.Array.
+     * Returns the next attribute in the stream in the form of a {@code
+     * java.sql.Array}.
      * 
-     * @return the next attribute as an Array. null if the value is SQL NULL.
+     * @return the next attribute as an {@code Array}. {@code null} if the value
+     *         is SQL {@code NULL}.
      * @throws SQLException
-     *             if there is a database error
+     *             if there is a database error.
+     * @see Array
      */
     public Array readArray() throws SQLException;
 
     /**
-     * Reports whether the last value read was SQL NULL.
+     * Reports whether the last value read was SQL {@code NULL}.
      * 
-     * @return true if the last value read was SQL NULL, false otherwise.
+     * @return {@code true} if the last value read was SQL {@code NULL}, {@code
+     *         false} otherwise.
      * @throws SQLException
-     *             if there is a database error
+     *             if there is a database error.
      */
     public boolean wasNull() throws SQLException;
 
     /**
      * Reads the next attribute in the stream (SQL DATALINK value) and returns
-     * it as a java.net.URL object.
+     * it as a {@code java.net.URL} object.
      * 
-     * @return the next attribute as a java.net.URL. null if the value is SQL
-     *         NULL.
+     * @return the next attribute as a {@code java.net.URL}. {@code null} if the
+     *         value is SQL {@code NULL}.
      * @throws SQLException
-     *             if there is a database error
+     *             if there is a database error.
+     * @see java.net.URL
      */
     public URL readURL() throws SQLException;
 }

Modified: harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/SQLOutput.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/SQLOutput.java?rev=770130&r1=770129&r2=770130&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/SQLOutput.java (original)
+++ harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/SQLOutput.java Thu Apr 30 09:45:40 2009
@@ -23,108 +23,110 @@
 import java.net.URL;
 
 /**
- * The interface for an output stream used to write attributes of an SQL User
- * Defined Type to the database. This interface is used for custom mapping of
- * types and is called by the JDBC driver. It is not expected that this
- * interface is used by applications.
+ * The interface for an output stream used to write attributes of an SQL <i>User
+ * Defined Type</i> (UDT) to the database. This interface is used for custom
+ * mapping of types and is called by the JDBC driver. It is not intended to be
+ * used by applications.
  * <p>
- * When an object which implements the SQLData interface is used as an argument
- * to an SQL statement, the JDBC driver calls the method
- * <code>SQLData.getSQLType</code> to establish the type of the SQL UDT that
- * is being passed. The driver then creates an SQLOutput stream and passes it to
- * the <code>SQLData.writeSQL</code> method, which in turn uses the
- * appropriate SQLOutput writer methods to write the data from the SQLData
+ * When an object which implements the {@code SQLData} interface is used as an
+ * argument to an SQL statement, the JDBC driver calls the method {@code
+ * SQLData.getSQLType} to establish the type of the SQL UDT that is being
+ * passed. The driver then creates an {@code SQLOutput} stream and passes it to
+ * the {@code SQLData.writeSQL} method, which in turn uses the appropriate
+ * {@code SQLOutput} writer methods to write the data from the {@code SQLData}
  * object into the stream according to the defined mapping.
+ *
+ * @see SQLData
  */
 public interface SQLOutput {
 
     /**
-     * Write a String value into the output stream.
+     * Write a {@code String} value into the output stream.
      * 
      * @param theString
-     *            the String to write
+     *            the {@code String} to write.
      * @throws SQLException
-     *             if a database error occurs
+     *             if a database error occurs.
      */
     public void writeString(String theString) throws SQLException;
 
     /**
-     * Write a boolean value into the output stream.
+     * Write a {@code boolean} value into the output stream.
      * 
      * @param theFlag
-     *            the boolean value to write
+     *            the {@code boolean} value to write.
      * @throws SQLException
-     *             if a database error occurs
+     *             if a database error occurs.
      */
     public void writeBoolean(boolean theFlag) throws SQLException;
 
     /**
-     * Write a byte value into the output stream.
+     * Write a {@code byte} value into the output stream.
      * 
      * @param theByte
-     *            the byte value to write
+     *            the {@code byte} value to write.
      * @throws SQLException
-     *             if a database error occurs
+     *             if a database error occurs.
      */
     public void writeByte(byte theByte) throws SQLException;
 
     /**
-     * Write a short value into the output stream.
+     * Write a {@code short} value into the output stream.
      * 
      * @param theShort
-     *            the short value to write
+     *            the {@code short} value to write.
      * @throws SQLException
-     *             if a database error occurs
+     *             if a database error occurs.
      */
     public void writeShort(short theShort) throws SQLException;
 
     /**
-     * Write an int value into the output stream.
+     * Write an {@code int} value into the output stream.
      * 
      * @param theInt
-     *            the int value to write
+     *            the {@code int} value to write.
      * @throws SQLException
-     *             if a database error occurs
+     *             if a database error occurs.
      */
     public void writeInt(int theInt) throws SQLException;
 
     /**
-     * Write a long value into the output stream.
+     * Write a {@code long} value into the output stream.
      * 
      * @param theLong
-     *            the long value to write
+     *            the {@code long} value to write.
      * @throws SQLException
-     *             if a database error occurs
+     *             if a database error occurs.
      */
     public void writeLong(long theLong) throws SQLException;
 
     /**
-     * Write a float value into the output stream.
+     * Write a {@code float} value into the output stream.
      * 
      * @param theFloat
-     *            the float value to write
+     *            the {@code float} value to write.
      * @throws SQLException
-     *             if a database error occurs
+     *             if a database error occurs.
      */
     public void writeFloat(float theFloat) throws SQLException;
 
     /**
-     * Write a double value into the output stream.
+     * Write a {@code double} value into the output stream.
      * 
      * @param theDouble
-     *            the double value to write
+     *            the {@code double} value to write.
      * @throws SQLException
-     *             if a database error occurs
+     *             if a database error occurs.
      */
     public void writeDouble(double theDouble) throws SQLException;
 
     /**
-     * Write a java.math.BigDecimal value into the output stream.
+     * Write a {@code java.math.BigDecimal} value into the output stream.
      * 
      * @param theBigDecimal
-     *            the BigDecimal value to write
+     *            the {@code BigDecimal} value to write.
      * @throws SQLException
-     *             if a database error occurs
+     *             if a database error occurs.
      */
     public void writeBigDecimal(BigDecimal theBigDecimal) throws SQLException;
 
@@ -132,50 +134,53 @@
      * Write an array of bytes into the output stream.
      * 
      * @param theBytes
-     *            the array of bytes to write
+     *            the array of bytes to write.
      * @throws SQLException
-     *             if a database error occurs
+     *             if a database error occurs.
      */
     public void writeBytes(byte[] theBytes) throws SQLException;
 
     /**
-     * Write a java.sql.Date value into the output stream.
+     * Write a {@code java.sql.Date} value into the output stream.
      * 
      * @param theDate
-     *            the Date value to write
+     *            the {@code Date} value to write.
      * @throws SQLException
-     *             if a database error occurs
+     *             if a database error occurs.
+     * @see Date
      */
     public void writeDate(Date theDate) throws SQLException;
 
     /**
-     * Write a java.sql.Time value into the output stream.
+     * Write a {@code java.sql.Time} value into the output stream.
      * 
      * @param theTime
-     *            the Time value to write
+     *            the {@code Time} value to write.
      * @throws SQLException
-     *             if a database error occurs
+     *             if a database error occurs.
+     * @see Time
      */
     public void writeTime(Time theTime) throws SQLException;
 
     /**
-     * Write a java.sql.Timestamp value into the output stream.
+     * Write a {@code java.sql.Timestamp} value into the output stream.
      * 
      * @param theTimestamp
-     *            the Timestamp value to write
+     *            the {@code Timestamp} value to write.
      * @throws SQLException
-     *             if a database error occurs
+     *             if a database error occurs.
+     * @see Timestamp
      */
     public void writeTimestamp(Timestamp theTimestamp) throws SQLException;
 
     /**
-     * Write a stream of Unicode characters into the output stream.
+     * Write a stream of unicode characters into the output stream.
      * 
      * @param theStream
-     *            the stream of Unicode characters to write, as a java.io.Reader
-     *            object
+     *            the stream of unicode characters to write, as a {@code
+     *            java.io.Reader} object.
      * @throws SQLException
-     *             if a database error occurs
+     *             if a database error occurs.
      */
     public void writeCharacterStream(Reader theStream) throws SQLException;
 
@@ -183,10 +188,10 @@
      * Write a stream of ASCII characters into the output stream.
      * 
      * @param theStream
-     *            the stream of ASCII characters to write, as a
-     *            java.io.InputStream object
+     *            the stream of ASCII characters to write, as a {@code
+     *            java.io.InputStream} object
      * @throws SQLException
-     *             if a database error occurs
+     *             if a database error occurs.
      */
     public void writeAsciiStream(InputStream theStream) throws SQLException;
 
@@ -194,87 +199,95 @@
      * Write a stream of uninterpreted bytes into the output stream.
      * 
      * @param theStream
-     *            the stream of bytes to write, as a java.io.InputStream object
+     *            the stream of bytes to write, as a {@code java.io.InputStream}
+     *            object
      * @throws SQLException
-     *             if a database error occurs
+     *             if a database error occurs.
      */
     public void writeBinaryStream(InputStream theStream) throws SQLException;
 
     /**
-     * Write an SQLData object into the output stream.
+     * Write an {@code SQLData} object into the output stream.
      * <p>
-     * If the SQLData object is null, writes SQL NULL to the stream.
+     * If the {@code SQLData} object is null, writes {@code NULL} to the stream.
      * <p>
-     * Otherwise, calls the <code>SQLData.writeSQL</code> method of the
-     * object, which writes the object's attributes to the stream by calling the
-     * appropriate SQLOutput writer methods for each attribute, in order. The
-     * order of the attributes is the order they are listed in the SQL
-     * definition of the User Defined Type.
+     * Otherwise, calls the {@code SQLData.writeSQL} method of the object, which
+     * writes the object's attributes to the stream by calling the appropriate
+     * SQLOutput writer methods for each attribute, in order. The order of the
+     * attributes is the order they are listed in the SQL definition of the User
+     * Defined Type.
      * 
      * @param theObject
-     *            the SQLData object to write
+     *            the {@code SQLData} object to write.
      * @throws SQLException
-     *             if a database error occurs
+     *             if a database error occurs.
+     * @see SQLData
      */
     public void writeObject(SQLData theObject) throws SQLException;
 
     /**
-     * Write an SQL Ref value into the output stream.
+     * Write an SQL {@code Ref} value into the output stream.
      * 
      * @param theRef
-     *            the java.sql.Ref object to write
+     *            the {@code java.sql.Ref} object to write.
      * @throws SQLException
-     *             if a database error occurs
+     *             if a database error occurs.
+     * @see Ref
      */
     public void writeRef(Ref theRef) throws SQLException;
 
     /**
-     * Write an SQL Blob value into the output stream.
+     * Write an SQL {@code Blob} value into the output stream.
      * 
      * @param theBlob
-     *            the java.sql.Blob object to write
+     *            the {@code java.sql.Blob} object to write.
      * @throws SQLException
-     *             if a database error occurs
+     *             if a database error occurs.
+     * @see Blob
      */
     public void writeBlob(Blob theBlob) throws SQLException;
 
     /**
-     * Write an SQL Clob value into the output stream.
+     * Write an SQL {@code Clob} value into the output stream.
      * 
      * @param theClob
-     *            the java.sql.Clob object to write
+     *            the {@code java.sql.Clob} object to write.
      * @throws SQLException
-     *             if a database error occurs
+     *             if a database error occurs.
+     * @see Clob
      */
     public void writeClob(Clob theClob) throws SQLException;
 
     /**
-     * Write an SQL Struct value into the output stream.
+     * Write an SQL {@code Struct} value into the output stream.
      * 
      * @param theStruct
-     *            the java.sql.Struct object to write
+     *            the {@code java.sql.Struct} object to write.
      * @throws SQLException
-     *             if a database error occurs
+     *             if a database error occurs.
+     * @see Struct
      */
     public void writeStruct(Struct theStruct) throws SQLException;
 
     /**
-     * Write an SQL Array value into the output stream.
+     * Write an SQL {@code Array} value into the output stream.
      * 
      * @param theArray
-     *            the java.sql.Array object to write
+     *            the {@code java.sql.Array} object to write.
      * @throws SQLException
-     *             if a database error occurs
+     *             if a database error occurs.
+     * @see Array
      */
     public void writeArray(Array theArray) throws SQLException;
 
     /**
-     * Write an SQL DATALINK value into the output stream.
+     * Write an SQL {@code DATALINK} value into the output stream.
      * 
      * @param theURL
-     *            the Datalink value as a java.net.URL to write
+     *            the datalink value as a {@code java.net.URL} to write.
      * @throws SQLException
-     *             if a database error occurs
+     *             if a database error occurs.
+     * @see java.net.URL
      */
     public void writeURL(URL theURL) throws SQLException;
 }

Modified: harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/SQLPermission.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/SQLPermission.java?rev=770130&r1=770129&r2=770130&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/SQLPermission.java (original)
+++ harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/SQLPermission.java Thu Apr 30 09:45:40 2009
@@ -22,13 +22,17 @@
 import java.security.Guard;
 
 /**
- * Permission relating to security access control in the java.sql package.
+ * A Permission relating to security access control in the {@code java.sql}
+ * package.
  * <p>
- * Currently, the only permission supported has the name "setLog". The setLog
- * permission controls whether a Java application or applet can open a logging
- * stream using the DriverManager.setLogWriter method or the
- * DriverManager.setLogStream method. This is a potentially dangerous operation
- * since the logging stream can contain usernames, passwords
+ * Currently, the only permission supported has the name " {@code setLog}". The
+ * {@code setLog} permission controls whether a Java application or applet can
+ * open a logging stream using the {@code DriverManager.setLogWriter} method or
+ * the {@code DriverManager.setLogStream} method. This is a potentially
+ * dangerous operation since the logging stream can contain sensitive
+ * information such as usernames and passwords.
+ * 
+ * @see DriverManager
  */
 public final class SQLPermission extends BasicPermission implements Guard,
         Serializable {
@@ -36,23 +40,23 @@
     private static final long serialVersionUID = -1439323187199563495L;
 
     /**
-     * Creates a new SQLPermission object with the specified name.
+     * Creates a new {@code SQLPermission} object with the specified name.
      * 
      * @param name
-     *            the name to use for this SQLPermission
+     *            the name to use for this {@code SQLPermission}.
      */
     public SQLPermission(String name) {
         super(name);
     }
 
     /**
-     * Creates a new SQLPermission object with the specified name.
+     * Creates a new {@code SQLPermission} object with the specified name.
      * 
      * @param name
-     *            is the name of the SQLPermission. Currently only "setLog" is
-     *            allowed.
+     *            is the name of the {@code SQLPermission}. Currently only
+     *            {@code "setLog"} is allowed.
      * @param actions
-     *            is currently unused and should be set to null
+     *            is currently unused and should be set to {@code null}.
      */
     public SQLPermission(String name, String actions) {
         super(name, null);

Modified: harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/SQLWarning.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/SQLWarning.java?rev=770130&r1=770129&r2=770130&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/SQLWarning.java (original)
+++ harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/SQLWarning.java Thu Apr 30 09:45:40 2009
@@ -29,56 +29,63 @@
     private static final long serialVersionUID = 3917336774604784856L;
 
     /**
-     * Creates an SQLWarning object. The Reason string is set to null, the
-     * SQLState string is set to null and the Error Code is set to 0.
+     * Creates an {@code SQLWarning} object. The reason string is set to {@code
+     * null}, the {@code SQLState} string is set to {@code null} and the error
+     * code is set to 0.
      */
     public SQLWarning() {
         super();
     }
 
     /**
-     * Creates an SQLWarning object. The Reason string is set to the given
-     * reason string, the SQLState string is set to null and the Error Code is
-     * set to 0.
+     * Creates an {@code SQLWarning} object. The reason string is set to the
+     * given reason string, the {@code SQLState} string is set to {@code null}
+     * and the error code is set to 0.
      * 
      * @param theReason
+     *            the reason why this warning is issued.
      */
     public SQLWarning(String theReason) {
         super(theReason);
     }
 
     /**
-     * Creates an SQLWarning object. The Reason string is set to the given
-     * reason string, the SQLState string is set to the given SQLState string
-     * and the Error Code is set to 0.
+     * Creates an {@code SQLWarning} object. The reason string is set to the
+     * given reason string, the {@code SQLState} string is set to the given
+     * {@code SQLState} string and the error code is set to 0.
      * 
      * @param theReason
-     *            the string to use as the Reason string
+     *            the reason why this warning is issued.
      * @param theSQLState
-     *            the string to use as the SQLState string
+     *            the string to use as the {@code SQLState} string.
      */
     public SQLWarning(String theReason, String theSQLState) {
         super(theReason, theSQLState);
     }
 
     /**
-     * Creates an SQLWarning object. The Reason string is set to the given
-     * reason string, the SQLState string is set to the given SQLState string
-     * and the Error Code is set to the given ErrorCode value.
+     * Creates an {@code SQLWarning} object. The reason string is set to the
+     * given reason string, the {@code SQLState} string is set to the given
+     * {@code SQLState} string and the error code is set to the given error code
+     * value.
      * 
      * @param theReason
+     *            the reason why this warning is issued.
      * @param theSQLState
+     *            the X/Open standard specifc error code.
      * @param theErrorCode
+     *            a vendor specific error code.
      */
     public SQLWarning(String theReason, String theSQLState, int theErrorCode) {
         super(theReason, theSQLState, theErrorCode);
     }
 
     /**
-     * Gets the SQLWarning chained to this SQLWarning object.
+     * Gets the next {@code SQLWarning} chained to this {@code SQLWarning} object.
      * 
-     * @return the SQLWarning chained to this SQLWarning. null if no SQLWarning
-     *         is chained to this SQLWarning.
+     * @return the {@code SQLWarning} chained to this {@code SQLWarning}.
+     *         {@code null} if no {@code SQLWarning} is chained to this {@code
+     *         SQLWarning}.
      */
     public SQLWarning getNextWarning() {
         SQLException next = super.getNextException();
@@ -92,10 +99,10 @@
     }
 
     /**
-     * Chains a supplied SQLWarning to this SQLWarning.
+     * Chains a supplied {@code SQLWarning} to this {@code SQLWarning}.
      * 
      * @param w
-     *            the SQLWarning to chain to this SQLWarning.
+     *            the {@code SQLWarning} linked to this {@code SQLWarning}.
      */
     public void setNextWarning(SQLWarning w) {
         super.setNextException(w);

Modified: harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/Savepoint.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/Savepoint.java?rev=770130&r1=770129&r2=770130&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/Savepoint.java (original)
+++ harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/Savepoint.java Thu Apr 30 09:45:40 2009
@@ -18,26 +18,28 @@
 package java.sql;
 
 /**
- * A Savepoint is an instant during the current transaction that can be utilized
- * by a Rollback from the Connection.rollback method. Rolling back to a
- * particular Savepoint means that all changes that occurred after that
- * Savepoint are removed.
+ * A savepoint is an instant during the current transaction that can be utilized
+ * by a rollback via the {@link Connection#rollback} command. Rolling back to a
+ * particular savepoint means that all changes that occurred after that
+ * savepoint are undone.
  */
 public interface Savepoint {
 
     /**
-     * Returns the constructed ID for this Savepoint.
+     * Returns the constructed ID for this savepoint.
      * 
-     * @return the ID for this Savepoint.
+     * @return the ID for this savepoint.
      * @throws SQLException
+     *             if an error occurrs accessing the database.
      */
     public int getSavepointId() throws SQLException;
 
     /**
-     * Returns the name for this Savepoint.
+     * Returns the name for this savepoint.
      * 
-     * @return the name of this Savepoint.
+     * @return the name of this savepoint.
      * @throws SQLException
+     *             if an error occurrs accessing the database.
      */
     public String getSavepointName() throws SQLException;
 }



Mime
View raw message