1 /*

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

    26 

    27 import java.time.Duration;

    28 import java.util.List;

    29 import java.util.concurrent.CompletionStage;

    30 import java.util.function.Consumer;

    31 import java.util.stream.Collector;

    32 

    33 /**

    34  * A database operation that returns a count that is executed multiple times

    35  * with multiple sets of parameter values in one database operation. The

    36  * parameters are submitted to the database in the same order as in the

    37  * sequences passed to the set methods. The count results are passed to the

    38  * collector in the same order they are produced by the database. The

    39  * value of the Operation is the final result produced by the collector.

    40  *

    41  * @param <T> the type of the result of collecting the counts

    42  */

    43 public interface ArrayRowCountOperation<T> extends Operation<T> {

    44 

    45   /**

    46    * Set a sequence of parameter values. The value is captured and should not be

    47    * modified before the {@link Operation} is completed.

    48    *

    49    * The Operation is completed exceptionally with ClassCastException if any of

    50    * the values cannot be converted to the specified SQL type.

    51    *

    52    * @param id the identifier of the parameter marker to be set

    53    * @param values the sequence of values the parameter is to be set to

    54    * @param type the SQL type of the values to send to the database

    55    * @return this Operation

    56    * @throws IllegalArgumentException if the length of values is not the same as

    57    * the length of the previously set parameter sequences or if the same id was

    58    * passed in a previous call.

    59    * @throws IllegalStateException if the {@link Operation} has been submitted

    60    */

    61   public ArrayRowCountOperation<T> set(String id, List<?> values, SqlType type);

    62 

    63   /**

    64    * Set a sequence of parameter values. Use a default SQL type determined by

    65    * the type of the value argument. The value is captured and should not be

    66    * modified before the {@link Operation} is completed.

    67    *

    68    * The Operation is completed exceptionally with ClassCastException if any of

    69    * the values cannot be converted to the specified SQL type.

    70    *

    71    * @param id the identifier of the parameter marker to be set

    72    * @param values the value the parameter is to be set to

    73    * @return this {@link Operation}

    74    * @throws IllegalArgumentException if the length of value is not the same as

    75    * the length of the previously set parameter sequences or if the same id was

    76    * passed in a previous call.

    77    * @throws IllegalStateException if the {@link Operation} has been submitted

    78    */

    79   public ArrayRowCountOperation<T> set(String id, List<?> values);

    80 

    81   /**

    82    * Set a sequence of parameter values. The first parameter is captured and

    83    * should not be modified before the {@link Operation} is completed.

    84    *

    85    * The Operation is completed exceptionally with ClassCastException if any of

    86    * the values cannot be converted to the specified SQL type.

    87    *

    88    * @param <S> the Java type of the individual parameter values

    89    * @param id the identifier of the parameter marker to be set

    90    * @param values the value the parameter is to be set to

    91    * @param type the SQL type of the value to send to the database

    92    * @return this Operation

    93    * @throws IllegalArgumentException if the length of value is not the same as

    94    * the length of the previously set parameter sequences or if the same id was

    95    * passed in a previous call.

    96    * @throws IllegalStateException if the {@link Operation} has been submitted

    97    */

    98   public <S> ArrayRowCountOperation<T> set(String id, S[] values, SqlType type);

    99 

   100   /**

   101    * Set a sequence of parameter values. Use a default SQL type determined by

   102    * the type of the value argument. The parameter is captured and should not be

   103    * modified before the {@link Operation} is completed.

   104    *

   105    * The Operation is completed exceptionally with ClassCastException if any of

   106    * the values cannot be converted to the specified SQL type.

   107    *

   108    * @param <S> the Java type of the individual parameter values

   109    * @param id the identifier of the parameter marker to be set

   110    * @param values the value the parameter is to be set to

   111    * @return this Operation

   112    * @throws IllegalArgumentException if the length of value is not the same as

   113    * the length of the previously set parameter sequences or if the same id was

   114    * passed in a previous call.

   115    * @throws IllegalStateException if the {@link Operation} has been submitted

   116    */

   117   public <S> ArrayRowCountOperation<T> set(String id, S[] values);

   118 

   119   /**

   120    * Provide a source for a sequence of parameter values.

   121    *

   122    * This Operation is not executed until source is completed normally. If

   123    * source completes exceptionally this Operation completes exceptionally with

   124    * an IllegealArgumentException with the source's exception as the cause.

   125    *

   126    * The Operation is completed exceptionally with ClassCastException if any of

   127    * the values of the source cannot be converted to the specified SQL type.

   128    *

   129    * If the length of the value of source is not the same as the length of all

   130    * other parameter sequences this Operation is completed exceptionally with

   131    * IllegalArgumentException.

   132    *

   133    * @param id the identifier of the parameter marker to be set

   134    * @param source supplies the values the parameter is to be set to

   135    * @param type the SQL type of the value to send to the database

   136    * @return this Operation

   137    * @throws IllegalArgumentException if the same id was passed in a previous

   138    * call.

   139    * @throws IllegalStateException if the {@link Operation} has been submitted

   140    */

   141   public ArrayRowCountOperation<T> set(String id, CompletionStage<?> source, SqlType type);

   142 

   143   /**

   144    * Provide a source for a sequence of parameter values. Use a default SQL type

   145    * determined by the element type of the value of the source.

   146    *

   147    * This Operation is not executed until source is completed normally. If

   148    * source completes exceptionally this Operation completes exceptionally with

   149    * an IllegealArgumentException with the source's exception as the cause.

   150    *

   151    * The Operation is completed exceptionally with ClassCastException if any of

   152    * the values of the source cannot be converted to the specified SQL type.

   153    *

   154    * If the length of the value of source is not the same as the length of all

   155    * other parameter sequences this Operation is completed exceptionally with

   156    * IllegalArgumentException.

   157    *

   158    * @param id the identifier of the parameter marker to be set

   159    * @param source supplies the values the parameter is to be set to

   160    * @return this {@link Operation}

   161    * @throws IllegalArgumentException if the same id was passed in a previous

   162    * call.

   163    * @throws IllegalStateException if the {@link Operation} has been submitted

   164    */

   165   public ArrayRowCountOperation<T> set(String id, CompletionStage<?> source);

   166 

   167   /**

   168    * Provides a {@link Collector} to reduce the sequence of Counts.The result of

   169    * the {@link Operation} is the result of calling finisher on the final

   170    * accumulated result. If the {@link Collector} is

   171    * {@link Collector.Characteristics#UNORDERED} counts may be accumulated out of

   172    * order. If the {@link Collector} is

   173    * {@link Collector.Characteristics#CONCURRENT} then the sequence of counts may be

   174    * split into subsequences that are reduced separately and then combined.

   175    *

   176    * @param <A> the type of the accumulator

   177    * @param <S> the type of the final result

   178    * @param c the Collector. Not null. 

   179    * @return This ArrayRowCountOperation

   180    * @throws IllegalStateException if this method had been called previously or

   181    * this Operation has been submitted.

   182   */

   183   public <A, S extends T> ArrayRowCountOperation<T> collect(Collector<? super Result.RowCount, A, S> c);

   184 

   185   @Override

   186   public ArrayRowCountOperation<T> onError(Consumer<Throwable> handler);

   187 

   188   @Override

   189   public ArrayRowCountOperation<T> timeout(Duration minTime);

   190 

   191 }