/*
 * 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 DataSource 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 ConnectionBuilder. 
The following example illustrates the use of ConnectionBuilder to create a Connection: 

    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();

Since:
9/**
 * 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 9
 *
 */
public interface ConnectionBuilder  {

    
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 ConnectionBuilder 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 ConnectionBuilder} instance
     */
    ConnectionBuilder 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 ConnectionBuilder 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 ConnectionBuilder} instance
     */
    ConnectionBuilder password(String password);

    
Specifies a shardingKey to be used when creating a connection 
Params:
shardingKey – the ShardingKey. May be null
See Also:
ShardingKey
ShardingKeyBuilder
Returns:
the same ConnectionBuilder instance/**
     * 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 superShardingKey to be used when creating a connection 
Params:
superShardingKey – the SuperShardingKey. May be null
See Also:
ShardingKey
ShardingKeyBuilder
Returns:
the same ConnectionBuilder instance/**
     * 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.
Throws:
SQLException – If an error occurs building the object
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
     */
    Connection build() throws SQLException;
}