# orion.cm.managedservice

Contributes a Managed Service. A Managed Service is a service that can receive configuration data.

## Service properties

A Managed Service must define the following property:

pid
  `String` Gives the PID for this Managed Service.

## Service methods

A Managed Service must implement the following method:

updated(properties)
  The ConfigurationAdmin invokes this method to provide configuration to this Managed Service. If no configuration exists for this Managed Service's PID, `properties` is `null`. Otherwise, `properties` is a dictionary containing the service's configuration data.

## Examples

This minimal example shows the implementation of a plugin which registers a Managed Service under the PID "example.pid". When its updated() method is called, it simply prints out what it received:

     define(["orion/plugin"], function(PluginProvider) {
         var provider = new PluginProvider();
         provider.registerService(["orion.cm.managedservice"],
             {  pid: "example.pid"
             },
             {  updated: function(properties) {
                    if (properties === null) {
                      console.log("We have no properties :(");
                    } else {
                      console.log("We got properties!");
                      console.dir(properties);
                    }
                }
             });
         provider.connect();
     });

Here is a larger example, showing how a validation service (a spellchecker that checks for any occurrences of the misspelling "definately") might accept options through its configuration properties. The service implementation in this example is both a validator and a Managed Service.

     define(["orion/plugin"], function(PluginProvider) {
         var provider = new PluginProvider();
         var options;
         provider.registerService(["orion.cm.managedservice", "orion.edit.validator"],
             {  pid: "example.validator",
                contentType: ["text/plain"]
             },
             {  updated: function(properties) {
                    if (properties === null) {
                        // No configuration, use default
                        options = { enabled: true };
                    } else {
                        options = { enabled: !!properties.enabled };
                    }
                },
                checkSyntax: function(title, contents) {
                    if (!options.enabled) {
                        return { problems: [] };
                    }
                    var problems = [];
                    contents.split(/\r?\n/).forEach(function(line, i) {
                        var index;
                        if ((index = line.indexOf("definately") !== -1) {
                            problems.push({
                                description: "Misspelled word",
                                line: i+1,
                                start: index,
                                end: index+10,
                                severity: "warning"
                            });
                        }
                    });
                    return { problems: problems };
                }
             });
         provider.connect();
     });

The `updated()` method here checks its configuration dictionary for a boolean `enabled` property that determines whether the validator is active. In the case of `null` properties, the service uses a reasonable default. (It's a best practice for configurable services to behave sanely when no configuration has been defined for them.)

Note that, by virtue of the configuration framework's guarantee that `updated()` is called before all other service methods, our `checkSyntax()` method can safely assume that the `options` variable has been set.