https://openjdk.java.net/ 
/*
 * Copyright (c) 2016, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */
package javax.sql;

import java.sql.SQLException;
import java.sql.ShardingKey;


A builder created from a ConnectionPoolDataSource object, used to establish a connection to the database that the data source object represents. The connection properties that were specified for the data source are used as the default values by the PooledConnectionBuilder. 
The following example illustrates the use of PooledConnectionBuilder to create a XAConnection: 

    ConnectionPoolDataSource ds = new MyConnectionPoolDataSource();
    ShardingKey superShardingKey = ds.createShardingKeyBuilder()
                          .subkey("EASTERN_REGION", JDBCType.VARCHAR)
                          .build();
    ShardingKey shardingKey = ds.createShardingKeyBuilder()
                          .subkey("PITTSBURGH_BRANCH", JDBCType.VARCHAR)
                          .build();
    PooledConnection con = ds.createPooledConnectionBuilder()
                      .user("rafa")
                      .password("tennis")
                      .setShardingKey(shardingKey)
                      .setSuperShardingKey(superShardingKey)
                      .build();



Since:9
/**
 * A builder created from a {@code ConnectionPoolDataSource} object,
 * used to establish a connection to the database that the
 * {@code data source} object represents.  The connection
 * properties that were specified for the {@code data source} are used as the
 * default values by the {@code PooledConnectionBuilder}.
 * <p>The following example illustrates the use of {@code PooledConnectionBuilder}
 * to create a {@link XAConnection}:
 *
 * <pre>{@code
 *     ConnectionPoolDataSource ds = new MyConnectionPoolDataSource();
 *     ShardingKey superShardingKey = ds.createShardingKeyBuilder()
 *                           .subkey("EASTERN_REGION", JDBCType.VARCHAR)
 *                           .build();
 *     ShardingKey shardingKey = ds.createShardingKeyBuilder()
 *                           .subkey("PITTSBURGH_BRANCH", JDBCType.VARCHAR)
 *                           .build();
 *     PooledConnection con = ds.createPooledConnectionBuilder()
 *                       .user("rafa")
 *                       .password("tennis")
 *                       .setShardingKey(shardingKey)
 *                       .setSuperShardingKey(superShardingKey)
 *                       .build();
 * }</pre>
 *
 * @since 9
 *
 */
public interface PooledConnectionBuilder  {

    
Specifies the username to be used when creating a connection

Params:
  • username – the database user on whose behalf the connection is being
made
Returns:the same PooledConnectionBuilder instance
/**
     * Specifies the username to be used when creating a connection
     *
     * @param username the database user on whose behalf the connection is being
     * made
     * @return the same {@code PooledConnectionBuilder} instance
     */
    PooledConnectionBuilder user(String username);

    
Specifies the password to be used when creating a connection

Params:
  • password – the password to use for this connection. May be null
Returns:the same PooledConnectionBuilder instance
/**
     * Specifies the password to be used when creating a connection
     *
     * @param password the password to use for this connection. May be {@code null}
     * @return the same {@code PooledConnectionBuilder} instance
     */
    PooledConnectionBuilder password(String password);

    
Specifies a shardingKey to be used when creating a connection 
Params:
  • shardingKey – the ShardingKey. May be null
See Also:
Returns:the same PooledConnectionBuilder instance
/**
     * Specifies a {@code shardingKey} to be used when creating a connection
     *
     * @param shardingKey the ShardingKey. May be {@code null}
     * @return the same {@code PooledConnectionBuilder} instance
     * @see java.sql.ShardingKey
     * @see java.sql.ShardingKeyBuilder
     */
    PooledConnectionBuilder shardingKey(ShardingKey shardingKey);

    
Specifies a superShardingKey to be used when creating a connection 
Params:
  • superShardingKey – the SuperShardingKey. May be null
See Also:
Returns:the same PooledConnectionBuilder instance
/**
     * Specifies a {@code superShardingKey} to be used when creating a connection
     *
     * @param superShardingKey the SuperShardingKey. May be {@code null}
     * @return the same {@code PooledConnectionBuilder} instance
     * @see java.sql.ShardingKey
     * @see java.sql.ShardingKeyBuilder
     */
    PooledConnectionBuilder superShardingKey(ShardingKey superShardingKey);

    
Returns an instance of the object defined by this builder.

Throws:
Returns:The built object
/**
     * Returns an instance of the object defined by this builder.
     *
     * @return The built object
     * @throws java.sql.SQLException If an error occurs building the object
     */
    PooledConnection build() throws SQLException;

}