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 | * |
| 34 | * <h3>Usage Examples</h3> |
| 35 | * Here, a "Dictionary" service instance is created for each existing "sample.DictionaryConfiguration" factory pids. |
| 36 | * |
| 37 | * First, we declare our factory configuration metadata using standard bndtools metatatype annotations |
| 38 | * (see http://www.aqute.biz/Bnd/MetaType): |
| 39 | * |
| 40 | * <blockquote> |
| 41 | * <pre> |
| 42 | * package sample; |
| 43 | * import java.util.List; |
| 44 | * import aQute.bnd.annotation.metatype.Meta.AD; |
| 45 | * import aQute.bnd.annotation.metatype.Meta.OCD; |
| 46 | * |
| 47 | * @OCD(factory = true, description = "Declare here some Dictionary instances.") |
| 48 | * public interface DictionaryConfiguration { |
| 49 | * @AD(description = "Describes the dictionary language.", deflt = "en") |
| 50 | * String lang(); |
| 51 | * |
| 52 | * @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^] | 53 | * List<String> words(); |
Pierre De Rop | 3a00a21 | 2015-03-01 09:27:46 +0000 | [diff] [blame] | 54 | * } |
| 55 | * </pre> |
| 56 | * </blockquote> |
| 57 | * |
| 58 | * And here is the Dictionary service: |
| 59 | * |
| 60 | * <blockquote> |
| 61 | * <pre> |
| 62 | * import java.util.List; |
| 63 | * import aQute.bnd.annotation.metatype.Configurable; |
| 64 | * |
| 65 | * @FactoryConfigurationAdapterService(factoryPidClass=DictionaryConfiguration.class) |
| 66 | * public class DictionaryImpl implements DictionaryService { |
| 67 | * protected void updated(Dictionary<String, ?> props) { |
| 68 | * // load configuration from the provided dictionary, or throw an exception of any configuration error. |
| 69 | * DictionaryConfiguration cnf = Configurable.createConfigurable(DictionaryConfiguration.class, props); |
| 70 | * |
| 71 | * m_lang = config.lang(); |
| 72 | * m_words.clear(); |
| 73 | * for (String word : conf.words()) { |
| 74 | * m_words.add(word); |
| 75 | * } |
| 76 | * } |
| 77 | * ... |
| 78 | * } |
| 79 | * </pre> |
| 80 | * </blockquote> |
| 81 | * |
| 82 | * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a> |
| 83 | */ |
| 84 | @Retention(RetentionPolicy.CLASS) |
| 85 | @Target(ElementType.TYPE) |
| 86 | public @interface FactoryConfigurationAdapterService |
| 87 | { |
| 88 | /** |
| 89 | * The interface(s) to use when registering adapters. By default, directly implemented |
| 90 | * interfaces will be registered in the OSGi registry. |
Pierre De Rop | 1c0431f | 2016-02-06 23:28:44 +0000 | [diff] [blame^] | 91 | * @return the registered service interfaces |
Pierre De Rop | 3a00a21 | 2015-03-01 09:27:46 +0000 | [diff] [blame] | 92 | */ |
| 93 | Class<?>[] provides() default {}; |
| 94 | |
| 95 | /** |
| 96 | * Adapter Service properties. Notice that public factory configuration is also registered in service properties, |
| 97 | * (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^] | 98 | * @return the adapter service properties |
Pierre De Rop | 3a00a21 | 2015-03-01 09:27:46 +0000 | [diff] [blame] | 99 | */ |
| 100 | Property[] properties() default {}; |
| 101 | |
| 102 | /** |
| 103 | * Returns the factory pid whose configurations will instantiate the annotated service class. (By default, the pid is the |
| 104 | * service class name). |
Pierre De Rop | 1c0431f | 2016-02-06 23:28:44 +0000 | [diff] [blame^] | 105 | * @return the factory pid |
Pierre De Rop | 3a00a21 | 2015-03-01 09:27:46 +0000 | [diff] [blame] | 106 | */ |
| 107 | String factoryPid() default ""; |
| 108 | |
| 109 | /** |
| 110 | * Returns the factory pid from a class name. The full class name will be used as the configuration PID. |
| 111 | * You can use this method when you use an interface annoted with standard bndtols metatype annotations. |
| 112 | * (see http://www.aqute.biz/Bnd/MetaType). |
Pierre De Rop | 1c0431f | 2016-02-06 23:28:44 +0000 | [diff] [blame^] | 113 | * @return the factory pid class |
Pierre De Rop | 3a00a21 | 2015-03-01 09:27:46 +0000 | [diff] [blame] | 114 | */ |
| 115 | Class<?> factoryPidClass() default Object.class; |
| 116 | |
| 117 | /** |
| 118 | * 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^] | 119 | * @return the updated callback |
Pierre De Rop | 3a00a21 | 2015-03-01 09:27:46 +0000 | [diff] [blame] | 120 | */ |
| 121 | String updated() default "updated"; |
| 122 | |
| 123 | /** |
| 124 | * Returns true if the configuration properties must be published along with the service. |
| 125 | * Any additional service properties specified directly are merged with these. |
| 126 | * @return true if configuration must be published along with the service, false if not. |
| 127 | */ |
| 128 | boolean propagate() default false; |
| 129 | |
| 130 | /** |
| 131 | * The label used to display the tab name (or section) where the properties are displayed. Example: "Printer Service". |
| 132 | * @return The label used to display the tab name where the properties are displayed. |
| 133 | * @deprecated use standard bndtools metatype annotations instead (see http://www.aqute.biz/Bnd/MetaType) |
| 134 | */ |
| 135 | String heading() default ""; |
| 136 | |
| 137 | /** |
| 138 | * A human readable description of the PID this annotation is associated with. Example: "Configuration for the PrinterService bundle". |
| 139 | * @return A human readable description of the PID this annotation is associated with. |
| 140 | * @deprecated use standard bndtools metatype annotations instead (see http://www.aqute.biz/Bnd/MetaType) |
| 141 | */ |
| 142 | String description() default ""; |
| 143 | |
| 144 | /** |
| 145 | * The list of properties types used to expose properties in web console. |
| 146 | * @return The list of properties types used to expose properties in web console. |
| 147 | * @deprecated use standard bndtools metatype annotations instead (see http://www.aqute.biz/Bnd/MetaType) |
| 148 | */ |
| 149 | PropertyMetaData[] metadata() default {}; |
| 150 | |
| 151 | /** |
| 152 | * Sets the static method used to create the adapter instance. |
Pierre De Rop | 1c0431f | 2016-02-06 23:28:44 +0000 | [diff] [blame^] | 153 | * @return the factory method |
Pierre De Rop | 3a00a21 | 2015-03-01 09:27:46 +0000 | [diff] [blame] | 154 | */ |
| 155 | String factoryMethod() default ""; |
| 156 | } |