Config Bundle contains the implementation of the OSGi Configuration Admin Service. The Config Bundle adds more functionality to OSGi basics by supporting initial load of configurations before bundles are started, giving remote access to its services, and providing utilities for administration of applications wishing to modify configurations.
Contents:
The Config Bundle uses packages from DB Bundle, ProSyst Util Bundle, OSGi Library Bundle and ProSyst Metatype Bundle. These bundles should be started in order to use the Config Bundle. The Config Bundle as well as the other four it depends on, are a part of the ProSyst base bundle configuration and they are active by default.
The JAR file of the Config Bundle is config.jar from the bundles directory.
All packages imported by the Config Bundle are exported by bundles in the Framework Package:
|
The Config Bundle exports the com.prosyst.mbs.services.config.cm
package, which contains a service for remote configuration management.
The Configuration Admin, defined by the OSGi Configuration Admin Specification and implemented in the Config Bundle, delivers two main functions:
Configuration is the process of assigning and providing configuration data
to bundles, running in the OSGi framework. An application that wants to become
configurable through the Configuration Admin, should register a Managed Service
(org.osgi.service.cm.ManagedService) or Managed Service Factory
(org.osgi.service.cm.ManagedServiceFactory) according to its needs.
The Configuration Admin provides management applications with access to exported
configurations in the form of org.osgi.service.cm.Configuration
objects.
The singleton configurations and factory configurations are stored persistently in the DB Bundle in a custom database called "CONFIG".
A service implementing ManagedService will receive a single set
of properties when registered, or when a configuration object is created for
it in the Configuration Admin, whichever happens later. It is also informed
when its configuration object is changed in the Configuration Admin by a management
application.
A service implementing ManagedServiceFactory will receive from
0 to n configuration sets when it registers in the OSGi framework.
The factory is informed of updates and deletion of generated configuration objects
in the Configuration Admin storage.
The following source is an example of a ManagedService implementation:
. . .
public class ConfigTest implements ManagedService, BundleActivator {
ServiceRegistration reg;
Hashtable configuration;
public void start(BundleContext bc) {
reg = bc.registerService(ManagedService.class.getName(),
this, getDefaults());
}
private Hashtable getDefaults() {
Hashtable defaults = new Hashtable();
defaults.put("port", "12345");
defaults.put("product", "device");
defaults.put("baud", "9600");
defaults.put(Constants.SERVICE_PID, "com.acme.serialport.device");
return defaults;
}
public synchronized void updated(Dictionary configuration) {
if (configuration == null){
reg.setProperties(getDefaults());
} else {
reg.setProperties(configuration);
}
}
public void stop(BundleContext bc) {
}
. . .
}
|
For the needs of remote management, a configuration
holding real data is represented as a CMDictionary object, which
extends com.prosyst.util.io.Externalizable and hence can be transported
over PMP and stored in the DB Bundle. A CMDictionary stores properties
with case sensitive keys.
To execute configuration management remotely over PMP,
an application should use the com.prosyst.mbs.services.config.cm.CMRemoteManager
service.
The Config Bundle is responsible for loading a bundle's initial configuration data on the basis of metadata exported by the bundle. Management of configuration metadata uses the ProSyst Metatype API, which extends the OSGi Metatype API by allowing definition of object class instances for initial generation, of attribute and object class modifiers and properties, etc.
Configuration metatypes are handled by the ProSyst Metatype Bundle, which implements the OSGi Metatype Specification and supports the ProSyst Metatype API. The bundle's Metadata Manager processes available configuration metatypes and delivers the information to the Config Bundle.
Configuration metadata should be put in a Metatype Provider with ID equal to Managed Service's or Managed Service Factory's PID and with a "template" ObjectClassDefinition again with ID equal to the PID.
For a configuration factory, the Metatype Provider can also provide a configuration object in its metatype definition, which will be automatically generated and loaded in the Configuration Admin storage at bundle installation in the case of XML metadata and at bundle start in the case of Metatype Provider service.
A bundle developer has two options for providing configuration metadata - implement a service or write an XML.
Implement a Metatype Provider Service. In this case, a configuration metatype should be registered as an org.mbs.services.metatype.MetaTypeProviderExtern service.
To indicate that the Metatype Provider contains configuration metadata, it should be registered with the following String properties:
org.osgi.service.metatype.Constants.SERVICE_PID - Indicates
the PID of the configuration this Metatype Provider is designed for.The ObjectClassDefinition, representing a configuration,
should be an instance of the ObjectClassDefinitionEx interface
and its attributes - AttributeDefinitionEx instances. To indicate
if a configuration and its attributes should be loaded in the Configuration
Admin storage, the ObjectClassDefinition should have a modifier (returned
by the getModifier method) with key load and value true.
Otherwise, the
configuration should be explicitly created with the config.create console command or with the Defaults mConsole option for the corresponding metatype. Optional attributes can be loaded by default if their load modifier
is true.
If the configuration is factory, the Metatype Provider can implement the
getConfigurationObjectsmethod so as to returnObjectClassDefinitionExinstances representing configuration objects to be automatically produced by the Config Bundle.Write a metadata XML resource. XML metadata should be created in accordance with the ProSyst proprietary DTD or according to the metatype XML Schema from the OSGi Service Platform, Service Compendium.
A bundle, which provides
its metadata in the ProSyst proprietary XML format, must use the Config (for ManagedService)
or FactoryConfig (for ManagerServiceFactory) manifest
header, or both. Their syntax is:
header := "Config"|"FactoryConfig"":"1*(,
metatype_provider)
metatype_provider := (xml=xmlresource_path; pid=service_pid; name=display_name[;
version=major.minior.micro])
For example:
Config: xml=myconfigs/myhttpconfig.xml; pid=my.http.pid;
name=My HTTP Configuration
Following is an example of metadata XML for an HTTP server in the format introduced by ProSyst:
<?xml version="1.0" encoding="UTF-8"?> |
If the configuration metatype will be developed in compliant with the OSGi metatype XML schema, it should be available in the bundle JAR file in the OSGI-INF/metatype directory.
Listing 2.2 contains the same configuration metatype as 2.1 but this time defined according to the OSGi metatype XML schema.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <metatype:MetaData xmlns:metatype="http://www.osgi.org/xmlns/metatype/v1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <OCD name="HTTP Server Configuration" id="httpConfig" description="HTTP Server Socket Configuration"> |
When a bundle is installed in the OSGi framework, the ProSyst Metatype Bundle inspects the bundle for availability of configuration metadata. This is determined by looking for Config and FactoryConfig "service.pid" properties or headers in the bundle manifest. If there is a match, the ProSyst Metatype Bundle sends extracted metadata to the Config Bundle, which converts it into a new configuration instance in the following way:
Finally, the Configuration Admin passes the configuration data to the target bundle.
If the Configuration Admin already holds configurations with the same PID or factory PID, then the default configurations will not be loaded. This allows management entities to predefine configuration data that differs from the default one.
Note: The Config Bundle does not load configurations with duplicate PIDs and factory PIDs.
If a bundle is uninstalled, its configurations are deleted from the Configuration Admin. This is done in compliance with OSGi Configuration Admin Service Specification requirements for deletion of only those configurations which are tightly bound to a bundle.
When a bundle is updated, its configuration data is preserved in the configuration database in binary format. If the update includes changes in a configuration metatype, the Config Bundle will update the information in its database as well.
The interface of the Configuration Admin service is org.osgi.service.cm.ConfigurationAdmin.
This is a service for administering configuration data. The purpose of the Configuration
Admin service is to provide management bundles with access to available configurations,
represented as Configuration objects.
The interface of the CM Remote Manager (com.prosyst.mbs.services.config.cm.CMRemoteManager)
is designed for remote usage over PMP.
It has functionality similar to org.osgi.service.cm.ConfigurationAdmin.
The Config Bundle registers a com.prosyst.util.pcommands.PluggableCommands
service that provides the console commands of the config group. Refer
to the "Console Commands" section for description of the config
command.
The following commands are available in the config group of the framework console:
|
|