/*

 * Copyright (c)  2017, 2018, 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 jdk.incubator.sql2;

import java.util.LinkedList;

import java.util.List;

import java.util.function.Consumer;

/**

 * method is provided as a convenience.

 * 

 * Implementations must be thread safe.

 */

public interface DataSource

        extends AutoCloseable {

  /**

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

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

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

   * 

   * ISSUE: Probably need property(DataSourceProperty prop, Object value).

   */

  public interface Builder {

    /**

     *

     * @return this {@link Builder}

     */

    public default Builder url(String url) {

    }

    /**

     *

     * @return this {@link Builder}

     */

    public default Builder username(String name) {

    }

    /**

     *

     * @return this {@link Builder}

     */

    public default Builder password(String password) {

    }

    /**

     *

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

     * @return this {@link Builder}

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

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

     * this property has been specified previously to this method or

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

     */

    /**

     * Attempting to set a different value via

     * {@link IllegalArgumentException}.

     *

     * {@code null}.

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

     * @return this {@link Builder}

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

     * not return {@code true}. If it throws an {@link Exception} that

     * {@link Exception} is the cause. Or if this property has been specified

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

     * called.

     */

    /**

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

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

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

     * set the default value. Convenience method.

     *

     * {@code null}.

     * @return this Builder

     * @throws IllegalArgumentException if this property has been specified

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

     * called.

     */

    }

    /**

     * Provide a method that the built {@link DataSource} will call to control the

     * {@link DataSource} will call {@code request} with a positive argument

     * the sum of all arguments passed to {@code request} and the number of

     * calls to {@link DataSource#builder} is the

     * <i>demand</i>. The demand must always be non-negative. If a call is made to

     * throws {@link IllegalStateException}. If {@code requestHook} is not called,

     * the demand is defined to be infinite.

     * 

     * <p>

     *

     * @param request accepts calls to increase the demand. Not null.

     * @return this {@link Builder}

     * @throws IllegalStateException if this method has been called previously

     */

    /**

     * Return a DataSource configured as specified. 

     *

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

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

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

     */

    public DataSource build();

  }

  /**

   * the returned builder.

   *

   * @throws IllegalStateException if this {@link DataSource} is closed

   */

  /**

   * method for use with try with resources.

   *

   * @throws IllegalStateException if this {@link DataSource} is closed

   */

  }

  /**

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

   *

   * @throws IllegalStateException if this {@link DataSource} is closed

   */

  }

  /**

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

   * provided by this {@link DataSource}. 

   * 

   * ISSUE: Just an idea

   * 

   * @param format not {@code null}

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

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

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

   * if the {@link DataSource} cannot translate the SQL

   * @throws IllegalStateException if this {@link DataSource} is closed

   */

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

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

  }

  /**

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

   * 

   * ISSUE: Just an idea

   * 

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

   * @throws IllegalStateException if this {@link DataSource} is closed

   */

  public default List<String> supportedTranslateSqlFormats() {

    return new LinkedList<>();

  }

  @Override

  public void close();

}