Metatype

bnd leverages the rich type information the Java class files contain. It inspects the returns types and from this it automatically calculates the AD type as well as the cardinality. For example, a method like:

List ints()

Provides an AD of:

<AD 
  name='Ints' 
  id='ints' 
  cardinality='-2147483648' 
  required='true' 
  type='Integer'/>

Naming

bnd attempts to make the names of the OCD and AD human readable by un-camel-casing the id. This means that it uses the upper cases in the id to decide where to use spaces. It also attempts to replace ‘_’ characters with spaces and removes ‘$’. If the result is not what is wanted, the name can always be explicitly set with the AD.name() field.

The id of the properties is by default derived from the method name. The name space of methods is restricted by the Java language both in character set as well as by the reserved keywords. Therefore, bnd mangles the name of the method to allow the method name to be adapted to common practices in proeprty names.

• ’$’ is removed from the name unless it is followed by another ‘$’, in that case it is a single ‘$’. This can be used to use Java keywords as a name. For example, $new maps to the new name. To make the name $x, use a method with the name $$x.
• ‘’ is replaced with ‘.’ unless it is followed by another ‘’, in that case it becomes a single ‘_’. This is useful for dotted names (a.b.c comes from a_b_c) and to indicate private properties, that is properties that start with a ‘.’. For example, _secret maps to .secret and this will be a property that is not registered as a service.

For example:

@OCD interface Config { String _password(); // .password - will not be registered as a service String $new(); // new - keyword }

@Meta.OCD

The OCD annotation is necessary to know that an interface is a Metatype interface. It should be used preferably without any parameters (they all have good defaults). However, each default is possible to override. The following table discusses the fields:

@Meta.AD

The AD is an optional annotation on methods of a OCD interface. The annotation makes it possible to override the defaults and provide extra information.

Runtime conversions

The type support the OSGi Metatype specification is limited to the primitives and strings. So what happens when you use another type? During the build phase, bnd will revert to a ‘String’ Metatype type. This means that those special types are going to be strings in the dictionary. However, the aQute.bnd.annotation.metatype package contains a helper class that simplifies the usage of properties in runtime. It has a @createConfigurable(Class c, Map props)`. This method returns an object that implements the given configuration interface. The implementation of these methods uses the properties to provide a value. That is, calling the method abc() on this interface will attempt to find the property "abc". It will then use the actual return type of the method to do conversion from the type in the properties to the return type. This takes generic information into account when present.

For example:

@Meta.OCD interface Config { URI[] uris(); }

public void updated( Map<String,Object> props) { config = Configurable.createConfigurable(Config.class,props); for ( URI URI : config.uris() ) { … } }

The Metatype specification does not support URIs, so how does this work? Lets first look at the AD:

<AD 
 name='uris' 
 id='uris' 
 cardinality='2147483647' 
 required='true' 
 type='String'/>

Any editor will therefore put an array of strings (String[]) in the properties. When the proxy gets the string, it will therefore have to convert from the String[] -> URI[]. In this case, the URI has a String constructor and is used to do the conversion from String to URI. The converter can handle general array to collection, collection to array, and as indicated, any conversion to an object that has a String constructor.

For convenience there are a number of built int conversions provided that cannot leverage the String constructor:

• Pattern - Allows regular expression to be set
• Class<?> - Tries to load a class through the class loader of the configuration interface
• boolean - Converts wrappers and primitive boolean to 0 (false) or non-0 (true) and vice versa.
• Numbers - Converts any known Number subclass to another Number subclass, including the primitive types.
• Enums - If the return type is an enum, it will use the valueOf method to get an instance.

Example

The following example shows a very simple metatype configuration interface:

package aQute.metatype.samples; import aQute.bnd.annotation.metatype.Meta.*; @OCD public interface Config { int port(); }

If the bnd.bnd file contains:

-metatype: *

Then bnd will detect this class as a Metatype and it generates the following XML in `OSGi-INF/metatype/aQute.metatype.samples.Config.xml

public void updated(Dictionary properties) 
  throws ConfigurationException {
  if ( properties != null ) {
    Config config = Configurable.createConfigurable(
      Config.class, properties);
    System.out.println(config.port());
  }
}   }