FELIX-4401 Update ServiceComponentRuntime to spec, enable/disable are async returhing Promise
git-svn-id: https://svn.apache.org/repos/asf/felix/trunk@1604452 13f79535-47bb-0310-9956-ffa450edef68
diff --git a/scr/src/main/java/org/osgi/util/promise/Promise.java b/scr/src/main/java/org/osgi/util/promise/Promise.java
new file mode 100644
index 0000000..74e4b59
--- /dev/null
+++ b/scr/src/main/java/org/osgi/util/promise/Promise.java
@@ -0,0 +1,403 @@
+/*
+ * Copyright (c) OSGi Alliance (2014). All Rights Reserved.
+ *
+ * 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 org.osgi.util.promise;
+
+import java.lang.reflect.InvocationTargetException;
+import org.osgi.annotation.versioning.ProviderType;
+import org.osgi.util.function.Function;
+import org.osgi.util.function.Predicate;
+
+/**
+ * A Promise of a value.
+ *
+ * <p>
+ * A Promise represents a future value. It handles the interactions for
+ * asynchronous processing. A {@link Deferred} object can be used to create a
+ * Promise and later resolve the Promise. A Promise is used by the caller of an
+ * asynchronous function to get the result or handle the error. The caller can
+ * either get a callback when the Promise is resolved with a value or an error,
+ * or the Promise can be used in chaining. In chaining, callbacks are provided
+ * that receive the resolved Promise, and a new Promise is generated that
+ * resolves based upon the result of a callback.
+ *
+ * <p>
+ * Both {@link #onResolve(Runnable) callbacks} and
+ * {@link #then(Success, Failure) chaining} can be repeated any number of times,
+ * even after the Promise has been resolved.
+ * <p>
+ * Example callback usage:
+ *
+ * <pre>
+ * final Promise<String> foo = foo();
+ * foo.onResolve(new Runnable() {
+ * public void run() {
+ * System.out.println(foo.getValue());
+ * }
+ * });
+ * </pre>
+ *
+ * Example chaining usage;
+ *
+ * <pre>
+ * Success<String,String> doubler = new Success<String,String>() {
+ * public Promise<String> call(Promise<String> p) throws Exception {
+ * return Promises.resolved(p.getValue()+p.getValue());
+ * }
+ * };
+ * final Promise<String> foo = foo().then(doubler).then(doubler);
+ * foo.onResolve(new Runnable() {
+ * public void run() {
+ * System.out.println(foo.getValue());
+ * }
+ * });
+ * </pre>
+ *
+ * @param <T> The value type associated with this Promise.
+ *
+ * @ThreadSafe
+ * @author $Id: 8a24f66339967ecdd03def57f31ac8c371a7f4cd $
+ */
+@ProviderType
+public interface Promise<T> {
+
+ /**
+ * Returns whether this Promise has been resolved.
+ *
+ * <p>
+ * This Promise may be successfully resolved or resolved with a failure.
+ *
+ * @return {@code true} if this Promise was resolved either successfully or
+ * with a failure; {@code false} if this Promise is unresolved.
+ */
+ boolean isDone();
+
+ /**
+ * Returns the value of this Promise.
+ *
+ * <p>
+ * If this Promise is not {@link #isDone() resolved}, this method must block
+ * and wait for this Promise to be resolved before completing.
+ *
+ * <p>
+ * If this Promise was successfully resolved, this method returns with the
+ * value of this Promise. If this Promise was resolved with a failure, this
+ * method must throw an {@code InvocationTargetException} with the
+ * {@link #getFailure() failure exception} as the cause.
+ *
+ * @return The value of this resolved Promise.
+ * @throws InvocationTargetException If this Promise was resolved with a
+ * failure. The cause of the {@code InvocationTargetException} is
+ * the failure exception.
+ * @throws InterruptedException If the current thread was interrupted while
+ * waiting.
+ */
+ T getValue() throws InvocationTargetException, InterruptedException;
+
+ /**
+ * Returns the failure of this Promise.
+ *
+ * <p>
+ * If this Promise is not {@link #isDone() resolved}, this method must block
+ * and wait for this Promise to be resolved before completing.
+ *
+ * <p>
+ * If this Promise was resolved with a failure, this method returns with the
+ * failure of this Promise. If this Promise was successfully resolved, this
+ * method must return {@code null}.
+ *
+ * @return The failure of this resolved Promise or {@code null} if this
+ * Promise was successfully resolved.
+ * @throws InterruptedException If the current thread was interrupted while
+ * waiting.
+ */
+ Throwable getFailure() throws InterruptedException;
+
+ /**
+ * Register a callback to be called when this Promise is resolved.
+ *
+ * <p>
+ * The specified callback is called when this Promise is resolved either
+ * successfully or with a failure.
+ *
+ * <p>
+ * This method may be called at any time including before and after this
+ * Promise has been resolved.
+ *
+ * <p>
+ * Resolving this Promise <i>happens-before</i> any registered callback is
+ * called. That is, in a registered callback, {@link #isDone()} must return
+ * {@code true} and {@link #getValue()} and {@link #getFailure()} must not
+ * block.
+ *
+ * <p>
+ * A callback may be called on a different thread than the thread which
+ * registered the callback. So the callback must be thread safe but can rely
+ * upon that the registration of the callback <i>happens-before</i> the
+ * registered callback is called.
+ *
+ * @param callback A callback to be called when this Promise is resolved.
+ * Must not be {@code null}.
+ * @return This Promise.
+ */
+ Promise<T> onResolve(Runnable callback);
+
+ /**
+ * Chain a new Promise to this Promise with Success and Failure callbacks.
+ *
+ * <p>
+ * The specified {@link Success} callback is called when this Promise is
+ * successfully resolved and the specified {@link Failure} callback is
+ * called when this Promise is resolved with a failure.
+ *
+ * <p>
+ * This method returns a new Promise which is chained to this Promise. The
+ * returned Promise must be resolved when this Promise is resolved after the
+ * specified Success or Failure callback is executed. The result of the
+ * executed callback must be used to resolve the returned Promise. Multiple
+ * calls to this method can be used to create a chain of promises which are
+ * resolved in sequence.
+ *
+ * <p>
+ * If this Promise is successfully resolved, the Success callback is
+ * executed and the result Promise, if any, or thrown exception is used to
+ * resolve the returned Promise from this method. If this Promise is
+ * resolved with a failure, the Failure callback is executed and the
+ * returned Promise from this method is failed.
+ *
+ * <p>
+ * This method may be called at any time including before and after this
+ * Promise has been resolved.
+ *
+ * <p>
+ * Resolving this Promise <i>happens-before</i> any registered callback is
+ * called. That is, in a registered callback, {@link #isDone()} must return
+ * {@code true} and {@link #getValue()} and {@link #getFailure()} must not
+ * block.
+ *
+ * <p>
+ * A callback may be called on a different thread than the thread which
+ * registered the callback. So the callback must be thread safe but can rely
+ * upon that the registration of the callback <i>happens-before</i> the
+ * registered callback is called.
+ *
+ * @param <R> The value type associated with the returned Promise.
+ * @param success A Success callback to be called when this Promise is
+ * successfully resolved. May be {@code null} if no Success callback
+ * is required. In this case, the returned Promise must be resolved
+ * with the value {@code null} when this Promise is successfully
+ * resolved.
+ * @param failure A Failure callback to be called when this Promise is
+ * resolved with a failure. May be {@code null} if no Failure
+ * callback is required.
+ * @return A new Promise which is chained to this Promise. The returned
+ * Promise must be resolved when this Promise is resolved after the
+ * specified Success or Failure callback, if any, is executed.
+ */
+ <R> Promise<R> then(Success<? super T, ? extends R> success, Failure failure);
+
+ /**
+ * Chain a new Promise to this Promise with a Success callback.
+ *
+ * <p>
+ * This method performs the same function as calling
+ * {@link #then(Success, Failure)} with the specified Success callback and
+ * {@code null} for the Failure callback.
+ *
+ * @param <R> The value type associated with the returned Promise.
+ * @param success A Success callback to be called when this Promise is
+ * successfully resolved. May be {@code null} if no Success callback
+ * is required. In this case, the returned Promise must be resolved
+ * with the value {@code null} when this Promise is successfully
+ * resolved.
+ * @return A new Promise which is chained to this Promise. The returned
+ * Promise must be resolved when this Promise is resolved after the
+ * specified Success, if any, is executed.
+ * @see #then(Success, Failure)
+ */
+ <R> Promise<R> then(Success<? super T, ? extends R> success);
+
+ /**
+ * Filter the value of this Promise.
+ *
+ * <p>
+ * If this Promise is successfully resolved, the returned Promise will
+ * either be resolved with the value of this Promise if the specified
+ * Predicate accepts that value or failed with a
+ * {@code NoSuchElementException} if the specified Predicate does not accept
+ * that value. If the specified Predicate throws an exception, the returned
+ * Promise will be failed with the exception.
+ *
+ * <p>
+ * If this Promise is resolved with a failure, the returned Promise will be
+ * failed with that failure.
+ *
+ * <p>
+ * This method may be called at any time including before and after this
+ * Promise has been resolved.
+ *
+ * @param predicate The Predicate to evaluate the value of this Promise.
+ * Must not be {@code null}.
+ * @return A Promise that filters the value of this Promise.
+ */
+ Promise<T> filter(Predicate<? super T> predicate);
+
+ /**
+ * Map the value of this Promise.
+ *
+ * <p>
+ * If this Promise is successfully resolved, the returned Promise will be
+ * resolved with the value of specified Function as applied to the value of
+ * this Promise. If the specified Function throws an exception, the returned
+ * Promise will be failed with the exception.
+ *
+ * <p>
+ * If this Promise is resolved with a failure, the returned Promise will be
+ * failed with that failure.
+ *
+ * <p>
+ * This method may be called at any time including before and after this
+ * Promise has been resolved.
+ *
+ * @param <R> The value type associated with the returned Promise.
+ * @param mapper The Function that will map the value of this Promise to the
+ * value that will be used to resolve the returned Promise. Must not
+ * be {@code null}.
+ * @return A Promise that returns the value of this Promise as mapped by the
+ * specified Function.
+ */
+ <R> Promise<R> map(Function<? super T, ? extends R> mapper);
+
+ /**
+ * FlatMap the value of this Promise.
+ *
+ * <p>
+ * If this Promise is successfully resolved, the returned Promise will be
+ * resolved with the Promise from the specified Function as applied to the
+ * value of this Promise. If the specified Function throws an exception, the
+ * returned Promise will be failed with the exception.
+ *
+ * <p>
+ * If this Promise is resolved with a failure, the returned Promise will be
+ * failed with that failure.
+ *
+ * <p>
+ * This method may be called at any time including before and after this
+ * Promise has been resolved.
+ *
+ * @param <R> The value type associated with the returned Promise.
+ * @param mapper The Function that will flatMap the value of this Promise to
+ * a Promise that will be used to resolve the returned Promise. Must
+ * not be {@code null}.
+ * @return A Promise that returns the value of this Promise as mapped by the
+ * specified Function.
+ */
+ <R> Promise<R> flatMap(Function<? super T, Promise<? extends R>> mapper);
+
+ /**
+ * Recover from a failure of this Promise with a recovery value.
+ *
+ * <p>
+ * If this Promise is successfully resolved, the returned Promise will be
+ * resolved with the value of this Promise.
+ *
+ * <p>
+ * If this Promise is resolved with a failure, the specified Function is
+ * applied to this Promise to produce a recovery value.
+ * <ul>
+ * <li>If the recovery value is not {@code null}, the returned Promise will
+ * be resolved with the recovery value.</li>
+ * <li>If the recovery value is {@code null}, the returned Promise will be
+ * failed with the failure of this Promise.</li>
+ * <li>If the specified Function throws an exception, the returned Promise
+ * will be failed with that exception.</li>
+ * </ul>
+ *
+ * <p>
+ * To recover from a failure of this Promise with a recovery value of
+ * {@code null}, the {@link #recoverWith(Function)} method must be used. The
+ * specified Function for {@link #recoverWith(Function)} can return
+ * {@code Promises.resolved(null)} to supply the desired {@code null} value.
+ *
+ * <p>
+ * This method may be called at any time including before and after this
+ * Promise has been resolved.
+ *
+ * @param recovery If this Promise resolves with a failure, the specified
+ * Function is called to produce a recovery value to be used to
+ * resolve the returned Promise. Must not be {@code null}.
+ * @return A Promise that resolves with the value of this Promise or
+ * recovers from the failure of this Promise.
+ */
+ Promise<T> recover(Function<Promise<?>, ? extends T> recovery);
+
+ /**
+ * Recover from a failure of this Promise with a recovery Promise.
+ *
+ * <p>
+ * If this Promise is successfully resolved, the returned Promise will be
+ * resolved with the value of this Promise.
+ *
+ * <p>
+ * If this Promise is resolved with a failure, the specified Function is
+ * applied to this Promise to produce a recovery Promise.
+ * <ul>
+ * <li>If the recovery Promise is not {@code null}, the returned Promise
+ * will be resolved with the recovery Promise.</li>
+ * <li>If the recovery Promise is {@code null}, the returned Promise will be
+ * failed with the failure of this Promise.</li>
+ * <li>If the specified Function throws an exception, the returned Promise
+ * will be failed with that exception.</li>
+ * </ul>
+ *
+ * <p>
+ * This method may be called at any time including before and after this
+ * Promise has been resolved.
+ *
+ * @param recovery If this Promise resolves with a failure, the specified
+ * Function is called to produce a recovery Promise to be used to
+ * resolve the returned Promise. Must not be {@code null}.
+ * @return A Promise that resolves with the value of this Promise or
+ * recovers from the failure of this Promise.
+ */
+ Promise<T> recoverWith(Function<Promise<?>, Promise<? extends T>> recovery);
+
+ /**
+ * Fall back to the value of the specified Promise if this Promise fails.
+ *
+ * <p>
+ * If this Promise is successfully resolved, the returned Promise will be
+ * resolved with the value of this Promise.
+ *
+ * <p>
+ * If this Promise is resolved with a failure, the successful result of the
+ * specified Promise is used to resolve the returned Promise. If the
+ * specified Promise is resolved with a failure, the returned Promise will
+ * be failed with the failure of this Promise rather than the failure of the
+ * specified Promise.
+ *
+ * <p>
+ * This method may be called at any time including before and after this
+ * Promise has been resolved.
+ *
+ * @param fallback The Promise whose value will be used to resolve the
+ * returned Promise if this Promise resolves with a failure. Must not
+ * be {@code null}.
+ * @return A Promise that returns the value of this Promise or falls back to
+ * the value of the specified Promise.
+ */
+ Promise<T> fallbackTo(Promise<? extends T> fallback);
+}