THIS IS A TEST INSTANCE. ALL YOUR CHANGES WILL BE LOST!!!!
...
| Code Block |
|---|
@AdapterService(adapteeService = AdapteeService.class, properties={@Property(name="param", value="value")})
class AdapterImpl implements AdapterService {
// The service we are adapting (injected by reflection)
protected AdapteeService adaptee;
public void doWork() {
adaptee.mehod1();
adaptee.method2();
}
}
|
@BundleAdapterService
@ResourceAdapterService
...
Bundle adapters are similar to AdapterService, but instead of adapting a service, they adapt a bundle with a certain set of states (STARTED|INSTALLED|...), and provide a service on top of it.
The bundle adapter will be applied to any bundle that matches the specified bundle state mask and filter conditions, which may match some of the bundle OSGi manifest headers. For each matching bundle an adapter will be created based on the adapter implementation class. The adapter will be registered with the specified interface and with service properties found from the original bundle OSGi manifest headers plus any extra properties you supply here. If you declare the original bundle as a member it will be injected.
Annotation attributes:
- filter: The filter used to match some OSGi manifest headers from a given bundle.
- provides: The interface(s) to use when registering adapters. By default, the interface(s) directly implemented by the annotated class is (are) used.
- properties: Additional properties to use with the service registration.
- stateMask: the bundle state mask to apply. The mask is made up of the flags provided by the org.osgi.framework.Bundle states (UNINSTALLED | INSTALLED | RESOLVED | STARTING | STARTED | ACTIVE).
- propagate: Specifies if manifest headers from the bundle should be propagated to the exposed service properties.
- factoryMethod: Sets the static method used to create the BundleAdapterService implementation instance.
Usage Examples
In the following example, a "VideoPlayer" Service is registered into the OSGi registry each time an active bundle containing a "Video-Path" manifest header is detected:
| Code Block |
|---|
@BundleAdapterService(filter = "(Video-Path=*)", stateMask = Bundle.ACTIVE, propagate=true)
public class VideoPlayerImpl implements VideoPlayer {
Bundle bundle; // Injected by reflection
void play() {
URL mpegFile = bundle.getEntry(bundle.getHeaders().get("Video-Path"));
// play the video provided by the bundle ...
}
void stop() {}
}
|
@ResourceAdapterService
Resource adapters are things that adapt a resource instead of a service, and provide an adapter service on top of this resource. Resources are an abstraction that is introduced by the dependency manager, represented as a URL. They can be implemented to serve resources embedded in bundles, somewhere on a file system or in an http content repository server, or database.
The adapter will be applied to any resource that matches the specified filter condition, which can match some part of the resource URL (with "path", "protocol", "port", or "host" filters). For each matching resource an adapter will be created based on the adapter implementation class. The adapter will be registered with the specified interface and with any extra service properties you supply here. Moreover, the following service properties will be propagated from the resource URL:
- host: this property exposes the host part of the resource URL
- path: the resource URL path
- protocol: the resource URL protocol
- port: the resource URL port
Usage Examples:
Here, the "VideoPlayer" service provides a video service on top of any movie resources, with service properties "host"/"port"/"protocol"/"path" extracted from the resource URL:
| Code Block |
|---|
@ResourceAdapterService(filter = "(&(path=/videos/*.mkv)(host=localhost))", propagate = true)
public class VideoPlayerImpl implements VideoPlayer {
// Injected by reflection
URL resource;
void play() {} // play video referenced by this.resource
void stop() {} // stop playing the video
void transcode() {} // ...
}
|
@FactoryConfigurationAdapterService
Annotates a class that acts as a Factory Configuration Adapter Service. For each new Config Admin factory configuration matching the specified factoryPid, an instance of this service will be created. The adapter will be registered with the specified interface, and with the specified adapter service properties. Depending on the propagate parameter, every public factory configuration properties (which don't start with ".") will be propagated along with the adapter service properties.
Like in @ConfigurationDependency, you can optionally specify the meta types of your configurations for Web Console GUI customization (configuration heading/descriptions/default values/etc ...).
Annotation attributes:
- provides: The interface(s) to use when registering adapters. By default, directly implemented interfaces will be registered in the OSGi registry.
- properties: Adapter Service properties. Notice that public factory configuration is also registered in service properties, (only if propagate is true). Public factory configuration properties are those which don't starts with a dot (".").
- factoryPid: Returns the factory pid whose configurations will instantiate the annotated service class. (By default, the pid is the service class name).
- updated: The Update method to invoke (defaulting to "updated"), when a factory configuration is created or updated
- propagate: Returns true if the configuration properties must be published along with the service. Any additional service properties specified directly are merged with these.
- heading: The label used to display the tab name (or section) where the properties are displayed. Example: "Printer Service".
- description: A human readable description of the PID this annotation is associated with. Example: "Configuration for the PrinterService bundle".
- factoryMethod: Sets the static method used to create the adapter instance.
- metadata: an array of "PropertyMetaData[]" annotations, specifying property types used to expose properties in web console
PropertyMetaData anotation attribute:
- description: 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: 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: 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: Return 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 []
- x = Integer.MAX_VALUE no limit, but use array []
- x = 0 1 occurrence required
- required: Tells if this property is required or not.
- optionLabels: 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: 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 factory configuration instances matching the factory pid "DictionaryServiceFactory".
| Code Block |
|---|
@FactoryConfigurationAdapterService(factoryPid="DictionaryServiceFactory", updated="updated")
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);
}
}
...
}
|
Here, this is the same example as above, but using meta types:
| Code Block |
|---|
@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);
}
}
...
}
|