You are viewing a plain text version of this content. The canonical link for it is here.
Posted to derby-commits@db.apache.org by rh...@apache.org on 2006/04/17 23:28:26 UTC
svn commit: r394780 - /db/derby/code/trunk/java/engine/org/apache/derby/jdbc/
Author: rhillegas
Date: Mon Apr 17 14:28:23 2006
New Revision: 394780
URL: http://svn.apache.org/viewcvs?rev=394780&view=rev
Log:
DERBY-1079: Expand public API javadoc for visible JDBC4 classes in the embedded client.
Modified:
db/derby/code/trunk/java/engine/org/apache/derby/jdbc/EmbedPooledConnection.java
db/derby/code/trunk/java/engine/org/apache/derby/jdbc/EmbedPooledConnection40.java
db/derby/code/trunk/java/engine/org/apache/derby/jdbc/EmbeddedConnectionPoolDataSource.java
db/derby/code/trunk/java/engine/org/apache/derby/jdbc/EmbeddedConnectionPoolDataSource40.java
db/derby/code/trunk/java/engine/org/apache/derby/jdbc/EmbeddedDataSource.java
db/derby/code/trunk/java/engine/org/apache/derby/jdbc/EmbeddedDataSource40.java
db/derby/code/trunk/java/engine/org/apache/derby/jdbc/EmbeddedXADataSource.java
db/derby/code/trunk/java/engine/org/apache/derby/jdbc/EmbeddedXADataSource40.java
Modified: db/derby/code/trunk/java/engine/org/apache/derby/jdbc/EmbedPooledConnection.java
URL: http://svn.apache.org/viewcvs/db/derby/code/trunk/java/engine/org/apache/derby/jdbc/EmbedPooledConnection.java?rev=394780&r1=394779&r2=394780&view=diff
==============================================================================
--- db/derby/code/trunk/java/engine/org/apache/derby/jdbc/EmbedPooledConnection.java (original)
+++ db/derby/code/trunk/java/engine/org/apache/derby/jdbc/EmbedPooledConnection.java Mon Apr 17 14:28:23 2006
@@ -52,7 +52,12 @@
A PooledConnection object is a connection object that provides hooks for
connection pool management.
- <P>This is Cloudscape's implementation of a PooledConnection.
+ <P>This is Derby's implementation of a PooledConnection for use 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>
*/
class EmbedPooledConnection implements javax.sql.PooledConnection, BrokeredConnectionControl
Modified: db/derby/code/trunk/java/engine/org/apache/derby/jdbc/EmbedPooledConnection40.java
URL: http://svn.apache.org/viewcvs/db/derby/code/trunk/java/engine/org/apache/derby/jdbc/EmbedPooledConnection40.java?rev=394780&r1=394779&r2=394780&view=diff
==============================================================================
--- db/derby/code/trunk/java/engine/org/apache/derby/jdbc/EmbedPooledConnection40.java (original)
+++ db/derby/code/trunk/java/engine/org/apache/derby/jdbc/EmbedPooledConnection40.java Mon Apr 17 14:28:23 2006
@@ -25,9 +25,16 @@
import java.sql.SQLException;
import javax.sql.StatementEventListener;
-/**
- * This class supports jdbc4.0 javax.sql.PooledConnection
- * older methods are inherited from EmbedPooledConnection
+/**
+ A PooledConnection object is a connection object that provides hooks for
+ connection pool management.
+
+ <P>This is Derby's implementation of a PooledConnection for use in
+ the following environments:
+ <UL>
+ <LI> JDBC 4.0 - J2SE 6.0
+ </UL>
+
*/
class EmbedPooledConnection40 extends EmbedPooledConnection {
Modified: db/derby/code/trunk/java/engine/org/apache/derby/jdbc/EmbeddedConnectionPoolDataSource.java
URL: http://svn.apache.org/viewcvs/db/derby/code/trunk/java/engine/org/apache/derby/jdbc/EmbeddedConnectionPoolDataSource.java?rev=394780&r1=394779&r2=394780&view=diff
==============================================================================
--- db/derby/code/trunk/java/engine/org/apache/derby/jdbc/EmbeddedConnectionPoolDataSource.java (original)
+++ db/derby/code/trunk/java/engine/org/apache/derby/jdbc/EmbeddedConnectionPoolDataSource.java Mon Apr 17 14:28:23 2006
@@ -27,7 +27,8 @@
import javax.sql.PooledConnection;
/**
- EmbeddedConnectionPoolDataSource is Derby's ConnectionPoolDataSource implementation.
+ EmbeddedConnectionPoolDataSource is Derby's ConnectionPoolDataSource
+ implementation for the JDBC3.0 and JDBC2.0 environments.
<P>A ConnectionPoolDataSource is a factory for PooledConnection
Modified: db/derby/code/trunk/java/engine/org/apache/derby/jdbc/EmbeddedConnectionPoolDataSource40.java
URL: http://svn.apache.org/viewcvs/db/derby/code/trunk/java/engine/org/apache/derby/jdbc/EmbeddedConnectionPoolDataSource40.java?rev=394780&r1=394779&r2=394780&view=diff
==============================================================================
--- db/derby/code/trunk/java/engine/org/apache/derby/jdbc/EmbeddedConnectionPoolDataSource40.java (original)
+++ db/derby/code/trunk/java/engine/org/apache/derby/jdbc/EmbeddedConnectionPoolDataSource40.java Mon Apr 17 14:28:23 2006
@@ -26,12 +26,29 @@
import javax.sql.ConnectionPoolDataSource;
import javax.sql.PooledConnection;
-/**
- * This class is meant to be used while running the applications with jdbc4.0
- * support. It extends EmbeddedDataSource40 which implements jdbc 4.0
- * specific methods.
- */
+/**
+ EmbeddedConnectionPoolDataSource40 is Derby's ConnectionPoolDataSource
+ implementation for the JDBC4.0 environment.
+
+
+ <P>A ConnectionPoolDataSource is a factory for PooledConnection
+ objects. An object that implements this interface will typically be
+ registered with a JNDI service.
+ <P>
+ EmbeddedConnectionPoolDataSource40 supports the JDBC 4.0 specification
+ for the J2SE 6.0 Java Virtual Machine environment. Use
+ EmbeddedConnectionPoolDataSource 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>EmbeddedConnectionPoolDataSource40 is serializable and referenceable.
+ <P>See EmbeddedDataSource40 for DataSource properties.
+
+ */
public class EmbeddedConnectionPoolDataSource40
extends EmbeddedConnectionPoolDataSource
implements ConnectionPoolDataSource {
Modified: db/derby/code/trunk/java/engine/org/apache/derby/jdbc/EmbeddedDataSource.java
URL: http://svn.apache.org/viewcvs/db/derby/code/trunk/java/engine/org/apache/derby/jdbc/EmbeddedDataSource.java?rev=394780&r1=394779&r2=394780&view=diff
==============================================================================
--- db/derby/code/trunk/java/engine/org/apache/derby/jdbc/EmbeddedDataSource.java (original)
+++ db/derby/code/trunk/java/engine/org/apache/derby/jdbc/EmbeddedDataSource.java Mon Apr 17 14:28:23 2006
@@ -43,7 +43,7 @@
/**
- EmbeddedDataSource is Derby's DataSource implementation.
+ EmbeddedDataSource is Derby's DataSource implementation for JDBC3.0 and JDBC2.0.
<P>A DataSource is a factory for Connection objects. An object that
Modified: db/derby/code/trunk/java/engine/org/apache/derby/jdbc/EmbeddedDataSource40.java
URL: http://svn.apache.org/viewcvs/db/derby/code/trunk/java/engine/org/apache/derby/jdbc/EmbeddedDataSource40.java?rev=394780&r1=394779&r2=394780&view=diff
==============================================================================
--- db/derby/code/trunk/java/engine/org/apache/derby/jdbc/EmbeddedDataSource40.java (original)
+++ db/derby/code/trunk/java/engine/org/apache/derby/jdbc/EmbeddedDataSource40.java Mon Apr 17 14:28:23 2006
@@ -28,6 +28,158 @@
import org.apache.derby.iapi.reference.SQLState;
+/**
+
+
+ EmbeddedDataSource40 is Derby's DataSource implementation for JDBC4.0.
+
+
+ <P>A DataSource is a factory for Connection objects. An object that
+ implements the DataSource interface will typically be registered with a
+ JNDI service provider.
+ <P>
+ EmbeddedDataSource40 supports the JDBC 4.0 specification
+ for the J2SE 6.0 Java Virtual Machine environment. Use EmbeddedDataSource
+ if your application is running in one of the following older
+ 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>The following is a list of properties that can be set on a Derby
+ DataSource object:
+ <P><B>Standard DataSource properties</B> (from JDBC 3.0 specification).
+
+ <UL><LI><B><code>databaseName</code></B> (String): <I>Mandatory</I>
+ <BR>This property must be set and it
+ identifies which database to access. If a database named wombat located at
+ g:/db/wombat is to be accessed, then one should call
+ <code>setDatabaseName("g:/db/wombat")</code> on the data source object.</LI>
+
+ <LI><B><code>dataSourceName</code></B> (String): <I>Optional</I>
+ <BR> Name for DataSource. Not used by the data source object. Used for
+ informational purpose only.</LI>
+
+ <LI><B><code>description</code></B> (String): <I>Optional</I>
+ <BR>Description of the data source. Not
+ used by the data source object. Used for informational purpose only.</LI>
+
+ <LI><B><code>password</code></B> (String): <I>Optional</I>
+ <BR>Database password for the no argument <code>DataSource.getConnection()</code>,
+ <code>ConnectionPoolDataSource.getPooledConnection()</code>
+ and <code>XADataSource.getXAConnection()</code> methods.
+
+ <LI><B><code>user</code></B> (String): <I>Optional</I>
+ <BR>Database user for the no argument <code>DataSource.getConnection()</code>,
+ <code>ConnectionPoolDataSource.getPooledConnection()</code>
+ and <code>XADataSource.getXAConnection()</code> methods.
+ </UL>
+
+ <BR><B>Derby specific DataSource properties.</B>
+
+ <UL>
+
+ <LI><B><code>attributesAsPassword</code></B> (Boolean): <I>Optional</I>
+ <BR>If true, treat the password value in a
+ <code>DataSource.getConnection(String user, String password)</code>,
+ <code>ConnectionPoolDataSource.getPooledConnection(String user, String password)</code>
+ or <code>XADataSource.getXAConnection(String user, String password)</code> as a set
+ of connection attributes. The format of the attributes is the same as the format
+ of the attributes in the property connectionAttributes. If false the password value
+ is treated normally as the password for the given user.
+ Setting this property to true allows a connection request from an application to
+ provide more authentication information that just a password, for example the request
+ can include the user's password and an encrypted database's boot password.</LI>
+
+ <LI><B><code>connectionAttributes</code></B> (String): <I>Optional</I>
+ <BR>Defines a set of Derby connection attributes for use in all connection requests.
+ The format of the String matches the format of the connection attributes in a Derby JDBC URL.
+ That is a list of attributes in the form <code><I>attribute</I>=<I>value</I></code>, each separated by semi-colon (';').
+ E.g. <code>setConnectionAttributes("bootPassword=erd3234dggd3kazkj3000");</code>.
+ <BR>The database name must be set by the DataSource property <code>databaseName</code> and not by setting the <code>databaseName</code>
+ connection attribute in the <code>connectionAttributes</code> property.
+ <BR>
+ Any attributes that can be set using a property of this DataSource implementation
+ (e.g user, password) should not be set in connectionAttributes. Conflicting
+ settings in connectionAttributes and properties of the DataSource will lead to
+ unexpected behaviour.
+ <BR>Please see the Derby documentation for a complete list of connection attributes. </LI>
+
+ <LI><B><code>createDatabase</code></B> (String): <I>Optional</I>
+ <BR>If set to the string "create", this will
+ cause a new database of <code>databaseName</code> if that database does not already
+ exist. The database is created when a connection object is obtained from
+ the data source. </LI>
+
+ <LI><B><code>shutdownDatabase</code></B> (String): <I>Optional</I>
+ <BR>If set to the string "shutdown",
+ this will cause the database to shutdown when a java.sql.Connection object
+ is obtained from the data source. E.g., If the data source is an
+ XADataSource, a getXAConnection().getConnection() is necessary to cause the
+ database to shutdown.
+
+ </UL>
+
+ <P><B>Examples.</B>
+
+ <P>This is an example of setting a property directly using Derby's
+ EmbeddedDataSource40 object. This code is typically written by a system integrator :
+ <PRE>
+ *
+ * import org.apache.derby.jdbc.*;
+ *
+ * // dbname is the database name
+ * // if create is true, create the database if necessary
+ * javax.sql.DataSource makeDataSource (String dbname, boolean create)
+ * throws Throwable
+ * {
+ * EmbeddedDataSource40 ds = new EmbeddedDataSource40();
+ * ds.setDatabaseName(dbname);
+ *
+ * if (create)
+ * ds.setCreateDatabase("create");
+ *
+ * return ds;
+ * }
+ </PRE>
+
+ <P>Example of setting properties thru reflection. This code is typically
+ generated by tools or written by a system integrator: <PRE>
+ *
+ * javax.sql.DataSource makeDataSource(String dbname)
+ * throws Throwable
+ * {
+ * Class[] parameter = new Class[1];
+ * parameter[0] = dbname.getClass();
+ * DataSource ds = new EmbeddedDataSource40();
+ * Class cl = ds.getClass();
+ *
+ * Method setName = cl.getMethod("setDatabaseName", parameter);
+ * Object[] arg = new Object[1];
+ * arg[0] = dbname;
+ * setName.invoke(ds, arg);
+ *
+ * return ds;
+ * }
+ </PRE>
+
+ <P>Example on how to register a data source object with a JNDI naming
+ service.
+ <PRE>
+ * DataSource ds = makeDataSource("mydb");
+ * Context ctx = new InitialContext();
+ * ctx.bind("jdbc/MyDB", ds);
+ </PRE>
+
+ <P>Example on how to retrieve a data source object from a JNDI naming
+ service.
+ <PRE>
+ * Context ctx = new InitialContext();
+ * DataSource ds = (DataSource)ctx.lookup("jdbc/MyDB");
+ </PRE>
+
+*/
public class EmbeddedDataSource40 extends EmbeddedDataSource {
public EmbeddedDataSource40() {
Modified: db/derby/code/trunk/java/engine/org/apache/derby/jdbc/EmbeddedXADataSource.java
URL: http://svn.apache.org/viewcvs/db/derby/code/trunk/java/engine/org/apache/derby/jdbc/EmbeddedXADataSource.java?rev=394780&r1=394779&r2=394780&view=diff
==============================================================================
--- db/derby/code/trunk/java/engine/org/apache/derby/jdbc/EmbeddedXADataSource.java (original)
+++ db/derby/code/trunk/java/engine/org/apache/derby/jdbc/EmbeddedXADataSource.java Mon Apr 17 14:28:23 2006
@@ -43,7 +43,7 @@
/**
- EmbeddedXADataSource is Derby's XADataSource implementation.
+ EmbeddedXADataSource is Derby's XADataSource implementation for JDBC3.0 and JDBC2.0.
<P>An XADataSource is a factory for XAConnection objects. It represents a
Modified: db/derby/code/trunk/java/engine/org/apache/derby/jdbc/EmbeddedXADataSource40.java
URL: http://svn.apache.org/viewcvs/db/derby/code/trunk/java/engine/org/apache/derby/jdbc/EmbeddedXADataSource40.java?rev=394780&r1=394779&r2=394780&view=diff
==============================================================================
--- db/derby/code/trunk/java/engine/org/apache/derby/jdbc/EmbeddedXADataSource40.java (original)
+++ db/derby/code/trunk/java/engine/org/apache/derby/jdbc/EmbeddedXADataSource40.java Mon Apr 17 14:28:23 2006
@@ -30,9 +30,30 @@
import javax.sql.XADataSource;
/**
- * This class is JDBC4.0 implementation of XADataSource
- * This class extends from EmbeddedDataSource40 so it inherits the
- * new method introduced in ConnectionPoolDataSource from EmbeddedDataSource40
+
+ EmbeddedXADataSource40 is Derby's XADataSource implementation for 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>
+ EmbeddedXADataSource40 supports the JDBC 4.0 specification
+ for the J2SE 6.0 Java Virtual Machine environment. Use EmbeddedXADataSource
+ 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>EmbeddedXADataSource40 object only works on a local database. There is no
+ client/server support. An EmbeddedXADataSource40 object must live in the same jvm as
+ the database.
+
+ <P>EmbeddedXADataSource40 is serializable and referenceable.
+
+ <P>See EmbeddedDataSource40 for DataSource properties.
+
*/
public class EmbeddedXADataSource40 extends EmbeddedXADataSource {
/** Creates a new instance of EmbeddedXADataSource40 */