Pierre De Rop | 3a00a21 | 2015-03-01 09:27:46 +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 | */ |
| 19 | package org.apache.felix.dm.annotation.api; |
| 20 | |
| 21 | import java.lang.annotation.ElementType; |
| 22 | import java.lang.annotation.Retention; |
| 23 | import java.lang.annotation.RetentionPolicy; |
| 24 | import java.lang.annotation.Target; |
| 25 | |
| 26 | |
| 27 | /** |
| 28 | * Annotates a class that acts as a Factory Configuration Adapter Service. For each new <code>Config Admin</code> |
| 29 | * factory configuration matching the specified factoryPid, an instance of this service will be created. |
| 30 | * The adapter will be registered with the specified interface, and with the specified adapter service properties. |
| 31 | * Depending on the <code>propagate</code> parameter, every public factory configuration properties |
Pierre De Rop | 1c0431f | 2016-02-06 23:28:44 +0000 | [diff] [blame] | 32 | * (which don't start with ".") will be propagated along with the adapter service properties. |
Pierre De Rop | 3a00a21 | 2015-03-01 09:27:46 +0000 | [diff] [blame] | 33 | * |
Pierre De Rop | 9e5cdba | 2016-02-17 20:35:16 +0000 | [diff] [blame^] | 34 | * <p> If you specify a configuration type, then the fqdn of the configuration interface is used as the factory pid, |
| 35 | * else you can specify the factory pid explicitly using the factoryPid attribute. |
| 36 | * If no configuration type is used and no factoryPid attribute is specified, then the factory pid will be set to the fqdn of |
| 37 | * the class on which this annotation is applied. |
| 38 | * |
| 39 | * <p> (see javadoc from {@link ConfigurationDependency} for more informations about configuration types). |
| 40 | * |
Pierre De Rop | 3a00a21 | 2015-03-01 09:27:46 +0000 | [diff] [blame] | 41 | * <h3>Usage Examples</h3> |
| 42 | * Here, a "Dictionary" service instance is created for each existing "sample.DictionaryConfiguration" factory pids. |
| 43 | * |
| 44 | * First, we declare our factory configuration metadata using standard bndtools metatatype annotations |
| 45 | * (see http://www.aqute.biz/Bnd/MetaType): |
| 46 | * |
| 47 | * <blockquote> |
| 48 | * <pre> |
| 49 | * package sample; |
| 50 | * import java.util.List; |
| 51 | * import aQute.bnd.annotation.metatype.Meta.AD; |
| 52 | * import aQute.bnd.annotation.metatype.Meta.OCD; |
| 53 | * |
| 54 | * @OCD(factory = true, description = "Declare here some Dictionary instances.") |
| 55 | * public interface DictionaryConfiguration { |
| 56 | * @AD(description = "Describes the dictionary language.", deflt = "en") |
| 57 | * String lang(); |
| 58 | * |
| 59 | * @AD(description = "Declare here the list of words supported by this dictionary.") |
Pierre De Rop | 1c0431f | 2016-02-06 23:28:44 +0000 | [diff] [blame] | 60 | * List<String> words(); |
Pierre De Rop | 3a00a21 | 2015-03-01 09:27:46 +0000 | [diff] [blame] | 61 | * } |
| 62 | * </pre> |
| 63 | * </blockquote> |
| 64 | * |
Pierre De Rop | 9e5cdba | 2016-02-17 20:35:16 +0000 | [diff] [blame^] | 65 | * And here is the factory pid adapter service, which is instantiated for each instance of the "sample.DictionaryConfiguration" factory pid: |
| 66 | * |
Pierre De Rop | 3a00a21 | 2015-03-01 09:27:46 +0000 | [diff] [blame] | 67 | * <blockquote> |
| 68 | * <pre> |
| 69 | * import java.util.List; |
| 70 | * import aQute.bnd.annotation.metatype.Configurable; |
| 71 | * |
Pierre De Rop | 9e5cdba | 2016-02-17 20:35:16 +0000 | [diff] [blame^] | 72 | * @FactoryConfigurationAdapterService(configType=DictionaryConfiguration.class) |
Pierre De Rop | 3a00a21 | 2015-03-01 09:27:46 +0000 | [diff] [blame] | 73 | * public class DictionaryImpl implements DictionaryService { |
Pierre De Rop | 9e5cdba | 2016-02-17 20:35:16 +0000 | [diff] [blame^] | 74 | * protected void updated(DictionaryConfiguration config) { |
Pierre De Rop | 3a00a21 | 2015-03-01 09:27:46 +0000 | [diff] [blame] | 75 | * m_lang = config.lang(); |
| 76 | * m_words.clear(); |
| 77 | * for (String word : conf.words()) { |
| 78 | * m_words.add(word); |
| 79 | * } |
| 80 | * } |
| 81 | * ... |
| 82 | * } |
| 83 | * </pre> |
| 84 | * </blockquote> |
| 85 | * |
Pierre De Rop | 9e5cdba | 2016-02-17 20:35:16 +0000 | [diff] [blame^] | 86 | * |
Pierre De Rop | 3a00a21 | 2015-03-01 09:27:46 +0000 | [diff] [blame] | 87 | * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a> |
| 88 | */ |
| 89 | @Retention(RetentionPolicy.CLASS) |
| 90 | @Target(ElementType.TYPE) |
| 91 | public @interface FactoryConfigurationAdapterService |
| 92 | { |
| 93 | /** |
| 94 | * The interface(s) to use when registering adapters. By default, directly implemented |
| 95 | * interfaces will be registered in the OSGi registry. |
Pierre De Rop | 1c0431f | 2016-02-06 23:28:44 +0000 | [diff] [blame] | 96 | * @return the registered service interfaces |
Pierre De Rop | 3a00a21 | 2015-03-01 09:27:46 +0000 | [diff] [blame] | 97 | */ |
| 98 | Class<?>[] provides() default {}; |
| 99 | |
| 100 | /** |
| 101 | * Adapter Service properties. Notice that public factory configuration is also registered in service properties, |
| 102 | * (only if propagate is true). Public factory configuration properties are those which don't starts with a dot ("."). |
Pierre De Rop | 1c0431f | 2016-02-06 23:28:44 +0000 | [diff] [blame] | 103 | * @return the adapter service properties |
Pierre De Rop | 3a00a21 | 2015-03-01 09:27:46 +0000 | [diff] [blame] | 104 | */ |
| 105 | Property[] properties() default {}; |
| 106 | |
| 107 | /** |
Pierre De Rop | 9e5cdba | 2016-02-17 20:35:16 +0000 | [diff] [blame^] | 108 | * Returns the type safe configuration class which will be injected in the updated callback. |
| 109 | * By default, the factory pid is assumed to match the fqdn of the configuration type. |
| 110 | * see javadoc from {@link ConfigurationDependency} for more informations about configuration types. |
| 111 | * @return the configuration type to pass in the "updated" callback argument. |
| 112 | * @see ConfigurationDependency |
| 113 | */ |
| 114 | Class<?> configType() default Object.class; |
| 115 | |
| 116 | /** |
Pierre De Rop | 3a00a21 | 2015-03-01 09:27:46 +0000 | [diff] [blame] | 117 | * Returns the factory pid whose configurations will instantiate the annotated service class. (By default, the pid is the |
| 118 | * service class name). |
Pierre De Rop | 1c0431f | 2016-02-06 23:28:44 +0000 | [diff] [blame] | 119 | * @return the factory pid |
Pierre De Rop | 3a00a21 | 2015-03-01 09:27:46 +0000 | [diff] [blame] | 120 | */ |
| 121 | String factoryPid() default ""; |
| 122 | |
| 123 | /** |
| 124 | * Returns the factory pid from a class name. The full class name will be used as the configuration PID. |
| 125 | * You can use this method when you use an interface annoted with standard bndtols metatype annotations. |
| 126 | * (see http://www.aqute.biz/Bnd/MetaType). |
Pierre De Rop | 1c0431f | 2016-02-06 23:28:44 +0000 | [diff] [blame] | 127 | * @return the factory pid class |
Pierre De Rop | 9e5cdba | 2016-02-17 20:35:16 +0000 | [diff] [blame^] | 128 | * @deprecated use {@link #configType()} and accept a configuration type parameter from your updated callback. The pid |
| 129 | * is then assumed to match the fqdn of the configuration type. |
Pierre De Rop | 3a00a21 | 2015-03-01 09:27:46 +0000 | [diff] [blame] | 130 | */ |
| 131 | Class<?> factoryPidClass() default Object.class; |
| 132 | |
| 133 | /** |
| 134 | * The Update method to invoke (defaulting to "updated"), when a factory configuration is created or updated |
Pierre De Rop | 1c0431f | 2016-02-06 23:28:44 +0000 | [diff] [blame] | 135 | * @return the updated callback |
Pierre De Rop | 3a00a21 | 2015-03-01 09:27:46 +0000 | [diff] [blame] | 136 | */ |
| 137 | String updated() default "updated"; |
| 138 | |
| 139 | /** |
| 140 | * Returns true if the configuration properties must be published along with the service. |
| 141 | * Any additional service properties specified directly are merged with these. |
| 142 | * @return true if configuration must be published along with the service, false if not. |
| 143 | */ |
| 144 | boolean propagate() default false; |
| 145 | |
| 146 | /** |
| 147 | * The label used to display the tab name (or section) where the properties are displayed. Example: "Printer Service". |
| 148 | * @return The label used to display the tab name where the properties are displayed. |
| 149 | * @deprecated use standard bndtools metatype annotations instead (see http://www.aqute.biz/Bnd/MetaType) |
| 150 | */ |
| 151 | String heading() default ""; |
| 152 | |
| 153 | /** |
| 154 | * A human readable description of the PID this annotation is associated with. Example: "Configuration for the PrinterService bundle". |
| 155 | * @return A human readable description of the PID this annotation is associated with. |
| 156 | * @deprecated use standard bndtools metatype annotations instead (see http://www.aqute.biz/Bnd/MetaType) |
| 157 | */ |
| 158 | String description() default ""; |
| 159 | |
| 160 | /** |
| 161 | * The list of properties types used to expose properties in web console. |
| 162 | * @return The list of properties types used to expose properties in web console. |
| 163 | * @deprecated use standard bndtools metatype annotations instead (see http://www.aqute.biz/Bnd/MetaType) |
| 164 | */ |
| 165 | PropertyMetaData[] metadata() default {}; |
| 166 | |
| 167 | /** |
| 168 | * Sets the static method used to create the adapter instance. |
Pierre De Rop | 1c0431f | 2016-02-06 23:28:44 +0000 | [diff] [blame] | 169 | * @return the factory method |
Pierre De Rop | 3a00a21 | 2015-03-01 09:27:46 +0000 | [diff] [blame] | 170 | */ |
| 171 | String factoryMethod() default ""; |
| 172 | } |