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 org.apache.felix.dm.lambda.callbacks.CbBundle; |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 22 | import org.apache.felix.dm.lambda.callbacks.CbBundleComponent; |
| 23 | import org.apache.felix.dm.lambda.callbacks.InstanceCbBundle; |
| 24 | import org.apache.felix.dm.lambda.callbacks.InstanceCbBundleComponent; |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 25 | |
| 26 | /** |
Pierre De Rop | 6e8f921 | 2016-02-20 21:44:59 +0000 | [diff] [blame^] | 27 | * Builds a Dependency Manager bundle adapter. <p> The adapter created by this builder will be applied to any bundle that matches the specified |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 28 | * bundle state mask and filter condition. For each matching bundle an adapter service will be created based on the adapter implementation class. |
| 29 | * The adapter will be registered with the specified interface and existing properties from the original bundle plus any extra properties |
| 30 | * you supply here. The bundle is injected by reflection in adapter class fields having a Bundle type, or using a callback method that you can |
| 31 | * specify. |
| 32 | * |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 33 | * You can specify reflection based (using method names), or java8 method references for callbacks. |
| 34 | * |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 35 | * <p> Example which creates a BundleAdapter service for each started bundle (the bundle is added by reflection on |
| 36 | * a class field that has a "Bundle" type): |
| 37 | * |
| 38 | * <pre> {@code |
| 39 | * public class Activator extends DependencyManagerActivator { |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 40 | * public void init(BundleContext ctx, DependencyManager dm) throws Exception { |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 41 | * bundleAdapter(adapt -> adapt |
| 42 | * .impl(BundleAdapterImpl.class) |
| 43 | * .provides(BundleAdapter.class) |
| 44 | * .mask(Bundle.INSTALLED | Bundle.RESOLVED | Bundle.ACTIVE)); |
| 45 | * } |
| 46 | * } |
| 47 | * } </pre> |
| 48 | * |
| 49 | * Example that creates a BundleAdapter service for each started bundle (the bundle is added using a method reference): |
| 50 | * |
| 51 | * <pre> {@code |
| 52 | * public class Activator extends DependencyManagerActivator { |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 53 | * public void init(BundleContext ctx, DependencyManager dm) throws Exception { |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 54 | * bundleAdapter(adapt -> adapt |
| 55 | * .impl(BundleAdapterImpl.class) |
| 56 | * .provides(BundleAdapter.class) |
| 57 | * .mask(Bundle.INSTALLED | Bundle.RESOLVED | Bundle.ACTIVE) |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 58 | * .add(BundleAdapterImpl::setBundle)); |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 59 | * } |
| 60 | * } |
| 61 | * }</pre> |
| 62 | * |
| 63 | * Example that creates a BundleAdapter service for each started bundle (the bundle is added using a method name): |
| 64 | * |
| 65 | * <pre> {@code |
| 66 | * public class Activator extends DependencyManagerActivator { |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 67 | * public void init(BundleContext ctx, DependencyManager dm) throws Exception { |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 68 | * bundleAdapter(adapt -> adapt |
| 69 | * .impl(BundleAdapterImpl.class) |
| 70 | * .provides(BundleAdapter.class) |
| 71 | * .mask(Bundle.INSTALLED | Bundle.RESOLVED | Bundle.ACTIVE) |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 72 | * .add("setBundle")); |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 73 | * } |
| 74 | * } |
| 75 | * }</pre> |
| 76 | * |
| 77 | * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a> |
| 78 | */ |
| 79 | public interface BundleAdapterBuilder extends ComponentBuilder<BundleAdapterBuilder> { |
| 80 | /** |
| 81 | * Sets the bundle state mask to depend on. The OSGi BundleTracker explains this mask in more detail, but |
| 82 | * it is basically a mask with flags for each potential state a bundle can be in. |
| 83 | * |
| 84 | * @param mask the mask to use |
| 85 | * @return this builder |
| 86 | */ |
| 87 | BundleAdapterBuilder mask(int mask); |
| 88 | |
| 89 | /** |
| 90 | * Sets the filter condition to depend on. Filters are matched against the full manifest of a bundle. |
| 91 | * |
| 92 | * @param filter the filter condition |
| 93 | * @return this builder |
| 94 | */ |
| 95 | BundleAdapterBuilder filter(String filter); |
| 96 | |
| 97 | /** |
| 98 | * Sets property propagation. If set to <code>true</code> any bundle manifest properties will be added |
| 99 | * to the service properties of the component that has this dependency (if it registers as a service). |
| 100 | * |
| 101 | * @param propagate <code>true</code> to propagate the bundle manifest properties |
| 102 | * @return this builder |
| 103 | */ |
| 104 | BundleAdapterBuilder propagate(boolean propagate); |
| 105 | |
| 106 | /** |
| 107 | * Enables property propagation. Any bundle manifest properties will be added |
| 108 | * to the service properties of the component that has this dependency (if it registers as a service). |
| 109 | * |
| 110 | * @return this builder |
| 111 | */ |
| 112 | BundleAdapterBuilder propagate(); |
| 113 | |
| 114 | /** |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 115 | * Sets a "add" callback name invoked on the component implementation instance(s). |
| 116 | * The callback can be used as hooks whenever the dependency is added. When you specify a callback, |
| 117 | * the auto configuration feature is automatically turned off, because we're assuming you don't need it in this case. |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 118 | * |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 119 | * @param callback the method to call when a bundle was added |
| 120 | * |
| 121 | * The following method signature are supported: |
| 122 | * <pre>{@code |
| 123 | * callback(Bundle b) |
| 124 | * callback(Component c, Bundle b) |
| 125 | * }</pre> |
| 126 | * |
| 127 | * @param callback the callback name |
| 128 | * @return this builder. |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 129 | */ |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 130 | BundleAdapterBuilder add(String callback); |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 131 | |
| 132 | /** |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 133 | * Sets a "change" callback name invoked on the component implementation instance(s). |
| 134 | * The callback can be used as hooks whenever the dependency is changed. When you specify a callback, |
| 135 | * the auto configuration feature is automatically turned off, because we're assuming you don't need it in this case. |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 136 | * |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 137 | * @param callback the method to call when a bundle was changed |
| 138 | * |
| 139 | * The following method signature are supported: |
| 140 | * <pre>{@code |
| 141 | * callback(Bundle b) |
| 142 | * callback(Component c, Bundle b) |
| 143 | * }</pre> |
| 144 | * |
| 145 | * @param callback the callback name |
| 146 | * @return this builder. |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 147 | */ |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 148 | BundleAdapterBuilder change(String callback); |
| 149 | |
| 150 | /** |
| 151 | * Sets a "remove" callback name invoked on the component implementation instance(s). |
| 152 | * The callback can be used as hooks whenever the dependency is removed. When you specify a callback, |
| 153 | * the auto configuration feature is automatically turned off, because we're assuming you don't need it in this case. |
| 154 | * |
| 155 | * @param callback the method to call when a bundle was removed |
| 156 | * |
| 157 | * The following method signature are supported: |
| 158 | * <pre>{@code |
| 159 | * callback(Bundle b) |
| 160 | * callback(Component c, Bundle b) |
| 161 | * }</pre> |
| 162 | * |
| 163 | * @param callback the callback name |
| 164 | * @return this builder. |
| 165 | */ |
| 166 | BundleAdapterBuilder remove(String callback); |
| 167 | |
| 168 | /** |
| 169 | * Sets a callback instance to use when invoking reflection based callbacks. |
| 170 | * |
| 171 | * @param callbackInstance the instance to call the reflection based callbacks on |
| 172 | * @return this builder. |
| 173 | * @see #add(String) |
| 174 | * @see #change(String) |
| 175 | * @see #remove(String) |
| 176 | */ |
| 177 | BundleAdapterBuilder callbackInstance(Object callbackInstance); |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 178 | |
| 179 | /** |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 180 | * Sets a reference to a callback method invoked on one of the component implementation classes. |
| 181 | * The method reference must point to a Component implementation class method, it is called when the bundle is added |
| 182 | * and takes as argument a Bundle. |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 183 | * |
Pierre De Rop | 6e8f921 | 2016-02-20 21:44:59 +0000 | [diff] [blame^] | 184 | * @param <T> the type of the component implementation class on which the callback is invoked. |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 185 | * @param add the method reference invoked when a bundle is added. |
| 186 | * @return this builder |
| 187 | */ |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 188 | <T> BundleAdapterBuilder add(CbBundle<T> add); |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 189 | |
| 190 | /** |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 191 | * Sets a reference to a callback method invoked on one of the component implementation classes. |
| 192 | * The method reference must point to a Component implementation class method, it is called when the bundle is changed |
| 193 | * and takes as argument a Bundle. |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 194 | * |
Pierre De Rop | 6e8f921 | 2016-02-20 21:44:59 +0000 | [diff] [blame^] | 195 | * @param <T> the type of the component implementation class on which the callback is invoked. |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 196 | * @param change the method reference invoked when a bundle has changed. |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 197 | * @return this builder |
| 198 | */ |
| 199 | <T> BundleAdapterBuilder change(CbBundle<T> change); |
| 200 | |
| 201 | /** |
| 202 | * Sets a reference to a callback method invoked on one of the component implementation classes. |
| 203 | * The method reference must point to a Component implementation class method, it is called when the bundle is removed |
| 204 | * and takes as argument a Bundle. |
| 205 | * |
Pierre De Rop | 6e8f921 | 2016-02-20 21:44:59 +0000 | [diff] [blame^] | 206 | * @param <T> the type of the component implementation class on which the callback is invoked. |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 207 | * @param remove the method reference invoked when a bundle is removed. |
| 208 | * @return this builder |
| 209 | */ |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 210 | <T> BundleAdapterBuilder remove(CbBundle<T> remove); |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 211 | |
| 212 | /** |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 213 | * Sets a reference to a callback method invoked on one of the component implementation classes. |
| 214 | * The method reference must point to a Component implementation class method, it is called when the bundle is added |
| 215 | * and takes as argument a Bundle and a Component. |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 216 | * |
Pierre De Rop | 6e8f921 | 2016-02-20 21:44:59 +0000 | [diff] [blame^] | 217 | * @param <T> the type of the component implementation class on which the callback is invoked. |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 218 | * @param add the method reference invoked when a bundle is added. |
| 219 | * @return this builder |
| 220 | */ |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 221 | <T> BundleAdapterBuilder add(CbBundleComponent<T> add); |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 222 | |
| 223 | /** |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 224 | * Sets a reference to a callback method invoked on one of the component implementation classes. |
| 225 | * The method reference must point to a Component implementation class method, it is called when the bundle is changed |
| 226 | * and takes as argument a Bundle and a Component. |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 227 | * |
Pierre De Rop | 6e8f921 | 2016-02-20 21:44:59 +0000 | [diff] [blame^] | 228 | * @param <T> the type of the component implementation class on which the callback is invoked. |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 229 | * @param change the method reference invoked when a bundle has changed. |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 230 | * @return this builder |
| 231 | */ |
| 232 | <T> BundleAdapterBuilder change(CbBundleComponent<T> change); |
| 233 | |
| 234 | /** |
| 235 | * Sets a reference to a callback method invoked on one of the component implementation classes. |
| 236 | * The method reference must point to a Component implementation class method, it is called when the bundle is removed |
| 237 | * and takes as argument a Bundle and a Component. |
| 238 | * |
Pierre De Rop | 6e8f921 | 2016-02-20 21:44:59 +0000 | [diff] [blame^] | 239 | * @param <T> the type of the component implementation class on which the callback is invoked. |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 240 | * @param remove the method reference invoked when a bundle is removed. |
| 241 | * @return this builder |
| 242 | */ |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 243 | <T> BundleAdapterBuilder remove(CbBundleComponent<T> remove); |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 244 | |
| 245 | /** |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 246 | * Sets a reference to a callback method invoked on a given Object instance. |
| 247 | * The method reference is invoked when the bundle is added and takes as argument a Bundle. |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 248 | * |
| 249 | * @param add the method reference invoked when a bundle is added. |
| 250 | * @return this builder |
| 251 | */ |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 252 | BundleAdapterBuilder add(InstanceCbBundle add); |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 253 | |
| 254 | /** |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 255 | * Sets a reference to a callback method invoked on a given Object instance. |
| 256 | * The method reference is invoked when the bundle has changed and takes as argument a Bundle. |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 257 | * |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 258 | * @param change the method reference invoked when a bundle has changed. |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 259 | * @return this builder |
| 260 | */ |
| 261 | BundleAdapterBuilder change(InstanceCbBundle change); |
| 262 | |
| 263 | /** |
| 264 | * Sets a reference to a callback method invoked on a given Object instance. |
| 265 | * The method reference is invoked when the bundle is removed and takes as argument a Bundle. |
| 266 | * |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 267 | * @param remove the method reference invoked when a bundle is removed. |
| 268 | * @return this builder |
| 269 | */ |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 270 | BundleAdapterBuilder remove(InstanceCbBundle remove); |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 271 | |
| 272 | /** |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 273 | * Sets a reference to a callback method invoked on a given Object instance. |
| 274 | * The method reference is invoked when the bundle is added and takes as argument a Bundle and a Component. |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 275 | * |
| 276 | * @param add the method reference invoked when a bundle is added. |
| 277 | * @return this builder |
| 278 | */ |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 279 | BundleAdapterBuilder add(InstanceCbBundleComponent add); |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 280 | |
| 281 | /** |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 282 | * Sets a reference to a callback method invoked on a given Object instance. |
| 283 | * The method reference is invoked when the bundle has changed and takes as argument a Bundle and a Component. |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 284 | * |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 285 | * @param change the method reference invoked when a bundle has changed. |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 286 | * @return this builder |
| 287 | */ |
| 288 | BundleAdapterBuilder change(InstanceCbBundleComponent change); |
| 289 | |
| 290 | /** |
| 291 | * Sets a reference to a callback method invoked on a given Object instance. |
| 292 | * The method reference is invoked when the bundle is removed and takes as argument a Bundle and a Component. |
| 293 | * |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 294 | * @param remove the method reference invoked when a bundle is removed. |
| 295 | * @return this builder |
| 296 | */ |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 297 | BundleAdapterBuilder remove(InstanceCbBundleComponent remove); |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 298 | } |