PooledConnectionBuilder.java revision 13507:09eca0dfafd6 
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 */
25package javax.sql;
26
27import java.sql.SQLException;
28import 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 */
58public 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}
106