Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 1 | package org.apache.felix.dm.lambda; |
| 2 | |
| 3 | import java.util.concurrent.Executor; |
| 4 | |
| 5 | import org.apache.felix.dm.Dependency; |
| 6 | import org.apache.felix.dm.lambda.callbacks.CbFuture; |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame^] | 7 | import org.apache.felix.dm.lambda.callbacks.InstanceCbFuture; |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 8 | |
| 9 | /** |
| 10 | * Defines a builder for a CompletableFuture dependency. |
| 11 | * Using such dependency allows your component to wait for the completion of a given asynchronous task |
| 12 | * represented by a standard jdk <code>CompletableFuture</code> object. |
| 13 | * |
| 14 | * A FutureDependency is required and unblock the Component once the CompletableFuture result has completed. |
| 15 | * |
| 16 | * <h3>Usage Example</h3> |
| 17 | * |
| 18 | * <p> Here is an Activator that downloads a page from the web and injects the string result to a component. |
| 19 | * When the web page is downloaded, the result is injected in the MyComponent::setPage method and |
| 20 | * the component is then called in its "start" method: |
| 21 | * |
| 22 | * <pre>{@code |
| 23 | * |
| 24 | * public class Activator extends DependencyManagerActivator { |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame^] | 25 | * public void init(BundleContext ctx, DependencyManager dm) throws Exception { |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 26 | * String url = "http://felix.apache.org/"; |
| 27 | * CompletableFuture<String> page = CompletableFuture.supplyAsync(() -> downloadSite(url)); |
| 28 | * |
| 29 | * // The component depends on a log service and on the content of the Felix site. |
| 30 | * // The lambda passed to the "withFuture" method configures the callback that is |
| 31 | * // invoked with the result of the CompletableFuture (the page content). |
| 32 | * component(comp -> comp |
| 33 | * .impl(MyComponent.class) |
| 34 | * .withService(LogService.class) |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame^] | 35 | * .withFuture(page, result -> result.complete(MyComponent::setPage))); |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 36 | * } |
| 37 | * } |
| 38 | * |
| 39 | * public class MyComponent { |
| 40 | * volatile LogService log; // injected. |
| 41 | * |
| 42 | * void setPage(String page) { |
| 43 | * // injected by the FutureDependency. |
| 44 | * } |
| 45 | * |
| 46 | * void start() { |
| 47 | * // all required dependencies injected. |
| 48 | * } |
| 49 | * } |
| 50 | * |
| 51 | * }</pre> |
| 52 | * |
| 53 | * @param <F> the type of the CompletableFuture result. |
| 54 | */ |
| 55 | public interface FutureDependencyBuilder<F> extends DependencyBuilder<Dependency> { |
| 56 | /** |
| 57 | * Sets the callback method name to invoke on the component instances, once the CompletableFuture has completed. |
| 58 | * @param callback the callback method name to invoke on the component instances, once the CompletableFuture on which we depend has completed. |
| 59 | * @return this dependency. |
| 60 | */ |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame^] | 61 | FutureDependencyBuilder<F> complete(String callback); |
| 62 | |
| 63 | /** |
| 64 | * Sets the callback instance method name to invoke on a given Object instance, once the CompletableFuture has completed. |
| 65 | * @param callbackInstance the object instance on which the callback must be invoked |
| 66 | * @param callback the callback method name to invoke on Object instance, once the CompletableFuture has completed. |
| 67 | * @return this dependency. |
| 68 | */ |
| 69 | FutureDependencyBuilder<F> complete(Object callbackInstance, String callback); |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 70 | |
| 71 | /** |
| 72 | * Sets the function to invoke when the future task has completed. The function is from one of the Component implementation classes, and it accepts the |
| 73 | * result of the completed future. |
| 74 | * |
| 75 | * @param <T> the type of the CompletableFuture result. |
| 76 | * @param callback the function to perform when the future task as completed. |
| 77 | * @return this dependency |
| 78 | */ |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame^] | 79 | <T> FutureDependencyBuilder<F> complete(CbFuture<T, ? super F> callback); |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 80 | |
| 81 | /** |
| 82 | * Sets the function to invoke asynchronously when the future task has completed. The function is from one of the Component implementation classes, |
| 83 | * and it accepts the result of the completed future. |
| 84 | * |
| 85 | * @param <T> the type of the CompletableFuture result. |
| 86 | * @param callback the function to perform when the future task as completed. |
| 87 | * @param async true if the callback should be invoked asynchronously using the default jdk execution facility, false if not. |
| 88 | * @return this dependency |
| 89 | */ |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame^] | 90 | <T> FutureDependencyBuilder<F> complete(CbFuture<T, ? super F> callback, boolean async); |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 91 | |
| 92 | /** |
| 93 | * Sets the function to invoke asynchronously when the future task has completed. The function is from one of the Component implementation classes, |
| 94 | * and it accepts the result of the completed future. |
| 95 | * |
| 96 | * @param <T> the type of the CompletableFuture result. |
| 97 | * @param callback the function to perform when the future task as completed. |
| 98 | * @param executor the executor used to schedule the callback. |
| 99 | * @return this dependency |
| 100 | */ |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame^] | 101 | <T> FutureDependencyBuilder<F> complete(CbFuture<T, ? super F> callback, Executor executor); |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 102 | |
| 103 | /** |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 104 | * Sets the callback instance to invoke when the future task has completed. The callback is a Consumer instance which accepts the |
| 105 | * result of the completed future. |
| 106 | * @param callback a Consumer instance which accepts the result of the completed future. |
| 107 | * @return this dependency |
| 108 | */ |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame^] | 109 | FutureDependencyBuilder<F> complete(InstanceCbFuture<? super F> callback); |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 110 | |
| 111 | /** |
| 112 | * Sets the callback instance to invoke when the future task has completed. The callback is a Consumer instance which accepts the |
| 113 | * result of the completed future. |
| 114 | * |
| 115 | * @param callback a Consumer instance which accepts the result of the completed future. |
| 116 | * @param async true if the callback should be invoked asynchronously using the default jdk execution facility, false if not. |
| 117 | * @return this dependency |
| 118 | */ |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame^] | 119 | FutureDependencyBuilder<F> complete(InstanceCbFuture<? super F> callback, boolean async); |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 120 | |
| 121 | /** |
| 122 | * Sets the callback instance to invoke when the future task has completed. The callback is a Consumer instance which accepts the |
| 123 | * result of the completed future. |
| 124 | * @param callback the action to perform when the future task as completed. |
| 125 | * @param executor the executor to use for asynchronous execution of the callback. |
| 126 | * @return this dependency |
| 127 | */ |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame^] | 128 | FutureDependencyBuilder<F> complete(InstanceCbFuture<? super F> callback, Executor executor); |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 129 | } |