Mailing-List: contact commits-help@harmony.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@harmony.apache.org
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Subject: svn commit: r770130 [10/10] - in
 /harmony/enhanced/classlib/trunk/modules/sql/src/main/java: java/sql/
 javax/sql/
Date: Thu, 30 Apr 2009 09:45:42 -0000
To: commits@harmony.apache.org
From: tellison@apache.org
Message-Id: <20090430094544.1BF7A2388D06@eris.apache.org>

Modified: harmony/enhanced/classlib/trunk/modules/sql/src/main/java/javax/sql/RowSetListener.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/sql/src/main/java/javax/sql/RowSetListener.java?rev=770130&r1=770129&r2=770130&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/sql/src/main/java/javax/sql/RowSetListener.java (original)
+++ harmony/enhanced/classlib/trunk/modules/sql/src/main/java/javax/sql/RowSetListener.java Thu Apr 30 09:45:40 2009
@@ -20,43 +20,48 @@
 import java.util.EventListener;
 
 /**
- * An interface used to send notification of events occurring in a RowSet. To
- * receive the notification events, an object must implement the RowSetListener
- * interface and then register itself with the RowSet of interest using the
- * <code>RowSet.addRowSetListener</code> method.
+ * An interface used to send notification of events occurring in the context of
+ * a {@link RowSet}. To receive the notification events, an object must
+ * implement the {@code RowSetListener} interface and then register itself with
+ * the {@code RowSet} of interest using the
+ * {@link RowSet#addRowSetListener(RowSetListener)} method.
  */
 public interface RowSetListener extends EventListener {
 
     /**
-     * Notifies the listener that one of the RowSet's rows has changed.
+     * Notifies the listener that the {@code RowSet}'s cursor in {@code
+     * theEvent.getSource} has moved.
      * 
      * @param theEvent
-     *            a RowSetEvent that contains information about the RowSet
-     *            involved. This information can be used to retrieve information
-     *            about the change, such as the new cursor position.
+     *            a {@code RowSetEvent} that contains information about the
+     *            {@code RowSet} involved. This information can be used to
+     *            retrieve information about the change, such as the updated
+     *            data values.
      */
     public void cursorMoved(RowSetEvent theEvent);
 
     /**
-     * Notifies the listener that the RowSet's cursor has moved.
+     * Notifies the listener that one of the {@code RowSet}'s rows in {@code
+     * theEvent.getSource} has changed.
      * 
      * @param theEvent
-     *            theEvent a RowSetEvent that contains information about the
-     *            RowSet involved. This information can be used to retrieve
-     *            information about the change, such as the updated data values.
+     *            a {@code RowSetEvent} that contains information about the
+     *            {@code RowSet} involved. This information can be used to
+     *            retrieve information about the change, such as the new cursor
+     *            position.
      */
     public void rowChanged(RowSetEvent theEvent);
 
     /**
-     * Notifies the listener that the RowSet's entire contents have been updated
-     * (an example is the execution of a command which retrieves new data from
-     * the database).
+     * Notifies the listener that the {@code RowSet}'s entire contents in
+     * {@code theEvent.getSource} have been updated (an example is the execution
+     * of a command which retrieves new data from the database).
      * 
      * @param theEvent
-     *            theEvent a RowSetEvent that contains information about the
-     *            RowSet involved. This information can be used to retrieve
-     *            information about the change, such as the updated rows of
-     *            data.
+     *            a {@code RowSetEvent} that contains information about the
+     *            {@code RowSet} involved. This information can be used to
+     *            retrieve information about the change, such as the updated
+     *            rows of data.
      */
     public void rowSetChanged(RowSetEvent theEvent);
 }

Modified: harmony/enhanced/classlib/trunk/modules/sql/src/main/java/javax/sql/RowSetMetaData.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/sql/src/main/java/javax/sql/RowSetMetaData.java?rev=770130&r1=770129&r2=770130&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/sql/src/main/java/javax/sql/RowSetMetaData.java (original)
+++ harmony/enhanced/classlib/trunk/modules/sql/src/main/java/javax/sql/RowSetMetaData.java Thu Apr 30 09:45:40 2009
@@ -22,261 +22,271 @@
 
 /**
  * An interface which provides facilities for getting information about the
- * columns in a RowSet.
+ * columns in a {@code RowSet}.
  * <p>
- * RowSetMetaData extends ResultSetMetaData, adding new operations for carrying
- * out value sets.
+ * {@code RowSetMetaData} extends {@link java.sql.ResultSetMetaData}, adding new
+ * operations for carrying out value sets.
  * <p>
  * Application code would not normally call this interface directly. It would be
- * called internally when <code>RowSet.execute</code> is called.
+ * called internally when {@code RowSet.execute} is called.
+ *
+ * @see RowSetInternal#setMetaData(RowSetMetaData)
  */
 public interface RowSetMetaData extends ResultSetMetaData {
 
     /**
-     * Sets automatic numbering for a specified column in the RowSet. If
-     * automatic numbering is on, the column is read only. The default value is
-     * for automatic numbering to be off.
+     * Sets automatic numbering for a specified column in the {@code RowSet}. If
+     * automatic numbering is on, the column is read-only. The default value for
+     * the auto increment parameter is {@code false}.
      * 
      * @param columnIndex
-     *            the index number for the column, where the first column has
-     *            index 1.
+     *            the index number for the column; the first column's index is
+     *            1.
      * @param autoIncrement
-     *            true to set automatic numbering on, false to turn it off.
+     *            {@code true} to set automatic numbering on, {@code false} to
+     *            turn it off (default).
      * @throws SQLException
-     *             if a problem occurs accessing the database
+     *             if a problem occurs accessing the database.
      */
     public void setAutoIncrement(int columnIndex, boolean autoIncrement)
             throws SQLException;
 
     /**
-     * Sets the case sensitive property for a specified column in the RowSet.
-     * The default is that the column is not case sensitive.
+     * Sets the case sensitive property for a specified column in the {@code
+     * RowSet}. The default is that the column is not case sensitive.
      * 
      * @param columnIndex
-     *            the index number for the column, where the first column has
-     *            index 1.
+     *            the index number for the column; the first column's index is
+     *            1.
      * @param caseSensitive
-     *            true to make the column case sensitive, false to make it not
-     *            case sensitive.
+     *            {@code true} to make the column case sensitive, {@code false}
+     *            to make it case insensitive (default).
      * @throws SQLException
-     *             if a problem occurs accessing the database
+     *             if a problem occurs accessing the database.
      */
     public void setCaseSensitive(int columnIndex, boolean caseSensitive)
             throws SQLException;
 
     /**
-     * Sets the Catalog Name for a specified column in the RowSet.
+     * Sets the catalog name for a specified column in the {@code RowSet}.
      * 
      * @param columnIndex
-     *            the index number for the column, where the first column has
-     *            index 1.
+     *            the index number for the column; the first column's index is
+     *            1.
      * @param catalogName
-     *            a string containing the new Catalog Name
+     *            the new catalog's name.
      * @throws SQLException
-     *             if a problem occurs accessing the database
+     *             if a problem occurs accessing the database.
      */
     public void setCatalogName(int columnIndex, String catalogName)
             throws SQLException;
 
     /**
-     * Sets the number of columns in the Row Set.
+     * Sets the number of columns contained in the row set.
      * 
      * @param columnCount
-     *            an integer containing the number of columns in the RowSet.
+     *            the number of columns contained in the {@code RowSet}.
      * @throws SQLException
-     *             if a problem occurs accessing the database
+     *             if a problem occurs accessing the database.
      */
     public void setColumnCount(int columnCount) throws SQLException;
 
     /**
      * Sets the normal maximum width in characters for a specified column in the
-     * RowSet.
+     * {@code RowSet}.
      * 
      * @param columnIndex
-     *            the index number for the column, where the first column has
-     *            index 1.
+     *            the index number for the column; the first column's index is
+     *            1.
      * @param displaySize
-     *            an integer with the normal maximum column width in characters
+     *            the normal maximum column width in characters.
      * @throws SQLException
-     *             if a problem occurs accessing the database
+     *             if a problem occurs accessing the database.
      */
     public void setColumnDisplaySize(int columnIndex, int displaySize)
             throws SQLException;
 
     /**
+     * Sets the suggested name as label for the column contained in the {@code
+     * RowSet}. The label is an alias for printing and displaying purposes.
      * 
      * @param columnIndex
-     *            the index number for the column, where the first column has
-     *            index 1.
+     *            the index number for the column; the first column's index is
+     *            1.
      * @param theLabel
+     *            the alias name for the column.
      * @throws SQLException
-     *             if a problem occurs accessing the database
+     *             if a problem occurs accessing the database.
      */
     public void setColumnLabel(int columnIndex, String theLabel)
             throws SQLException;
 
     /**
-     * Sets the suggested column label for a specified column in the RowSet.
-     * This label is typically used in displaying or printing the column.
+     * Sets the column name for a specified column in the {@code RowSet}.
      * 
      * @param columnIndex
-     *            the index number for the column, where the first column has
-     *            index 1.
+     *            the index number for the column; the first column's index is
+     *            1.
      * @param theColumnName
-     *            a string containing the column label
+     *            the column's label.
      * @throws SQLException
-     *             if a problem occurs accessing the database
+     *             if a problem occurs accessing the database.
      */
     public void setColumnName(int columnIndex, String theColumnName)
             throws SQLException;
 
     /**
-     * Sets the SQL type for a specified column in the RowSet
+     * Sets the SQL type for a specified column in the {@code RowSet}.
      * 
      * @param columnIndex
-     *            the index number for the column, where the first column has
-     *            index 1.
+     *            the index number for the column; the first column's index is
+     *            1.
      * @param theSQLType
-     *            an integer containing the SQL Type, as defined by
-     *            java.sql.Types.
+     *            the SQL Type, as defined by {@code java.sql.Types}.
      * @throws SQLException
-     *             if a problem occurs accessing the database
+     *             if a problem occurs accessing the database.
      */
     public void setColumnType(int columnIndex, int theSQLType)
             throws SQLException;
 
     /**
-     * Sets the Type Name for a specified column in the RowSet, where the data
-     * type is specific to the datasource.
+     * Sets the type name for a specified column in the {@code RowSet}, where
+     * the data type is specific to the data source.
      * 
      * @param columnIndex
-     *            the index number for the column, where the first column has
-     *            index 1.
+     *            the index number for the column; the first column's index is
+     *            1.
      * @param theTypeName
-     *            a string containing the Type Name for the column
+     *            the SQL type name for the column.
      * @throws SQLException
-     *             if a problem occurs accessing the database
+     *             if a problem occurs accessing the database.
      */
     public void setColumnTypeName(int columnIndex, String theTypeName)
             throws SQLException;
 
     /**
-     * Sets whether a specified column is a currency value.
+     * Sets whether a specified column is a currency value. The default value is
+     * {@code false}.
      * 
      * @param columnIndex
-     *            the index number for the column, where the first column has
-     *            index 1.
+     *            the index number for the column; the first column's index is
+     *            1.
      * @param isCurrency
-     *            true if the column should be treated as a currency value,
-     *            false if it should not be treated as a currency value.
+     *            {@code true} if the column should be treated as a currency
+     *            value, {@code false} if it should not be treated as a currency
+     *            value (default).
      * @throws SQLException
-     *             if a problem occurs accessing the database
+     *             if a problem occurs accessing the database.
      */
     public void setCurrency(int columnIndex, boolean isCurrency)
             throws SQLException;
 
     /**
-     * Sets whether a specified column can contain SQL NULL values.
+     * Sets whether a specified column can contain SQL {@code NULL} values.
      * 
      * @param columnIndex
-     *            the index number for the column, where the first column has
-     *            index 1.
+     *            the index number for the column; the first column's index is
+     *            1.
      * @param nullability
      *            an integer which is one of the following values:
-     *            ResultSetMetaData.columnNoNulls,
-     *            ResultSetMetaData.columnNullable, or
-     *            ResultSetMetaData.columnNullableUnknown
+     *            <ul>
+     *            <li>{@code ResultSetMetaData.columnNoNulls}</li>
+     *            <li>{@code ResultSetMetaData.columnNullable}</li>
+     *            <li>{@code ResultSetMetaData.columnNullableUnknown}</li>
+     *            </ul>
      *            <p>
-     *            The default value is ResultSetMetaData.columnNullableUnknown
+     *            The default value is {@code
+     *            ResultSetMetaData.columnNullableUnknown}.
      * @throws SQLException
-     *             if a problem occurs accessing the database
+     *             if a problem occurs accessing the database.
      */
     public void setNullable(int columnIndex, int nullability)
             throws SQLException;
 
     /**
-     * Sets the number of decimal digits for a specified column in the RowSet.
+     * Sets the number of decimal digits for a specified column in the {@code
+     * RowSet}.
      * 
      * @param columnIndex
-     *            the index number for the column, where the first column has
-     *            index 1.
+     *            the index number for the column; the first column's index is
+     *            1.
      * @param thePrecision
-     *            an integer containing the number of decimal digits
+     *            the number of decimal digits.
      * @throws SQLException
-     *             if a problem occurs accessing the database
+     *             if a problem occurs accessing the database.
      */
     public void setPrecision(int columnIndex, int thePrecision)
             throws SQLException;
 
     /**
-     * For the column specified by <code>columnIndex</code> declares how many
-     * digits there should be after a decimal point.
+     * Declares how many decimal digits there should be after a decimal point
+     * for the column specified by {@code columnIndex}.
      * 
      * @param columnIndex
-     *            the index number for the column, where the first column has
-     *            index 1.
+     *            the index number for the column; the first column's index is
+     *            1.
      * @param theScale
-     *            an integer containing the number of digits after the decimal
-     *            point
+     *            the number of digits after the decimal point.
      * @throws SQLException
-     *             if a problem occurs accessing the database
+     *             if a problem occurs accessing the database.
      */
     public void setScale(int columnIndex, int theScale) throws SQLException;
 
     /**
-     * Sets the Schema Name for a specified column in the RowSet
+     * Sets the schema name for a specified column in the {@code RowSet}.
      * 
      * @param columnIndex
-     *            the index number for the column, where the first column has
-     *            index 1.
+     *            the index number for the column; the first column's index is
+     *            1.
      * @param theSchemaName
-     *            a String containing the schema name
+     *            a {@code String} containing the schema name.
      * @throws SQLException
-     *             if a problem occurs accessing the database
+     *             if a problem occurs accessing the database.
      */
     public void setSchemaName(int columnIndex, String theSchemaName)
             throws SQLException;
 
     /**
-     * Sets whether a specified column can be used in a search involving a WHERE
-     * clause. The default value is false.
+     * Sets whether a specified column can be used in a search involving a
+     * {@code WHERE} clause. The default value is {@code false}.
      * 
      * @param columnIndex
-     *            the index number for the column, where the first column has
-     *            index 1.
+     *            the index number for the column; the first column's index is
+     *            1.
      * @param isSearchable
-     *            true of the column can be used in a WHERE clause search, false
-     *            otherwise.
+     *            {@code true} of the column can be used in a {@code WHERE}
+     *            clause search, {@code false} otherwise.
      * @throws SQLException
-     *             if a problem occurs accessing the database
+     *             if a problem occurs accessing the database.
      */
     public void setSearchable(int columnIndex, boolean isSearchable)
             throws SQLException;
 
     /**
-     * Sets if a specified column can contain signed numbers
+     * Sets if a specified column can contain signed numbers.
      * 
      * @param columnIndex
-     *            the index number for the column, where the first column has
-     *            index 1.
+     *            the index number for the column; the first column's index is
+     *            1.
      * @param isSigned
-     *            true if the column can contain signed numbers, false otherwise
+     *            {@code true} if the column can contain signed numbers, {@code
+     *            false} otherwise.
      * @throws SQLException
-     *             if a problem occurs accessing the database
+     *             if a problem occurs accessing the database.
      */
     public void setSigned(int columnIndex, boolean isSigned)
             throws SQLException;
 
     /**
-     * Sets the Table Name for a specified column in the RowSet
+     * Sets the table name for a specified column in the {@code RowSet}.
      * 
      * @param columnIndex
-     *            the index number for the column, where the first column has
-     *            index 1.
+     *            the index number for the column; the first column's index is
+     *            1.
      * @param theTableName
-     *            a String containing the Table Name for the column
+     *            the table name for the column.
      * @throws SQLException
-     *             if a problem occurs accessing the database
+     *             if a problem occurs accessing the database.
      */
     public void setTableName(int columnIndex, String theTableName)
             throws SQLException;

Modified: harmony/enhanced/classlib/trunk/modules/sql/src/main/java/javax/sql/RowSetReader.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/sql/src/main/java/javax/sql/RowSetReader.java?rev=770130&r1=770129&r2=770130&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/sql/src/main/java/javax/sql/RowSetReader.java (original)
+++ harmony/enhanced/classlib/trunk/modules/sql/src/main/java/javax/sql/RowSetReader.java Thu Apr 30 09:45:40 2009
@@ -20,31 +20,37 @@
 import java.sql.SQLException;
 
 /**
- * An interface which provides functionality for a disconnected RowSet to get
- * data from a data source into its rows. The RowSet calls the RowSetReader
- * interface when the RowSet's execute method is invoked - a RowSetReader must
- * first be registered with the RowSet for this to work.
+ * An interface which provides functionality for a disconnected {@code RowSet}
+ * to get data from a database into its rows. The {@code RowSet} calls the
+ * {@code RowSetReader} interface when the {@code RowSet}'s execute method is
+ * invoked - a {@code RowSetReader} must first be registered with the {@code
+ * RowSet} for this to work.
+ * 
+ * @see RowSet
  */
 public interface RowSetReader {
 
     /**
-     * Reads new data into the RowSet. The calling RowSet object must itself
-     * implement the RowSetInternal interface and the RowSetReader must be
-     * registered as a Reader on the RowSet.
+     * Reads new data into the {@code RowSet}. The calling {@code RowSet} object
+     * must itself implement the {@code RowSetInternal} interface and the
+     * {@code RowSetReader} must be registered as a reader on the 
+     * {@code RowSet}.
      * <p>
-     * This method adds rows into the calling RowSet. The Reader may invoke any
-     * of the RowSet's methods except for the <code>execute</code> method
-     * (calling execute will cause an SQLException to be thrown). However, when
-     * the Reader calls the RowSet's methods, no events are sent to listeners -
-     * any listeners are informed by the calling RowSet's execute method once
-     * the Reader returns from the readData method.
+     * This method adds rows into the calling {@code RowSet}. The reader may
+     * invoke any of the {@code RowSet}'s methods except for the {@code execute}
+     * method (calling {@code execute} will cause an {@code SQLException} to be
+     * thrown). However, when the reader calls the {@code RowSet}'s methods, no
+     * events are sent to listeners - any listeners are informed by the calling
+     * {@code RowSet}'s {@code execute} method once the reader returns from the
+     * {@code readData} method.
      * 
      * @param theCaller
-     *            must be the calling RowSet object, which must have implemented
-     *            the RowSetInternal interface.
+     *            must be the calling {@code RowSet} object, which must have
+     *            implemented the {@code RowSetInternal} interface.
      * @throws SQLException
-     *             if a problem occurs accessing the database or if the Reader
-     *             calls the RowSet.execute method.
+     *             if a problem occurs accessing the database or if the reader
+     *             calls the {@link RowSet#execute()} method.
+     * @see RowSetInternal
      */
     public void readData(RowSetInternal theCaller) throws SQLException;
 }

Modified: harmony/enhanced/classlib/trunk/modules/sql/src/main/java/javax/sql/RowSetWriter.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/sql/src/main/java/javax/sql/RowSetWriter.java?rev=770130&r1=770129&r2=770130&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/sql/src/main/java/javax/sql/RowSetWriter.java (original)
+++ harmony/enhanced/classlib/trunk/modules/sql/src/main/java/javax/sql/RowSetWriter.java Thu Apr 30 09:45:40 2009
@@ -20,33 +20,39 @@
 import java.sql.SQLException;
 
 /**
- * An interface which provides functionality for a disconnected RowSet to put
- * data updates back to the data source from which the RowSet was originally
- * populated. An object implementing this interface is called a Writer.
+ * An interface which provides functionality for a disconnected {@code RowSet}
+ * to put data updates back to the data source from which the {@code RowSet} was
+ * originally populated. An object implementing this interface is called a
+ * writer.
  * <p>
- * The Writer must establish a connection to the RowSet's data source before
- * writing the data. The RowSet calling this interface must implement the
- * RowSetInternal interface.
+ * The writer must establish a connection to the {@code RowSet}'s database
+ * before writing the data. The {@code RowSet} calling this interface must
+ * implement the {@code RowSetInternal} interface.
  * <p>
- * The Writer may encounter a situation where the updated data being written
- * back to the data source has already been updated in the data source. How a
- * conflict of this kind is handled is determined by the implementation of the
- * Writer.
+ * The writer may encounter a situation where the updated data needs to be
+ * written back to the database, but has already been updated there in the mean
+ * time. How a conflict of this kind is handled is determined by the
+ * implementation of this writer.
+ *
+ * @see RowSetInternal
  */
 public interface RowSetWriter {
 
     /**
-     * Writes changes in the RowSet associated with this RowSetWriter back to
-     * its data source.
+     * Writes changes made in the {@code RowSet}, which is associated with this
+     * {@code RowSetWriter}, back to the database.
      * 
      * @param theRowSet
-     *            the RowSet object. This RowSet must a) Implement the
-     *            RowSetInternal interface and b) have have this RowSetWriter
-     *            registered with it and c) must call this method internally
-     * @return true if the modified data was written, false otherwise (which
-     *         typically implies some form of conflict)
+     *            a row set that fulfills the following criteria:
+     *            <ul>
+     *            <li>it must implement the {@code RowSetInternal} interface,</li>
+     *            <li>have this {@code RowSetWriter} registered with it,</li>
+     *            <li>must call this method internally.</li>
+     *            </ul>
+     * @return {@code true} if the modified data was written, {@code false}
+     *         otherwise (which typically implies some form of conflict).
      * @throws SQLException
-     *             if a problem occurs accessing the database
+     *             if a problem occurs accessing the database.
      */
     public boolean writeData(RowSetInternal theRowSet) throws SQLException;
 }