ratpack.exec.util.Batch Maven / Gradle / Ivy
/*
* Copyright 2016 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package ratpack.exec.util;
import org.reactivestreams.Publisher;
import ratpack.exec.ExecResult;
import ratpack.exec.Operation;
import ratpack.exec.Promise;
import ratpack.func.BiAction;
import ratpack.stream.Streams;
import ratpack.stream.TransformablePublisher;
import java.util.List;
/**
* A batch of promises to be processed.
*
* See {@link SerialBatch} and {@link ParallelBatch}.
*
*
{@code
* import ratpack.exec.Promise;
* import ratpack.exec.util.Batch;
* import ratpack.exec.util.ParallelBatch;
* import ratpack.test.exec.ExecHarness;
*
* import java.util.ArrayList;
* import java.util.List;
*
* import static org.junit.Assert.assertEquals;
*
* public class Example {
* public static void main(String[] args) throws Exception {
* int sum = ExecHarness.yieldSingle(e -> {
*
* List> promises = new ArrayList<>();
* for (int i = 0; i < 100; i++) {
* promises.add(Promise.value(i));
* }
*
* return ParallelBatch.of(promises)
* .publisher()
* .reduce(0, (r, i) -> r + i);
*
* }).getValueOrThrow();
*
* assertEquals(sum, 4950);
* }
* }
* }
*
* @param the type of value produced by each promise in the batch
* @since 1.4
*/
public interface Batch {
/**
* Processes all the promises of the batch, collecting any errors.
*
* This method differs from {@link #yield()} in that every promise will be processed, regardless of any failure.
* As such, it returns {@link ExecResult} objects representing the outcome as it may be an error.
*
* The promise returned from this method will not fail, as failure is conveyed via the result objects of the list.
*
* The order of the entries in the promised list corresponds to the order of the promises originally.
* That is, it is guaranteed that the 2nd item in the list was the 2nd promise specified.
*
* @return a promise for the result of each promise
*/
Promise>> yieldAll();
/**
* Processes all the promises of the batch, stopping at the first error.
*
* This method differs from {@link #yieldAll()} in that processing will be halted as soon as the first error occurs.
* The error will be propagated through the returned promise.
*
* The order of the entries in the promised list corresponds to the order of the promises originally.
* That is, it is guaranteed that the 2nd item in the list was the 2nd promise specified.
* It does not reflect the order in which promises completed.
*
* @return a promise for each promised value
*/
Promise> yield();
/**
* Processes the promises of the batch, stopping at the first error, emitting results to the given callback.
*
* This method is useful for aggregating or reducing the batch.
*
* The returned operation will complete after all items have been consumed or if there is an error.
*
* The integer value given the to consumer indicates the source position of the corresponding promise.
*
* @param consumer the consumer of promise values
* @return an operation for the consumption of the values
*/
Operation forEach(BiAction consumer);
/**
* Creates a publisher that emits the promised values.
*
* This method differs to {@link #yield()} and {@link #yieldAll()} in that items are emitted as soon as they have completed.
* As such, it is more appropriate when wanting to stream the results in some fashion.
*
* Items are emitted in completion order, not source order.
*
* Processing is effectively halted when the first error occurs.
*
* The returned publisher is NOT {@link Streams#bindExec(Publisher) execution bound}.
*
* @return a publisher for the batch
*/
TransformablePublisher publisher();
}