changeset 13507:09eca0dfafd6

8146803: Enhance and update Sharding API Reviewed-by: joehw
author lancea
date Wed, 20 Jan 2016 07:36:42 -0500
parents b6bd1a9bf016
children 1f33e517236e 927f285009b6
files src/java.sql/share/classes/javax/sql/CommonDataSource.java src/java.sql/share/classes/javax/sql/ConnectionPoolDataSource.java src/java.sql/share/classes/javax/sql/DataSource.java src/java.sql/share/classes/javax/sql/PooledConnectionBuilder.java src/java.sql/share/classes/javax/sql/XAConnection.java src/java.sql/share/classes/javax/sql/XAConnectionBuilder.java src/java.sql/share/classes/javax/sql/XADataSource.java
diffstat 7 files changed, 151 insertions(+), 159 deletions(-) [+]
line wrap: on
line diff
--- a/src/java.sql/share/classes/javax/sql/CommonDataSource.java	Wed Jan 20 09:54:13 2016 +0100
+++ b/src/java.sql/share/classes/javax/sql/CommonDataSource.java	Wed Jan 20 07:36:42 2016 -0500
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2016, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -26,8 +26,8 @@
 package javax.sql;
 
 import java.sql.SQLException;
-import java.io.PrintWriter;
 import java.sql.SQLFeatureNotSupportedException;
+import java.sql.ShardingKeyBuilder;
 import java.util.logging.Logger;
 
 /**
@@ -128,4 +128,20 @@
      * @since 1.7
      */
     public Logger getParentLogger() throws SQLFeatureNotSupportedException;
+
+    //------------------------- JDBC 4.3 -----------------------------------
+
+    /**
+     * Creates a new {@code ShardingKeyBuilder} instance
+     * @implSpec
+     * The default implementation will throw a {@code SQLFeatureNotSupportedException}.
+     * @return The ShardingKeyBuilder instance that was created
+     * @throws SQLException if an error occurs creating the builder
+     * @throws SQLFeatureNotSupportedException if the driver does not support this method
+     * @since 9
+     * @see ShardingKeyBuilder
+    */
+    default ShardingKeyBuilder createShardingKeyBuilder() throws SQLException {
+        throw new SQLFeatureNotSupportedException("createShardingKeyBuilder not implemented");
+  };
 }
--- a/src/java.sql/share/classes/javax/sql/ConnectionPoolDataSource.java	Wed Jan 20 09:54:13 2016 +0100
+++ b/src/java.sql/share/classes/javax/sql/ConnectionPoolDataSource.java	Wed Jan 20 07:36:42 2016 -0500
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2000, 2016, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -26,6 +26,7 @@
 package javax.sql;
 
 import java.sql.SQLException;
+import java.sql.SQLFeatureNotSupportedException;
 
 
 /**
@@ -70,4 +71,20 @@
    */
   PooledConnection getPooledConnection(String user, String password)
     throws SQLException;
+
+  //------------------------- JDBC 4.3 -----------------------------------
+
+  /**
+   * Creates a new {@code PooledConnectionBuilder} instance
+   * @implSpec
+   * The default implementation will throw a {@code SQLFeatureNotSupportedException}.
+   * @return The ConnectionBuilder instance that was created
+   * @throws SQLException if an error occurs creating the builder
+   * @throws SQLFeatureNotSupportedException if the driver does not support sharding
+   * @since 9
+   * @see PooledConnectionBuilder
+   */
+  default PooledConnectionBuilder createPooledConnectionBuilder() throws SQLException {
+        throw new SQLFeatureNotSupportedException("createPooledConnectionBuilder not implemented");
+  };
  }
--- a/src/java.sql/share/classes/javax/sql/DataSource.java	Wed Jan 20 09:54:13 2016 +0100
+++ b/src/java.sql/share/classes/javax/sql/DataSource.java	Wed Jan 20 07:36:42 2016 -0500
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2000, 2016, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -29,7 +29,6 @@
 import java.sql.ConnectionBuilder;
 import java.sql.SQLException;
 import java.sql.SQLFeatureNotSupportedException;
-import java.sql.ShardingKeyBuilder;
 import java.sql.Wrapper;
 
 /**
@@ -119,25 +118,11 @@
    * @return The ConnectionBuilder instance that was created
    * @throws SQLException if an error occurs creating the builder
    * @throws SQLFeatureNotSupportedException if the driver does not support sharding
-   * @since 1.9
-   * @see createConnectionBuilder
+   * @since 9
+   * @see ConnectionBuilder
    */
   default ConnectionBuilder createConnectionBuilder() throws SQLException {
         throw new SQLFeatureNotSupportedException("createConnectionBuilder not implemented");
   };
 
-  /**
-   * Create a new {@code ShardingKeyBuilder} instance
-   * @implSpec
-   * The default implementation will throw a {@code SQLFeatureNotSupportedException}
-   * @return The ShardingKeyBuilder instance that was created
-   * @throws SQLException if an error occurs creating the builder
-   * @throws SQLFeatureNotSupportedException if the driver does not support this method
-   * @since 1.9
-   * @see ShardingKeyBuilder
-   */
-  default ShardingKeyBuilder  createShardingKeyBuilder()
-          throws SQLException {
-        throw new SQLFeatureNotSupportedException("createShardingKeyBuilder not implemented");
-  };
 }
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/src/java.sql/share/classes/javax/sql/PooledConnectionBuilder.java	Wed Jan 20 07:36:42 2016 -0500
@@ -0,0 +1,105 @@
+/*
+ * Copyright (c) 2016, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+package javax.sql;
+
+import java.sql.SQLException;
+import java.sql.ShardingKey;
+
+/**
+ * A builder created from a {@code ConnectionPoolDataSource} object,
+ * used to establish a connection to the database that the
+ * {@code data source} object represents.  The connection
+ * properties that were specified for the {@code data source} are used as the
+ * default values by the {@code PooledConnectionBuilder}.
+ * <p>The following example illustrates the use of {@code PooledConnectionBuilder}
+ * to create a {@link XAConnection}:
+ *
+ * <pre>{@code
+ *     ConnectionPoolDataSource ds = new MyConnectionPoolDataSource();
+ *     ShardingKey superShardingKey = ds.createShardingKeyBuilder()
+ *                           .subkey("EASTERN_REGION", JDBCType.VARCHAR)
+ *                           .build();
+ *     ShardingKey shardingKey = ds.createShardingKeyBuilder()
+ *                           .subkey("PITTSBURGH_BRANCH", JDBCType.VARCHAR)
+ *                           .build();
+ *     PooledConnection con = ds.createPooledConnectionBuilder()
+ *                       .user("rafa")
+ *                       .password("tennis")
+ *                       .setShardingKey(shardingKey)
+ *                       .setSuperShardingKey(superShardingKey)
+ *                       .build();
+ * }</pre>
+ *
+ * @since 9
+ *
+ */
+public interface PooledConnectionBuilder  {
+
+    /**
+     * Specifies the username to be used when creating a connection
+     *
+     * @param username the database user on whose behalf the connection is being
+     * made
+     * @return the same {@code PooledConnectionBuilder} instance
+     */
+    PooledConnectionBuilder user(String username);
+
+    /**
+     * Specifies the password to be used when creating a connection
+     *
+     * @param password the password to use for this connection. May be {@code null}
+     * @return the same {@code PooledConnectionBuilder} instance
+     */
+    PooledConnectionBuilder password(String password);
+
+    /**
+     * Specifies a {@code shardingKey} to be used when creating a connection
+     *
+     * @param shardingKey the ShardingKey. May be {@code null}
+     * @return the same {@code PooledConnectionBuilder} instance
+     * @see java.sql.ShardingKey
+     * @see java.sql.ShardingKeyBuilder
+     */
+    PooledConnectionBuilder shardingKey(ShardingKey shardingKey);
+
+    /**
+     * Specifies a {@code superShardingKey} to be used when creating a connection
+     *
+     * @param superShardingKey the SuperShardingKey. May be {@code null}
+     * @return the same {@code PooledConnectionBuilder} instance
+     * @see java.sql.ShardingKey
+     * @see java.sql.ShardingKeyBuilder
+     */
+    PooledConnectionBuilder superShardingKey(ShardingKey superShardingKey);
+
+    /**
+     * Returns an instance of the object defined by this builder.
+     *
+     * @return The built object
+     * @throws java.sql.SQLException If an error occurs building the object
+     */
+    PooledConnection build() throws SQLException;
+
+}
--- a/src/java.sql/share/classes/javax/sql/XAConnection.java	Wed Jan 20 09:54:13 2016 +0100
+++ b/src/java.sql/share/classes/javax/sql/XAConnection.java	Wed Jan 20 07:36:42 2016 -0500
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2000, 2015, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2000, 2016, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -52,121 +52,4 @@
      * @since 1.4
      */
     javax.transaction.xa.XAResource getXAResource() throws SQLException;
-
-    // JDBC 4.3
-
-    /**
-     * Sets and validates the sharding keys for this connection.
-     *
-     * @implSpec The default implementation will throw a
-     * {@code SQLFeatureNotSupportedException}.
-     *
-     * @apiNote This method validates that the sharding keys are valid for the
-     * {@code Connection}. The timeout value indicates how long the driver
-     * should wait for the {@code Connection} to verify that the sharding key is
-     * valid before {@code setShardingKeyIfValid} returns false.
-     * @param shardingKey the sharding key to be validated against this
-     * connection
-     * @param superShardingKey the super sharding key to be validated against
-     * this connection. The super sharding key may be {@code null}.
-     * @param timeout time in seconds before which the validation process is
-     * expected to be completed, otherwise the validation process is aborted. A
-     * value of 0 indicates the validation process will not time out.
-     * @return true if the connection is valid and the sharding keys are valid
-     * and set on this connection; false if the sharding keys are not valid or
-     * the timeout period expires before the operation completes.
-     * @throws SQLException if an error occurs while performing this validation;
-     * the {@code shardingkey} is {@code null}; a {@code superSharedingKey} is specified
-     * without a {@code shardingKey}; this method is called on a closed
-     * {@code connection}; or the {@code timeout} value is less than 0.
-     * @throws SQLFeatureNotSupportedException if the driver does not support
-     * sharding
-     * @since 1.9
-     * @see ShardingKey
-     * @see ShardingKeyBuilder
-     */
-    default boolean setShardingKeyIfValid(ShardingKey shardingKey,
-            ShardingKey superShardingKey, int timeout)
-            throws SQLException {
-        throw new SQLFeatureNotSupportedException("setShardingKeyIfValid not implemented");
-    }
-
-    /**
-     * Sets and validates the sharding key for this connection.
-     * @implSpec
-     * The default implementation will throw a
-     * {@code SQLFeatureNotSupportedException}.
-     * @apiNote
-     * This method validates  that the sharding key is valid for the
-     * {@code Connection}. The timeout value indicates how long the driver
-     * should wait for the {@code Connection} to verify that the sharding key
-     * is valid before {@code setShardingKeyIfValid} returns false.
-     * @param shardingKey the sharding key to be validated against this connection
-     * @param timeout time in seconds before which the validation process is expected to
-     * be completed,else the validation process is aborted. A value of 0 indicates
-     * the validation process will not time out.
-     * @return true if the connection is valid and the sharding key is valid to be
-     * set on this connection; false if the sharding key is not valid or
-     * the timeout period expires before the operation completes.
-     * @throws SQLException if there is an error while performing this validation;
-     * this method is called on a closed {@code connection}; the {@code shardingkey}
-     * is {@code null}; or the {@code timeout} value is less than 0.
-     * @throws SQLFeatureNotSupportedException if the driver does not support sharding
-     * @since 1.9
-     * @see ShardingKey
-     * @see ShardingKeyBuilder
-     */
-    default boolean setShardingKeyIfValid(ShardingKey shardingKey, int timeout)
-            throws SQLException {
-        throw new SQLFeatureNotSupportedException("setShardingKeyIfValid not implemented");
-    }
-
-    /**
-     * Specifies a shardingKey and superShardingKey to use with this Connection
-     * @implSpec
-     * The default implementation will throw a
-     * {@code SQLFeatureNotSupportedException}.
-     * @apiNote
-     * This method sets the specified sharding keys but does not require a
-     * round trip to the database to validate that the sharding keys are valid
-     * for the {@code Connection}.
-     * @param shardingKey the sharding key to set on this connection.
-     * @param superShardingKey the super sharding key to set on this connection.
-     * The super sharding key may be {@code null}
-     * @throws SQLException if an error  occurs setting the sharding keys;
-     * this method is called on a closed {@code connection};
-     * the {@code shardingkey} is {@code null}; or
-     * a {@code superSharedingKey} is specified without a {@code shardingKey}
-     * @throws SQLFeatureNotSupportedException if the driver does not support sharding
-     * @since 1.9
-     * @see ShardingKey
-     * @see ShardingKeyBuilder
-     */
-    default void setShardingKey(ShardingKey shardingKey, ShardingKey superShardingKey)
-            throws SQLException {
-        throw new SQLFeatureNotSupportedException("setShardingKey not implemented");
-    }
-
-    /**
-     * Specifies a shardingKey to use with this Connection
-     * @implSpec
-     * The default implementation will throw a
-     * {@code SQLFeatureNotSupportedException}.
-     * @apiNote
-     * This method sets the specified sharding key but does not require a
-     * round trip to the database to validate that the sharding key is valid
-     * for the {@code Connection}.
-     * @param shardingKey the sharding key to set on this connection.
-     * @throws SQLException if an error  occurs setting the sharding key;
-     * this method is called on a closed {@code connection}; or the
-     * {@code shardkingKey} is {@code null}
-     * @throws SQLFeatureNotSupportedException if the driver does not support sharding
-     * @since 1.9
-     * @see ShardingKey
-     * @see ShardingKeyBuilder
-     */
-    default void setShardingKey(ShardingKey shardingKey)
-            throws SQLException {
-        throw new SQLFeatureNotSupportedException("setShardingKey not implemented");
-    }
 }
--- a/src/java.sql/share/classes/javax/sql/XAConnectionBuilder.java	Wed Jan 20 09:54:13 2016 +0100
+++ b/src/java.sql/share/classes/javax/sql/XAConnectionBuilder.java	Wed Jan 20 07:36:42 2016 -0500
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2015, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2016, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -37,7 +37,7 @@
  * to create a {@link XAConnection}:
  *
  * <pre>{@code
- *     DataSource ds = new MyDataSource();
+ *     XADataSource ds = new MyXADataSource();
  *     ShardingKey superShardingKey = ds.createShardingKeyBuilder()
  *                           .subkey("EASTERN_REGION", JDBCType.VARCHAR)
  *                           .build();
@@ -52,7 +52,7 @@
  *                       .build();
  * }</pre>
  *
- * @since 1.9
+ * @since 9
  *
  */
 public interface XAConnectionBuilder  {
--- a/src/java.sql/share/classes/javax/sql/XADataSource.java	Wed Jan 20 09:54:13 2016 +0100
+++ b/src/java.sql/share/classes/javax/sql/XADataSource.java	Wed Jan 20 07:36:42 2016 -0500
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2000, 2015, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2000, 2016, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -87,28 +87,14 @@
    * Creates a new {@code XAConnectionBuilder} instance
    * @implSpec
    * The default implementation will throw a {@code SQLFeatureNotSupportedException}.
-   * @return The ConnectionBuilder instance that was created
+   * @return The XAConnectionBuilder instance that was created
    * @throws SQLException if an error occurs creating the builder
    * @throws SQLFeatureNotSupportedException if the driver does not support sharding
-   * @since 1.9
+   * @since 9
    * @see XAConnectionBuilder
    */
   default XAConnectionBuilder createXAConnectionBuilder() throws SQLException {
         throw new SQLFeatureNotSupportedException("createXAConnectionBuilder not implemented");
   };
 
-  /**
-   * Creates a new {@code ShardingKeyBuilder} instance
-   * @implSpec
-   * The default implementation will throw a {@code SQLFeatureNotSupportedException}.
-   * @return The ShardingKeyBuilder instance that was created
-   * @throws SQLException if an error occurs creating the builder
-   * @throws SQLFeatureNotSupportedException if the driver does not support this method
-   * @since 1.9
-   * @see ShardingKeyBuilder
-   */
-  default ShardingKeyBuilder createShardingKeyBuilder()
-          throws SQLException {
-        throw new SQLFeatureNotSupportedException("createShardingKeyBuilder not implemented");
-  };
  }