svn commit: r397650 - in /db/derby/code/trunk/java/client/org/apache/derby/jdbc: ClientConnectionPoolDataSource.java ClientConnectionPoolDataSource40.java ClientDataSource.java ClientDataSource40.java ClientXADataSource.java ClientXADataSource40.java

[rh...@apache.org]

Author: rhillegas
Date: Thu Apr 27 14:48:59 2006
New Revision: 397650

URL: http://svn.apache.org/viewcvs?rev=397650&view=rev
Log:
DERBY-1079: Commit bug1079_clientPublicAPI, adding javadoc for client classes in our public api.

Modified:
    db/derby/code/trunk/java/client/org/apache/derby/jdbc/ClientConnectionPoolDataSource.java
    db/derby/code/trunk/java/client/org/apache/derby/jdbc/ClientConnectionPoolDataSource40.java
    db/derby/code/trunk/java/client/org/apache/derby/jdbc/ClientDataSource.java
    db/derby/code/trunk/java/client/org/apache/derby/jdbc/ClientDataSource40.java
    db/derby/code/trunk/java/client/org/apache/derby/jdbc/ClientXADataSource.java
    db/derby/code/trunk/java/client/org/apache/derby/jdbc/ClientXADataSource40.java

Modified: db/derby/code/trunk/java/client/org/apache/derby/jdbc/ClientConnectionPoolDataSource.java
URL: http://svn.apache.org/viewcvs/db/derby/code/trunk/java/client/org/apache/derby/jdbc/ClientConnectionPoolDataSource.java?rev=397650&r1=397649&r2=397650&view=diff
==============================================================================
--- db/derby/code/trunk/java/client/org/apache/derby/jdbc/ClientConnectionPoolDataSource.java (original)
+++ db/derby/code/trunk/java/client/org/apache/derby/jdbc/ClientConnectionPoolDataSource.java Thu Apr 27 14:48:59 2006
@@ -28,8 +28,17 @@
 import org.apache.derby.client.am.SqlException;
 
 /**
- * ClientConnectionPoolDataSource is a factory for PooledConnection objects. An object that implements this interface
- * will typically be registered with a naming service that is based on the Java Naming and Directory Interface (JNDI).
+ * ClientConnectionPoolDataSource is a factory for PooledConnection objects.
+ * An object that implements this interface
+ * will typically be registered with a naming service that is based on the
+ * Java Naming and Directory Interface (JNDI). Use
+ * ClientConnectionPoolDataSource if your application runs under
+ * JDBC3.0 or JDBC2.0, that is, on the following Java Virtual Machines:
+ * <p/>
+ * <UL>
+ * <LI> JDBC 3.0 - Java 2 - JDK 1.4, J2SE 5.0
+ * <LI> JDBC 2.0 - Java 2 - JDK 1.2,1.3
+ * </UL>
  */
 public class ClientConnectionPoolDataSource extends ClientBaseDataSource 
                                            implements ConnectionPoolDataSource {

Modified: db/derby/code/trunk/java/client/org/apache/derby/jdbc/ClientConnectionPoolDataSource40.java
URL: http://svn.apache.org/viewcvs/db/derby/code/trunk/java/client/org/apache/derby/jdbc/ClientConnectionPoolDataSource40.java?rev=397650&r1=397649&r2=397650&view=diff
==============================================================================
--- db/derby/code/trunk/java/client/org/apache/derby/jdbc/ClientConnectionPoolDataSource40.java (original)
+++ db/derby/code/trunk/java/client/org/apache/derby/jdbc/ClientConnectionPoolDataSource40.java Thu Apr 27 14:48:59 2006
@@ -27,7 +27,19 @@
 import org.apache.derby.client.am.SQLExceptionFactory;
 
 /**
- * ConnectionPoolDataSource for jdbc4.0
+ * ClientConnectionPoolDataSource40 is a factory for PooledConnection objects.
+ * An object that implements this interface
+ * will typically be registered with a naming service that is based on the
+ * Java Naming and Directory Interface (JNDI). Use this factory
+ * if your application runs under JDBC4.0.
+ * Use
+ * ClientConnectionPoolDataSource, instead, if your application runs under
+ * JDBC3.0 or JDBC2.0, that is, on the following Java Virtual Machines:
+ * <p/>
+ * <UL>
+ * <LI> JDBC 3.0 - Java 2 - JDK 1.4, J2SE 5.0
+ * <LI> JDBC 2.0 - Java 2 - JDK 1.2,1.3
+ * </UL>
  */
 public class ClientConnectionPoolDataSource40
         extends ClientConnectionPoolDataSource {

Modified: db/derby/code/trunk/java/client/org/apache/derby/jdbc/ClientDataSource.java
URL: http://svn.apache.org/viewcvs/db/derby/code/trunk/java/client/org/apache/derby/jdbc/ClientDataSource.java?rev=397650&r1=397649&r2=397650&view=diff
==============================================================================
--- db/derby/code/trunk/java/client/org/apache/derby/jdbc/ClientDataSource.java (original)
+++ db/derby/code/trunk/java/client/org/apache/derby/jdbc/ClientDataSource.java Thu Apr 27 14:48:59 2006
@@ -30,11 +30,20 @@
 import org.apache.derby.client.net.NetLogWriter;
 
 /**
- * ClientDataSource is a simple data source implementation that can be used for establishing connections in a
- * non-pooling, non-distributed environment. The class ClientConnectionPoolDataSource can be used in a connection pooling environment,
- * and the class ClientXADataSource can be used in a distributed, and pooling environment.
+ * ClientDataSource is a simple data source implementation
+ * that can be used for establishing connections in a
+ * non-pooling, non-distributed environment.
+ * The class ClientConnectionPoolDataSource can be used in a connection pooling environment,
+ * and the class ClientXADataSource can be used in a distributed, and pooling
+ * environment. Use these DataSources if your application runs under
+ * JDBC3.0 or JDBC2.0, that is, on the following Java Virtual Machines:
  * <p/>
- * The example below registers a DNC data source object with a JNDI naming service.
+ * <UL>
+ * <LI> JDBC 3.0 - Java 2 - JDK 1.4, J2SE 5.0
+ * <LI> JDBC 2.0 - Java 2 - JDK 1.2,1.3
+ * </UL>
+ *
+ * <p>The example below registers a DNC data source object with a JNDI naming service.
  * <pre>
  * org.apache.derby.client.ClientDataSource dataSource = new org.apache.derby.client.ClientDataSource ();
  * dataSource.setServerName ("my_derby_database_server");
@@ -42,35 +51,52 @@
  * javax.naming.Context context = new javax.naming.InitialContext();
  * context.bind ("jdbc/my_datasource_name", dataSource);
  * </pre>
- * The first line of code in the example creates a data source object. The next two lines initialize the data source's
- * properties. Then a Java object that references the initial JNDI naming context is created by calling the
- * InitialContext() constructor, which is provided by JNDI. System properties (not shown) are used to tell JNDI the
- * service provider to use. The JNDI name space is hierarchical, similar to the directory structure of many file
- * systems. The data source object is bound to a logical JNDI name by calling Context.bind(). In this case the JNDI name
- * identifies a subcontext, "jdbc", of the root naming context and a logical name, "my_datasource_name", within the jdbc
- * subcontext. This is all of the code required to deploy a data source object within JNDI. This example is provided
- * mainly for illustrative purposes. We expect that developers or system administrators will normally use a GUI tool to
+ * The first line of code in the example creates a data source object.
+ * The next two lines initialize the data source's
+ * properties. Then a Java object that references the initial JNDI naming
+ * context is created by calling the
+ * InitialContext() constructor, which is provided by JNDI.
+ * System properties (not shown) are used to tell JNDI the
+ * service provider to use. The JNDI name space is hierarchical,
+ * similar to the directory structure of many file
+ * systems. The data source object is bound to a logical JNDI name
+ * by calling Context.bind(). In this case the JNDI name
+ * identifies a subcontext, "jdbc", of the root naming context
+ * and a logical name, "my_datasource_name", within the jdbc
+ * subcontext. This is all of the code required to deploy
+ * a data source object within JNDI. This example is provided
+ * mainly for illustrative purposes. We expect that developers
+ * or system administrators will normally use a GUI tool to
  * deploy a data source object.
  * <p/>
- * Once a data source has been registered with JNDI, it can then be used by a JDBC application, as is shown in the
+ * Once a data source has been registered with JNDI,
+ * it can then be used by a JDBC application, as is shown in the
  * following example.
  * <pre>
  * javax.naming.Context context = new javax.naming.InitialContext ();
  * javax.sql.DataSource dataSource = (javax.sql.DataSource) context.lookup ("jdbc/my_datasource_name");
  * java.sql.Connection connection = dataSource.getConnection ("user", "password");
  * </pre>
- * The first line in the example creates a Java object that references the initial JNDI naming context. Next, the
- * initial naming context is used to do a lookup operation using the logical name of the data source. The
- * Context.lookup() method returns a reference to a Java Object, which is narrowed to a javax.sql.DataSource object. In
- * the last line, the DataSource.getConnection() method is called to produce a database connection.
+ * The first line in the example creates a Java object
+ * that references the initial JNDI naming context. Next, the
+ * initial naming context is used to do a lookup operation
+ * using the logical name of the data source. The
+ * Context.lookup() method returns a reference to a Java Object,
+ * which is narrowed to a javax.sql.DataSource object. In
+ * the last line, the DataSource.getConnection() method
+ * is called to produce a database connection.
  * <p/>
- * This simple data source subclass of ClientBaseDataSource maintains it's own private <code>password</code> property.
+ * This simple data source subclass of ClientBaseDataSource maintains
+ * it's own private <code>password</code> property.
  * <p/>
- * The specified password, along with the user, is validated by DERBY.  This property can be overwritten by specifing
+ * The specified password, along with the user, is validated by DERBY.
+ * This property can be overwritten by specifing
  * the password parameter on the DataSource.getConnection() method call.
  * <p/>
- * This password property is not declared transient, and therefore may be serialized to a file in clear-text, or stored
- * to a JNDI server in clear-text when the data source is saved. Care must taken by the user to prevent security
+ * This password property is not declared transient, and therefore
+ * may be serialized to a file in clear-text, or stored
+ * to a JNDI server in clear-text when the data source is saved.
+ * Care must taken by the user to prevent security
  * breaches.
  * <p/>
  */

Modified: db/derby/code/trunk/java/client/org/apache/derby/jdbc/ClientDataSource40.java
URL: http://svn.apache.org/viewcvs/db/derby/code/trunk/java/client/org/apache/derby/jdbc/ClientDataSource40.java?rev=397650&r1=397649&r2=397650&view=diff
==============================================================================
--- db/derby/code/trunk/java/client/org/apache/derby/jdbc/ClientDataSource40.java (original)
+++ db/derby/code/trunk/java/client/org/apache/derby/jdbc/ClientDataSource40.java Thu Apr 27 14:48:59 2006
@@ -28,6 +28,79 @@
 import org.apache.derby.client.am.SqlException;
 import org.apache.derby.shared.common.reference.SQLState;
 
+/**
+ * ClientDataSource40 is a simple data source implementation
+ * that can be used for establishing connections in a
+ * non-pooling, non-distributed environment.
+ * The class ClientConnectionPoolDataSource40 can be used in a connection pooling environment,
+ * and the class ClientXADataSource40 can be used in a distributed, and pooling
+ * environment. Use these DataSources if your application runs under
+ * JDBC4.0. Use the corresponding ClientDataSource, ClientConnectionPoolDataSource, and
+ * ClientXADataSource classes if 
+ * your application runs in the following environments:
+ * <p/>
+ *	<UL>
+ *	<LI> JDBC 3.0 - Java 2 - JDK 1.4, J2SE 5.0
+ *	<LI> JDBC 2.0 - Java 2 - JDK 1.2,1.3
+ * </UL>
+ *
+ * <p>The example below registers a DNC data source object with a JNDI naming service.
+ * <pre>
+ * org.apache.derby.client.ClientDataSource40 dataSource = new org.apache.derby.client.ClientDataSource40 ();
+ * dataSource.setServerName ("my_derby_database_server");
+ * dataSource.setDatabaseName ("my_derby_database_name");
+ * javax.naming.Context context = new javax.naming.InitialContext();
+ * context.bind ("jdbc/my_datasource_name", dataSource);
+ * </pre>
+ * The first line of code in the example creates a data source object.
+ * The next two lines initialize the data source's
+ * properties. Then a Java object that references the initial JNDI naming
+ * context is created by calling the
+ * InitialContext() constructor, which is provided by JNDI.
+ * System properties (not shown) are used to tell JNDI the
+ * service provider to use. The JNDI name space is hierarchical,
+ * similar to the directory structure of many file
+ * systems. The data source object is bound to a logical JNDI name
+ * by calling Context.bind(). In this case the JNDI name
+ * identifies a subcontext, "jdbc", of the root naming context
+ * and a logical name, "my_datasource_name", within the jdbc
+ * subcontext. This is all of the code required to deploy
+ * a data source object within JNDI. This example is provided
+ * mainly for illustrative purposes. We expect that developers
+ * or system administrators will normally use a GUI tool to
+ * deploy a data source object.
+ * <p/>
+ * Once a data source has been registered with JNDI,
+ * it can then be used by a JDBC application, as is shown in the
+ * following example.
+ * <pre>
+ * javax.naming.Context context = new javax.naming.InitialContext ();
+ * javax.sql.DataSource dataSource = (javax.sql.DataSource) context.lookup ("jdbc/my_datasource_name");
+ * java.sql.Connection connection = dataSource.getConnection ("user", "password");
+ * </pre>
+ * The first line in the example creates a Java object
+ * that references the initial JNDI naming context. Next, the
+ * initial naming context is used to do a lookup operation
+ * using the logical name of the data source. The
+ * Context.lookup() method returns a reference to a Java Object,
+ * which is narrowed to a javax.sql.DataSource object. In
+ * the last line, the DataSource.getConnection() method
+ * is called to produce a database connection.
+ * <p/>
+ * This simple data source subclass of ClientBaseDataSource maintains
+ * it's own private <code>password</code> property.
+ * <p/>
+ * The specified password, along with the user, is validated by DERBY.
+ * This property can be overwritten by specifing
+ * the password parameter on the DataSource.getConnection() method call.
+ * <p/>
+ * This password property is not declared transient, and therefore
+ * may be serialized to a file in clear-text, or stored
+ * to a JNDI server in clear-text when the data source is saved.
+ * Care must taken by the user to prevent security
+ * breaches.
+ * <p/>
+ */
 public class ClientDataSource40 extends ClientDataSource {
     
     public ClientDataSource40() {

Modified: db/derby/code/trunk/java/client/org/apache/derby/jdbc/ClientXADataSource.java
URL: http://svn.apache.org/viewcvs/db/derby/code/trunk/java/client/org/apache/derby/jdbc/ClientXADataSource.java?rev=397650&r1=397649&r2=397650&view=diff
==============================================================================
--- db/derby/code/trunk/java/client/org/apache/derby/jdbc/ClientXADataSource.java (original)
+++ db/derby/code/trunk/java/client/org/apache/derby/jdbc/ClientXADataSource.java Thu Apr 27 14:48:59 2006
@@ -30,6 +30,25 @@
 import org.apache.derby.client.am.SqlException;
 
 
+/**
+ * <p>
+ * This is Derby's network XADataSource for use with JDBC3.0 and JDBC2.0.
+ * </p>
+ * An XADataSource is a factory for XAConnection objects.  It represents a
+ * RM in a DTP environment.  An object that implements the XADataSource
+ * interface is typically registered with a JNDI service provider.   	
+ * <P>
+ * ClientXADataSource automatically supports the correct JDBC specification version
+ * for the Java Virtual Machine's environment.
+ * <UL>
+ * <LI> JDBC 3.0 - Java 2 - JDK 1.4, J2SE 5.0
+ * <LI> JDBC 2.0 - Java 2 - JDK 1.2,1.3
+ * </UL>
+ *
+ * <P>ClientXADataSource is serializable and referenceable.</p>
+ *
+ * <P>See ClientDataSource for DataSource properties.</p>
+ */
 public class ClientXADataSource extends ClientBaseDataSource implements XADataSource {
     public static final String className__ = "org.apache.derby.jdbc.ClientXADataSource";
 

Modified: db/derby/code/trunk/java/client/org/apache/derby/jdbc/ClientXADataSource40.java
URL: http://svn.apache.org/viewcvs/db/derby/code/trunk/java/client/org/apache/derby/jdbc/ClientXADataSource40.java?rev=397650&r1=397649&r2=397650&view=diff
==============================================================================
--- db/derby/code/trunk/java/client/org/apache/derby/jdbc/ClientXADataSource40.java (original)
+++ db/derby/code/trunk/java/client/org/apache/derby/jdbc/ClientXADataSource40.java Thu Apr 27 14:48:59 2006
@@ -31,7 +31,24 @@
 import org.apache.derby.client.net.NetLogWriter;
 
 /**
- * XADataSource for jdbc4.0
+ * <p>
+ * This is Derby's network XADataSource for use with JDBC4.0.
+ * </p>
+ * An XADataSource is a factory for XAConnection objects.  It represents a
+ * RM in a DTP environment.  An object that implements the XADataSource
+ * interface is typically registered with a JNDI service provider.   	
+ * <P>
+ * ClientXADataSource40 supports the JDBC 4.0 specification
+ * for the J2SE 6.0 Java Virtual Machine environment. Use ClientXADataSource
+ * if your application runs in the following environments:
+ * <UL>
+ * <LI> JDBC 3.0 - Java 2 - JDK 1.4, J2SE 5.0
+ * <LI> JDBC 2.0 - Java 2 - JDK 1.2,1.3
+ * </UL>
+ *
+ * <P>ClientXADataSource40 is serializable and referenceable.</p>
+ *
+ * <P>See ClientDataSource40 for DataSource properties.</p>
  */
 public class ClientXADataSource40 extends ClientXADataSource {
     /**