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