db-derby-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From d..@apache.org
Subject svn commit: r1603549 - in /db/derby/code/trunk: ./ java/client/org/apache/derby/jdbc/ java/drda/org/apache/derby/impl/drda/ java/engine/org/apache/derby/jdbc/
Date Wed, 18 Jun 2014 17:38:22 GMT
Author: dag
Date: Wed Jun 18 17:38:21 2014
New Revision: 1603549

URL: http://svn.apache.org/r1603549
Log:
DERBY-6552 The public api includes methods inherited from superclasses which aren't in the
public api and so have no javadoc comments

Patch derby-6552-only-public-members.

Changes the way we generate public API javadocs by restricting it to
public class members.

Adds back Javadocs for private, class private and protected members
removed before.

Added some missing Javadocs.

Moved the top level class javadocs that were nto visible (root
classes) down to the first level visible data sources, so we can get
the data source properties documented for embedded. Added this for
client.  Cf. BasicEmbeddedDataSource40 and BasicClientDataSource40
respectively.

Added missing @serial tags

Modified:
    db/derby/code/trunk/build.xml
    db/derby/code/trunk/java/client/org/apache/derby/jdbc/BasicClientDataSource40.java
    db/derby/code/trunk/java/drda/org/apache/derby/impl/drda/XADatabase.java
    db/derby/code/trunk/java/engine/org/apache/derby/jdbc/BasicEmbeddedDataSource40.java
    db/derby/code/trunk/java/engine/org/apache/derby/jdbc/BasicEmbeddedXADataSource40.java
    db/derby/code/trunk/java/engine/org/apache/derby/jdbc/EmbeddedConnectionPoolDataSource.java
    db/derby/code/trunk/java/engine/org/apache/derby/jdbc/EmbeddedDataSource.java
    db/derby/code/trunk/java/engine/org/apache/derby/jdbc/EmbeddedDataSourceInterface.java
    db/derby/code/trunk/java/engine/org/apache/derby/jdbc/EmbeddedXADataSource.java

Modified: db/derby/code/trunk/build.xml
URL: http://svn.apache.org/viewvc/db/derby/code/trunk/build.xml?rev=1603549&r1=1603548&r2=1603549&view=diff
==============================================================================
--- db/derby/code/trunk/build.xml (original)
+++ db/derby/code/trunk/build.xml Wed Jun 18 17:38:21 2014
@@ -1082,8 +1082,9 @@
     <javadoc bootclasspath="${bootClasspath}"
              classpath="${bootClasspath};${osgi};${servlet24};${out.dir};${jars.javadoc}"
              sourcepath="${derby.engine.src.dir}:${derby.client.src.dir}:${derby.drda.src.dir}:${derby.shared.src.dir}:${derby.optional.src.dir}:${derby.tools.src.dir}"
-         excludepackagenames="org.apache.derby.*"
+             excludepackagenames="org.apache.derby.*"
              breakiterator="true"
+             access="public"
              destdir="${public.api.dir}"
     	     Overview="${basedir}/published_api_overview.html"
              Windowtitle="Apache Derby ${major}.${minor} API Documentation"   

Modified: db/derby/code/trunk/java/client/org/apache/derby/jdbc/BasicClientDataSource40.java
URL: http://svn.apache.org/viewvc/db/derby/code/trunk/java/client/org/apache/derby/jdbc/BasicClientDataSource40.java?rev=1603549&r1=1603548&r2=1603549&view=diff
==============================================================================
--- db/derby/code/trunk/java/client/org/apache/derby/jdbc/BasicClientDataSource40.java (original)
+++ db/derby/code/trunk/java/client/org/apache/derby/jdbc/BasicClientDataSource40.java Wed
Jun 18 17:38:21 2014
@@ -58,6 +58,36 @@ import org.apache.derby.shared.common.re
  * BasicClientDataSource40 is similar to ClientDataSource except it
  * can not be used with JNDI, i.e. it does not implement
  * {@code javax.naming.Referenceable}.
+ * <p/>
+ *  * The standard attributes provided are, cf. e.g. table
+ * 9.1 in the JDBC 4.2 specification.
+ * <ul>
+ *   <li>databaseName</li>
+ *   <li>dataSourceName</li>
+ *   <li>description</li>
+ *   <li>password</li>
+ *   <li>user</li>
+ * </ul>
+ * These standard attributes are not supported:
+ * <ul>
+ *   <li>networkProtocol</li>
+ *   <li>roleName</li>
+ * </ul>
+ * The Derby client driver also supports these attributes:
+ * <ul>
+ *   <li>loginTimeout</li> @see javax.sql.CommonDataSource set/get
+ *   <li>logWriter</li> @see javax.sql.CommonDataSource set/get
+ *   <li>createDatabase</li>
+ *   <li>connectionAttributes</li>
+ *   <li>shutdownDatabase</li>
+ *   <li>attributesAsPassword</li>
+ *   <li>retrieveMessageText</li>
+ *   <li>securityMechanism</li>
+ *   <li>traceDirectory</li>
+ *   <li>traceFile</li>
+ *   <li>traceFileAppend</li>
+ *   <li>traceLevel<li>
+ * </ul>
  */
 @SuppressWarnings("ResultOfObjectAllocationIgnored")
 public class BasicClientDataSource40 
@@ -230,7 +260,7 @@ public class BasicClientDataSource40 
     // other data source properties should probably also be supported as
     // connection properties.
 
-        // ---------------------------- loginTimeout ------------------------------
+    // ---------------------------- loginTimeout ------------------------------
     //
     // was serialized in 1.0 release
     /**
@@ -270,36 +300,50 @@ public class BasicClientDataSource40 
 
     // ---------------------------- databaseName ------------------------------
     //
-    // Stores the relational database name, RDBNAME.
-    // The length of the database name may be limited to 18 bytes
-    // and therefore may throw an SQLException.
-    //
-    //
+    
+    /**
+     * Stores the relational database name, RDBNAME.
+     * The length of the database name may be limited to 18 bytes
+     * and therefore may throw an SQLException.
+     * @serial
+     */
     private String databaseName;
 
     // databaseName is not permitted in a properties object
 
 
     // ---------------------------- description ------------------------------
-    // A description of this data source.
+    
+    /**
+     * A description of this data source.
+     * @serial
+     */
     private String description;
 
     // ---------------------------- dataSourceName ----------------------------
     //
-    // A data source name;
-    // used to name an underlying XADataSource,
-    // or ConnectionPoolDataSource when pooling of connections is done.
-    //
+    
+    /**
+     * A data source name;
+     * used to name an underlying XADataSource,
+     * or ConnectionPoolDataSource when pooling of connections is done.
+     * @serial
+     */
     private String dataSourceName;
 
     // ---------------------------- portNumber --------------------------------
-    //
+
+    /**
+     * @serial
+     */
     private int portNumber = propertyDefault_portNumber;
 
     // ---------------------------- serverName --------------------------------
-    //
-    // Derby-410 fix.
-    private String serverName = propertyDefault_serverName;
+    
+    /**
+     * @serial 
+     */
+    private String serverName = propertyDefault_serverName; // Derby-410 fix.
 
     // serverName is not permitted in a properties object
 
@@ -372,17 +416,22 @@ public class BasicClientDataSource40 
 
     // ---------------------------- user -----------------------------------
     //
-    // This property can be overwritten by specifing the
-    // username parameter on the DataSource.getConnection() method
-    // call.  If user is specified, then password must also be
-    // specified, either in the data source object or provided on
-    // the DataSource.getConnection() call.
-    //
-    // Each data source implementation subclass will maintain it's own
-    // <code>password</code> property.  This password property may or may not
-    // be declared transient, and therefore may be serialized to a file in
-    // clear-text, care must taken by the user to prevent security breaches.
-    // Derby-406 fix
+    
+    /**
+     * This property can be overwritten by specifing the
+     * username parameter on the DataSource.getConnection() method
+     * call.  If user is specified, then password must also be
+     * specified, either in the data source object or provided on
+     * the DataSource.getConnection() call.
+     *
+     * Each data source implementation subclass will maintain it's own
+     * <code>password</code> property.  This password property may or may not
+     * be declared transient, and therefore may be serialized to a file in
+     * clear-text, care must taken by the user to prevent security breaches.
+     * Derby-406 fix
+     * 
+     * @serial
+     */
     private String user = propertyDefault_user;
 
     public static String getUser(Properties properties) {
@@ -424,23 +473,28 @@ public class BasicClientDataSource40 
     // or on the Client DataSource object
     private final static short SECMEC_HAS_NOT_EXPLICITLY_SET = 0;
 
-    // Security Mechanism can be specified explicitly either when obtaining a
-    // connection via a DriverManager or via Datasource.
-    // Via DriverManager, securityMechanism can be set on the connection
-    // request using the 'securityMechanism' attribute.
-    // Via DataSource, securityMechanism can be set by calling
-    // setSecurityMechanism() on the ClientDataSource
-    // If the security mechanism is not explicitly set as mentioned above, in
-    // that case the Client will try to upgrade the security mechanism to a
-    // more secure one, if possible.
-    // @see #getUpgradedSecurityMechanism
-    // Therefore, need to keep track if the securityMechanism has been
-    // explicitly set
+    /**
+     * Security Mechanism can be specified explicitly either when obtaining a
+     * connection via a DriverManager or via Datasource.
+     * Via DriverManager, securityMechanism can be set on the connection
+     * request using the 'securityMechanism' attribute.
+     * Via DataSource, securityMechanism can be set by calling
+     * setSecurityMechanism() on the ClientDataSource
+     * If the security mechanism is not explicitly set as mentioned above, in
+     * that case the Client will try to upgrade the security mechanism to a
+     * more secure one, if possible.
+     * See {@link #getUpgradedSecurityMechanism}.
+     * Therefore, need to keep track if the securityMechanism has been
+     * explicitly set.
+     *
+     * @serial
+     */
     private short securityMechanism = SECMEC_HAS_NOT_EXPLICITLY_SET;
 
 
 
     // We use the NET layer constants to avoid a mapping for the NET driver.
+    
     /**
      * Return security mechanism if it is set, else upgrade the security
      * mechanism if possible and return the upgraded security mechanism
@@ -526,7 +580,10 @@ public class BasicClientDataSource40 
     }
 
     // ---------------------------- getServerMessageTextOnGetMessage ---------
-    //
+
+    /**
+     * @serial
+     */
     private boolean retrieveMessageText = propertyDefault_retrieveMessageText;
 
     public static boolean getRetrieveMessageText(Properties properties) {
@@ -537,7 +594,10 @@ public class BasicClientDataSource40 
     }
 
     // ---------------------------- traceFile ---------------------------------
-    //
+
+    /**
+     * @serial
+     */
     private String traceFile;
 
     static String getTraceFile(Properties properties) {
@@ -547,7 +607,10 @@ public class BasicClientDataSource40 
     // ---------------------------- traceDirectory ----------------------------
     // For the suffix of the trace file when traceDirectory is enabled.
     private transient int traceFileSuffixIndex_ = 0;
-    //
+
+    /**
+     * @serial
+     */
     private String traceDirectory;
 
     /**
@@ -598,7 +661,10 @@ public class BasicClientDataSource40 
     }
 
     // ---------------------------- traceFileAppend ---------------------------
-    //
+
+    /**
+     * @serial
+     */
     private boolean traceFileAppend = propertyDefault_traceFileAppend;
 
     static boolean getTraceFileAppend(Properties properties) {
@@ -619,6 +685,9 @@ public class BasicClientDataSource40 
         return properties.getProperty("password");
     }
 
+    /**
+     * @serial
+     */
     private String password;
 
     synchronized public void setPassword(String password) {
@@ -868,7 +937,7 @@ public class BasicClientDataSource40 
      * Properties to be seen by Bean - access thru reflection.
      */
 
-    // -- Stardard JDBC DataSource Properties
+    // -- Standard JDBC DataSource Properties
 
     public synchronized void setDatabaseName(String databaseName) {
         this.databaseName = databaseName;
@@ -973,6 +1042,9 @@ public class BasicClientDataSource40 
 
     // ----------------------- ssl
 
+    /**
+     * @serial
+     */
     private int sslMode;
 
     /**
@@ -1011,11 +1083,13 @@ public class BasicClientDataSource40 
     // ----------------------- set/getCreate/ShutdownDatabase -----------------
     /**
      * Set to true if the database should be created.
+     * @serial
      */
     private boolean createDatabase;
 
     /**
      * Set to true if the database should be shutdown.
+     * @serial
      */
     private boolean shutdownDatabase;
 
@@ -1072,6 +1146,9 @@ public class BasicClientDataSource40 
         return shutdownstr;
     }
 
+    /**
+     * @serial
+     */
     private String connectionAttributes = null;
 
     /**
@@ -1104,7 +1181,9 @@ public class BasicClientDataSource40 
     }
 
 
-
+    /**
+     * @serial
+     */
     private int traceLevel = propertyDefault_traceLevel;
 
     /**

Modified: db/derby/code/trunk/java/drda/org/apache/derby/impl/drda/XADatabase.java
URL: http://svn.apache.org/viewvc/db/derby/code/trunk/java/drda/org/apache/derby/impl/drda/XADatabase.java?rev=1603549&r1=1603548&r2=1603549&view=diff
==============================================================================
--- db/derby/code/trunk/java/drda/org/apache/derby/impl/drda/XADatabase.java (original)
+++ db/derby/code/trunk/java/drda/org/apache/derby/impl/drda/XADatabase.java Wed Jun 18 17:38:21
2014
@@ -58,9 +58,10 @@ class XADatabase extends Database {
     /**
      * Make a new connection using the database name and set 
      * the connection in the database
-     **/
-    synchronized void makeConnection(Properties p) throws
- SQLException
+     * @throws java.sql.SQLException
+     */
+    @Override
+    synchronized void makeConnection(Properties p) throws SQLException
     {
         if (xaDataSource == null) {
             try {

Modified: db/derby/code/trunk/java/engine/org/apache/derby/jdbc/BasicEmbeddedDataSource40.java
URL: http://svn.apache.org/viewvc/db/derby/code/trunk/java/engine/org/apache/derby/jdbc/BasicEmbeddedDataSource40.java?rev=1603549&r1=1603548&r2=1603549&view=diff
==============================================================================
--- db/derby/code/trunk/java/engine/org/apache/derby/jdbc/BasicEmbeddedDataSource40.java (original)
+++ db/derby/code/trunk/java/engine/org/apache/derby/jdbc/BasicEmbeddedDataSource40.java Wed
Jun 18 17:38:21 2014
@@ -48,6 +48,37 @@ import org.apache.derby.impl.jdbc.Util;
  * BasicEmbeddedDataSource40 is similar to EmbeddedDataSource, but does
  * not support JNDI naming, i.e. it does not implement
  * {@code javax.naming.Referenceable}.
+ * <p/>
+ * The standard attributes provided are, cf. e.g. table
+ * 9.1 in the JDBC 4.2 specification.
+ * <ul>
+ *   <li>databaseName</li>
+ *   <li>dataSourceName</li>
+ *   <li>description</li>
+ *   <li>password</li>
+ *   <li>user</li>
+ * </ul>
+ * These standard attributes are not supported:
+ * <ul>
+ *   <li>networkProtocol</li>
+ *   <li>portNumber</li>
+ *   <li>roleName</li>
+ *   <li>serverName</li>
+ * </ul>
+ * The embedded Derby driver also supports these attributes:
+ * <ul>
+ *   <li>loginTimeout</li> @see javax.sql.CommonDataSource set/get
+ *   <li>logWriter</li> @see javax.sql.CommonDataSource set/get
+ *   <li>createDatabase</li>
+ *   <li>connectionAttributes</li>
+ *   <li>shutdownDatabase</li>
+ *   <li>attributesAsPassword</li>
+ * </ul>
+ * <br>
+ * See the specific Derby DataSource implementation for details on their
+ * meaning.
+ * <p/>
+ * See also the JDBC specifications for more details.
  *
  * @see EmbeddedDataSource
  */
@@ -58,47 +89,95 @@ public class BasicEmbeddedDataSource40 
 
     private static final long serialVersionUID = -4945135214995641182L;
 
+    /**
+     * Set by {@link #setDescription(java.lang.String)}.
+     * @serial
+     */
     protected String description;
+
+    /**
+     * Set by {@link #setDataSourceName(java.lang.String)}.
+     * @serial
+     */
     protected String dataSourceName;
+
+    /**
+     * Set by {@link #setDatabaseName(java.lang.String)}.
+     * @serial
+     */
     protected String databaseName;
+
     /**
-     * Derby specific connection attributes.
+     * Derby specific connection attributes. Set by
+     * {@link #setConnectionAttributes(java.lang.String)}.
      * @serial
      */
     protected String connectionAttributes;
 
     /**
      * Set to "create" if the database should be created.
+     * See {@link #setCreateDatabase(java.lang.String)}.
      * @serial
      */
     protected String createDatabase;
 
     /**
-     * Set to "shutdown" if the database should be shutdown.
+     * Set to "shutdown" if the database should be shutdown. See {@link
+     * #setShutdownDatabase(java.lang.String)}.
      * @serial
      */
     protected String shutdownDatabase;
 
     /**
      * Set password to be a set of connection attributes.
+     * @serial
      */
     protected boolean attributesAsPassword;
 
-    // shortDatabaseName has attributes of databaseName stripped off
+    /**
+     * {@code shortDatabaseName} has attributes of {@code databaseName}
+     * stripped off. See {@link #databaseName}.
+     * @serial
+     */
     private String shortDatabaseName;
 
+    /**
+     * Set by {@link #setPassword(java.lang.String)}.
+     * @serial
+     */
     private String password;
+
+    /**
+     * Set by {@link #setUser(java.lang.String)}.
+     * @serial
+     */
     private String user;
+
+    /**
+     * Set by {@link #setLoginTimeout(int)}.
+     * @serial
+     */
     protected int loginTimeout;
 
-    // instance variables that will not be serialized
+    /**
+     * Instance variable that will not be serialized.
+     */
     transient private PrintWriter printer;
+
+    /**
+     * Instance variable that will not be serialized.
+     */
     transient protected String jdbcurl;
 
-    // Unlike a DataSource, LocalDriver is shared by all
-    // Derby databases in the same jvm.
+    /**
+     * Unlike a DataSource, the internal driver is shared by all
+     * Derby databases in the same JVM.
+     */
     transient protected InternalDriver driver;
 
+    /**
+     * Constructs a basic embedded data source. See the class Javadoc.
+     */
     public BasicEmbeddedDataSource40() {
         update();
     }
@@ -137,9 +216,9 @@ public class BasicEmbeddedDataSource40 
         return databaseName;
     }
 
-    //
-    // Return database name with ant attributes stripped off.
-    //
+    /**
+     * Return database name with ant attributes stripped off.
+    */
     private String getShortDatabaseName() {
         return shortDatabaseName;
     }
@@ -303,6 +382,10 @@ public class BasicEmbeddedDataSource40 
         printer = out;
     }
 
+
+    /**
+     * Update {@link #jdbcurl} from attributes set.
+     */
     protected void update() {
         StringBuilder sb = new StringBuilder(64);
 
@@ -375,6 +458,13 @@ public class BasicEmbeddedDataSource40 
         return createDatabase;
     }
 
+    /**
+     * Return a handle to the internal driver, possibly instantiating it first
+     * if it hasn't been booted or if it has been shut down.
+     *
+     * @return The internal driver handle
+     * @throws SQLException
+     */
     @SuppressWarnings("ResultOfObjectAllocationIgnored")
     InternalDriver findDriver() throws SQLException {
         String url = jdbcurl;
@@ -494,15 +584,15 @@ public class BasicEmbeddedDataSource40 
         return attributesAsPassword;
     }
 
-    // Most of our customers would be using JNDI to get the data
-    // sources. Since we don't have a jndi in the test setup to test this, we
-    // are adding this method to fake it. This is getting used in XAJNDITest
-    // so we can compare the two data sources.
+     // Most of our customers would be using JNDI to get the data
+     // sources. Since we don't have a JNDI in the test setup to test this, we
+     // are adding this method to fake it. This is getting used in XAJNDITest
+     // so we can compare the two data sources.
     @Override
-    public boolean equals(Object p0) {
+    public boolean equals(Object other) {
 
-        if (p0 instanceof EmbeddedDataSource) {
-            EmbeddedDataSource ds = (EmbeddedDataSource)p0;
+        if (other instanceof EmbeddedDataSource) {
+            EmbeddedDataSource ds = (EmbeddedDataSource)other;
 
             boolean match = true;
 
@@ -564,6 +654,9 @@ public class BasicEmbeddedDataSource40 
         return false;
     }
 
+    // We don't really need this in the tests
+    // (see equals), but unsafe not to
+    // define hashCode if we define equals.
     @Override
     public int hashCode() {
         int hash = 5;
@@ -627,8 +720,16 @@ public class BasicEmbeddedDataSource40 
         return this.getConnection(username, password, true);
     }
 
-    // requestPassword Use {@code true} if the password came from the
-    // getConnection() call.
+    /**
+     * Get a user connection: minion method.
+     *
+     * @param username the user name
+     * @param password the password
+     * @param requestPassword {@code true} if the password came from the
+     *        getConnection() call with user and password arguments..
+     * @return user connection
+     * @throws SQLException
+     */
     final Connection getConnection(String username,
                                    String password,
                                    boolean requestPassword)
@@ -717,6 +818,19 @@ public class BasicEmbeddedDataSource40 
         }
     }
 
+    /**
+     * Return a resource adapter. Use {@code ra} if non-null and active, else
+     * get the one for the data base.
+     *
+     * @param ds The data source
+     * @param ra The cached value if any
+     * @param user The user name
+     * @param password The password in clear text
+     * @param requestPassword If {@code true}, use the supplied user and
+     *                        password to boot the database if required
+     * @return the resource adapter
+     * @throws SQLException An error occurred
+     */
     protected static ResourceAdapter setupResourceAdapter(
         EmbeddedXADataSourceInterface ds,
         ResourceAdapter ra,

Modified: db/derby/code/trunk/java/engine/org/apache/derby/jdbc/BasicEmbeddedXADataSource40.java
URL: http://svn.apache.org/viewvc/db/derby/code/trunk/java/engine/org/apache/derby/jdbc/BasicEmbeddedXADataSource40.java?rev=1603549&r1=1603548&r2=1603549&view=diff
==============================================================================
--- db/derby/code/trunk/java/engine/org/apache/derby/jdbc/BasicEmbeddedXADataSource40.java
(original)
+++ db/derby/code/trunk/java/engine/org/apache/derby/jdbc/BasicEmbeddedXADataSource40.java
Wed Jun 18 17:38:21 2014
@@ -45,9 +45,14 @@ public class BasicEmbeddedXADataSource40
 
     private static final long serialVersionUID = -5715798975598379739L;
 
-    // link to the database
+    /**
+     * link to the database
+     */
     private transient ResourceAdapter ra;
 
+    /**
+     * Constructs a basic embedded XA data source. See the class Javadoc.
+     */
     public BasicEmbeddedXADataSource40() {
         super();
     }
@@ -77,7 +82,11 @@ public class BasicEmbeddedXADataSource40
         return createXAConnection (ra, user, password, true);
     }
 
-    // implementation methods
+    /**
+     * {@inheritDoc}
+     * <p/>
+     * Also clears {@link ra}.
+     */
     @Override
     protected void update() {
         ra = null;
@@ -85,8 +94,16 @@ public class BasicEmbeddedXADataSource40
     }
 
 
-    // Instantiate and return an EmbedXAConnection from this instance
-    // of EmbeddedXADataSource.
+    /**
+     * Instantiate and return an EmbedXAConnection from this instance
+     * of EmbeddedXADataSource. Minion method.
+     * @param ra The resource adapter for this database
+     * @param user The user name
+     * @param password The password
+     * @param requestPassword @{@code false} if original call is from a
+     *        no-argument constructor, otherwise {@code true}
+     * @return An XA connection to the database
+     */
     private XAConnection createXAConnection(
             ResourceAdapter ra,
             String user,

Modified: db/derby/code/trunk/java/engine/org/apache/derby/jdbc/EmbeddedConnectionPoolDataSource.java
URL: http://svn.apache.org/viewvc/db/derby/code/trunk/java/engine/org/apache/derby/jdbc/EmbeddedConnectionPoolDataSource.java?rev=1603549&r1=1603548&r2=1603549&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
Wed Jun 18 17:38:21 2014
@@ -104,10 +104,17 @@ public class EmbeddedConnectionPoolDataS
 		return createPooledConnection (username, password, true);
 	}
         
-    //
-    // Create and return an EmbedPooledConnection from this instance
-    // of EmbeddedConnectionPoolDataSource.
-    //
+    /**
+     * Create and return an EmbedPooledConnection from this instance
+     * of EmbeddedConnectionPoolDataSource.
+     *
+     * @param user The user name
+     * @param password The password
+     * @param requestPassword @{@code false} if original call is from a
+     *        no-argument constructor, otherwise {@code true}
+     * @return A pooled connection
+     * @throws SQLException An error occurred
+     */
     private PooledConnection createPooledConnection (String user,
         String password, boolean requestPassword) throws SQLException
     {

Modified: db/derby/code/trunk/java/engine/org/apache/derby/jdbc/EmbeddedDataSource.java
URL: http://svn.apache.org/viewvc/db/derby/code/trunk/java/engine/org/apache/derby/jdbc/EmbeddedDataSource.java?rev=1603549&r1=1603548&r2=1603549&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 Wed Jun
18 17:38:21 2014
@@ -249,14 +249,18 @@ public class EmbeddedDataSource extends 
         return ref;
 	}
 
-    //
-    // Add Java Bean properties to the reference using
-    // StringRefAddr for each property. List of bean properties
-    // is defined from the public getXXX() methods on this object
-    // that take no arguments and return short, int, boolean or String.
-    // The StringRefAddr has a key of the Java bean property name,
-    // converted from the method name. E.g. traceDirectory for
-    // traceDirectory.
+    /**
+    * Add Java Bean properties to the reference using
+    * StringRefAddr for each property. List of bean properties
+    * is defined from the public getXXX() methods on this object
+    * that take no arguments and return short, int, boolean or String.
+    * The {@link StringRefAddr} has a key of the Java bean property name,
+    * converted from the method name. E.g. traceDirectory for
+    * traceDirectory.
+    *
+     * @param ths {@code this} object
+     * @param ref The reference to add properties to
+    */
     private static void addBeanProperties(Object ths, Reference ref)
     {
         // Look for all the getXXX methods in the class that take no arguments.

Modified: db/derby/code/trunk/java/engine/org/apache/derby/jdbc/EmbeddedDataSourceInterface.java
URL: http://svn.apache.org/viewvc/db/derby/code/trunk/java/engine/org/apache/derby/jdbc/EmbeddedDataSourceInterface.java?rev=1603549&r1=1603548&r2=1603549&view=diff
==============================================================================
--- db/derby/code/trunk/java/engine/org/apache/derby/jdbc/EmbeddedDataSourceInterface.java
(original)
+++ db/derby/code/trunk/java/engine/org/apache/derby/jdbc/EmbeddedDataSourceInterface.java
Wed Jun 18 17:38:21 2014
@@ -24,33 +24,6 @@ package org.apache.derby.jdbc;
 /**
  * Methods that extend the API of
  * {@code javax.sql.DataSource} common for all Derby embedded data sources.
- * <p>
- * EmbeddedDataSourceInterface provides support for JDBC standard DataSource
- * attributes
- * <p>
- * The standard attributes provided by implementations are, cf. e.g. table
- * 9.1 in the JDBC 4.1 specification.
- * <ul>
- *   <li>databaseName</li>
- *   <li>dataSourceName</li>
- *   <li>description</li>
- *   <li>password</li>
- *   <li>user</li>
- * </ul>
- * The embedded Derby driver also supports these attributes:
- * <ul>
- *   <li>loginTimeout</li> @see javax.sql.CommonDataSource set/get
- *   <li>logWriter</li> @see javax.sql.CommonDataSource set/get
- *   <li>createDatabase</li>
- *   <li>connectionAttributes</li>
- *   <li>shutdownDatabase</li>
- *   <li>attributesAsPassword</li>
- * </ul>
- * <br>
- * See the specific Derby DataSource implementation for details on their
- * meaning.
- * <br>
- * See the JDBC specifications for more details.
  */
 public interface EmbeddedDataSourceInterface extends javax.sql.DataSource {
     public void setDatabaseName(String databaseName);

Modified: db/derby/code/trunk/java/engine/org/apache/derby/jdbc/EmbeddedXADataSource.java
URL: http://svn.apache.org/viewvc/db/derby/code/trunk/java/engine/org/apache/derby/jdbc/EmbeddedXADataSource.java?rev=1603549&r1=1603548&r2=1603549&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 Wed Jun
18 17:38:21 2014
@@ -70,7 +70,10 @@ public class EmbeddedXADataSource extend
 
 	private static final long serialVersionUID = -5715798975598379738L;
 
-	// link to the database
+    /**
+     * A cached link to the database, set up with the first connection is
+     * made.
+     */
 	transient private ResourceAdapter ra;
   
 	/**
@@ -121,10 +124,11 @@ public class EmbeddedXADataSource extend
         return createXAConnection (ra, user, password, true);
 	}
 	
-	/*
-	 * private method
-	 */
-
+    /**
+     * {@inheritDoc}
+     * <p/>
+     * Also clear the cached value of {@link #ra}.
+     */
     @Override
     protected void update() {
 		ra = null;
@@ -132,9 +136,17 @@ public class EmbeddedXADataSource extend
 	}
 
         
-    //
-    // Instantiate and return an EmbedXAConnection from this instance
-    // of EmbeddedXADataSource.
+    /**
+     * Instantiate and return an EmbedXAConnection from this instance
+     * of EmbeddedXADataSource.
+     * @param ra The resource adapter to the database
+     * @param user The user name
+     * @param password The password
+     * @param requestPassword @{@code false} if original call is from a
+     *        no-argument constructor, otherwise {@code true}
+     * @return An XA connection to the database
+     * @throws java.sql.SQLException
+     */
     //
     private XAConnection createXAConnection (ResourceAdapter ra,
         String user, String password, boolean requestPassword)
@@ -172,9 +184,8 @@ public class EmbeddedXADataSource extend
 
 
     /**
-     *
-     * @return The ResourceAdapter instance for
-     *         the underlying database
+     * @return The cached {@code ResourceAdapter} instance for the underlying
+     * database
      */
     @Override
     public ResourceAdapter getResourceAdapter()



Mime
View raw message