1 /*

     2  * Copyright (c) 2016, Oracle and/or its affiliates. All rights reserved.

     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

     4  *

     5  * This code is free software; you can redistribute it and/or modify it

     6  * under the terms of the GNU General Public License version 2 only, as

     7  * published by the Free Software Foundation.  Oracle designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Oracle in the LICENSE file that accompanied this code.

    10  *

    11  * This code is distributed in the hope that it will be useful, but WITHOUT

    12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

    13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

    14  * version 2 for more details (a copy is included in the LICENSE file that

    15  * accompanied this code).

    16  *

    17  * You should have received a copy of the GNU General Public License version

    18  * 2 along with this work; if not, write to the Free Software Foundation,

    19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

    20  *

    21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

    22  * or visit www.oracle.com if you need additional information or have any

    23  * questions.

    24  */

    25 package javax.sql;

    26 

    27 import java.sql.SQLException;

    28 import java.sql.ShardingKey;

    29 

    30 /**

    31  * A builder created from a {@code ConnectionPoolDataSource} object,

    32  * used to establish a connection to the database that the

    33  * {@code data source} object represents.  The connection

    34  * properties that were specified for the {@code data source} are used as the

    35  * default values by the {@code PooledConnectionBuilder}.

    36  * <p>The following example illustrates the use of {@code PooledConnectionBuilder}

    37  * to create a {@link XAConnection}:

    38  *

    39  * <pre>{@code

    40  *     ConnectionPoolDataSource ds = new MyConnectionPoolDataSource();

    41  *     ShardingKey superShardingKey = ds.createShardingKeyBuilder()

    42  *                           .subkey("EASTERN_REGION", JDBCType.VARCHAR)

    43  *                           .build();

    44  *     ShardingKey shardingKey = ds.createShardingKeyBuilder()

    45  *                           .subkey("PITTSBURGH_BRANCH", JDBCType.VARCHAR)

    46  *                           .build();

    47  *     PooledConnection con = ds.createPooledConnectionBuilder()

    48  *                       .user("rafa")

    49  *                       .password("tennis")

    50  *                       .setShardingKey(shardingKey)

    51  *                       .setSuperShardingKey(superShardingKey)

    52  *                       .build();

    53  * }</pre>

    54  *

    55  * @since 9

    56  *

    57  */

    58 public interface PooledConnectionBuilder  {

    59 

    60     /**

    61      * Specifies the username to be used when creating a connection

    62      *

    63      * @param username the database user on whose behalf the connection is being

    64      * made

    65      * @return the same {@code PooledConnectionBuilder} instance

    66      */

    67     PooledConnectionBuilder user(String username);

    68 

    69     /**

    70      * Specifies the password to be used when creating a connection

    71      *

    72      * @param password the password to use for this connection. May be {@code null}

    73      * @return the same {@code PooledConnectionBuilder} instance

    74      */

    75     PooledConnectionBuilder password(String password);

    76 

    77     /**

    78      * Specifies a {@code shardingKey} to be used when creating a connection

    79      *

    80      * @param shardingKey the ShardingKey. May be {@code null}

    81      * @return the same {@code PooledConnectionBuilder} instance

    82      * @see java.sql.ShardingKey

    83      * @see java.sql.ShardingKeyBuilder

    84      */

    85     PooledConnectionBuilder shardingKey(ShardingKey shardingKey);

    86 

    87     /**

    88      * Specifies a {@code superShardingKey} to be used when creating a connection

    89      *

    90      * @param superShardingKey the SuperShardingKey. May be {@code null}

    91      * @return the same {@code PooledConnectionBuilder} instance

    92      * @see java.sql.ShardingKey

    93      * @see java.sql.ShardingKeyBuilder

    94      */

    95     PooledConnectionBuilder superShardingKey(ShardingKey superShardingKey);

    96 

    97     /**

    98      * Returns an instance of the object defined by this builder.

    99      *

   100      * @return The built object

   101      * @throws java.sql.SQLException If an error occurs building the object

   102      */

   103     PooledConnection build() throws SQLException;

   104 

   105 }