Pierre De Rop | 6e8f921 | 2016-02-20 21:44:59 +0000 | [diff] [blame^] | 1 | /* |
| 2 | * Licensed to the Apache Software Foundation (ASF) under one |
| 3 | * or more contributor license agreements. See the NOTICE file |
| 4 | * distributed with this work for additional information |
| 5 | * regarding copyright ownership. The ASF licenses this file |
| 6 | * to you under the Apache License, Version 2.0 (the |
| 7 | * "License"); you may not use this file except in compliance |
| 8 | * with the License. You may obtain a copy of the License at |
| 9 | * |
| 10 | * http://www.apache.org/licenses/LICENSE-2.0 |
| 11 | * |
| 12 | * Unless required by applicable law or agreed to in writing, |
| 13 | * software distributed under the License is distributed on an |
| 14 | * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| 15 | * KIND, either express or implied. See the License for the |
| 16 | * specific language governing permissions and limitations |
| 17 | * under the License. |
| 18 | */ |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 19 | package org.apache.felix.dm.lambda; |
| 20 | |
| 21 | import java.util.Dictionary; |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 22 | import java.util.function.Function; |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 23 | |
| 24 | import org.apache.felix.dm.BundleDependency; |
| 25 | import org.apache.felix.dm.lambda.callbacks.CbBundle; |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 26 | import org.apache.felix.dm.lambda.callbacks.CbBundleComponent; |
| 27 | import org.apache.felix.dm.lambda.callbacks.InstanceCbBundle; |
| 28 | import org.apache.felix.dm.lambda.callbacks.InstanceCbBundleComponent; |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 29 | import org.osgi.framework.Bundle; |
| 30 | |
| 31 | /** |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 32 | * Builds a Dependency Manager Bundle Dependency. |
Pierre De Rop | 6e8f921 | 2016-02-20 21:44:59 +0000 | [diff] [blame^] | 33 | * When a bundle dependency is not explicitly defined as "required" or "optional", then it is assumed to be required by default. |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 34 | * |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 35 | * <p> Example of a Pojo Component which tracks a started bundle having a given bundle symbolic name: |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 36 | * |
| 37 | * <pre> {@code |
| 38 | * public class Activator extends DependencyManagerActivator { |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 39 | * public void init(BundleContext ctx, DependencyManager dm) throws Exception { |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 40 | * String BSN = "org.apache.felix.dependencymanager"; |
| 41 | * component(comp -> comp |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 42 | * .impl(Pojo.class) |
| 43 | * .withBundle(b -> b.mask(Bundle.ACTIVE).filter("(Bundle-SymbolicName=" + BSN + ")").add(Pojo::add).remove(Pojo::remove))); |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 44 | * } |
| 45 | * } |
| 46 | * } </pre> |
| 47 | * |
| 48 | * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a> |
| 49 | */ |
| 50 | public interface BundleDependencyBuilder extends DependencyBuilder<BundleDependency> { |
| 51 | /** |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 52 | * Enables auto configuration for this dependency. This means the component implementation class fields will be |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 53 | * injected with this bundle dependency automatically. |
| 54 | * |
| 55 | * @param autoConfig <code>true</code> to enable auto configuration |
| 56 | * @return the bundle dependency builder |
| 57 | */ |
| 58 | public BundleDependencyBuilder autoConfig(boolean autoConfig); |
| 59 | |
| 60 | /** |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 61 | * Enables auto configuration for this dependency. This means the component implementation class fields will be |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 62 | * injected with this bundle dependency automatically. |
| 63 | * |
| 64 | * @return the bundle dependency builder |
| 65 | */ |
| 66 | public BundleDependencyBuilder autoConfig(); |
| 67 | |
| 68 | /** |
Pierre De Rop | 6e8f921 | 2016-02-20 21:44:59 +0000 | [diff] [blame^] | 69 | * Sets the dependency to be required. |
| 70 | * @param required <code>true</code> if this bundle dependency is required. |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 71 | * @return the bundle dependency builder |
| 72 | */ |
| 73 | public BundleDependencyBuilder required(boolean required); |
| 74 | |
| 75 | /** |
Pierre De Rop | 6e8f921 | 2016-02-20 21:44:59 +0000 | [diff] [blame^] | 76 | * Sets the dependency to be required. |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 77 | * |
| 78 | * @return the bundle dependency builder |
| 79 | */ |
| 80 | public BundleDependencyBuilder required(); |
| 81 | |
| 82 | /** |
| 83 | * Sets the bundle to depend on directly. |
| 84 | * |
| 85 | * @param bundle the bundle to depend on |
| 86 | * @return the bundle dependency builder |
| 87 | */ |
| 88 | public BundleDependencyBuilder bundle(Bundle bundle); |
| 89 | |
| 90 | /** |
| 91 | * Sets the filter condition to depend on. Filters are matched against the full manifest of a bundle. |
| 92 | * |
| 93 | * @param filter the filter condition |
| 94 | * @return the bundle dependency builder |
| 95 | */ |
| 96 | public BundleDependencyBuilder filter(String filter); |
| 97 | |
| 98 | /** |
| 99 | * Sets the bundle state mask to depend on. The OSGi BundleTracker explains this mask in more detail, but |
| 100 | * it is basically a mask with flags for each potential state a bundle can be in. |
| 101 | * |
| 102 | * @param mask the mask to use |
| 103 | * @return the bundle dependency builder |
| 104 | */ |
| 105 | public BundleDependencyBuilder mask(int mask); |
| 106 | |
| 107 | /** |
| 108 | * Sets property propagation. If set to <code>true</code> any bundle manifest properties will be added |
Pierre De Rop | 57ffa3f | 2016-02-19 12:54:30 +0000 | [diff] [blame] | 109 | * to the service properties of the component that declares this dependency (if it provides a service). |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 110 | * |
| 111 | * @param propagate <code>true</code> to propagate the bundle manifest properties |
| 112 | * @return the bundle dependency builder |
| 113 | */ |
| 114 | public BundleDependencyBuilder propagate(boolean propagate); |
| 115 | |
| 116 | /** |
| 117 | * Sets property propagation. any bundle manifest properties will be added |
| 118 | * to the service properties of the component that has this dependency (if it registers as a service). |
| 119 | * |
| 120 | * @return the bundle dependency builder |
| 121 | */ |
| 122 | public BundleDependencyBuilder propagate(); |
| 123 | |
| 124 | /** |
| 125 | * Sets an Object instance and a callback method used to propagate some properties to the provided service properties. |
| 126 | * The method will be invoked on the specified object instance and must have one of the following signatures: |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 127 | * |
| 128 | * <p><ul><li>Dictionary callback(Bundle bundle)</ul> |
| 129 | * |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 130 | * @param instance the Object instance which is used to retrieve propagated service properties |
| 131 | * @param method the method to invoke for retrieving the properties to be propagated to the service properties. |
| 132 | * @return this service dependency. builder |
| 133 | */ |
| 134 | public BundleDependencyBuilder propagate(Object instance, String method); |
| 135 | |
| 136 | /** |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 137 | * Sets a reference to a method on an Object instance used to propagate some bundle properties to the provided service properties. |
| 138 | * |
| 139 | * @param propagate a function which accepts a Bundle argument and which returns some properties that will be |
| 140 | * propagated to the provided component service properties. |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 141 | * @return this service dependency. builder |
| 142 | */ |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 143 | public BundleDependencyBuilder propagate(Function<Bundle, Dictionary<?, ?>> propagate); |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 144 | |
| 145 | /** |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 146 | * Sets a "add" <code>callback</code> method to invoke on the component implementation instance(s). |
| 147 | * The callback is invoked when the bundle is added, and the following signatures are supported: |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 148 | * |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 149 | * <p><ol> |
| 150 | * <li>method(Bundle)</li> |
| 151 | * <li>method(Component, Bundle)</li> |
| 152 | * </ol> |
| 153 | * |
| 154 | * @param callback the add callback |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 155 | * @return this builder |
| 156 | */ |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 157 | BundleDependencyBuilder add(String callback); |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 158 | |
| 159 | /** |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 160 | * Sets a "change" <code>callback</code> method to invoke on the component implementation instance(s). |
| 161 | * The callback is invoked when the bundle state has changed, and the following signatures are supported: |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 162 | * |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 163 | * <p><ol> |
| 164 | * <li>method(Bundle)</li> |
| 165 | * <li>method(Component, Bundle)</li> |
| 166 | * </ol> |
| 167 | * |
| 168 | * @param callback the change callback |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 169 | * @return this builder |
| 170 | */ |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 171 | BundleDependencyBuilder change(String callback); |
| 172 | |
| 173 | /** |
| 174 | * Sets a "remove" <code>callback</code> method to invoke on the component implementation instance(s). |
| 175 | * The callback is invoked when the bundle is removed, and the following signatures are supported: |
| 176 | * <p><ol> |
| 177 | * <li>method(Bundle)</li> |
| 178 | * <li>method(Component, Bundle)</li> |
| 179 | * </ol> |
| 180 | * |
| 181 | * @param callback the remove callback |
| 182 | * @return this builder |
| 183 | */ |
| 184 | BundleDependencyBuilder remove(String callback); |
| 185 | |
| 186 | /** |
| 187 | * Specifies a callback instance used to invoke the reflection based callbacks on it. |
Pierre De Rop | 57ffa3f | 2016-02-19 12:54:30 +0000 | [diff] [blame] | 188 | * @param callbackInstance the instance to invoke the reflection based callbacks on |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 189 | * @return this builder |
| 190 | * @see #add(String) |
| 191 | * @see #change(String) |
| 192 | * @see #remove(String) |
| 193 | */ |
| 194 | BundleDependencyBuilder callbackInstance(Object callbackInstance); |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 195 | |
| 196 | /** |
| 197 | * Sets a <code>callback</code> method reference which is invoked when a bundle is added. |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 198 | * The method reference must point to a Component implementation class method, and takes as argument a Bundle. |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 199 | * |
| 200 | * @param <T> the type of the component implementation class on which the callback is invoked on. |
| 201 | * @param add the method reference invoked when a bundle is added. |
| 202 | * @return this builder |
| 203 | */ |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 204 | <T> BundleDependencyBuilder add(CbBundle<T> add); |
| 205 | |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 206 | /** |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 207 | * Sets a <code>callback</code> method reference which is invoked when a bundle is changed. |
| 208 | * The method reference must point to a Component implementation class method, and takes as argument a Bundle. |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 209 | * |
| 210 | * @param <T> the type of the component implementation class on which the callback is invoked on. |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 211 | * @param change the method reference invoked when a bundle has changed. |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 212 | * @return this builder |
| 213 | */ |
| 214 | <T> BundleDependencyBuilder change(CbBundle<T> change); |
| 215 | |
| 216 | /** |
| 217 | * Sets a <code>callback</code> method reference which is invoked when a bundle is removed. |
| 218 | * The method reference must point to a Component implementation class method, and takes as argument a Bundle. |
| 219 | * |
| 220 | * @param <T> the type of the component implementation class on which the callback is invoked on. |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 221 | * @param remove the method reference invoked when a bundle is removed. |
| 222 | * @return this builder |
| 223 | */ |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 224 | <T> BundleDependencyBuilder remove(CbBundle<T> remove); |
| 225 | |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 226 | /** |
| 227 | * Sets a <code>callback</code> method reference which is invoked when a bundle is added. |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 228 | * The method reference must point to a Component implementation class method, and takes as argument a Bundle and a Component. |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 229 | * |
| 230 | * @param <T> the type of the component implementation class on which the callback is invoked on. |
| 231 | * @param add the method reference invoked when a bundle is added. |
| 232 | * @return this builder |
| 233 | */ |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 234 | <T> BundleDependencyBuilder add(CbBundleComponent<T> add); |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 235 | |
| 236 | /** |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 237 | * Sets a <code>callback</code> method reference which is invoked when a bundle is changed. |
| 238 | * The method reference must point to a Component implementation class method, and takes as argument a Bundle and a Component. |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 239 | * |
| 240 | * @param <T> the type of the component implementation class on which the callback is invoked on. |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 241 | * @param change the method reference invoked when a bundle has changed. |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 242 | * @return this builder |
| 243 | */ |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 244 | <T> BundleDependencyBuilder change(CbBundleComponent<T> change); |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 245 | |
| 246 | /** |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 247 | * Sets a <code>callback</code> method reference which is invoked when a bundle is removed. |
| 248 | * The method reference must point to a Component implementation class method, and takes as argument a Bundle and a Component. |
| 249 | * |
| 250 | * @param <T> the type of the component implementation class on which the callback is invoked on. |
| 251 | * @param remove the method reference invoked when a bundle is removed. |
| 252 | * @return this builder |
| 253 | */ |
| 254 | <T> BundleDependencyBuilder remove(CbBundleComponent<T> remove); |
| 255 | |
| 256 | /** |
| 257 | * Sets a method reference on an Object instance which is invoked when a bundle is added. |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 258 | * The method reference must point to an Object instance method, and takes as argument a Bundle parameter. |
| 259 | * |
| 260 | * @param add the method reference invoked when a bundle is added. |
| 261 | * @return this builder |
| 262 | */ |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 263 | BundleDependencyBuilder add(InstanceCbBundle add); |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 264 | |
| 265 | /** |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 266 | * Sets a method reference on an Object instance which is invoked when a bundle is changed. |
| 267 | * The method reference must point to an Object instance method, and takes as argument a Bundle parameter. |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 268 | * |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 269 | * @param change the method reference invoked when a bundle is changed. |
| 270 | * @return this builder |
| 271 | */ |
| 272 | BundleDependencyBuilder change(InstanceCbBundle change); |
| 273 | |
| 274 | /** |
| 275 | * Sets a method reference on an Object instance which is invoked when a bundle is removed. |
| 276 | * The method reference must point to an Object instance method, and takes as argument a Bundle parameter. |
| 277 | * |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 278 | * @param remove the method reference invoked when a bundle is removed. |
| 279 | * @return this builder |
| 280 | */ |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 281 | BundleDependencyBuilder remove(InstanceCbBundle remove); |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 282 | |
| 283 | /** |
| 284 | * Sets a <code>callback instance</code> method reference which is invoked when a bundle is added. |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 285 | * The method reference must point to an Object instance method, and takes as arguments a Bundle and a Component. |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 286 | * |
| 287 | * @param add the method reference invoked when a bundle is added. |
| 288 | * @return this builder |
| 289 | */ |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 290 | BundleDependencyBuilder add(InstanceCbBundleComponent add); |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 291 | |
| 292 | /** |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 293 | * Sets a <code>callback instance</code> method reference which is invoked when a bundle is changed. |
| 294 | * The method reference must point to an Object instance method, and takes as argument a Bundle and a Component. |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 295 | * |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 296 | * @param change the method reference invoked when a bundle is changed. |
| 297 | * @return this builder |
| 298 | */ |
| 299 | BundleDependencyBuilder change(InstanceCbBundleComponent change); |
| 300 | |
| 301 | /** |
| 302 | * Sets a <code>callback instance</code> method reference which is invoked when a bundle is removed. |
| 303 | * The method reference must point to an Object instance method, and takes as argument a Bundle and a Component. |
| 304 | * |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 305 | * @param remove the method reference invoked when a bundle is removed. |
| 306 | * @return this builder |
| 307 | */ |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 308 | BundleDependencyBuilder remove(InstanceCbBundleComponent remove); |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 309 | } |