javascalautils.concurrent.Promise 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 javascalautils.Failure;
import javascalautils.Success;
import javascalautils.Try;
/**
* The Promise is the promise to deliver a value at some time in the future.
* This is the handle the actual computation side of of the job uses.
* Once a job is finished it will report the outcome to the Promise which in turn relays it to the Future the client/application is monitoring.
* A promise can be fulfilled either by invoking success or failure but not both.
* Nor can {@link #success(Object) success}/{@link #failure(Throwable) failure} be invoked twice.
* The principle is that a {@link Promise} will deliver exactly one successful or failure response.
* The successful response is of any type whilst the failure is expected to be of type (or subclass of) {@link Throwable}.
*
* Together with a {@link Future} this allows a safe publication of asynchronously calculated results into another thread.
* The basic principle is to first create a {@link Promise}.
* Promise<String> promise = Promise.apply();
Using that instance one can get hold of the {@link Future} that is the container
* for the value-to-be.
* Future<String> future = promise.future();
To complete the Promise and by extension completing the Future one can use any of
* several methods:
*
* - {@link #success(Object)}
* - {@link #failure(Throwable)}
* - {@link #complete(Try)}
* - {@link #completeWith(Future)}
*
* E.g. promise.success("Peter was here");
Note that only one of the methods may be invoked as the Promise can only be fulfilled
* once.
* The above methods come with a variant tryNNN which allows for multiple invocations without raising an exception.
* Though still only the first invocation/completion counts.
*
* @author Peter Nerg
* @since 1.2
* @param
* The type this Promise will produce as result
*/
public interface Promise {
/**
* Creates an instance of Promise.
* E.g. Promise<String> p = Promise.apply();
*
* @param
* The type this Promise will produce as result
* @return The Promise instance
* @since 1.2
*/
static Promise apply() {
return new PromiseImpl<>();
}
/**
* Get a {@link Future} that will hold the value once this Promise is completed.
* Each {@link Promise} is connected to a single {@link Future}, invoking this method multiple times will always return the same {@link Future} instance.
*
* @return A Future that will hold the value once this Promise is completed.
* @since 1.2
*/
Future future();
/**
* Check if the {@link Promise} have been completed, with a value or an exception.
*
* @return true if the {@link Promise} has been completed. false otherwise.
* @since 1.2
*/
boolean isCompleted();
/**
* Completes the {@link Promise} with either a {@link Success} or a {@link Failure}.
*
* @param result
* The result to complete with.
* @throws IllegalStateException
* Thrown if the Promise is already completed.
* @since 1.3
*/
void complete(Try result);
/**
* Completes the {@link Promise} with the value from the provided {@link Future} once that is completed.
*
* @param future
* The future whose value will complete this Promise
* @throws IllegalStateException
* Thrown if the Promise is already completed.
* @since 1.3
*/
void completeWith(Future future);
/**
* Completes the {@link Promise} with a value.
*
* @param result
* The value to complete with.
* @throws IllegalStateException
* Thrown if the Promise is already completed.
* @since 1.2
*/
void success(T result);
/**
* Completes the {@link Promise} with an exception.
*
* @param throwable
* The Throwable to complete with.
* @throws IllegalStateException
* Thrown if the Promise is already completed.
* @since 1.2
*/
void failure(Throwable throwable);
/**
* Tries to complete the {@link Promise} with either a {@link Success} or a {@link Failure}.
* Contrary to the {@link #complete(Try)} method this does not throw an exception in case the Promise is already completed.
*
* @param result
* The result to complete with.
* @return true if the Promise was not completed before, false otherwise
* @since 1.3
*/
boolean tryComplete(Try result);
/**
* Tries to complete this {@link Promise} with the value from the provided {@link Future} once that is completed.
* Contrary to the {@link #complete(Try)} method this does not throw an exception in case the Promise is already completed.
*
* @param future
* The future whose value will complete this Promise
* @return true if the Promise was not completed before, false otherwise
* @since 1.3
*/
boolean tryCompleteWith(Future future);
/**
* Tries to complete the {@link Promise} with a value.
* Contrary to the {@link #success(Object)} method this does not throw an exception in case the Promise is already completed.
*
* @param result
* The value to complete with.
* @return true if the Promise was not completed before, false otherwise
* @since 1.3
*/
boolean trySuccess(T result);
/**
* Tries to complete the {@link Promise} with an exception.
* Contrary to the {@link #failure(Throwable)} method this does not throw an exception in case the Promise is already completed.
*
* @param throwable
* The Throwable to complete with.
* @return true if the Promise was not completed before, false otherwise
* @since 1.3
*/
boolean tryFailure(Throwable throwable);
}