db-derby-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From rhille...@apache.org
Subject svn commit: r394780 - /db/derby/code/trunk/java/engine/org/apache/derby/jdbc/
Date Mon, 17 Apr 2006 21:28:26 GMT
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 */



Mime
View raw message