Difference between revisions of "Orion/Documentation/Developer Guide/Configuration services"

From Eclipsepedia

Jump to: navigation, search
(orion.cm.configadmin)
(orion.cm.configadmin)
Line 39: Line 39:
  
 
; getConfiguration(pid)
 
; getConfiguration(pid)
: Returns a Configuration with the given PID, creating a new Configuration if one does not already exist.
+
: Returns the Configuration with the given PID from the database. If no such Configuration exists, a new one is created and then returned.
 
; listConfigurations()
 
; listConfigurations()
: Returns an array of all current Configuration objects.
+
: Returns an array of all current Configuration objects from the database.
  
 
Refer to <code>orion.cm.ConfigurationAdmin</code> in the client API reference for a full description of this service's API methods.
 
Refer to <code>orion.cm.ConfigurationAdmin</code> in the client API reference for a full description of this service's API methods.

Revision as of 13:12, 27 August 2012

Contents

Overview

Orion provides a number of service APIs related to service configuration.

Managed Services

A service may need configuration information before it can perform its intended functionality. Such services are called Managed Services. A Managed Service implements a method, updated(), which is called by the Orion configuration framework to provide configuration data to the service. (As with all service methods, updated() is called asynchronously.) Configuration data takes the form of a dictionary of key-value pairs, called properties. If no configuration data exists for the Managed Service, null is passed.

A Managed Service needs to receive its configuration information before the service is invoked to perform other work. For example, a configurable validation service would want to receive any custom validation options (or null, if no custom options were configured) before actually performing any validation. For this reason, the framework guarantees that a Managed Service's updated() method will be called prior to any other service methods the service may implement. Service developers

Managed Services can be contributed by registering against the orion.cm.managedservice service name. Every Managed Service must provide a service property "pid" giving a PID (persistent identifier). The PID uniquely identifies the Managed Service, and serves as a primary key for its configuration information.

The Orion concept of a Managed Service is analogous to the OSGi Managed Service.

Meta Typing

A Metatype describes the shape of configuration data. In other words, it specifies what property names can appear in the properties dictionary, and what data types (string, boolean, number, etc) their values may have. Metatype information is defined in terms of "object classes", which can be reused. Metatype information is associated with a Managed Service's PID. Metatype information is optional, so not every Managed Service need have Metatype information associated with it.

Metatype information can be contributed by registering a service with the orion.cm.metatype service name.

The Orion concept of a Metatype is analogous to the OSGi Metatype.

Configuration management

Configuration data is managed by a ConfigurationAdmin service, which maintains a database of Configuration objects. The ConfigurationAdmin monitors the service registry and provides configuration data to Managed Services that are registered. Orion's implementation of ConfigurationAdmin persists configuration data to a Preferences Service.

In JavaScript code, configuration information is represented as Configuration objects (refer to "orion.cm.Configuration" in the client API reference for details), which are returned by the ConfigurationAdmin's service methods. Because the ConfigurationAdmin service is currently only accessible to page code, Configuration objects can only be managed from page code. Managed Services currently cannot interact with Configurations directly, and can only receive configuration information via their updated() method.

The Orion ConfigurationAdmin service is analogous to the OSGi ConfigurationAdmin.

Settings

On top of the basic configuration and metatype APIs, Orion also provides a higher-level Settings API.

orion.cm.configadmin

The orion.cm.configadmin service, also called ConfigurationAdmin, provides management of configuration information. Internally, the ConfigurationAdmin service is used by the Plugin Settings page to manage the values of settings.

The service methods are:

getConfiguration(pid)
Returns the Configuration with the given PID from the database. If no such Configuration exists, a new one is created and then returned.
listConfigurations()
Returns an array of all current Configuration objects from the database.

Refer to orion.cm.ConfigurationAdmin in the client API reference for a full description of this service's API methods.

Here is an example of how to use the ConfigurationAdmin service to print out all existing configurations and their property values:

var configurations = serviceRegistry.getService("orion.cm.configadmin").listConfigurations().then(function(configurations) {
        configurations.forEach(function(configuration) {
            var properties = configuration.getProperties();
            var propertyInfo = Object.keys(properties).map(function(propertyName) {
                if (propertyName !== "pid") {
                    return "\n        " + propertyName + ": " + JSON.stringify(properties[propertyName]) + "\n";
                }
            }).join("");
            console.log("Configuration pid: " + configuration.getPid() + "\n"
                      + "  properties: {" + propertyInfo + "\n"
                      + "  }");
        });
});

The result might look something like this:

Configuration pid: nonnls.config
  properties: {
        enabled: false
  }
Configuration pid: jslint.config
  properties: {
        options: "laxbreak:true, maxerr:50"
  }

orion.cm.managedservice

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

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 will be null. Otherwise, properties is an object containing the service's configuration data.

orion.cm.metatype

Contributes type definitions, which may be associated with a service's configuration.

See also

Plugging into the settings page