changeset 13126:0967adb92393

8085984: Add JDBC Sharding API Reviewed-by: ulfzibis, joehw
author lancea
date Wed, 25 Nov 2015 15:36:03 -0500
parents 6abacd981c4a
children e1a21828acc1
files src/java.sql/share/classes/java/sql/Connection.java src/java.sql/share/classes/java/sql/ConnectionBuilder.java src/java.sql/share/classes/java/sql/DatabaseMetaData.java src/java.sql/share/classes/java/sql/ShardingKey.java src/java.sql/share/classes/java/sql/ShardingKeyBuilder.java src/java.sql/share/classes/javax/sql/DataSource.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 9 files changed, 681 insertions(+), 27 deletions(-) [+]
line wrap: on
line diff
--- a/src/java.sql/share/classes/java/sql/Connection.java	Wed Nov 25 15:28:30 2015 -0500
+++ b/src/java.sql/share/classes/java/sql/Connection.java	Wed Nov 25 15:36:03 2015 -0500
@@ -1587,4 +1587,119 @@
     default void endRequest() throws SQLException {
             // Default method takes no action
     }
+
+    /**
+     * 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");
+    }
 }
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/src/java.sql/share/classes/java/sql/ConnectionBuilder.java	Wed Nov 25 15:36:03 2015 -0500
@@ -0,0 +1,101 @@
+/*
+ * Copyright (c) 2015, 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 java.sql;
+
+/**
+ * A builder created from a {@code DataSource} 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 ConnectionBuilder}.
+ * <p>The following example illustrates the use of {@code ConnectionBuilder}
+ * to create a {@link Connection}:
+ *
+ * <pre>{@code
+ *     DataSource ds = new MyDataSource();
+ *     ShardingKey superShardingKey = ds.createShardingKeyBuilder()
+ *                           .subkey("EASTERN_REGION", JDBCType.VARCHAR)
+ *                           .build();
+ *     ShardingKey shardingKey = ds.createShardingKeyBuilder()
+ *                           .subkey("PITTSBURGH_BRANCH", JDBCType.VARCHAR)
+ *                           .build();
+ *     Connection con = ds.createConnectionBuilder()
+ *                       .user("rafa")
+ *                       .password("tennis")
+ *                       .setShardingKey(shardingKey)
+ *                       .setSuperShardingKey(superShardingKey)
+ *                       .build();
+ * }</pre>
+ *
+ * @since 1.9
+ *
+ */
+public interface ConnectionBuilder  {
+
+    /**
+     * 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 ConnectionBuilder} instance
+     */
+    ConnectionBuilder 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 ConnectionBuilder} instance
+     */
+    ConnectionBuilder 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 ConnectionBuilder} instance
+     * @see ShardingKey
+     * @see ShardingKeyBuilder
+     */
+    ConnectionBuilder 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 ConnectionBuilder} instance
+     * @see ShardingKey
+     * @see ShardingKeyBuilder
+     */
+    ConnectionBuilder 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
+     */
+    Connection build() throws SQLException;
+}
--- a/src/java.sql/share/classes/java/sql/DatabaseMetaData.java	Wed Nov 25 15:28:30 2015 -0500
+++ b/src/java.sql/share/classes/java/sql/DatabaseMetaData.java	Wed Nov 25 15:36:03 2015 -0500
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1996, 2014, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 2015, 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
@@ -3684,4 +3684,19 @@
         return false;
     }
 
+    // JDBC 4.3
+
+    /**
+     * Retrieves whether this database supports sharding.
+     * @implSpec
+     * The default implementation will return {@code false}
+     *
+     * @return {@code true} if this database supports sharding;
+     *         {@code false} otherwise
+     * @exception SQLException if a database access error occurs
+     * @since 1.9
+     */
+    default boolean supportsSharding() throws SQLException {
+        return false;
+    }
 }
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/src/java.sql/share/classes/java/sql/ShardingKey.java	Wed Nov 25 15:36:03 2015 -0500
@@ -0,0 +1,76 @@
+/*
+ * Copyright (c) 2015, 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 java.sql;
+
+/**
+ * Interface used to indicate that this object represents a Sharding Key. A
+ * {@code ShardingKey} instance is only guaranteed to be compatible with the
+ * data source instance that it was derived from. A {@code ShardingKey} is
+ * created using {@link ShardingKeyBuilder}.
+ * <p>
+ * The following example illustrates the use of {@link ShardingKeyBuilder} to
+ * create a {@code ShardingKey}:
+ * <pre>
+ * {@code
+ *
+ *     DataSource ds = new MyDataSource();
+ *     ShardingKey shardingKey = ds.createShardingKeyBuilder()
+ *                           .subkey("abc", JDBCType.VARCHAR)
+ *                           .subkey(94002, JDBCType.INTEGER)
+ *                           .build();
+ * }
+ * </pre>
+ * <p>
+ *
+ * A {@code ShardingKey} may also be used for specifying a
+ * {@code superShardingKey}. Databases that support composite Sharding may use a
+ * {@code superShardingKey} to specify a additional level of partitioning within
+ * the Shard.
+ * <p>
+ * The following example illustrates the use of {@link ShardingKeyBuilder} to
+ * create a {@code superShardingKey} for an eastern region with a
+ * {@code ShardingKey} specified for the Pittsburgh branch office:
+ * <pre>
+ * {@code
+ *
+ *     DataSource ds = new MyDataSource();
+ *     ShardingKey superShardingKey = ds.createShardingKeyBuilder()
+ *                           .subkey("EASTERN_REGION", JDBCType.VARCHAR)
+ *                           .build();
+ *     ShardingKey shardingKey = ds.createShardingKeyBuilder()
+ *                           .subkey("PITTSBURGH_BRANCH", JDBCType.VARCHAR)
+ *                           .build();
+ *     Connection con = ds.createConnectionBuilder()
+ *                           .superShardingKey(superShardingKey)
+ *                           .shardingKey(shardingKey)
+ *                           .build();
+ * }
+ * </pre>
+ *
+ * @since 1.9
+ */
+public interface ShardingKey {
+
+}
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/src/java.sql/share/classes/java/sql/ShardingKeyBuilder.java	Wed Nov 25 15:36:03 2015 -0500
@@ -0,0 +1,66 @@
+/*
+ * Copyright (c) 2015, 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 java.sql;
+
+/**
+ * A builder created from a {@code DataSource}  or {@code XADataSource} object,
+ * used to create a {@link ShardingKey} with sub-keys of supported data types.
+ * Implementations must
+ * support JDBCType.VARCHAR and  may also support additional data types.
+ * <p>
+ * The following example illustrates the use of {@code ShardingKeyBuilder} to
+ * create a {@link ShardingKey}:
+ * <pre>
+ * {@code
+ *
+ *     DataSource ds = new MyDataSource();
+ *     ShardingKey shardingKey = ds.createShardingKeyBuilder()
+ *                           .subkey("abc", JDBCType.VARCHAR)
+ *                           .subkey(94002, JDBCType.INTEGER)
+ *                           .build();
+ * }
+ * </pre>
+ */
+public interface ShardingKeyBuilder {
+
+    /**
+     * This method will be called to add a subkey into a Sharding Key object being
+     * built. The order in which subkey method is called is important as it
+     * indicates the order of placement of the subkey within the Sharding Key.
+     *
+     * @param subkey contains the object that needs to be part of shard sub key
+     * @param subkeyType sub-key data type of type java.sql.SQLType
+     * @return this builder object
+     */
+    ShardingKeyBuilder subkey(Object subkey, SQLType subkeyType);
+
+    /**
+     * 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
+     */
+    ShardingKey build() throws SQLException;
+}
--- a/src/java.sql/share/classes/javax/sql/DataSource.java	Wed Nov 25 15:28:30 2015 -0500
+++ b/src/java.sql/share/classes/javax/sql/DataSource.java	Wed Nov 25 15:36:03 2015 -0500
@@ -26,7 +26,10 @@
 package javax.sql;
 
 import java.sql.Connection;
+import java.sql.ConnectionBuilder;
 import java.sql.SQLException;
+import java.sql.SQLFeatureNotSupportedException;
+import java.sql.ShardingKeyBuilder;
 import java.sql.Wrapper;
 
 /**
@@ -106,4 +109,35 @@
    */
   Connection getConnection(String username, String password)
     throws SQLException;
+
+  // JDBC 4.3
+
+  /**
+   * Create a new {@code ConnectionBuilder} 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 1.9
+   * @see createConnectionBuilder
+   */
+  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");
+  };
 }
--- a/src/java.sql/share/classes/javax/sql/XAConnection.java	Wed Nov 25 15:28:30 2015 -0500
+++ b/src/java.sql/share/classes/javax/sql/XAConnection.java	Wed Nov 25 15:36:03 2015 -0500
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2000, 2006, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2000, 2015, 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
@@ -22,40 +22,151 @@
  * or visit www.oracle.com if you need additional information or have any
  * questions.
  */
-
 package javax.sql;
 
 import java.sql.*;
 
-
 /**
- * An object that provides support for distributed
- * transactions.  An <code>XAConnection</code> object  may be enlisted
- * in a distributed transaction by means of an <code>XAResource</code> object.
- * A transaction manager, usually part of a middle tier server, manages an
- * <code>XAConnection</code> object through the <code>XAResource</code> object.
+ * An object that provides support for distributed transactions. An
+ * {@code XAConnection} object may be enlisted in a distributed transaction
+ * by means of an {@code XAResource} object. A transaction manager, usually
+ * part of a middle tier server, manages an {@code XAConnection} object
+ * through the {@code XAResource} object.
  * <P>
- * An application programmer does not use this interface directly; rather,
- * it is used by a transaction manager working in the middle tier server.
+ * An application programmer does not use this interface directly; rather, it is
+ * used by a transaction manager working in the middle tier server.
  *
  * @since 1.4
  */
-
 public interface XAConnection extends PooledConnection {
 
+    /**
+     * Retrieves an {@code XAResource} object that the transaction manager
+     * will use to manage this {@code XAConnection} object's participation
+     * in a distributed transaction.
+     *
+     * @return the {@code XAResource} object
+     * @exception SQLException if a database access error occurs
+     * @exception SQLFeatureNotSupportedException if the JDBC driver does not
+     * support this method
+     * @since 1.4
+     */
+    javax.transaction.xa.XAResource getXAResource() throws SQLException;
 
-  /**
-   * Retrieves an <code>XAResource</code> object that
-   * the transaction manager will use
-   * to manage this <code>XAConnection</code> object's participation in a
-   * distributed transaction.
-   *
-   * @return the <code>XAResource</code> object
-   * @exception SQLException if a database access error occurs
-   * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
-   * this method
-   * @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");
+    }
+}
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/src/java.sql/share/classes/javax/sql/XAConnectionBuilder.java	Wed Nov 25 15:36:03 2015 -0500
@@ -0,0 +1,105 @@
+/*
+ * Copyright (c) 2015, 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 XADataSource} 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 XAConnectionBuilder}.
+ * <p>The following example illustrates the use of {@code XAConnectionBuilder}
+ * to create a {@link XAConnection}:
+ *
+ * <pre>{@code
+ *     DataSource ds = new MyDataSource();
+ *     ShardingKey superShardingKey = ds.createShardingKeyBuilder()
+ *                           .subkey("EASTERN_REGION", JDBCType.VARCHAR)
+ *                           .build();
+ *     ShardingKey shardingKey = ds.createShardingKeyBuilder()
+ *                           .subkey("PITTSBURGH_BRANCH", JDBCType.VARCHAR)
+ *                           .build();
+ *     XAConnection con = ds.createXAConnectionBuilder()
+ *                       .user("rafa")
+ *                       .password("tennis")
+ *                       .setShardingKey(shardingKey)
+ *                       .setSuperShardingKey(superShardingKey)
+ *                       .build();
+ * }</pre>
+ *
+ * @since 1.9
+ *
+ */
+public interface XAConnectionBuilder  {
+
+    /**
+     * 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 XAConnectionBuilder} instance
+     */
+    XAConnectionBuilder 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 XAConnectionBuilder} instance
+     */
+    XAConnectionBuilder 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 XAConnectionBuilder} instance
+     * @see java.sql.ShardingKey
+     * @see java.sql.ShardingKeyBuilder
+     */
+    XAConnectionBuilder 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 XAConnectionBuilder} instance
+     * @see java.sql.ShardingKey
+     * @see java.sql.ShardingKeyBuilder
+     */
+    XAConnectionBuilder 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
+     */
+    XAConnection build() throws SQLException;
+
+}
--- a/src/java.sql/share/classes/javax/sql/XADataSource.java	Wed Nov 25 15:28:30 2015 -0500
+++ b/src/java.sql/share/classes/javax/sql/XADataSource.java	Wed Nov 25 15:36:03 2015 -0500
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2000, 2015, 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
@@ -80,4 +80,35 @@
    */
   XAConnection getXAConnection(String user, String password)
     throws SQLException;
+
+  // JDBC 4.3
+
+  /**
+   * Creates a new {@code XAConnectionBuilder} 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 1.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");
+  };
  }