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 | |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 21 | import org.apache.felix.dm.lambda.callbacks.CbConfiguration; |
| 22 | import org.apache.felix.dm.lambda.callbacks.CbConfigurationComponent; |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 23 | import org.apache.felix.dm.lambda.callbacks.CbDictionary; |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 24 | import org.apache.felix.dm.lambda.callbacks.CbDictionaryComponent; |
| 25 | import org.apache.felix.dm.lambda.callbacks.InstanceCbConfiguration; |
| 26 | import org.apache.felix.dm.lambda.callbacks.InstanceCbConfigurationComponent; |
| 27 | import org.apache.felix.dm.lambda.callbacks.InstanceCbDictionary; |
| 28 | import org.apache.felix.dm.lambda.callbacks.InstanceCbDictionaryComponent; |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 29 | |
| 30 | /** |
Pierre De Rop | 6e8f921 | 2016-02-20 21:44:59 +0000 | [diff] [blame^] | 31 | * Builds a Dependency Manager Factory Configuration Adapter Component. <p> For each new Config Admin factory configuration matching a given factory pid, |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 32 | * an adapter will be created based on the adapter implementation class. The adapter will be registered with the specified interface, |
| 33 | * and with the specified adapter service properties. Depending on the propagate parameter, every public factory configuration properties |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 34 | * (which don't start with ".") will be propagated along with the adapter service properties. |
| 35 | * |
| 36 | * This builded supports type safe configuration types. For a given factory configuration, you can specify an interface of your choice, |
| 37 | * and DM will implement it using a dynamic proxy that converts interface methods to lookups in the actual factory configuration dictionary. |
Pierre De Rop | 57ffa3f | 2016-02-19 12:54:30 +0000 | [diff] [blame] | 38 | * For more information about configuration types, please refer to {@link ConfigurationDependencyBuilder}. |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 39 | * |
Pierre De Rop | 57ffa3f | 2016-02-19 12:54:30 +0000 | [diff] [blame] | 40 | * <p> Example that defines a factory configuration adapter service for the "foo.bar" factory pid. For each factory pid instance, |
| 41 | * an instance of the DictionaryImpl component will be created. |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 42 | * |
| 43 | * <pre> {@code |
| 44 | * public class Activator extends DependencyManagerActivator { |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 45 | * public void init(BundleContext ctx, DependencyManager dm) throws Exception { |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 46 | * factoryPidAdapter(adapter -> adapter |
| 47 | * .impl(DictionaryImpl.class) |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 48 | * .factoryPid("foo.bar") |
| 49 | * .update(ServiceImpl::updated) |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 50 | * .propagate() |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 51 | * .withSvc(LogService.class, log -> log.optional())); |
| 52 | * } |
| 53 | * } |
| 54 | * }</pre> |
| 55 | * |
| 56 | * <p> Example that defines a factory configuration adapter using a user defined configuration type |
| 57 | * (the pid is by default assumed to match the fqdn of the configuration type): |
| 58 | * |
| 59 | * <pre> {@code |
| 60 | * |
| 61 | * public interface DictionaryConfiguration { |
| 62 | * public String getLanguage(); |
| 63 | * public List<String> getWords(); |
| 64 | * } |
| 65 | * |
| 66 | * public class Activator extends DependencyManagerActivator { |
| 67 | * public void init(BundleContext ctx, DependencyManager dm) throws Exception { |
| 68 | * factoryPidAdapter(adapter -> adapter |
| 69 | * .impl(DictionaryImpl.class) |
| 70 | * .factoryPid("foo.bar") |
| 71 | * .update(DictionaryConfiguration.class, ServiceImpl::updated) |
| 72 | * .propagate() |
| 73 | * .withSvc(LogService.class, log -> log.optional())); |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 74 | * } |
| 75 | * } |
| 76 | * }</pre> |
| 77 | */ |
| 78 | public interface FactoryPidAdapterBuilder extends ComponentBuilder<FactoryPidAdapterBuilder> { |
| 79 | /** |
| 80 | * Specifies the factory pid used by the adapter. |
| 81 | * @param pid the factory pid. |
| 82 | * @return this builder |
| 83 | */ |
| 84 | FactoryPidAdapterBuilder factoryPid(String pid); |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 85 | |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 86 | /** |
Pierre De Rop | 57ffa3f | 2016-02-19 12:54:30 +0000 | [diff] [blame] | 87 | * Specifies if the public properties (not starting with a dot) should be propagated to the adapter service properties (false by default). |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 88 | * |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 89 | * @return this builder. |
| 90 | */ |
| 91 | FactoryPidAdapterBuilder propagate(); |
| 92 | |
| 93 | /** |
Pierre De Rop | 57ffa3f | 2016-02-19 12:54:30 +0000 | [diff] [blame] | 94 | * Specifies if the public properties (not starting with a dot) should be propagated to the adapter service properties (false by default). |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 95 | * |
Pierre De Rop | 57ffa3f | 2016-02-19 12:54:30 +0000 | [diff] [blame] | 96 | * @param propagate true if the public properties should be propagated to the adapter service properties (false by default). |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 97 | * @return this builder. |
| 98 | */ |
| 99 | FactoryPidAdapterBuilder propagate(boolean propagate); |
| 100 | |
| 101 | /** |
Pierre De Rop | 6e8f921 | 2016-02-20 21:44:59 +0000 | [diff] [blame^] | 102 | * Specifies a callback method that will be called on the component implementation when the configuration is injected. |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 103 | * |
Pierre De Rop | 6e8f921 | 2016-02-20 21:44:59 +0000 | [diff] [blame^] | 104 | * @param updateMethod the method to call on the component implementation when the configuration is available ("updated" by default). |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 105 | * |
Pierre De Rop | 57ffa3f | 2016-02-19 12:54:30 +0000 | [diff] [blame] | 106 | * <p>The following method signatures are supported: |
| 107 | * <ol> |
| 108 | * <li> method(Dictionary properties) |
| 109 | * <li> method(Component component, Dictionary properties) |
| 110 | * </ol> |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 111 | * |
| 112 | * @return this builder |
| 113 | */ |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 114 | FactoryPidAdapterBuilder update(String updateMethod); |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 115 | |
| 116 | /** |
Pierre De Rop | 6e8f921 | 2016-02-20 21:44:59 +0000 | [diff] [blame^] | 117 | * Sets a callback method to call on the component implementation when the configuration is updated. |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 118 | * The callback is invoked with a configuration type argument. |
| 119 | * |
Pierre De Rop | 57ffa3f | 2016-02-19 12:54:30 +0000 | [diff] [blame] | 120 | * <p>The following callback signatures are supported and searched in the following order: |
| 121 | * <ol> |
| 122 | * <li>method(Dictionary)</li> |
| 123 | * <li>method(Component, Dictionary)</li> |
| 124 | * <li>method(Configuration) // same type as the one specified in the "configType" argument</li> |
| 125 | * <li>method(Component, Configuration) // Configuration has the same type as the one specified in the "configType" argument</li> |
| 126 | * </ol> |
| 127 | * |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 128 | * @param configType the type of a configuration that is passed as argument to the callback |
Pierre De Rop | 6e8f921 | 2016-02-20 21:44:59 +0000 | [diff] [blame^] | 129 | * @param updateMethod the callback to call on the component implementation when the configuration is updated. |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 130 | * @return this builder |
| 131 | */ |
| 132 | FactoryPidAdapterBuilder update(Class<?> configType, String updateMethod); |
| 133 | |
| 134 | /** |
| 135 | * Specifies a callback instance method that will be called on a given object instance when the configuration is injected. |
| 136 | * |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 137 | * @param updateMethod the method to call on the given object instance when the configuration is available ("updated" by default). |
| 138 | * The following method signatures are supported: |
| 139 | * |
| 140 | * <pre> {@code |
| 141 | * method(Dictionary properties) |
| 142 | * method(Component component, Dictionary properties) |
| 143 | * }</pre> |
| 144 | * |
| 145 | * @param callbackInstance the Object instance on which the updated callback will be invoked. |
| 146 | * @return this builder |
| 147 | */ |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 148 | FactoryPidAdapterBuilder update(Object callbackInstance, String updateMethod); |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 149 | |
| 150 | /** |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 151 | * Specifies a callback instance method that will be called on a given object instance when the configuration is injected. |
| 152 | * The callback is invoked with a configuration type argument. |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 153 | * |
Pierre De Rop | 57ffa3f | 2016-02-19 12:54:30 +0000 | [diff] [blame] | 154 | * <p>The following callback signatures are supported and searched in the following order: |
| 155 | * <ol> |
| 156 | * <li>method(Dictionary)</li> |
| 157 | * <li>method(Component, Dictionary)</li> |
| 158 | * <li>method(Configuration) // same type as the one specified in the "configType" argument</li> |
| 159 | * <li>method(Component, Configuration) // Configuration has the same type as the one specified in the "configType" argument</li> |
| 160 | * </ol> |
| 161 | * |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 162 | * @param configType the type of a configuration that is passed as argument to the callback |
| 163 | * @param callbackInstance the Object instance on which the updated callback will be invoked. |
| 164 | * @param updateMethod the method to call on the given object instance when the configuration is available. The callback is invoked |
| 165 | * with a configuration type argument (matching the configType you have specified. |
| 166 | * @return this builder |
| 167 | */ |
| 168 | FactoryPidAdapterBuilder update(Class<?> configType, Object callbackInstance, String updateMethod); |
| 169 | |
| 170 | /** |
| 171 | * Specifies a method reference that will be called on one of the component classes when the configuration is injected. |
| 172 | * The callback is invoked with a Dictionary argument. |
| 173 | * |
| 174 | * @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] | 175 | * @param callback the method to call on one of the component classes when the configuration is available. |
| 176 | * @return this builder |
| 177 | */ |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 178 | <T> FactoryPidAdapterBuilder update(CbDictionary<T> callback); |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 179 | |
| 180 | /** |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 181 | * Specifies a method reference that will be called on one of the component classes when the configuration is injected. |
| 182 | * The callback is invoked with a configuration type argument. |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 183 | * |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 184 | * @param <T> the type of the component implementation class on which the callback is invoked on. |
| 185 | * @param <U> the configuration type accepted by the callback method. |
| 186 | * @param configType the type of a configuration that is passed as argument to the callback |
| 187 | * @param callback the method to call on one of the component classes when the configuration is available. |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 188 | * @return this builder |
| 189 | */ |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 190 | <T, U> FactoryPidAdapterBuilder update(Class<U> configType, CbConfiguration<T, U> callback); |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 191 | |
| 192 | /** |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 193 | * Specifies a method reference that will be called on one of the component classes when the configuration is injected |
| 194 | * |
| 195 | * @param <T> the type of the component implementation class on which the callback is invoked on. |
Pierre De Rop | 57ffa3f | 2016-02-19 12:54:30 +0000 | [diff] [blame] | 196 | * @param callback the reference to a method on one of the component classes. The method may takes as arguments a Dictionary and a Component. |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 197 | * @return this builder |
| 198 | */ |
| 199 | <T> FactoryPidAdapterBuilder update(CbDictionaryComponent<T> callback); |
| 200 | |
| 201 | /** |
| 202 | * Specifies a method reference that will be called on one of the component classes when the configuration is injected. |
| 203 | * The callback is invoked with the following arguments: a configuration type, and a Component object. |
| 204 | * |
| 205 | * @param <T> the type of the component implementation class on which the callback is invoked on. |
| 206 | * @param <U> the configuration type accepted by the callback method. |
| 207 | * @param configType the type of a configuration that is passed as argument to the callback |
Pierre De Rop | 57ffa3f | 2016-02-19 12:54:30 +0000 | [diff] [blame] | 208 | * @param callback the reference to a method on one of the component classes. The method may takes as arguments a configuration type and a Component. |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 209 | * @return this builder |
| 210 | */ |
| 211 | <T, U> FactoryPidAdapterBuilder update(Class<U> configType, CbConfigurationComponent<T, U> callback); |
| 212 | |
| 213 | /** |
| 214 | * Specifies a method reference that will be called on a given object instance when the configuration is injected |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 215 | * |
| 216 | * @param callback the method to call on a given object instance when the configuration is available. The callback takes as argument a |
| 217 | * a Dictionary parameter. |
| 218 | * @return this builder |
| 219 | */ |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 220 | FactoryPidAdapterBuilder update(InstanceCbDictionary callback); |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 221 | |
| 222 | /** |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 223 | * Specifies a method reference that will be called on a given object instance when the configuration is injected. |
| 224 | * The callback is invoked with a type-safe configuration type argument. |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 225 | * |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 226 | * @param <T> the configuration type accepted by the callback method. |
| 227 | * @param configType the type of a configuration that is passed as argument to the callback |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 228 | * @param callback the method to call on a given object instance when the configuration is available. The callback takes as argument a |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 229 | * a configuration type parameter. |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 230 | * @return this builder |
| 231 | */ |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 232 | <T> FactoryPidAdapterBuilder update(Class<T> configType, InstanceCbConfiguration<T> callback); |
| 233 | |
| 234 | /** |
| 235 | * Specifies a method reference that will be called on a given object instance when the configuration is injected. |
| 236 | * |
| 237 | * @param callback the method to call on a given object instance when the configuration is available. The callback takes as argument a |
| 238 | * Dictionary, and a Component parameter. |
| 239 | * @return this builder |
| 240 | */ |
| 241 | FactoryPidAdapterBuilder update(InstanceCbDictionaryComponent callback); |
| 242 | |
| 243 | /** |
| 244 | * Specifies a method reference that will be called on a given object instance when the configuration is injected. |
| 245 | * |
| 246 | * @param <T> the configuration type accepted by the callback method. |
| 247 | * @param configType the type of a configuration that is passed as argument to the callback |
Pierre De Rop | 57ffa3f | 2016-02-19 12:54:30 +0000 | [diff] [blame] | 248 | * @param callback the method to call on a given object instance when the configuration is available. The callback takes as arguments a |
Pierre De Rop | 1152750 | 2016-02-18 21:07:16 +0000 | [diff] [blame] | 249 | * configuration type, and a Component parameter. |
| 250 | * @return this builder |
| 251 | */ |
| 252 | <T> FactoryPidAdapterBuilder update(Class<T> configType, InstanceCbConfigurationComponent<T> callback); |
Pierre De Rop | faca289 | 2016-01-31 23:27:05 +0000 | [diff] [blame] | 253 | } |