infernap12/jdk
1
0
Fork 0
mirror of https://github.com/openjdk/jdk.git synced 2026-03-11 08:23:26 +00:00
Code Issues Packages Projects Releases Wiki Activity

8085984: Add JDBC Sharding API

Browse Source 
Reviewed-by: ulfzibis, joehw
This commit is contained in:
Lance Andersen 2015-11-25 15:36:03 -05:00
parent 0c8069758d
commit 2667a7cfed
9 changed files with 681 additions and 27 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

115
jdk/src/java.sql/share/classes/java/sql/Connection.java
View File

@ -1587,4 +1587,119 @@ throws SQLException;
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");
}
}

101
jdk/src/java.sql/share/classes/java/sql/ConnectionBuilder.java Normal file
View File

@ -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;
}

17
jdk/src/java.sql/share/classes/java/sql/DatabaseMetaData.java
View File

@ -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 @@ public interface DatabaseMetaData extends Wrapper {
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;
}
}

76
jdk/src/java.sql/share/classes/java/sql/ShardingKey.java Normal file
View File

@ -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 {
}

66
jdk/src/java.sql/share/classes/java/sql/ShardingKeyBuilder.java Normal file
View File

@ -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;
}

34
jdk/src/java.sql/share/classes/javax/sql/DataSource.java
View File

@ -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 @@ public interface DataSource extends CommonDataSource, Wrapper {
*/
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");
};
}

161
jdk/src/java.sql/share/classes/javax/sql/XAConnection.java
View File

@ -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");
}
}

105
jdk/src/java.sql/share/classes/javax/sql/XAConnectionBuilder.java Normal file
View File

@ -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;
}

33
jdk/src/java.sql/share/classes/javax/sql/XADataSource.java
View File

@ -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 @@ public interface XADataSource extends CommonDataSource {
*/
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");
};
}