1 /*

     2  * Copyright (c)  2017, 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 

    26 package java.sql2;

    27 

    28 import java.util.LinkedList;

    29 import java.util.List;

    30 import java.util.function.Consumer;

    31 

    32 /**

    33  * Uses the builder pattern to get a {@link Connection}. A {@link getConnection}

    34  * method is provided as a convenience.

    35  */

    36 public interface DataSource

    37         extends AutoCloseable {

    38 

    39   /**

    40    * Instances of this type are used to build {@link DataSource}s. This type is 

    41    * immutable once configured. No property can be set more than once. No 

    42    * property can be set after {@link build} is called. 

    43    */

    44   public interface Builder {

    45 

    46     /**

    47      * A convenience method for setting the {@link JdbcConnectionProperty#URL}.

    48      *

    49      * @param url the value to be set for {@link JdbcConnectionProperty#URL}

    50      * @return this {@link Builder}

    51      * @see connectionProperty

    52      */

    53     public default Builder url(String url) {

    54       return connectionProperty(JdbcConnectionProperty.URL, url);

    55     }

    56 

    57     /**

    58      * A convenience method for setting the {@link JdbcConnectionProperty#USER}.

    59      *

    60      * @param name the value to be set for {@link JdbcConnectionProperty#USER}

    61      * @return this {@link Builder}

    62      * @see connectionProperty

    63      */

    64     public default Builder username(String name) {

    65       return connectionProperty(JdbcConnectionProperty.USER, name);

    66     }

    67 

    68     /**

    69      * A convenience method for setting the {@link JdbcConnectionProperty#PASSWORD}.

    70      *

    71      * @param password the value to be set for {@link JdbcConnectionProperty#PASSWORD}

    72      * @return this {@link Builder}

    73      * @see connectionProperty

    74      */

    75     public default Builder password(String password) {

    76       return connectionProperty(JdbcConnectionProperty.PASSWORD, password);

    77     }

    78     

    79     /**

    80      * Specify the value of a {@link Connection} property that will be set by default on

    81      * all {@link Connection}s produced by this {@link DataSource}. A different value can be set

    82      * for a particular {@link Connection} via {@link Connection.Builder#property}.

    83      *

    84      * @param property the {@link ConnectionProperty} to be set. May not be {@code null}.

    85      * @param value the value to be set for {@code property}

    86      * @return this {@link Builder}

    87      * @throws IllegalArgumentException if {@code property.validate(value)} does not

    88      * return {@code true}. If it throws an {@link Exception} that {@link Exception} is the cause. Or if

    89      * this property has been specified previously to this method or

    90      * {@link connectionProperty}.

    91      * @throws IllegalStateException if {@link build} has previously been called.

    92      */

    93     public Builder defaultConnectionProperty(ConnectionProperty property, Object value);

    94 

    95     /**

    96      * Specify the value of a {@link Connection} property that will be set on all

    97      * {@link Connection}s produced by the built {@link DataSource}. Attempting to set a

    98      * different value via {@link Connection.Builder#property} will throw

    99      * {@link IllegalArgumentException}.

   100      *

   101      * @param property the {@link ConnectionProperty} to set. May not be {@code null}.

   102      * @param value the value to set as the default for {@code property}

   103      * @return this {@link Builder}

   104      * @throws IllegalArgumentException if {@code property.validate(value)} does not

   105      * return {@code true}. If it throws an {@link Exception} that {@link Exception} is the cause. Or if

   106      * this property has been specified previously to this method or

   107      * {@link defaultConnectionProperty}.

   108      * @throws IllegalStateException if {@link build} has previously been called.

   109      */

   110     public Builder connectionProperty(ConnectionProperty property, Object value);

   111 

   112     /**

   113      * Make a user defined property known to the implementation. One reason to

   114      * do this is so the default value of the property will be used. If the

   115      * {@link DataSource} doesn't know about the property then it cannot know to set the

   116      * default value. Registering a property already known to the DataSource is

   117      * a no-op.

   118      *

   119      * @param property the {@link ConnectionProperty} to make known. May not be {@code null}.

   120      * @return this Builder

   121      * @throws IllegalStateException if {@link build} has previously been called.

   122      */

   123     public Builder registerConnectionProperty(ConnectionProperty property);

   124 

   125     /**

   126      * Return a DataSource configured as specified. 

   127      *

   128      * @return a configured {@link DataSource}. Not {@code null}.

   129      * @throws IllegalArgumentException if unable to return a {@link DataSource} due to

   130      * problems with the configuration such is missing or conflicting properties.

   131      */

   132     public DataSource build();

   133   }

   134 

   135   /**

   136    * Returns a {@link Connection} builder. By default that builder will return

   137    * {@link Connection}s with the {@code ConnectionProperty}s specified when creating this

   138    * DataSource. Default and unspecified {@link ConnectionProperty}s can be set with

   139    * the returned builder.

   140    *

   141    * @return a new {@link Connection} builder. Not {@code null}.

   142    */

   143   public Connection.Builder builder();

   144 

   145   /**

   146    * Returns a {@link Connection} that has a submitted connect {@link Operation}. Convenience

   147    * method for use with try with resources.

   148    *

   149    * @return a {@link Connection}

   150    */

   151   public default Connection getConnection() {

   152     return builder().build().connect();

   153   }

   154 

   155   /**

   156    * Returns a {@link Connection} that has a submitted connect {@link Operation} with an error

   157    * handler. Convenience method for use with try with resources. The error

   158    * handle handles errors in the connect {@link Operation}.

   159    *

   160    * @param handler for errors in the connect {@link Operation}

   161    * @return a {@link Connection}

   162    */

   163   public default Connection getConnection(Consumer<Throwable> handler) {

   164     return builder().build().connect(handler);

   165   }

   166   

   167   /**

   168    * Translates a SQL string from the format specified by the format argument

   169    * to a format that can be used to create {@link Operation}s for the {@link Connection}s

   170    * provided by this {@link DataSource}. 

   171    * 

   172    * ISSUE: Just an idea

   173    * 

   174    * @param format not {@code null}

   175    * @param source SQL in the format specified by {@code format}. Not {@code null}.

   176    * @return SQL in the format supported by this {@link DataSource}. Not {@code null}.

   177    * @throws IllegalArgumentException if the {@code format} is not supported

   178    * @throws SqlException if the {@link DataSource} cannot translate the SQL

   179    */

   180   public default String translateSql(String format, String source) throws SqlException {

   181     throw new IllegalArgumentException("Unsupported format: \"" + format + "\"");

   182   }

   183   

   184   /**

   185    * Return a list of the source formats accepted by the {@link translateSql} method.

   186    * 

   187    * ISSUE: Just an idea

   188    * 

   189    * @return an array of Strings each of which identifies a supported format

   190    */

   191   public default List<String> supportedTranslateSqlFormats() {

   192     return new LinkedList<>();

   193   }

   194   

   195   @Override

   196   public void close();

   197 

   198 }