harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From telli...@apache.org
Subject svn commit: r770130 [5/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/Date.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/Date.java?rev=770130&r1=770129&r2=770130&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/Date.java (original)
+++ harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/Date.java Thu Apr 30 09:45:40 2009
@@ -18,35 +18,37 @@
 package java.sql;
 
 /**
- * A Date class which can consume and produce dates in SQL Date format.
+ * A class which can consume and produce dates in SQL {@code Date} format.
  * <p>
- * The SQL date format represents a date as yyyy-mm-dd. Note that this date
+ * Dates are represented in SQL as {@code yyyy-mm-dd}. Note that this date
  * format only deals with year, month and day values. There are no values for
  * hours, minutes, seconds.
  * <p>
- * This contrasts with regular java.util.Date values, which include time values
- * for hours, minutes, seconds, milliseconds.
+ * This is unlike the familiar {@code java.util.Date} object, which also includes
+ * values for hours, minutes, seconds, and milliseconds.
  * <p>
- * Time points are handled as millisecond values - milliseconds since the epoch,
- * January 1st 1970, 00:00:00.000 GMT. Time values passed to the java.sql.Date
- * class are "normalized" to the time 00:00:00.000 GMT on the date implied by
- * the time value.
+ * Time points are handled as millisecond values - milliseconds since the Epoch,
+ * January 1st 1970, 00:00:00.000 GMT. Time values passed to the {@code
+ * java.sql.Date} class are "normalized" to the time 00:00:00.000 GMT on the
+ * date implied by the time value.
  */
 public class Date extends java.util.Date {
 
     private static final long serialVersionUID = 1511598038487230103L;
 
     /**
-     * @deprecated Please use the constructor Date( long ) Constructs a Date
-     *             object corresponding to the supplied Year, Month and Day.
+     * Constructs a {@code Date} object corresponding to the supplied year,
+     * month and day.
+     *
+     * @deprecated Please use the constructor {@link #Date(long)}.
      * @param theYear
      *            the year, specified as the year minus 1900. Must be in the
-     *            range 0 to 8099.
+     *            range {@code [0,8099]}.
      * @param theMonth
      *            the month, specified as a number with 0 = January. Must be in
-     *            the range 0 to 11.
+     *            the range {@code [0,11]}.
      * @param theDay
-     *            the day in the month. Must be in the range 1 to 31.
+     *            the day in the month. Must be in the range {@code [1,31]}.
      */
     @Deprecated
     public Date(int theYear, int theMonth, int theDay) {
@@ -54,14 +56,14 @@
     }
 
     /**
-     * Creates a Date which corresponds to the day implied by the supplied
-     * theDate milliseconds time value.
+     * Creates a date which corresponds to the day determined by the supplied
+     * milliseconds time value {@code theDate}.
      * 
-     * @param theDate -
+     * @param theDate
      *            a time value in milliseconds since the epoch - January 1 1970
      *            00:00:00 GMT. The time value (hours, minutes, seconds,
-     *            milliseconds) stored in the Date object is adjusted to
-     *            correspond to 00:00:00 GMT on the day implied by the supplied
+     *            milliseconds) stored in the {@code Date} object is adjusted to
+     *            correspond to 00:00:00 GMT on the day determined by the supplied
      *            time value.
      */
     public Date(long theDate) {
@@ -69,11 +71,11 @@
     }
 
     /**
-     * @deprecated This method is deprecated and must not be used. SQL Date
-     *             values do not have an hours component.
-     * @return does not return
+     * @deprecated This method is deprecated and must not be used. SQL {@code
+     *             Date} values do not have an hours component.
+     * @return does not return anything.
      * @throws IllegalArgumentException
-     *             if this method is called
+     *             if this method is called.
      */
     @Deprecated
     @Override
@@ -82,11 +84,11 @@
     }
 
     /**
-     * @deprecated This method is deprecated and must not be used. SQL Date
-     *             values do not have a minutes component.
-     * @return does not return
+     * @deprecated This method is deprecated and must not be used. SQL {@code
+     *             Date} values do not have a minutes component.
+     * @return does not return anything.
      * @throws IllegalArgumentException
-     *             if this method is called
+     *             if this method is called.
      */
     @Deprecated
     @Override
@@ -95,11 +97,11 @@
     }
 
     /**
-     * @deprecated This method is deprecated and must not be used. SQL Date
-     *             values do not have a seconds component.
-     * @return does not return
+     * @deprecated This method is deprecated and must not be used. SQL {@code
+     *             Date} values do not have a seconds component.
+     * @return does not return anything.
      * @throws IllegalArgumentException
-     *             if this method is called
+     *             if this method is called.
      */
     @Deprecated
     @Override
@@ -108,12 +110,12 @@
     }
 
     /**
-     * @deprecated This method is deprecated and must not be used. SQL Date
-     *             values do not have an hours component.
+     * @deprecated This method is deprecated and must not be used. SQL {@code
+     *             Date} values do not have an hours component.
      * @param theHours
-     *            the number of hours to set
+     *            the number of hours to set.
      * @throws IllegalArgumentException
-     *             if this method is called
+     *             if this method is called.
      */
     @Deprecated
     @Override
@@ -122,12 +124,12 @@
     }
 
     /**
-     * @deprecated This method is deprecated and must not be used. SQL Date
-     *             values do not have a minutes component.
+     * @deprecated This method is deprecated and must not be used. SQL {@code
+     *             Date} values do not have a minutes component.
      * @param theMinutes
-     *            the number of minutes to set
+     *            the number of minutes to set.
      * @throws IllegalArgumentException
-     *             if this method is called
+     *             if this method is called.
      */
     @Deprecated
     @Override
@@ -136,12 +138,12 @@
     }
 
     /**
-     * @deprecated This method is deprecated and must not be used. SQL Date
-     *             values do not have a seconds component.
+     * @deprecated This method is deprecated and must not be used. SQL {@code
+     *             Date} values do not have a seconds component.
      * @param theSeconds
-     *            the number of seconds to set
+     *            the number of seconds to set.
      * @throws IllegalArgumentException
-     *             if this method is called
+     *             if this method is called.
      */
     @Deprecated
     @Override
@@ -151,11 +153,10 @@
 
     /**
      * Sets this date to a date supplied as a milliseconds value. The date is
-     * set based on the supplied time value after removing any time elements
-     * finer than a day, based on zero GMT for that day.
+     * set based on the supplied time value and rounded to zero GMT for that day.
      * 
      * @param theTime
-     *            the time in milliseconds since the Epoch
+     *            the time in milliseconds since the Epoch.
      */
     @Override
     public void setTime(long theTime) {
@@ -167,9 +168,10 @@
     }
 
     /**
-     * Produces a string representation of the Date in SQL format
+     * Produces a string representation of the date in SQL format
      * 
-     * @return a string representation of the Date in SQL format - "yyyy-mm-dd".
+     * @return a string representation of the date in SQL format - {@code
+     *         "yyyy-mm-dd"}.
      */
     @Override
     public String toString() {
@@ -198,12 +200,13 @@
     }
 
     /**
-     * Creates a Date from a string representation of a date in SQL format.
+     * Creates a {@code Date} from a string representation of a date in SQL
+     * format.
      * 
      * @param dateString
-     *            the string representation of a date in SQL format -
-     *            "yyyy-mm-dd".
-     * @return the Date object
+     *            the string representation of a date in SQL format - " {@code
+     *            yyyy-mm-dd}".
+     * @return the {@code Date} object.
      * @throws IllegalArgumentException
      *             if the format of the supplied string does not match the SQL
      *             format.

Modified: harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/Driver.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/Driver.java?rev=770130&r1=770129&r2=770130&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/Driver.java (original)
+++ harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/Driver.java Thu Apr 30 09:45:40 2009
@@ -20,14 +20,19 @@
 import java.util.Properties;
 
 /**
- * An Interface to a JDBC Driver.
+ * An interface to a JDBC driver.
  * <p>
- * The JDBC Driver uses URLs to specify the location of specific data. URL
- * format typically takes the form "xxxx:yyyy:SpecificData", where "xxxx:yyyy"
- * is termed the subprotocol and is normally the same for all uses of a
- * particular driver. "SpecificData" is a string which identifies the particular
- * data source that the driver should use.
- * 
+ * The JDBC driver uses URLs to specify the location of specific data. URL
+ * format typically takes the form " {@code xxxx:yyyy:SpecificData}", where "
+ * {@code xxxx:yyyy}" is referred to as the <i>subprotocol</i> and is normally
+ * the same for all of a particular driver. " {@code SpecificData}" is a string
+ * which identifies the particular data source that the driver should use.
+ * <p>
+ * A driver needs to be registered with a {@link DriverManager}. It is
+ * registered and instantiated by calling {@code Class.forName("DriverURL")}
+ * with the URL string as argument.
+ *
+ * @see DriverManager
  */
 public interface Driver {
 
@@ -37,43 +42,44 @@
      * 
      * @param url
      *            the URL to connect to.
-     * @return true if the driver thinks that is can open a connection to the
-     *         supplied URL, false otherwise. Typically, the driver will respond
-     *         true if it thinks that it can handle the subprotocol specified by
-     *         the driver.
+     * @return {@code true} if the driver thinks that is can open a connection
+     *         to the supplied URL, {@code false} otherwise. Typically, the
+     *         driver will respond {@code true} if it thinks that it can handle
+     *         the subprotocol specified by the driver.
      * @throws SQLException
+     *          if a database error occurs.
      */
     public boolean acceptsURL(String url) throws SQLException;
 
     /**
-     * Attempts to make a database connection to a datasource specified by a
+     * Attempts to make a database connection to a data source specified by a
      * supplied URL.
      * 
      * @param url
-     *            the url to connect.
+     *            the URL to connect.
      * @param info
      *            some properties that should be used in establishing the
      *            connection. The properties consist of name/value pairs of
-     *            Strings. Normally, a connection to a database requires at
-     *            least two properties - for "user" and "password" in order to
-     *            pass authentication to the database.
-     * @return a Connection object representing the connection to the database.
+     *            strings. Normally, a connection to a database requires at
+     *            least two properties - for {@code "user"} and {@code
+     *            "password"} in order to pass authentication to the database.
+     * @return the connection to the database.
      * @throws SQLException
-     *             if a database error occurs
+     *             if a database error occurs.
      */
     public Connection connect(String url, Properties info) throws SQLException;
 
     /**
      * Gets the driver's major version number.
      * 
-     * @return the major version number of the Driver - typically starts at 1.
+     * @return the major version number of the driver - typically starts at 1.
      */
     public int getMajorVersion();
 
     /**
      * Gets the driver's minor version number.
      * 
-     * @return the minor version number of the Driver - typically starts at 0.
+     * @return the minor version number of the driver - typically starts at 0.
      */
     public int getMinorVersion();
 
@@ -81,32 +87,38 @@
      * Gets information about possible properties for this driver.
      * <p>
      * This method is intended to provide a listing of possible properties that
-     * the user of the driver may need to supply in order to correct connect to
-     * a database. Note that the returned array of Properties may change
+     * the client of the driver must supply in order to establish a connection
+     * to a database. Note that the returned array of properties may change
      * depending on the supplied list of property values.
-     * 
+     *
      * @param url
-     *            the url of the database. A using program may call this method
+     *            the URL of the database. An application may call this method
      *            iteratively as the property list is built up - for example,
      *            when displaying a dialog to an end-user as part of the
      *            database login process.
      * @param info
-     * @return an array of DriverPropertyInfo records which provide detail on
-     *         each property that the driver will accept.
+     *            a set of tag/value pairs giving data that a user may be 
+     *            prompted to provide in order to connect to the database.
+     * @return an array of {@code DriverPropertyInfo} records which provide
+     *         details on which additional properties are required (in addition
+     *         to those supplied in the {@code info} parameter) in order to 
+     *         connect to the database.
      * @throws SQLException
+     *             if a database error occurs.
      */
     public DriverPropertyInfo[] getPropertyInfo(String url, Properties info)
             throws SQLException;
 
     /**
      * Reports whether this driver is a genuine JDBC CompliantTM driver. The
-     * driver may only return true from this method if it passes all the JDBC
-     * Compliance tests.
+     * driver may only return {@code true} if it passes all the JDBC compliance
+     * tests.
      * <p>
      * A driver may not be fully compliant if the underlying database has
      * limited functionality.
-     * 
-     * @return true if the driver is fully JDBC compliant, false otherwise.
+     *
+     * @return {@code true} if the driver is fully JDBC compliant, {@code false}
+     *         otherwise.
      */
     public boolean jdbcCompliant();
 

Modified: harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/DriverManager.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/DriverManager.java?rev=770130&r1=770129&r2=770130&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/DriverManager.java (original)
+++ harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/DriverManager.java Thu Apr 30 09:45:40 2009
@@ -31,10 +31,11 @@
 import org.apache.harmony.kernel.vm.VM;
 
 /**
- * Provides facilities for managing JDBC Drivers.
+ * Provides facilities for managing JDBC drivers.
  * <p>
- * The DriverManager class will load JDBC drivers during its initialization,
- * from the list of drivers referenced by the System Property "jdbc.drivers".
+ * The {@code DriverManager} class loads JDBC drivers during its initialization,
+ * from the list of drivers referenced by the system property {@code
+ * "jdbc.drivers"}.
  */
 public class DriverManager {
 
@@ -104,17 +105,19 @@
     }
 
     /**
-     * Removes a driver from the DriverManager's registered driver list. This
-     * will only succeed where the caller's classloader loaded the driver that
-     * is to be removed. If the driver was loaded by a different classloader,
-     * the removal of the driver will fail silently.
+     * Removes a driver from the {@code DriverManager}'s registered driver list.
+     * This will only succeed when the caller's class loader loaded the driver
+     * that is to be removed. If the driver was loaded by a different class
+     * loader, the removal of the driver fails silently.
      * <p>
-     * If the removal succeeds, the DriverManager will not in future use this
-     * driver when asked to get a Connection.
-     * 
+     * If the removal succeeds, the {@code DriverManager} will not use this
+     * driver in the future when asked to get a {@code Connection}.
+     *
      * @param driver
+     *            the JDBC driver to remove.
      * @throws SQLException
-     *             if there is an exception accessing the database.
+     *             if there is a problem interfering with accessing the
+     *             database.
      */
     public static void deregisterDriver(Driver driver) throws SQLException {
         if (driver == null) {
@@ -136,12 +139,12 @@
      * Attempts to establish a connection to the given database URL.
      * 
      * @param url
-     *            a URL string representing the database target to connect with
-     * @return a Connection to the database identified by the URL. null if no
-     *         connection can be made.
+     *            a URL string representing the database target to connect with.
+     * @return a {@code Connection} to the database identified by the URL.
+     *         {@code null} if no connection can be established.
      * @throws SQLException
      *             if there is an error while attempting to connect to the
-     *             database identified by the URL
+     *             database identified by the URL.
      */
     public static Connection getConnection(String url) throws SQLException {
         return getConnection(url, new Properties());
@@ -153,17 +156,17 @@
      * @param url
      *            a URL string representing the database target to connect with
      * @param info
-     *            a set of Properties to use as arguments to set up the
+     *            a set of properties to use as arguments to set up the
      *            connection. Properties are arbitrary string/value pairs.
-     *            Normally, at least the properties "user" and "password" should
-     *            be passed, with appropriate settings for the userid and its
-     *            corresponding password to get access to the database
-     *            concerned.
-     * @return a Connection to the database identified by the URL. null if no
-     *         connection can be made.
+     *            Normally, at least the properties {@code "user"} and {@code
+     *            "password"} should be passed, with appropriate settings for
+     *            the user ID and its corresponding password to get access to
+     *            the corresponding database.
+     * @return a {@code Connection} to the database identified by the URL.
+     *         {@code null} if no connection can be established.
      * @throws SQLException
      *             if there is an error while attempting to connect to the
-     *             database identified by the URL
+     *             database identified by the URL.
      */
     public static Connection getConnection(String url, Properties info)
             throws SQLException {
@@ -196,16 +199,16 @@
      * Attempts to establish a connection to the given database URL.
      * 
      * @param url
-     *            a URL string representing the database target to connect with
+     *            a URL string representing the database target to connect with.
      * @param user
-     *            a userid used to login to the database
+     *            a user ID used to login to the database.
      * @param password
-     *            a password for the userid to login to the database
-     * @return a Connection to the database identified by the URL. null if no
-     *         connection can be made.
+     *            a password for the user ID to login to the database.
+     * @return a {@code Connection} to the database identified by the URL.
+     *         {@code null} if no connection can be established.
      * @throws SQLException
      *             if there is an error while attempting to connect to the
-     *             database identified by the URL
+     *             database identified by the URL.
      */
     public static Connection getConnection(String url, String user,
             String password) throws SQLException {
@@ -223,11 +226,11 @@
      * Tries to find a driver that can interpret the supplied URL.
      * 
      * @param url
-     *            the URL of a database
-     * @return a Driver that can understand the given URL. null if no Driver
-     *         understands the URL
+     *            the URL of a database.
+     * @return a {@code Driver} that matches the provided URL. {@code null} if
+     *         no {@code Driver} understands the URL
      * @throws SQLException
-     *             if there is any kind of Database Access problem
+     *             if there is any kind of problem accessing the database.
      */
     public static Driver getDriver(String url) throws SQLException {
         ClassLoader callerClassLoader = VM.callerClassLoader();
@@ -256,10 +259,11 @@
     }
 
     /**
-     * Returns an Enumeration that contains all of the loaded JDBC drivers that
-     * the current caller can access.
+     * Returns an {@code Enumeration} that contains all of the loaded JDBC
+     * drivers that the current caller can access.
      * 
-     * @return An Enumeration containing all the currently loaded JDBC Drivers
+     * @return An {@code Enumeration} containing all the currently loaded JDBC
+     *         {@code Drivers}.
      */
     public static Enumeration<Driver> getDrivers() {
         ClassLoader callerClassLoader = VM.callerClassLoader();
@@ -286,18 +290,20 @@
     }
 
     /**
-     * Returns the login timeout when connecting to a database, in seconds.
+     * Returns the login timeout when connecting to a database in seconds.
      * 
-     * @return the login timeout in seconds
+     * @return the login timeout in seconds.
      */
     public static int getLoginTimeout() {
         return loginTimeout;
     }
 
     /**
-     * @deprecated Gets the log PrintStream used by the DriverManager and all
-     *             the JDBC Drivers.
-     * @return the PrintStream used for logging activity
+     * Gets the log {@code PrintStream} used by the {@code DriverManager} and
+     * all the JDBC Drivers.
+     *
+     * @deprecated use {@link #getLogWriter()} instead.
+     * @return the {@code PrintStream} used for logging activities.
      */
     @Deprecated
     public static PrintStream getLogStream() {
@@ -307,8 +313,8 @@
     /**
      * Retrieves the log writer.
      * 
-     * @return A PrintWriter object used as the log writer. null if no log
-     *         writer is set.
+     * @return A {@code PrintWriter} object used as the log writer. {@code null}
+     *         if no log writer is set.
      */
     public static PrintWriter getLogWriter() {
         return thePrintWriter;
@@ -316,10 +322,10 @@
 
     /**
      * Prints a message to the current JDBC log stream. This is either the
-     * PrintWriter or (deprecated) the PrintStream, if set.
+     * {@code PrintWriter} or (deprecated) the {@code PrintStream}, if set.
      * 
      * @param message
-     *            the message to print to the JDBC log stream
+     *            the message to print to the JDBC log stream.
      */
     public static void println(String message) {
         if (thePrintWriter != null) {
@@ -337,13 +343,13 @@
     }
 
     /**
-     * Registers a given JDBC driver with the DriverManager.
+     * Registers a given JDBC driver with the {@code DriverManager}.
      * <p>
      * A newly loaded JDBC driver class should register itself with the
-     * DriverManager by calling this method.
-     * 
+     * {@code DriverManager} by calling this method.
+     *
      * @param driver
-     *            the Driver to register with the DriverManager
+     *            the {@code Driver} to register with the {@code DriverManager}.
      * @throws SQLException
      *             if a database access error occurs.
      */
@@ -357,7 +363,7 @@
     }
 
     /**
-     * Set the login timeout when connecting to a database, in seconds.
+     * Sets the login timeout when connecting to a database in seconds.
      * 
      * @param seconds
      *            seconds until timeout. 0 indicates wait forever.
@@ -368,12 +374,12 @@
     }
 
     /**
-     * @deprecated Sets the Print Stream to use for logging data from the
-     *             DriverManager and the JDBC drivers.
-     *             <p>
-     *             Use setLogWriter instead.
+     * Sets the print stream to use for logging data from the {@code
+     * DriverManager} and the JDBC drivers.
+     *
+     * @deprecated Use {@link #setLogWriter} instead.
      * @param out
-     *            the PrintStream to use for logging.
+     *            the {@code PrintStream} to use for logging.
      */
     @Deprecated
     public static void setLogStream(PrintStream out) {
@@ -382,11 +388,11 @@
     }
 
     /**
-     * Sets the PrintWriter that will be used by all loaded drivers, and also
-     * the DriverManager.
+     * Sets the {@code PrintWriter} that is used by all loaded drivers, and also
+     * the {@code DriverManager}.
      * 
      * @param out
-     *            the PrintWriter to be used
+     *            the {@code PrintWriter} to be used.
      */
     public static void setLogWriter(PrintWriter out) {
         checkLogSecurity();
@@ -406,14 +412,14 @@
     }
 
     /**
-     * Finds if a supplied Object belongs to the given ClassLoader.
+     * Determines whether the supplied object was loaded by the given {@code ClassLoader}.
      * 
      * @param theObject
-     *            the object to check
+     *            the object to check.
      * @param theClassLoader
-     *            the ClassLoader
-     * @return true if the Object does belong to the ClassLoader, false
-     *         otherwise
+     *            the {@code ClassLoader}.
+     * @return {@code true} if the Object does belong to the {@code ClassLoader}
+     *         , {@code false} otherwise
      */
     private static boolean isClassFromClassLoader(Object theObject,
             ClassLoader theClassLoader) {

Modified: harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/DriverPropertyInfo.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/DriverPropertyInfo.java?rev=770130&r1=770129&r2=770130&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/DriverPropertyInfo.java (original)
+++ harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/DriverPropertyInfo.java Thu Apr 30 09:45:40 2009
@@ -18,20 +18,21 @@
 package java.sql;
 
 /**
- * A class holding information about Driver Properties for making a Connection.
- * This class is returned from the <code>Driver.getDriverProperties</code>
- * method and is useful in using Connections in an advanced way.
+ * A class holding information about driver properties of a database connection.
+ * This class is returned by the
+ * {@link Driver#getPropertyInfo(String, java.util.Properties)} method and
+ * allows for the advanced connection handling.
  */
 public class DriverPropertyInfo {
 
     /**
      * If the value member can be chosen from a set of possible values, they are
-     * contained here. Otherwise choices is null.
+     * contained here. Otherwise choices is {@code null}.
      */
     public String[] choices;
 
     /**
-     * A description of the property. May be null.
+     * A description of the property. May be {@code null}.
      */
     public String description;
 
@@ -41,26 +42,26 @@
     public String name;
 
     /**
-     * True when the value member must be provided during Driver.connect. False
-     * otherwise.
+     * {@code True} when the value member must be provided during {@code
+     * Driver.connect}. {@code False} otherwise.
      */
     public boolean required;
 
     /**
-     * The current value associated with this property. This is based on the
-     * data gathered by the getPropertyInfo method, the general Java environment
-     * and the default values for the driver.
+     * The current value associated with this property. It is depending on the
+     * data gathered by the {@code getPropertyInfo} method, the general Java
+     * environment and the driver's default values.
      */
     public String value;
 
     /**
-     * Creates a DriverPropertyInfo instance with the supplied name and value.
-     * Other members take their default values.
+     * Creates a {@code DriverPropertyInfo} instance with the supplied name and
+     * value. Other class members take their default values.
      * 
      * @param name
-     *            The property name
+     *            The property name.
      * @param value
-     *            The property value
+     *            The property value.
      */
     public DriverPropertyInfo(String name, String value) {
         this.name = name;

Modified: harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/ParameterMetaData.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/ParameterMetaData.java?rev=770130&r1=770129&r2=770130&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/ParameterMetaData.java (original)
+++ harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/ParameterMetaData.java Thu Apr 30 09:45:40 2009
@@ -19,22 +19,22 @@
 
 /**
  * An interface used to get information about the types and properties of
- * parameters in a PreparedStatement object.
+ * parameters in a {@code PreparedStatement}.
  */
 public interface ParameterMetaData {
 
     /**
-     * Indicates that the parameter mode is IN.
+     * Indicates that the parameter mode is {@code IN}.
      */
     public static final int parameterModeIn = 1;
 
     /**
-     * Indicates that the parameter mode is INOUT.
+     * Indicates that the parameter mode is {@code INOUT}.
      */
     public static final int parameterModeInOut = 2;
 
     /**
-     * Indicates that the parameter mode is OUT.
+     * Indicates that the parameter mode is {@code OUT}.
      */
     public static final int parameterModeOut = 4;
 
@@ -44,58 +44,61 @@
     public static final int parameterModeUnknown = 0;
 
     /**
-     * Indicates that a parameter is not permitted to be NULL.
+     * Indicates that a parameter is not permitted to be {@code NULL}.
      */
     public static final int parameterNoNulls = 0;
 
     /**
-     * Indicates that a parameter is permitted to be NULL.
+     * Indicates that a parameter is permitted to be {@code NULL}.
      */
     public static final int parameterNullable = 1;
 
     /**
-     * Indicates that whether a parameter is allowed to be null or not is not
-     * known.
+     * Indicates that whether a parameter is allowed to be {@code null} or not
+     * is not known.
      */
     public static final int parameterNullableUnknown = 2;
 
     /**
      * Gets the fully-qualified name of the Java class which should be passed as
-     * a parameter to the method <code>PreparedStatement.setObject</code>.
+     * a parameter to the method {@code PreparedStatement.setObject}.
      * 
      * @param paramIndex
      *            the index number of the parameter, where the first parameter
-     *            has an index of 1
-     * @return a String with the fully qualified Java class name of the
-     *         parameter with the specified index. This class name is used for
-     *         custom mapping.
+     *            has index 1.
+     * @return the fully qualified Java class name of the parameter with the
+     *         specified index. This class name is used for custom mapping
+     *         between SQL types and Java objects.
      * @throws SQLException
-     *             if a database error happens
+     *             if a database error happens.
      */
     public String getParameterClassName(int paramIndex) throws SQLException;
 
     /**
-     * Gets the number of parameters in the PreparedStatement for which this
-     * ParameterMetaData contains information.
+     * Gets the number of parameters in the {@code PreparedStatement} for which
+     * this {@code ParameterMetaData} contains information.
      * 
-     * @return the number of parameters as an int
+     * @return the number of parameters.
      * @throws SQLException
-     *             if a database error happens
+     *             if a database error happens.
      */
     public int getParameterCount() throws SQLException;
 
     /**
-     * Gets the mode of the specified parameter.
+     * Gets the mode of the specified parameter. Can be one of:
+     * <ul>
+     * <li>ParameterMetaData.parameterModeIn</li>
+     * <li>ParameterMetaData.parameterModeOut</li>
+     * <li>ParameterMetaData.parameterModeInOut</li>
+     * <li>ParameterMetaData.parameterModeUnknown</li>
+     * </ul>
      * 
      * @param paramIndex
      *            the index number of the parameter, where the first parameter
-     *            has an index of 1
-     * @return the parameters mode. Can be: ParameterMetaData.parameterModeIn,
-     *         ParameterMetaData.parameterModeOut,
-     *         ParameterMetaData.parameterModeInOut or
-     *         ParameterMetaData.parameterModeUnknown.
+     *            has index 1.
+     * @return the parameter's mode.
      * @throws SQLException
-     *             if a database error happens
+     *             if a database error happens.
      */
     public int getParameterMode(int paramIndex) throws SQLException;
 
@@ -104,11 +107,11 @@
      * 
      * @param paramIndex
      *            the index number of the parameter, where the first parameter
-     *            has an index of 1
-     * @return the type of the parameter - an SQL type as defined in
-     *         java.sql.Types.
+     *            has index 1.
+     * @return the SQL type of the parameter as defined in {@code
+     *         java.sql.Types}.
      * @throws SQLException
-     *             if a database error happens
+     *             if a database error happens.
      */
     public int getParameterType(int paramIndex) throws SQLException;
 
@@ -117,12 +120,12 @@
      * 
      * @param paramIndex
      *            the index number of the parameter, where the first parameter
-     *            has an index of 1
+     *            has index 1.
      * @return the type name for the parameter as used by the database. A
-     *         fully-qualified name is returned if the parameter is a User
-     *         Defined Type.
+     *         fully-qualified name is returned if the parameter is a <i>User
+     *         Defined Type</i> (UDT).
      * @throws SQLException
-     *             if a database error happens
+     *             if a database error happens.
      */
     public String getParameterTypeName(int paramIndex) throws SQLException;
 
@@ -131,11 +134,11 @@
      * 
      * @param paramIndex
      *            the index number of the parameter, where the first parameter
-     *            has an index of 1
+     *            has index 1.
      * @return the number of decimal digits ("the precision") for the parameter.
-     *         0 if the parameter is not a numeric type.
+     *         {@code 0} if the parameter is not a numeric type.
      * @throws SQLException
-     *             if a database error happens
+     *             if a database error happens.
      */
     public int getPrecision(int paramIndex) throws SQLException;
 
@@ -145,26 +148,29 @@
      * 
      * @param paramIndex
      *            the index number of the parameter, where the first parameter
-     *            has an index of 1
+     *            has index 1.
      * @return the number of digits after the decimal point ("the scale") for
-     *         the parameter. 0 if the parameter is not a numeric type.
+     *         the parameter. {@code 0} if the parameter is not a numeric type.
      * @throws SQLException
-     *             if a database error happens
+     *             if a database error happens.
      */
     public int getScale(int paramIndex) throws SQLException;
 
     /**
-     * Gets whether null values are allowed for the specified parameter.
+     * Gets whether {@code null} values are allowed for the specified parameter.
+     * The returned value is one of:
+     * <ul>
+     * <li>ParameterMetaData.parameterNoNulls</li>
+     * <li>ParameterMetaData.parameterNullable</li>
+     * <li>ParameterMetaData.parameterNullableUnknown</li>
+     * </ul>
      * 
      * @param paramIndex
      *            the index number of the parameter, where the first parameter
-     *            has an index of 1
-     * @return indicator of nullability, can be:
-     *         ParameterMetaData.parameterNoNulls,
-     *         ParameterMetaData.parameterNullable, or
-     *         ParameterMetaData.parameterNullableUnknown
+     *            has index 1.
+     * @return the int code indicating the nullability of the parameter.
      * @throws SQLException
-     *             if a database error is encountered
+     *             if a database error is encountered.
      */
     public int isNullable(int paramIndex) throws SQLException;
 
@@ -173,11 +179,11 @@
      * 
      * @param paramIndex
      *            the index number of the parameter, where the first parameter
-     *            has an index of 1
-     * @return true if values can be signed numbers for this parameter, false
-     *         otherwise.
+     *            has index 1.
+     * @return {@code true} if values can be signed numbers for this parameter,
+     *         {@code false} otherwise.
      * @throws SQLException
-     *             if a database error happens
+     *             if a database error happens.
      */
     public boolean isSigned(int paramIndex) throws SQLException;
 }

Modified: harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/PreparedStatement.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/PreparedStatement.java?rev=770130&r1=770129&r2=770130&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/PreparedStatement.java (original)
+++ harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/PreparedStatement.java Thu Apr 30 09:45:40 2009
@@ -24,22 +24,22 @@
 import java.math.BigDecimal;
 
 /**
- * An interface for a Precompiled SQL Statement.
+ * An interface for a precompiled SQL Statement.
  * <p>
- * An SQL Statement is put into a PreparedStatement and is precompiled so that
- * it can be executed multiple times efficiently.
+ * An SQL Statement is put into a {@code PreparedStatement} and is precompiled
+ * so that it can be executed efficiently multiple times.
  * <p>
- * Setter methods are supplied in the PreparedStatement interface for the
- * setting of IN parameters for the Statement. The setter method used for each
- * IN parameter must match the type of the IN parameter being set.
+ * Setter methods are supplied in the {@code PreparedStatement} interface for
+ * the setting of {@code IN} parameters for the statement. The setter method
+ * used for each {@code IN} parameter must match the parameter's type.
  */
 public interface PreparedStatement extends Statement {
 
     /**
-     * Add a set of parameters to the PreparedStatement's command batch.
+     * Add a set of parameters to the {@code PreparedStatement}'s command batch.
      * 
      * @throws SQLException
-     *             if a database error happens
+     *             if a database error happens.
      */
     public void addBatch() throws SQLException;
 
@@ -47,365 +47,399 @@
      * Clear the current parameter values.
      * <p>
      * Typically, parameter values are retained for multiple executions of the
-     * Statement. Setting a parameter value replaces the previous value. This
+     * {@code Statement}. Setting a parameter value replaces the previous value. This
      * method clears the values for all parameters, releasing all resources used
      * by those parameters.
-     * 
+     *
      * @throws SQLException
-     *             if a database error happens
+     *             if a database error happens.
      */
     public void clearParameters() throws SQLException;
 
     /**
-     * Executes the SQL statement in this PreparedStatement.
+     * Executes the SQL statement in this {@code PreparedStatement}.
      * <p>
-     * A PreparedStatement may return multiple results. The execute method
-     * returns a flag indicating the kind of result produced by
-     * PreparedStatement. The methods <code>
-     * getResultSet</code> or
-     * <code>getUpdateCount</code> are used to retrieve the first result,
-     * while <code>getMoreResults</code> must be used to retrieve the second
-     * and subsequent results.
-     * 
-     * @return true if the result of the execution is a ResultSet, false if
-     *         there is no result or if the result is an update count.
+     * A {@code PreparedStatement} may return multiple results. The execute
+     * method executes the {@code PreparedStatement} and returns a flag 
+     * indicating the kind of result produced by the action. The methods 
+     * {@code getResultSet} or {@code getUpdateCount} are used to retrieve 
+     * the first result, and the second and subsequent results are 
+     * retrieved with {@code getMoreResults}.
+     *
+     * @return {@code true} if the result of the execution is a {@code
+     *         ResultSet}, {@code false} if there is no result or if the result
+     *         is an update count.
      * @throws SQLException
-     *             if a database error happens
+     *             if a database error happens.
      */
     public boolean execute() throws SQLException;
 
     /**
-     * Execute the SQL query in the PreparedStatement and return the ResultSet
-     * generated by the query.
+     * Executes the SQL query in the {@code PreparedStatement} and returns the
+     * {@code ResultSet} generated by the query.
      * 
-     * @return the ResultSet generated by the query - never null.
+     * @return the {@code ResultSet} generated by the query, never {@code null}.
      * @throws SQLException
      *             if a database error happens or if the SQL statement does not
-     *             produce a ResultSet.
+     *             produce a {@code ResultSet}.
      */
     public ResultSet executeQuery() throws SQLException;
 
     /**
-     * Invoke the SQL command contained within the Prepared Statement. This must
-     * be INSERT, UPDATE, DELETE, or a command that returns nothing.
+     * Invokes the SQL command contained within the prepared statement. This
+     * must be {@code INSERT}, {@code UPDATE}, {@code DELETE}, or a command that
+     * returns nothing.
      * 
-     * @return the count of rows for INSERT, UPDATE or DELETE statements, 0 for
-     *         statements that return nothing
+     * @return the number of affected rows for {@code INSERT}, {@code UPDATE} or {@code
+     *         DELETE} statements, {@code 0} for statements that return nothing.
      * @throws SQLException
      *             if a database error happens or if the SQL statement returns a
-     *             ResultSet.
+     *             {@code ResultSet}.
      */
     public int executeUpdate() throws SQLException;
 
     /**
-     * Returns a ResultSetMetaData containing data from the ResultSet that is
-     * produced when the PreparedStatement is invoked.
+     * Returns a {@code ResultSetMetaData} describing the {@code
+     * ResultSet} that would be produced by execution of the {@code PreparedStatement}.
      * <p>
-     * It is possible to know the Metadata for the ResultSet without executing
-     * the PreparedStatement, because the PreparedStatement is precompiled. As a
-     * result the Metadata can be queried ahead of time without actually
-     * executing the statement.
-     * 
-     * @return a ResultSetMetaData object with the information about the columns
-     *         of the ResultSet, if the driver can return a ResultSetMetaData.
-     *         null otherwise.
+     * It is possible to know the metadata for the {@code ResultSet} without
+     * executing the {@code PreparedStatement}, because the {@code
+     * PreparedStatement} is precompiled. As a result the metadata can be
+     * queried ahead of time without actually executing the statement.
+     *
+     * @return a {@code ResultSetMetaData} object with the information about the
+     *         columns of the {@code ResultSet}, if the driver can return a
+     *         {@code ResultSetMetaData}. {@code null} otherwise.
      * @throws SQLException
-     *             if there is a database error
+     *             if there is a database error.
      */
     public ResultSetMetaData getMetaData() throws SQLException;
 
     /**
-     * Gets information about the parameters of the PreparedStatement.
+     * Gets information about the parameters of the {@code PreparedStatement}.
      * 
-     * @return a ParameterMetaData object which holds information about the
-     *         number, type and properties of the parameters of this
-     *         PreparedStatement.
+     * @return a {@code ParameterMetaData} object which holds information about
+     *         the number, type, and properties of the parameters of this {@code
+     *         PreparedStatement}.
      * @throws SQLException
-     *             if a database error happens
+     *             if a database error happens.
      */
     public ParameterMetaData getParameterMetaData() throws SQLException;
 
     /**
-     * Sets the value of a specified parameter to the supplied Array object.
+     * Sets the value of a specified parameter to the supplied {@code Array}.
      * 
      * @param parameterIndex
      *            the parameter number index, where the first parameter has
-     *            index 1
+     *            index 1.
      * @param theArray
-     *            a java.sql.Array holing the data to set.
+     *            a {@code java.sql.Array} giving the new value of the parameter at {@code
+     *            parameterIndex}.
      * @throws SQLException
-     *             if a database error happens
+     *             if a database error happens.
+     * @see Array
      */
     public void setArray(int parameterIndex, Array theArray)
             throws SQLException;
 
     /**
      * Sets the value of a specified parameter to the content of a supplied
-     * InputStream, which has a specified number of bytes.
+     * {@code InputStream}, which has a specified number of bytes.
      * <p>
-     * This is a good method for setting an SQL LONVARCHAR parameter where the
-     * length of the data is large. Data is read from the InputStream until
-     * end-of-file is reached or the specified number of bytes is copied.
-     * 
+     * This is a good method for setting an SQL {@code LONVARCHAR} parameter
+     * where the length of the data is large. Data is read from the {@code
+     * InputStream} until end-of-file is reached or the specified number of
+     * bytes is copied.
+     *
      * @param parameterIndex
      *            the parameter number index, where the first parameter has
-     *            index 1
+     *            index 1.
      * @param theInputStream
-     *            the ASCII InputStream carrying the data to update the
-     *            parameter
+     *            the ASCII {@code InputStream} carrying the data to which the
+     *            parameter at {@code parameterIndex} is set.
      * @param length
-     *            the number of bytes in the InputStream to copy to the
-     *            parameter
+     *            the number of bytes in the {@code InputStream} to copy to the
+     *            parameter.
      * @throws SQLException
-     *             if a database error happens
+     *             if a database error happens.
      */
     public void setAsciiStream(int parameterIndex, InputStream theInputStream,
             int length) throws SQLException;
 
     /**
-     * Sets the value of a specified parameter to a supplied
-     * java.math.BigDecimal value.
+     * Sets the value of a specified parameter to a supplied {@code
+     * java.math.BigDecimal} value.
      * 
      * @param parameterIndex
      *            the parameter number index, where the first parameter has
-     *            index 1
+     *            index 1.
      * @param theBigDecimal
-     *            the java.math.BigInteger value to set
+     *            the value to which the parameter at {@code parameterIndex} is
+     *            set.
      * @throws SQLException
-     *             if a database error happens
+     *             if a database error happens.
+     * @see java.math.BigDecimal
      */
     public void setBigDecimal(int parameterIndex, BigDecimal theBigDecimal)
             throws SQLException;
 
     /**
      * Sets the value of a specified parameter to the content of a supplied
-     * binary InputStream, which has a specified number of bytes.
+     * binary {@code InputStream}, which has a specified number of bytes.
      * <p>
      * Use this method when a large amount of data needs to be set into a
-     * LONGVARBINARY parameter.
-     * 
+     * {@code LONGVARBINARY} parameter.
+     *
      * @param parameterIndex
      *            the parameter number index, where the first parameter has
-     *            index 1
+     *            index 1.
      * @param theInputStream
-     *            the binary InputStream carrying the data to update the
-     *            parameter
+     *            the binary {@code InputStream} carrying the data to update the
+     *            parameter.
      * @param length
-     *            the number of bytes in the InputStream to copy to the
-     *            parameter
+     *            the number of bytes in the {@code InputStream} to copy to the
+     *            parameter.
      * @throws SQLException
-     *             if a database error happens
+     *             if a database error happens.
      */
     public void setBinaryStream(int parameterIndex, InputStream theInputStream,
             int length) throws SQLException;
 
     /**
-     * Sets the value of a specified parameter to the given Blob object.
+     * Sets the value of a specified parameter to the given {@code Blob} object.
      * 
      * @param parameterIndex
      *            the parameter number index, where the first parameter has
-     *            index 1
+     *            index 1.
      * @param theBlob
-     *            a java.sql.Blob holding the data to update the parameter
+     *            the {@code java.sql.Blob} to which the parameter at {@code
+     *            parameterIndex} is set.
      * @throws SQLException
-     *             if a database error happens
+     *             if a database error happens.
+     * @see Blob
      */
     public void setBlob(int parameterIndex, Blob theBlob) throws SQLException;
 
     /**
-     * Sets the value of a specified parameter to a supplied boolean value.
+     * Sets the value of a specified parameter to a supplied {@code boolean}
+     * value.
      * 
      * @param parameterIndex
      *            the parameter number index, where the first parameter has
-     *            index 1
+     *            index 1.
      * @param theBoolean
-     *            the boolean value to update the parameter
+     *            the boolean value to which the parameter at {@code
+     *            parameterIndex} is set.
      * @throws SQLException
-     *             if a database error happens
+     *             if a database error happens.
      */
     public void setBoolean(int parameterIndex, boolean theBoolean)
             throws SQLException;
 
     /**
-     * Sets the value of a specified parameter to a supplied byte value.
+     * Sets the value of a specified parameter to a supplied {@code byte} value.
      * 
      * @param parameterIndex
      *            the parameter number index, where the first parameter has
-     *            index 1
+     *            index 1.
      * @param theByte
-     *            the byte value to update the parameter
+     *            the byte value to which the parameter at {@code
+     *            parameterIndex} is set.
      * @throws SQLException
-     *             if a database error happens
+     *             if a database error happens.
      */
     public void setByte(int parameterIndex, byte theByte) throws SQLException;
 
     /**
      * Sets the value of a specified parameter to a supplied array of bytes. The
-     * array is mapped to a VARBINARY or LONGVARBINARY in the database.
+     * array is mapped to a {@code VARBINARY} or {@code LONGVARBINARY} in the
+     * database.
      * 
      * @param parameterIndex
      *            the parameter number index, where the first parameter has
-     *            index 1
+     *            index 1.
      * @param theBytes
-     *            the array of bytes to update the parameter
+     *            the array of bytes to which the parameter at {@code
+     *            parameterIndex} is set.
      * @throws SQLException
-     *             if a database error happens
+     *             if a database error happens.
      */
     public void setBytes(int parameterIndex, byte[] theBytes)
             throws SQLException;
 
     /**
      * Sets the value of a specified parameter to the character content of a
-     * Reader object, with the specified length of character data.
-     * 
+     * {@code Reader} object, with the specified length of character data.
+     * <p>
+     * Data is read from the {@code
+     * Reader} until end-of-file is reached or the specified number of
+     * characters are copied.
+     *
      * @param parameterIndex
      *            the parameter number index, where the first parameter has
      *            index 1
      * @param reader
-     *            the java.io.Reader encompassing the character data
+     *            the {@code java.io.Reader} containing the character data.
      * @param length
-     *            the amount of characters to be read
+     *            the number of characters to be read.
      * @throws SQLException
-     *             if a database error happens
+     *             if a database error happens.
      */
     public void setCharacterStream(int parameterIndex, Reader reader, int length)
             throws SQLException;
 
     /**
-     * Sets the value of a specified parameter to the given Clob object.
+     * Sets the value of a specified parameter to the given {@code Clob} object.
      * 
      * @param parameterIndex
      *            the parameter number index, where the first parameter has
-     *            index 1
+     *            index 1.
      * @param theClob
-     *            a java.sql.Clob holding the data to update the parameter
+     *            a {@code java.sql.Clob} holding the data to which the
+     *            parameter at {@code parameterIndex} is set.
      * @throws SQLException
-     *             if a database error happens
+     *             if a database error happens.
      */
     public void setClob(int parameterIndex, Clob theClob) throws SQLException;
 
     /**
-     * Sets the value of a specified parameter to a supplied java.sql.Date
-     * value.
+     * Sets the value of a specified parameter to a supplied {@code
+     * java.sql.Date} value.
      * 
      * @param parameterIndex
      *            the parameter number index, where the first parameter has
-     *            index 1
+     *            index 1.
      * @param theDate
-     *            a java.sql.Date to update the parameter
+     *            a {@code java.sql.Date} to which the parameter at {@code
+     *            parameterIndex} is set.
      * @throws SQLException
-     *             if a database error happens
+     *             if a database error happens.
      */
     public void setDate(int parameterIndex, Date theDate) throws SQLException;
 
     /**
-     * Sets the value of a specified parameter to a supplied java.sql.Date
-     * value, using a supplied Calendar to map the Date. The Calendar allows the
-     * application to control the timezone used to compute the SQL DATE in the
-     * database - without the supplied Calendar, the driver uses the default
-     * timezone of the Java virtual machine.
+     * Sets the value of a specified parameter to a supplied {@code
+     * java.sql.Date} value, using a supplied {@code Calendar} to map the Date.
+     * The {@code Calendar} allows the application to control the timezone used
+     * to compute the SQL {@code DATE} in the database - without the supplied
+     * {@code Calendar}, the driver uses the default timezone of the Java
+     * virtual machine.
      * 
      * @param parameterIndex
      *            the parameter number index, where the first parameter has
-     *            index 1
+     *            index 1.
      * @param theDate
-     *            a java.sql.Date to update the parameter
+     *            a {@code java.sql.Date} to which the parameter at {@code
+     *            parameterIndex} is set.
      * @param cal
-     *            a Calendar to use to construct the SQL DATE value
+     *            a {@code Calendar} to use to construct the SQL {@code DATE}
+     *            value.
      * @throws SQLException
-     *             if a database error happens
+     *             if a database error happens.
+     * @see Date
+     * @see java.util.Calendar
      */
     public void setDate(int parameterIndex, Date theDate, Calendar cal)
             throws SQLException;
 
     /**
-     * Sets the value of a specified parameter to a supplied double value.
+     * Sets the value of a specified parameter to a supplied {@code double}
+     * value.
      * 
      * @param parameterIndex
      *            the parameter number index, where the first parameter has
-     *            index 1
+     *            index 1.
      * @param theDouble
-     *            the double value to update the parameter
+     *            the {@code double} value to which the parameter at {@code
+     *            parameterIndex} is set.
      * @throws SQLException
-     *             if a database error happens
+     *             if a database error happens.
      */
     public void setDouble(int parameterIndex, double theDouble)
             throws SQLException;
 
     /**
-     * Sets the value of a specified parameter to to a supplied float value.
+     * Sets the value of a specified parameter to to a supplied {@code float}
+     * value.
      * 
      * @param parameterIndex
      *            the parameter number index, where the first parameter has
-     *            index 1
+     *            index 1.
      * @param theFloat
-     *            the float value to update the parameter
+     *            the {@code float} value to update the parameter.
      * @throws SQLException
-     *             if a database error happens
+     *             if a database error happens.
      */
     public void setFloat(int parameterIndex, float theFloat)
             throws SQLException;
 
     /**
-     * Sets the value of a specified parameter to a supplied int value.
+     * Sets the value of a specified parameter to a supplied {@code int} value.
      * 
      * @param parameterIndex
      *            the parameter number index, where the first parameter has
-     *            index 1
+     *            index 1.
      * @param theInt
-     *            the int value to update the parameter
+     *            the {@code int} value to which the parameter at {@code
+     *            parameterIndex} is set.
      * @throws SQLException
-     *             if a database error happens
+     *             if a database error happens.
      */
     public void setInt(int parameterIndex, int theInt) throws SQLException;
 
     /**
-     * Sets the value of a specified parameter to a supplied long value.
+     * Sets the value of a specified parameter to a supplied {@code long} value.
      * 
      * @param parameterIndex
      *            the parameter number index, where the first parameter has
-     *            index 1
+     *            index 1.
      * @param theLong
-     *            the long value to update the parameter
+     *            the {@code long} value to which the parameter at {@code
+     *            parameterIndex} is set.
      * @throws SQLException
-     *             if a database error happens
+     *             if a database error happens.
      */
     public void setLong(int parameterIndex, long theLong) throws SQLException;
 
     /**
-     * Sets the value of a specified parameter to SQL NULL. Don't use this
-     * version of setNull for User Defined Types or for REF type parameters.
+     * Sets the value of a specified parameter to SQL {@code NULL}. Don't use
+     * this version of {@code setNull} for <i>User Defined Types</i> (UDT) or
+     * for REF type parameters.
      * 
      * @param parameterIndex
      *            the parameter number index, where the first parameter has
-     *            index 1
+     *            index 1.
      * @param sqlType
-     *            the SQL Type of the parameter, as defined in java.sql.Types
+     *            the SQL type of the parameter, as defined in {@code
+     *            java.sql.Types}.
      * @throws SQLException
-     *             if a database error happens
+     *             if a database error happens.
      */
     public void setNull(int parameterIndex, int sqlType) throws SQLException;
 
     /**
-     * Sets the value of a specified parameter to SQL NULL. This version of
-     * setNull should be used for User Defined Types (UDTs) and also REF types.
-     * UDTs can be STRUCT, DISTINCT, JAVA_OBJECT and named array types.
-     * <p>
-     * Applications must provide the SQL Type code and also a fully qualified
-     * SQL Type name when supplying a NULL UDT or REF. For a UDT, the type name
-     * is the type name of the parameter itself, but for a REF parameter the
-     * type name is the type name of the referenced type.
-     * 
+     * Sets the value of a specified parameter to SQL {@code NULL}. This version
+     * of {@code setNull} should be used for <i>User Defined Types</i> (UDTs)
+     * and also REF types. UDTs can be {@code STRUCT}, {@code DISTINCT}, {@code
+     * JAVA_OBJECT} and named array types.
+     * <p>
+     * Applications must provide the SQL type code and also a fully qualified
+     * SQL type name when supplying a {@code NULL} UDT or REF. For a UDT, the
+     * type name is the type name of the parameter itself, but for a REF
+     * parameter the type name is the type name of the referenced type.
+     *
      * @param paramIndex
      *            the parameter number index, where the first parameter has
-     *            index 1
+     *            index 1.
      * @param sqlType
-     *            the SQL Type of the parameter, as defined in java.sql.Types
+     *            the SQL type of the parameter, as defined in {@code
+     *            java.sql.Types}.
      * @param typeName
      *            the fully qualified name of a UDT or REF type - ignored if the
      *            parameter is not a UDT.
      * @throws SQLException
-     *             if a database error happens
+     *             if a database error happens.
+     * @see Types
      */
     public void setNull(int paramIndex, int sqlType, String typeName)
             throws SQLException;
@@ -415,143 +449,164 @@
      * <p>
      * There is a standard mapping from Java types to SQL types, defined in the
      * JDBC specification. The passed object is then transformed into the
-     * appropriate SQL type, and then transferred to the database. setObject can
-     * be used to pass abstract data types unique to the database, by using a
-     * JDBC driver specific Java type. If the object's class implements the
-     * interface SQLData, the JDBC driver calls <code>SQLData.writeSQL</code>
-     * to write it to the SQL data stream. If the object's class implements Ref,
-     * Blob, Clob, Struct, or Array, the driver passes it to the database as a
-     * value of the corresponding SQL type.
-     * 
+     * appropriate SQL type, and then transferred to the database. {@code
+     * setObject} can be used to pass abstract data types unique to the
+     * database, by using a JDBC driver specific Java type. If the object's
+     * class implements the interface {@code SQLData}, the JDBC driver calls
+     * {@code SQLData.writeSQL} to write it to the SQL data stream. If the
+     * object's class implements {@code Ref}, {@code Blob}, {@code Clob},
+     * {@code Struct}, or {@code Array}, the driver passes it to the database as
+     * a value of the corresponding SQL type.
+     *
      * @param parameterIndex
      *            the parameter number index, where the first parameter has
-     *            index 1
+     *            index 1.
      * @param theObject
-     *            the Object containing the value to update the parameter
+     *            the object containing the value to which the parameter at
+     *            {@code parameterIndex} is set.
      * @throws SQLException
-     *             if a database error happens
+     *             if a database error happens.
      */
     public void setObject(int parameterIndex, Object theObject)
             throws SQLException;
 
     /**
-     * Sets the value of a specified parameter.
+     * Sets the value of a specified parameter using a supplied object.
      * <p>
-     * The Object is converted to the target SQL type before it is added to the
-     * database. If the Object is an instance of SQLData then SQLData.writeSQL
-     * is called to write out its data.
-     * </p>
-     * 
+     * The object is converted to the given {@code targetSqlType} before it is
+     * sent to the database. If the object has a custom mapping (its class
+     * implements the interface {@code SQLData}), the JDBC driver will call the method
+     * {@code SQLData.writeSQL} to write it to the SQL data stream. If the
+     * object's class implements {@code Ref}, {@code Blob}, {@code Clob},
+     * {@code Struct}, or {@code Array}, the driver will pass it to the database
+     * in the form of the relevant SQL type.
+     *
      * @param parameterIndex
-     *            the parameter index, where the first parameter has index 1
+     *            the parameter index, where the first parameter has index 1.
      * @param theObject
-     *            the Object containing the value to update the parameter
+     *            the Object containing the value to which the parameter at
+     *            {@code parameterIndex} is set.
      * @param targetSqlType
-     *            the SQL Type to send to the database, as defined in
-     *            java.sql.Types
+     *            the SQL type to send to the database, as defined in {@code
+     *            java.sql.Types}.
      * @throws SQLException
-     *             if a database error happens
+     *             if a database error happens.
      */
     public void setObject(int parameterIndex, Object theObject,
             int targetSqlType) throws SQLException;
 
     /**
-     * Sets the value of a specified parameter.
+     * Sets the value of a specified parameter using a supplied object.
      * <p>
-     * The Object is converted to the target SQL type before it is added to the
-     * database. If the Object is an instance of SQLData then SQLData.writeSQL
-     * is called to write out its data.
-     * </p>
-     * 
+     * The object is converted to the given {@code targetSqlType} before it is
+     * sent to the database. If the object has a custom mapping (its class
+     * implements the interface {@code SQLData}), the JDBC driver will call the method
+     * {@code SQLData.writeSQL} to write it to the SQL data stream. If the
+     * object's class implements {@code Ref}, {@code Blob}, {@code Clob},
+     * {@code Struct}, or {@code Array}, the driver will pass it to the database
+     * in the form of the relevant SQL type.
+     *
      * @param parameterIndex
-     *            the parameter index, where the first parameter has index 1
+     *            the parameter index, where the first parameter has index 1.
      * @param theObject
-     *            the Object containing the value to update the parameter
+     *            the Object containing the value to which the parameter at
+     *            {@code parameterIndex} is set.
      * @param targetSqlType
-     *            the SQL Type to send to the database, as defined in
-     *            java.sql.Types
+     *            the SQL type to send to the database, as defined in {@code
+     *            java.sql.Types}.
      * @param scale
-     *            the number of decimal places if the types is
-     *            java.sql.Types.DECIMAL or java.sql.Types.NUMERIC
+     *            the number of digits after the decimal point - only applies to
+     *            the types {@code java.sql.Types.DECIMAL} and {@code
+     *            java.sql.Types.NUMERIC} - ignored for all other types.
      * @throws SQLException
-     *             if a database error happens
+     *             if a database error happens.
      */
     public void setObject(int parameterIndex, Object theObject,
             int targetSqlType, int scale) throws SQLException;
 
     /**
-     * Sets the value of a specified parameter to a supplied REF(<structured-type>)
-     * value. This is stored as an SQL REF.
+     * Sets the value of a specified parameter to a supplied {@code
+     * REF(<structured-type>)} value. This is stored as an SQL {@code REF}.
      * 
      * @param parameterIndex
      *            the parameter number index, where the first parameter has
-     *            index 1
+     *            index 1.
      * @param theRef
-     *            a java.sql.Ref value to update the parameter
+     *            a {@code java.sql.Ref} value to which the parameter at {@code
+     *            parameterIndex} is set.
      * @throws SQLException
-     *             if a database error happens
+     *             if a database error happens.
+     * @see Ref
      */
     public void setRef(int parameterIndex, Ref theRef) throws SQLException;
 
     /**
-     * Sets the value of a specified parameter to a supplied short value.
+     * Sets the value of a specified parameter to a supplied {@code short}
+     * value.
      * 
      * @param parameterIndex
      *            the parameter number index, where the first parameter has
-     *            index 1
+     *            index 1.
      * @param theShort
-     *            a short value to update the parameter
+     *            a {@code short} value to which the parameter at {@code
+     *            parameterIndex} is set.
      * @throws SQLException
-     *             if a database error happens
+     *             if a database error happens.
      */
     public void setShort(int parameterIndex, short theShort)
             throws SQLException;
 
     /**
-     * Sets the value of a specified parameter to a supplied String.
+     * Sets the value of a specified parameter to a supplied string.
      * 
      * @param parameterIndex
      *            the parameter number index, where the first parameter has
-     *            index 1
+     *            index 1.
      * @param theString
-     *            a String value to update the parameter
+     *            the value to which the parameter at {@code parameterIndex} is
+     *            set.
      * @throws SQLException
-     *             if a database error happens
+     *             if a database error happens.
      */
     public void setString(int parameterIndex, String theString)
             throws SQLException;
 
     /**
-     * Sets the value of a specified parameter to a supplied java.sql.Time
-     * value.
+     * Sets the value of a specified parameter to a supplied {@code
+     * java.sql.Time} value.
      * 
      * @param parameterIndex
      *            the parameter number index, where the first parameter has
-     *            index 1
+     *            index 1.
      * @param theTime
-     *            a java.sql.Time value to update the parameter
+     *            a {@code java.sql.Time} value to which the parameter at
+     *            {@code parameterIndex} is set.
      * @throws SQLException
-     *             if a database error happens
+     *             if a database error happens.
      */
     public void setTime(int parameterIndex, Time theTime) throws SQLException;
 
     /**
-     * Sets the value of a specified parameter to a supplied java.sql.Time
-     * value, using a supplied Calendar.
+     * Sets the value of a specified parameter to a supplied {@code
+     * java.sql.Time} value, using a supplied {@code Calendar}.
      * <p>
-     * The driver uses the supplied Calendar to create the SQL TIME value, which
-     * allows it to use a custom timezone - otherwise the driver uses the
-     * default timezone of the Java virtual machine.
-     * 
+     * The driver uses the supplied {@code Calendar} to create the SQL {@code
+     * TIME} value, which allows it to use a custom timezone - otherwise the
+     * driver uses the default timezone of the Java virtual machine.
+     *
      * @param parameterIndex
-     *            the parameter number index, where the first parameter has
-     *            index 1
+     *            the parameter number index, where the first parameter has 
+     *            index 1.
      * @param theTime
-     *            a java.sql.Time value to update the parameter
+     *            a {@code java.sql.Time} value to which the parameter at
+     *            {@code parameterIndex} is set.
      * @param cal
-     *            a Calendar to use to construct the SQL TIME value
+     *            a {@code Calendar} to use to construct the SQL {@code TIME}
+     *            value.
      * @throws SQLException
-     *             if a database error happens
+     *             if a database error happens.
+     * @see Time
+     * @see java.util.Calendar
      */
     public void setTime(int parameterIndex, Time theTime, Calendar cal)
             throws SQLException;
@@ -562,65 +617,74 @@
      * 
      * @param parameterIndex
      *            the parameter number index, where the first parameter has
-     *            index 1
+     *            index 1.
      * @param theTimestamp
-     *            the java.sql.Timestamp value to update the parameter
+     *            the java.sql.Timestamp value to which the parameter at {@code
+     *            parameterIndex} is set.
      * @throws SQLException
-     *             if a database error happens
+     *             if a database error happens.
      */
     public void setTimestamp(int parameterIndex, Timestamp theTimestamp)
             throws SQLException;
 
     /**
-     * Sets the value of a specified parameter to a supplied java.sql.Timestamp
-     * value, using the supplied Calendar.
+     * Sets the value of a specified parameter to a supplied {@code
+     * java.sql.Timestamp} value, using the supplied {@code Calendar}.
      * <p>
-     * The driver uses the supplied Calendar to create the SQL TIMESTAMP value,
-     * which allows it to use a custom timezone - otherwise the driver uses the
-     * default timezone of the Java virtual machine.
-     * 
+     * The driver uses the supplied {@code Calendar} to create the SQL {@code
+     * TIMESTAMP} value, which allows it to use a custom timezone - otherwise
+     * the driver uses the default timezone of the Java virtual machine.
+     *
      * @param parameterIndex
      *            the parameter number index, where the first parameter has
-     *            index 1
+     *            index 1.
      * @param theTimestamp
-     *            the java.sql.Timestamp value to update the parameter
+     *            the {@code java.sql.Timestamp} value to which the parameter at
+     *            {@code parameterIndex} is set.
      * @param cal
-     *            a Calendar to use to construct the SQL TIMESTAMP value
+     *            a {@code Calendar} to use to construct the SQL {@code
+     *            TIMESTAMP} value
      * @throws SQLException
-     *             if a database error happens
+     *             if a database error happens.
+     * @see Timestamp
+     * @see java.util.Calendar
      */
     public void setTimestamp(int parameterIndex, Timestamp theTimestamp,
             Calendar cal) throws SQLException;
 
     /**
-     * @deprecated Sets the value of a specified parameter to the characters
-     *             from a supplied InputStream, with a specified number of
-     *             bytes.
+     * Sets the value of a specified parameter to the characters from a supplied
+     * {@code InputStream}, with a specified number of bytes.
+     * 
+     * @deprecated Use {@link #setCharacterStream(int, Reader, int)}
      * @param parameterIndex
      *            the parameter number index, where the first parameter has
-     *            index 1
+     *            index 1.
      * @param theInputStream
-     *            the InputStream with the character data to update the
-     *            parameter
+     *            the {@code InputStream} with the character data to which the
+     *            parameter at {@code parameterIndex} is set.
      * @param length
-     *            the number of bytes to read from the InputStream
+     *            the number of bytes to read from the {@code InputStream}.
      * @throws SQLException
-     *             if a database error happens
+     *             if a database error happens.
      */
     @Deprecated
     public void setUnicodeStream(int parameterIndex,
             InputStream theInputStream, int length) throws SQLException;
 
     /**
-     * Sets the value of a specified parameter to a supplied java.net.URL.
+     * Sets the value of a specified parameter to a supplied {@code
+     * java.net.URL}.
      * 
      * @param parameterIndex
      *            the parameter number index, where the first parameter has
-     *            index 1
+     *            index 1.
      * @param theURL
-     *            the URL to update the parameter
+     *            the {@code URL} to which the parameter at {@code
+     *            parameterIndex} is set.
      * @throws SQLException
-     *             if a database error happens
+     *             if a database error happens.
+     * @see URL
      */
     public void setURL(int parameterIndex, URL theURL) throws SQLException;
 }

Modified: harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/Ref.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/Ref.java?rev=770130&r1=770129&r2=770130&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/Ref.java (original)
+++ harmony/enhanced/classlib/trunk/modules/sql/src/main/java/java/sql/Ref.java Thu Apr 30 09:45:40 2009
@@ -20,35 +20,38 @@
 import java.util.Map;
 
 /**
- * A manifestation of the SQL REF type - a reference to an SQL type contained in
- * the database.
+ * This interface represents an SQL Ref - a data object containing a cursor
+ * or pointer to a result table.
  * <p>
- * The SQL REF's are held in a table along with SQL structured types. Every REF
- * has an individual identifier for each single instance. The SQL REF is used
- * instead of the structured type it references.
+ * The data structure identified by an instance of Ref is held in the 
+ * database, so the data is not necessarily read and converted
+ * into a Java object until {@code getObject} is called. However, if 
+ * the database supports the {@code Ref} type, it is not typically 
+ * necessary to get the underlying object before using it in a method call -
+ * the {@code Ref} object can be used in place of the data structure.
  * <p>
- * A Ref object is stored into the database using the PreparedStatement.setRef
- * method.
+ * A {@code Ref} object is stored into the database using the
+ * {@link PreparedStatement#setRef(int, Ref)} method.
  */
 public interface Ref {
 
     /**
      * Gets the fully-qualified SQL name of the SQL structured type that this
-     * Ref references.
+     * {@code Ref} references.
      * 
-     * @return the fully qualified name of the SQL structured type
+     * @return the fully qualified name of the SQL structured type.
      * @throws SQLException
-     *             if there is a database error
+     *             if there is a database error.
      */
     public String getBaseTypeName() throws SQLException;
 
     /**
-     * Gets the SQL structured type instance referenced by this Ref.
+     * Gets the SQL structured type instance referenced by this {@code Ref}.
      * 
      * @return a Java object whose type is defined by the mapping for the SQL
      *         structured type.
      * @throws SQLException
-     *             if there is a database error
+     *             if there is a database error.
      */
     public Object getObject() throws SQLException;
 
@@ -57,23 +60,23 @@
      * to a Java type.
      * 
      * @param map
-     *            a java.util.Map which contains the mapping to use
+     *            the mapping for type conversion.
      * @return a Java object whose type is defined by the mapping for the SQL
      *         structured type.
      * @throws SQLException
-     *             if there is a database error
+     *             if there is a database error.
      */
     public Object getObject(Map<String, Class<?>> map) throws SQLException;
 
     /**
-     * Sets the value of the structured typethat this Ref references to a
-     * supplied Object.
+     * Sets the value of the structured type that this {@code Ref} references to
+     * a supplied object.
      * 
      * @param value
-     *            the Object representing the new SQL structured type that this
-     *            Ref will reference.
+     *            the {@code Object} representing the new SQL structured type
+     *            that this {@code Ref} references.
      * @throws SQLException
-     *             if there is a database error
+     *             if there is a database error.
      */
     public void setObject(Object value) throws SQLException;
 }



Mime
View raw message