--- a/jdk/src/java.sql/share/classes/java/sql/Connection.java Wed Nov 25 15:28:30 2015 -0500
+++ b/jdk/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/jdk/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/jdk/src/java.sql/share/classes/java/sql/DatabaseMetaData.java Wed Nov 25 15:28:30 2015 -0500
+++ b/jdk/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/jdk/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/jdk/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/jdk/src/java.sql/share/classes/javax/sql/DataSource.java Wed Nov 25 15:28:30 2015 -0500
+++ b/jdk/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/jdk/src/java.sql/share/classes/javax/sql/XAConnection.java Wed Nov 25 15:28:30 2015 -0500
+++ b/jdk/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/jdk/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/jdk/src/java.sql/share/classes/javax/sql/XADataSource.java Wed Nov 25 15:28:30 2015 -0500
+++ b/jdk/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");
+ };
}