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