Figure 1: mConsole General Property Editor
The Config Demo demonstrates the usage of the Config Bundle defined by the OSGi Service Compendium and part of the OSGi bundle group of the Framework Professional Edition Package . The demo is provided as a simple bundle called Config Demo Bundle.
Contents:
The JAR file of the Config Demo bundle is located in the demo/bundles directory and is called configdemo.jar.
The demo itself, its sources and script files are located in the demo/framework/config directory. There is a mk script for rebuilding the demo, an install.txt file for installation through the Kit Manager Bundle, a readme.txt file with short description of the demo and the demo folder, holding the package of the demo source files. There is also a JARINFO file which is automatically generated by the ProSyst mBedded Builder project for the Framework Professional Edition Package demos and serves to enable automatic creation of a JAR file from mBedded Builder.
To start the Config Demo bundle you only need the Config Bundle running on the framework. This bundle is a part of the system bundle group so it is installed by default. You only need to install the demo bundle and the demo is started. You may use mConsole, the HTTP Administrator or the framework console with the following command:
>$fw.i -s ../../../demo/bundles/configdemo.jar
The Config Demo only class is ConfigDemo. It is placed in a demo.config
package. The demo bundle registers an org.osgi.service.cm.ManagedService
with configuration PID mbs.config.demo.pid. The bundle has a configuration
XML file in its JAR, with its initial configuration and metatype information.
This is config.xml in the demo/framework/config/demo/config directory.
The bundle manifest file is in the same directory.
The bundle manifest file determines the configuration XML file by the Config
manifest tag. This tag has three attributes: xml, pid
and name.
xml attribute states the place of the XML file in the JAR.
The XML file of the Config Demo is in a demo/config directory and
the value of the xml attribute is /demo/config/config.xml.
pid attribute gives the service PID for the bundle configuration.
The PID of the Config Demo is mbs.config.demo.pid and so is the
value of this attribute. name attribute is optional. It gives the name of the general
property editor for the bundle in mConsole. If this attribute is
not present, the value of the <name> tag in the XML file
is considered. The value of the name manifest attribute of the
Config manifest tag in the Config Demo bundle manifest
is Config Demo. Here is the whole Config manifest tag:
Config: xml=/demo/config/config.xml; pid=mbs.config.demo.pid; name=Configuration
Demo
The XML file of the Config Demo defines the elements of the configuration and only one configuration property. The following table gives a description of the configuration elements:
|
The configuration property has the following attributes:
|
The Config Demo is in fact a simple TCP server with configurable port. Thus it demonstrates how the configuration properties may be used as a simple way to affect the work of a bundle at runtime without the need to restart it and especially to alter its code.
The bundle class implements two interfaces - org.osgi.framework.BundleActivator
and org.osgi.services.cm.ManagedService, and extends java.lang.Thread.
The Bundle Activator interface turns the demo into a bundle. In its start
and stop methods a single service is registered and unregistered.
This is the Managed Service, which will provide the bundle with the ability
to be configured. The registration of a Managed Service requires a service.pid
registration property to be given. The value of this property is the configuration
PID, which must obligatory match exactly the PID given in the bundle manifest
file and the <id> tag of the configuration XML file. The
registered service object is the ConfigDemo class itself, because
it provides the implementation of the Managed Service interface.
. . .
private ServiceRegistration msReg;
. . .
Hashtable properties = new Hashtable(1, 1f);
properties.put("service.pid", "mbs.config.demo.pid");
msReg = bc.registerService(ManagedService.class.getName(), this, properties);
. . .
|
The implementation of the Managed Service interface requires a single method
- updated. This method will be called by the Config Bundle on activation
of the bundle and every time a modification to the bundle configuration is made.
The method receives as a parameter a Dictionary object holding the new configuration
properties. Note that the updated method can receive null for configuration
properties. This can happen if there is no configuration with the same service.pid
as the one of the Managed Service, if there is a configuration but it has no
properties, or if the configuration is being deleted.
. . .
int port = -1;
. . .
public void updated(Dictionary properties) throws ConfigurationException {
. . .
port = ((Integer)properties.get("port")).intValue();
. . .
|
The updated method of the Config Demo does not make a validation
check of the received property. The limitations to the acceptable data are stipulated
in the metatype information. Here, the data format, the minimum and the maximum
value are totally sufficient to determine setting of a valid port.
The value of the configuration property is read and a server socket is opened
at this port in a separate method called startServer. When the
bundle is started for the first time, the server thread that listens for client
connections to this port, is started. The body of thread is placed in the run
method of this class, which creates a new Config Demo thread named Config
Demo Server.
The startServer method also closes the existing socket and creates
a new one each time the configuration is updated with a new port. At the same time the server thread waits for the modification
process to be completed.
When registered, a configuration may be viewed and altered in the config command group of the framework console, from mConsole or from the HTTP Administrator (Portal Package).
From config console command group you can change the value of the port:
config>$setvalue mbs.config.demo.pid port 7777
The printing on the system console indicates that the server socket change has been performed successfully.
Each registered configuration is represented as a subnode to the registering bundle in mConsole. The metatype information is represented by a general property editor. The top label gives the name and PID of the configuration. The properties are arranged in input control components, named after the property name and appropriate for the property data type, which is listed after the component. In this case, the property is an integer number and a text field is used for its input. You may use it to change the port property.
Figure 1: mConsole General Property Editor
You may change the server port by typing the new one in the field or using
the up and down arrows. After you enter the new value, click the Set
button at the bottom. The console output shows that the port change has been
performed successfully. If you have entered a value out of the limitations set
by the minValue and the maxValue attributes of the
Port property, the port will be set to the nearest boundary value. The Default
button will set the value given in the value property attribute.