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 package java.sql2;

    26 

    27 import java.time.Duration;

    28 import java.util.concurrent.CompletionStage;

    29 import java.util.concurrent.Flow;

    30 import java.util.function.Consumer;

    31 

    32 /**

    33  *

    34  * @param <T> the type of the result of the {@link Operation}

    35  */

    36 public interface RowProcessorOperation<T> extends ParameterizedOperation<T> {

    37 

    38   /** DRAFT

    39    * Accepts a Processor that subscribes to a stream of Rows and publishes

    40    * a stream of result values. The last result value published is the result

    41    * of the Operation. If no value is published the result of Operation is null.

    42    *

    43    * The result of this Operation is the last value passed to the onNext method

    44    * of the Subscriber passed to rowProcessor.subscribe. If onComplete

    45    * is called before any value is passed to onNext this Operation is completed

    46    * with null. If onError is called this Operation completes exceptionally

    47    * with the passed exception. If neither onComplete or onError is called

    48    * this Operation will complete exceptionally after the inactivity timeout

    49    * expires.

    50    * 

    51    * Calling Row.cancel is the same as calling Subscription.cancel on the Row

    52    * Subscription.

    53    *

    54    * @param rowToResult subscribes to a stream of Result.Rows and publishes a

    55    * stream of results of type T

    56    * @return this RowProcessorOperation

    57    */

    58   public RowProcessorOperation<T> rowProcessor(Flow.Processor<Result.Row, T> rowToResult);

    59   

    60   /** DRAFT

    61    * Sets the minimum time the Operation will wait for Processor activity before

    62    * terminating. If all of the following hold for some time exceeding minTime,

    63    * this Operation will be completed exceptionally with 

    64    * {@link java.util.concurrent.TimeoutException}.

    65    * <ul>

    66    * <li>no calls to the onNext, onComplete, or

    67    * onError methods of the Subscriber passed to rowToResult.subscribe</li>

    68    * <li>the demand for Rows is zero or all rows have been published</li>

    69    * </ul>

    70    * If the Operation can publish no more rows either because all rows have

    71    * been published or because the demand for rows is 0 and rowToResult

    72    * has neither published a result nor terminated the stream and this state has

    73    * continued for at least minTime, the Operation is completed exceptionally.

    74    * 

    75    * The default value is one minute.

    76    * 

    77    * Note: The minTime parameter value must be small to guarantee that the 

    78    * Connection does not hang for long periods. The default is large enough

    79    * that it most likely is insignificant for most apps, but small enough to

    80    * kick loose a hung Connection in semi-reasonable time.

    81    * 

    82    * @param minTime

    83    * @return this RowProcessorOperation

    84    */

    85   public RowProcessorOperation<T> inactivityTimeout(Duration minTime);

    86   

    87   // Covariant overrides

    88   

    89   @Override

    90   public RowProcessorOperation<T> onError(Consumer<Throwable> handler);

    91   

    92   @Override

    93   public RowProcessorOperation<T> set(String id, Object value, SqlType type);

    94 

    95   @Override

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

    97 

    98   @Override

    99   public RowProcessorOperation<T> set(String id, CompletionStage<?> source);

   100 

   101   @Override

   102   public RowProcessorOperation<T> set(String id, Object value);

   103 

   104   @Override

   105   public RowProcessorOperation<T> timeout(Duration minTime);

   106 

   107 }