OSGi services: Generate config xmls through annotations

[davidgraeff]

Abstract

In Declarative Services 1.3 there are Configuration Property Types, so you can write:

@interface ServerConfig {
  String host() default "0.0.0.0";
  int port() default 8080;
  boolean enableSSL() default false;
}

@Component
public class ServerService {
  @Activate public void activate(ServerConfig cfg) {
  }
}

Manual parsing of property parameters is something you wouldn't do in DS 1.3.
On DS 1.2, we can at least establish a similar pattern:

class ServerConfig {
  String host = "0.0.0.0";
  int port = 8080;
  boolean enableSSL = false;
}

@Component
public class ServerService {
  @Activate public void activate(Map<String,Object> cfg) {
     ServerConfig config = new Configuration(cfg).as(ServerConfig.class);
  }
}

The documentation should be clear about this pattern, it might even be made mandatory for new code.
Now we do have a class that perfectly describes the full configuration. Why don't we go one step further.

Generate config xmls through annotations

If we start to annotate those configuration classes, at some point we are able to fully generate the "config-description:config-descriptions" xml files.

I suggest to add all necessary annotations to a "core.config.annotation" namespace within the core bundle. An annotated class could look like this:

@ServiceConfiguration(uri="mqtt:mqttembeddedbroker")
class ServerConfig {
  @Description("The host to connect to")
  @Label("Embedded broker host name")
  public @Required String host = "0.0.0.0";

  @Description("The port to connect to")
  @Label("Embedded broker host port")
  public int port = 8080;

  @Description("Use a secure on non-secure connection")
  @Label("Enable SSL")
  public @Advanced boolean enableSSL = false;

  public final bool ignored_value_because_final;
  public transient bool ignored_value_because_transient;
}

WDYT?

[maggu2810]

I like and use that feature of "Declarative Services 1.3" most of the time. There is also a simple to understand article here: http://njbartlett.name/2015/08/17/osgir6-declarative-services.html

I would be more happy if we can change our minimum requirements to "OSGi Release 6", but as this does not seem to happen soon (or are there any news?)...

Shouldn't we use a "non-config" package for that annotations?
The mechanism should be usable from every bundle also the ones that don't depend on "config".
I see, that we cannot use the currently existing configuration implementations then, but perhaps it would be okay to use a separate implementation for the parsing etc.

[davidgraeff]

The mentioned "Configuration" class for de-marshaling is within "config.core". As soon as a service requires configuration it should depend on "config.core" anyway, I thought.
In #5292 I moved the de-marshaling code to ConfigUtils. That helper class or parts of it can be moved to a separate bundle of course.

[maggu2810]

The bundle org.eclipse.smarthome.core must not depend on org.eclipse.smarthome.config.core (so no package import of config.core). If we have a custom implementation for "configuration property types", it would be nice to use it in DS components of esh.core, too.

[davidgraeff]

@maggu2810 I have adapted the proposal. Annotations would go to core.config.annotations within the core bundle.

[maggu2810]

I missed that feature a few days ago: https://github.com/eclipse/smarthome/pull/5231/files#diff-fffa1e559c1bd5be08121b24f97873e0R71 😉

[davidgraeff]

@maggu2810 I know :) I have adapted the former MqttService PR (#4173) which is ready to be merged now by the way, and it does it the easier way.

[maggu2810]

@davidgraeff If you haven't read it already and are interested in: Configuration Updater

[davidgraeff]

Thanks @maggu2810, a good read. And I read on on this topic and apparently at least bnd can generate xml files out of OSGi R6 @interface configuration descriptions. So this issue is basically about replicating functionality of R6 to make life for binding developers easier.