Managing Configurations via API

Creating Configurations

To access a configuration, make sure you have the relevant configuration type exported in the Config Tree. For example, if your application is not the one exporting the type, use the cft.list command in the runtime console to see available configurable objects or the API of the Config Tree Admin service (use the getConfigurableTypes() method).

Follow these steps to create a new configuration and add it to the Config Tree:

1. Create the configuration data:
   1. Create a root ConfigNode object to hold the data of the configurable.
   2. Create the structure of ConfigNode objects to attach to the root node - nesting them and setting needed default property values.
   3. Add the structure to the root ConfigNode by calling its addChild method.
2. Get the Config Tree Admin service from the framework service registry.
3. Invoke the getConfigurable method of the Config Tree Admin service to get the Configurable for the target type of configuration.
4. Save the root ConfigNode to the Config Tree by invoking the setConfig method of the Configurable.

Editing Existing Configurations

Retrieving Configurations

To retrieve an existing configuration:

1. Get the ConfigTree Admin service (com.prosyst.mbs.services.configtree.ConfigTreeAdmin) from the framework service registry.
2. Call the getConfigurable method and pass the name (type) of the configuration that you want to retrieve.

You can retrieve the names of all available configurations (as a string array) by calling the getConfigurableTypes method.

Adding/Appending Nodes

A configuration is represented by a Configurable object. Its nodes are represented by ConfigNode objects.

To retrieve a config node:

1. Retrieve the desired configuration.
2. Use one of the following methods:
   1. getConfig() - Returns the root ConfigNode and then you can use the children and getChild methods to navigate the tree structure.
   2. getConfig(String[] tree)- Pass a String[] holding all parent nodes of the one you want to retrieve. You must not include the root config node in the array. For example, calling getConfig(new String[] {"X10","HomeDevice23"}) will make the Config Tree retrieve the root config node and its sub-node called "X10" and then its sub-node called "HomeDevice23".

You can append a new node to any config node by calling the addChild(ConfigNode child) method on the desired node and passing a config node object as a child.

To save persistently the changes, store the root ConfigNode to the Config Tree by invoking the setConfig method of the Configurable object. Otherwise, the modifications will be lost upon restart of the Config Tree. You can check the execution status by using the returned Status object.

Adding/Editing Configuration Properties

A node stores configuration properties.

• You can retrieve the value of any of the node's properties by calling the getProperty method
• You can retrieve the keys of all properties of the node by calling the keys method.

To add a new property to the node, use the setProperty method. Again, call the save method to apply your changes.

//Retrieve the Config Tree

service ConfigTreeAdmin configtreeadmin = (ConfigTreeAdmin)

service; Configurable devicesconfiguration = configtreeadmin.getConfigurable("devices");

//Retrieve the root node

ConfigNode root = devicesconfiguration.getConfig();

//Construct a new node

ConfigNode child = new ConfigNode("01");

child.setProperty("startTime", new Long("1352723555000"));

child.setProperty("UID", "0002");

child.setProperty("vendor", "test");

//append it to the root

root.addChild(child);

//Apply your changes

root.save()

If you are accessing the ConfigTree via the JSON-RPC Remote API you can edit a configuration by exporting it as an XML file, editing the file and than importing it back to ConfigTree.

Importing and Exporting Configurations

Importing/Exporting Several Configurations Together

You can import or export configuration data for several configurations at the same time by placing configurable XML or BIN files in a ZIP file.

Follow the structure described here to create such ZIP files for importing.

1. Retrieve the Config Tree Admin OSGi service (com.prosyst.mbs.services.configtree.ConfigTreeAdmin).
2. Call the importZip or exportZip methods (or configtree/importZip and configtree/exportZip if you are using the JSON-RPC API) and pass the following arguments:
   • A java.util.zip.ZipOutputStream or java.util.zip.ZipInputStream for the ZIP file holding the configuration data.
   • An array of the configurable types of the configurations you want to import/export.
   • A constant that represents the file format in which the configuration data will be exported/imported.

The following example retrieves the configurable types of all configurations that are registered in the system (using the getConfigurableTypes method ) and exports them in the config.zip file.

//Construct a zip output stream

File file = new File("D:\\config.zip");

FileOutputStream out = null;

try {

out = new FileOutputStream(file);

} catch (FileNotFoundException e) {

e.printStackTrace();

}

ZipOutputStream outzip = new ZipOutputStream(out);

//Retrieve all configuration in the system

String[] configurations = configtreeadmin.getConfigurableTypes();

//The ConfigTree Admin Service is stored under the configtreeadmin variable

configtreeadmin.exportZip(outzip, configurations, ConfigTreeAdmin.XML);

try {

outzip.finish();

outzip.close();

} catch (IOException e)

{ e.printStackTrace();

}

Importing/Exporting Individual Configuration Nodes

You can import and export individual configuration nodes.

1. Retrieve the Config Tree Admin OSGi service (com.prosyst.mbs.services.configtree.ConfigTreeAdmin).
2. Call the importConfig or exportConfig method and pass the following arguments:
   • The type of the configuration that contains the node.
   • A file where it should be imported from or exported to.
   • A constant that represents the file format that the configuration node will be exported to/imported from.
   • If you are using the exportConfig method, pass the name of the node you want to export, predeceased by the names of all its parent nodes. If you are using the importConfig method, pass the name of the node to which the imported one should be appended, again predeceased by the names of all its parents.

For example: If you have a configuration with a node with a name "A" that contains a sub node with name "B", you can export "B" by calling the exportConfig method with path {"A", "B"}. To import "B" to the same location from where you exported it, call importConfig with path {"A"}.

• If exportConfig() is used a Status of executed operation will be returned.

When you want to import a node on the first level (directly after the root), pass an empty array as path.

The following example loads the node that is contained in the AbsoluteTimerCondition1.xml file to the first level of the AbsoluteTimerCondition configuration.

File fileforimport = new File("D:\\AbsoluteTimerCondition1.xml");

FileInputStream in=null;

try {

in = new FileInputStream(fileforimport);

} catch (FileNotFoundException e) {

e.printStackTrace();

} String[] path = {};

//The import method returns a result object

Status result = configtreeadmin.importConfig("AbsoluteTimerCondition", in, ConfigTreeAdmin.XML, path);

if (!result.isOK()){

for (int i = 0; i < result.getErrors().length; i++) {

System.out.println(result.getErrors()[i]);

} }

You cannot create a new configuration by importing data from a file, because each configuration has to be registered as an OSGi service but you can add a new node to an existing configuration from a file.