javascalautils.concurrent.Future Maven / Gradle / Ivy
/**
* Copyright 2015 Peter Nerg
*
* 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 javascalautils.concurrent;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;
import java.util.function.Consumer;
import java.util.function.Function;
import java.util.function.Predicate;
import javascalautils.Failure;
import javascalautils.None;
import javascalautils.Option;
import javascalautils.Some;
import javascalautils.Success;
import javascalautils.ThrowableFunction0;
import javascalautils.Try;
/**
* A Future that will hold the result of an asynchronous computation.
* The Future is paired with an instance of {@link Promise} which is also the way to get hold of a Future.
* One can see a Future as a holder for a value-to-be, not yet available but accessible sometime in the future.
* The preferred way to get hold of the value-to-be is to register a listener on any of the provided listener types since this allows for asynchronous
* non-blocking operations.
*
* - {@link #onComplete(Consumer)}
* - {@link #onSuccess(Consumer)}
* - {@link #onFailure(Consumer)}
*
* It is possible to register multiple listeners to several/same listener type.
* One can register a listener both before and after a Future has been completed.
* Should the Future already be completed when the listener is added it is fired immediately.
* The guarantee is that a listener is only fired once.
*
* All operations on this class are non-blocking, i.e. allowing for proper asynchronous/non-blocking programming patterns.
* With one exception, for situations where it is necessary to maintain synchronous/blocking behavior the method {@link #result(long, TimeUnit)} is provided.
*
* For real short and consistent programming one can use the {@link #apply(ThrowableFunction0)} method to provide a function that will be executed in the
* future.
* The result of the function will be reported to the Future returned by the method.
*
*
*
*
* Future<Integer> resultSuccess = Future.apply(() -> 9 / 3); // The Future will at some point contain: Success(3)
* Future<Integer> resultFailure = Future.apply(() -> 9 / 0); // The Future will at some point contain: Failure(ArithmeticException)
*
*
*
*
*
* @author Peter Nerg
* @since 1.2
* @param
* The type this Future will hold as result
*/
public interface Future {
/**
* Allows for easy creation of asynchronous computations that will be executed in the future.
* The method will use the {@link Executors#getDefault()} method to get hold of the default {@link Executor} to use for executing the provided job.
* Simple examples:
*
*
*
*
* Future<Integer> resultSuccess = Future.apply(() -> 9 / 3); // The Future will at some point contain: Success(3)
* Future<Integer> resultFailure = Future.apply(() -> 9 / 0); // The Future will at some point contain: Failure(ArithmeticException)
*
*
*
*
* @param
* The type for the Future
* @param function
* The function to render either the value T or raise an exception.
* @return The future that will hold the result provided by the function
* @since 1.3
*/
static Future apply(ThrowableFunction0 function) {
return Executors.getDefault().execute(promise -> {
try {
promise.success(function.apply());
} catch (Throwable t) {
promise.failure(t);
}
});
}
/**
* Check if this Future is completed, with a value or an exception.
*
* @return true if completed, false otherwise.
*/
boolean isCompleted();
/**
* The current (completed or not) value of the future.
* This is a non-blocking method, it will return the current state/value of the Future.
* There are three possible outcomes:
*
* - The future has not been completed -> {@link None} is returned
* - The execution of the Future was successful -> {@link Some} with a {@link Success} containing the value of the executed job
* - The execution failed and an exception was reported -> {@link Some} with a {@link Failure} containing the Throwable
*
*
* @return An {@link Option} with the result.
*/
Option> value();
/**
* Register a handler to be invoked if the Future gets completed with an exception.
* If the Future has already been completed the notification will happen in the current thread.
* Multiple handlers can be registered, without any guarantee of notification order.
* Each individual event handler will only be invoked once.
*
* @param failureHandler
* Consumer to invoke.
*/
void onFailure(Consumer failureHandler);
/**
* Register a handler to be invoked if the Future gets completed with a value.
* If the Future has already been completed the notification will happen in the current thread.
* Multiple handlers can be registered, without any guarantee of notification order.
* Each individual event handler will only be invoked once.
*
* @param successHandler
* Consumer to invoke.
*/
void onSuccess(Consumer successHandler);
/**
* Register a handler to be invoked if the Future gets completed with a value or a failure.
* If the Future has already been completed the notification will happen in the current thread.
* Multiple handlers can be registered, without any guarantee of notification order.
* Each individual event handler will only be invoked once.
*
* @param completeHandler
* Consumer to invoke.
*/
void onComplete(Consumer> completeHandler);
/**
* Asynchronously processes the value in the Future once it is available.
* Only successful Futures are reported to the consumer.
* This is pretty much the same as {@link #onSuccess(Consumer)} but is here for completion keeping a consistent look and feel.
*
* @param consumer
* The consumer to digest the result
*/
void forEach(Consumer consumer);
/**
* Creates a new {@link Future} that will hold the mapped successful value of this instance once it is completed.
* Unsuccessful Futures will not be mapped, they are kept unsuccessful as they are.
*
* @param
* The type for the value held by the mapped future
* @param function
* The function to apply
* @return The mapped Future
*/
Future map(Function function);
/**
* Creates a new {@link Future} that will hold the mapped successful value of this instance once it is completed.
* Unsuccessful Futures will not be mapped, they are kept unsuccessful as they are.
*
* @param
* The type for the value held by the mapped future
* @param function
* The function to apply
* @return The mapped Future
*/
Future flatMap(Function> function);
/**
* Creates a new {@link Future} that will filter the successful value of this instance once it is completed.
* The possible outcomes are:
*
* - This Future is successful -> predicate matches -> The filtered future is completed with the value.
* - This Future is successful -> predicate fails -> The filtered future is failed with NoSuchElementException.
* - This Future is failure -> The failure is passed on to the filtered Future.
*
*
* @param predicate
* The predicate to apply
* @return The filtered Future
*/
Future filter(Predicate predicate);
/**
* Creates a new {@link Future} that will hold the mapped successful value of this instance once it is completed.
* Successful futures are mapped with the onSuccess function and unsuccessful/failure futures are mapped with onFailure.
*
* @param
* The type for the value held by the mapped future
* @param onSuccess
* The function to apply on a 'successful' result
* @param onFailure
* The function to apply on a 'failure' result
* @return The mapped Future
* @since 1.3
*/
Future transform(Function onSuccess, Function onFailure);
/**
* Creates a new {@link Future} that in case this {@link Future} is a 'failure' will apply the function to recover the 'failure' to a 'success'.
* Should this {@link Future} be a 'success' the value is propagated as-is.
* E.g.
*
*
*
*
* Future<String> future = ...
* Future<String> recovered = future.recover(t -> t.getMessage());
*
*
*
*
* In case of 'future' being successful then that value is passed on to 'recovered', in case of failure then the recover function kicks in and returns the
* message from the throwable.
*
*
* @param recoverFunction
* The function to apply in case of a 'failure'
* @return The recover Future
* @since 1.3
*/
Future recover(Function recoverFunction);
/**
* Blocks and waits for this Future to complete.
* Returns the result of a successful Future or throws the exception in case of a failure.
* The methods blocks for at most the provided duration.
* If the Future is already completed the method returns immediately.
*
* @param duration
* The duration to block
* @param timeUnit
* The unit for the duration
* @return The result in case successful
* @throws Throwable
* The error reported in case of a failure
* @throws TimeoutException
* In case the waiting time is passed
*/
T result(long duration, TimeUnit timeUnit) throws Throwable, TimeoutException;
}