You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@felix.apache.org by pd...@apache.org on 2015/03/08 00:05:24 UTC
svn commit: r1664928 -
/felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/reference/component-factory-configuration-adapter.mdtext
Author: pderop
Date: Sat Mar 7 23:05:23 2015
New Revision: 1664928
URL: http://svn.apache.org/r1664928
Log:
Removed deprecated DM annotations metatype attributes, which are replaced by standard bnd metatype annotations.
Modified:
felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/reference/component-factory-configuration-adapter.mdtext
Modified: felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/reference/component-factory-configuration-adapter.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/reference/component-factory-configuration-adapter.mdtext?rev=1664928&r1=1664927&r2=1664928&view=diff
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/reference/component-factory-configuration-adapter.mdtext (original)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/reference/component-factory-configuration-adapter.mdtext Sat Mar 7 23:05:23 2015
@@ -40,6 +40,15 @@ annotated service class.
(By default, the pid is the service class name).
----
+**`factoryClass`**
+*Required*: False
+*Default*: The class name, including the package.
+
+Returns the factory pid from a class name. The full class name will be used as the
+configuration PID. You can use this method when you use an interface annoted with
+standard bndtols metatype annotations. (see http://www.aqute.biz/Bnd/MetaType).
+
+----
**`updated`**
*Required*: False
*Default*: "updated"
@@ -57,117 +66,12 @@ along with the service. Any additional s
are merged with these.
----
-**`heading`**
-*Required*: False
-*Default*: --
-
-The label used to display the tab name (or section) where the properties are
-displayed. Example: "Printer Service".
-
-----
-**`description`**
-*Required*: False
-*Default*: --
-
-A human readable description of the PID this annotation is associated with.
-Example: "Configuration for the PrinterService bundle".
-
-----
**`factoryMethod`**
*Required*: False
*Default*: --
Sets the static method used to create the adapter instance.
-----
-**`metadata`**
-*Required*: False
-*Default*: --
-An array of "PropertyMetaData annotations, specifying property types used to
-expose properties in web console
-
-### PropertyMetaData anotation attributes:
-
-----
-**`description`**
-*Required*: True
-*Default*: --
-Returns the property description. The description may be localized and must
-describe the semantics of this type and any constraints.
-Example: "Select the log level for the Printer Service".
-
-----
-**`type`**
-*Required*: False
-*Default*: String
-
-Return the property primitive type (java.lang.String.class by default).
-If must be either one of the following types:
-
-- String.class
-- Long.class
-- Integer.class
-- Character.class
-- Byte.class
-- Double.class
-- Float.class
-- Boolean.class
-
-----
-**`defaults`**
-*Required*: False
-*Default*: --
-
-Return a default for this property. The object must be of the appropriate
-type as defined by the cardinality and getType(). The return type is a list of
-String objects that can be converted to the appropriate type.
-The cardinality of the return array must follow the absolute cardinality of
-this type. E.g. if the cardinality = 0, the array must contain 1 element. If
-the cardinality is 1, it must contain 0 or 1 elements. If it is -5, it must
-contain from 0 to max 5 elements. Note that the special case of a 0
-cardinality, meaning a single value, does not allow arrays or vectors of 0
-elements.
-
-----
-**`cardinality`**
-*Required*: False
-*Default*: --
-
-Returns the cardinality of this property (0 by default). The OSGi environment
-handles multi valued properties in arrays or in Vector objects.
-The return value is defined as follows:
-
-- x = Integer.MIN_VALUE: no limit, but use Vector
-- x < 0: -x = max occurrences, store in Vector
-- x > 0: x = max occurrences, store in array []({{ refs..path }})
-- x = Integer.MAX_VALUE: no limit, but use array []({{ refs..path }})
-- x = 0: 1 occurrence required
-
-----
-**`required`**
-*Required*: False
-*Default*: true
-
-Tells if this property is required or not.
-
-----
-**`optionLabels`**
-*Required*: False
-*Default*: --
-
-Return a list of valid option labels for this property. The purpose of this
-method is to allow menus with localized labels. It is associated with the
-*optionValues* attribute. The labels returned here are ordered in the same
-way as the *optionValues* attribute values.
-
-----
-**`optionValues`**
-*Required*: False
-*Default*: --
-
-Return a list of option values that this property can take. This list must be
-in the same sequence as the *optionLabels* attribute.
-
### Usage Examples
Here, a "Dictionary" service instance is instantiated for each existing
@@ -210,62 +114,44 @@ factory pid:
// ...
}
-Here, this is the same example as above, but using meta types:
+Here is the same example as above, but using meta types (the DM annotations metatype attributes are deprecated and
+it's better to use standard bnd metatype annotations, the following example are using bnd metatypes):
+
+First, we declare our factory configuration metadata using standard bndtools metatype annotations (see http://www.aqute.biz/Bnd/MetaType):
:::java
- @FactoryConfigurationAdapterService(
- factoryPid="DictionaryServiceFactory",
- propagate=true,
- updated="updated",
- heading="Dictionary Services",
- description="Declare here some Dictionary instances, allowing to instantiates some DictionaryService services for a given dictionary language",
- metadata={
- @PropertyMetaData(
- heading="Dictionary Language",
- description="Declare here the language supported by this dictionary. " +
- "This property will be propagated with the Dictionary Service properties.",
- defaults={"en"},
- id=DictionaryImpl.LANG,
- cardinality=0),
- @PropertyMetaData(
- heading="Dictionary words",
- description="Declare here the list of words supported by this dictionary. This properties starts with a Dot and won't be propagated with Dictionary OSGi service properties.",
- defaults={"hello", "world"},
- id=DictionaryImpl.WORDS,
- cardinality=Integer.MAX_VALUE)
- }
- )
- public class DictionaryImpl implements DictionaryService
- {
- /**
- * The key of our config admin dictionary language.
- */
- final static String LANG = "lang";
-
- /**
- * The key of our config admin dictionary values.
- */
- final static String WORDS = "words";
-
- /**
- * We store all configured words in a thread-safe data structure, because ConfigAdmin
- * may invoke our updated method at any time.
- */
- private CopyOnWriteArrayList<String> m_words = new CopyOnWriteArrayList<String>();
-
- /**
- * Our Dictionary language.
- */
- private String m_lang;
-
- protected void updated(Dictionary<String, ?> config) {
- m_lang = (String) config.get(LANG);
- m_words.clear();
- String[] words = (String[]) config.get(WORDS);
- for (String word : words) {
- m_words.add(word);
- }
- }
-
- // ...
+ package sample;
+ import java.util.List;
+ import aQute.bnd.annotation.metatype.Meta.AD;
+ import aQute.bnd.annotation.metatype.Meta.OCD;
+
+ @OCD(factory = true, description = "Declare here some Dictionary instances.")
+ public interface DictionaryConfiguration {
+ @AD(description = "Describes the dictionary language.", deflt = "en")
+ String lang();
+
+ @AD(description = "Declare here the list of words supported by this dictionary.")
+ List words();
}
+
+And here is the Dictionary service, and we instantiate our DictionaryConfiguration interface using the bndlib *Configurable* helper class.
+
+ :::java
+ import java.util.List;
+ import aQute.bnd.annotation.metatype.Configurable;
+
+ @FactoryConfigurationAdapterService(factoryPidClass=DictionaryConfiguration.class)
+ public class DictionaryImpl implements DictionaryService {
+ protected void updated(Dictionary<String, ?> props) {
+ // load configuration from the provided dictionary, or throw an exception of any configuration error.
+ DictionaryConfiguration cnf = Configurable.createConfigurable(DictionaryConfiguration.class, props);
+
+ m_lang = config.lang();
+ m_words.clear();
+ for (String word : conf.words()) {
+ m_words.add(word);
+ }
+ }
+ ...
+ }
+