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