154 Residential Device Management Tree Specification

154.1 Introduction

The chapter defines the Device Management Tree (DMT) for residential applications called the Residential Management Tree (RMT). This RMT is based on the Dmt Admin Service Specification. The RMT allows remote managers to manage the residential device through an abstract tree. As this tree is an abstract representation, different management protocols can use the same underlying management components, the Dmt Admin Plugins, in the OSGi framework.

This chapter requires full understanding of the concepts in the Dmt Admin Service Specification and uses its terminology.

154.1.1 Essentials

The following essentials are associated with the Residential Management Tree specification:

  • Complete - The RMT must cover all functionality to completely manage an OSGi Framework as defined by OSGi Core Release 8.

  • Performance - The RMT runs on devices with limited resources.

  • Searchable - Provide an efficient way to search the RMT remotely.

  • Services - Provide efficient access to standardized services like the Log Service.

154.1.2 Entities

  • Remote Manager - The entity that remotely controls an OSGi Framework.

  • Management Agent - An entity running on the device that is responsible for the management of the local OSGi Framework. It usually acts as a proxy for a Remote Manager.

  • Protocol Adapter - Communicates with a Remote Manager and translates the protocol instructions to instructions to a local Management Agent.

  • DMT - The Device Management Tree. This is the general structure available through the Dmt Admin service.

  • RMT - The Residential Management Tree. This is the part of the DMT that is involved with residential management.

Figure 154.1 Device Management Architecture

Device Management Architecture

154.2 The Residential Management Tree

The OSGi node is the root node for OSGi specific information. This OSGi node can be placed anywhere in the Device Management Tree and acts as parent to all the top level nodes in this specification. Therefore, in this specification the parent node of, for example, the Framework node is referred to as $, which effectively represents the OSGi node. The description of the nodes are using the types defined in OSGi Object Modeling.

The value of $ for a specific system can be defined with the following Framework property:

org.osgi.dmt.residential

For this specifications, the RMT Consists of the following top level nodes:

  • Framework - Managing the local Framework

  • Filter - Searching nodes in the DMT

  • Log - Access to the log

154.3 Managing Bundles

The Framework node provides a remote management model for managing the life cycle of bundles and inspecting the Framework's state.

To change the state, for example install a new bundle, requires an atomic session on at least the Framework node. The model is constructed to reflect the requested state. When the session is committed, the underlying Plugin must effectuate these requested states into the real state.

For example, to install a bundle it is first necessary to create a new Bundle child node. The Bundle node is a MAP node, the name of the child node is the location of the bundle as given in the installBundle(location,input stream) method and returned from the getLocation() method.

This location should not be treated as the actual URL of the bundle, the location is better intended to be used a management name for the bundle as the remote manager can choose it. It is normally best to make this name a reverse domain name, for example com.acme.admin. The name " System Bundle" is a reserved name for the system bundle. The Framework management plugin must therefore not treat the location as a URL.

Creating the child node has no effect as long as the session is not committed. This new Bundle node automatically gets the members defined in the Bundle type.

The URL node should be set to the download URL, the URL used to download the JAR file from. The URL node is used as the download URL for an install operation (after the node is created newly) or the update location when the node is changed after the bundle had been installed in a previous session. Creating a new Bundle node without setting the URL must generate an error when the session is committed.

To start this newly installed bundle, the manager can set the RequestedState to ACTIVE. If this bundle needs to be started when the framework is restarted, then the AutoStart node can be set to true. If there bundles to be uninstalled then their RequestedState node must be set to UNINSTALLED as it is not possible to delete a Bundle node. The RequestedState must be applied after the bundle has been installed or updated. An uninstalled bundle will be automatically removed from the RMT.

The RequestedState node is really the requested state, depending on start levels and other existing conditions the bundle can either follow the requested state or have another state if, for example, its start level is not met. The RequestedState must be stored persistently between invocations, its initial value is INSTALLED.

The manager can create any number of new Bundle nodes to install a number of bundles at the same time during commit. It can also change the life cycle of existing bundles. None of these changes must have any effect until the session is committed.

If the session is finally committed, the Plugin must compare the state in the Dmt Admin tree with the actual state and update the framework accordingly. The order in which the operations occur is up to the implementation except for framework operations, they must always occur last. After bundles have been installed, uninstalled, or updated, the Plugin must refresh all the packages to ensure that the remote management system sees a consistent state.

Downloading the bundles from a remote system can take substantial time. As the commit is used synchronously, it is sometimes advisable to download the bundles to the device before they are installed.

If any error occurs, any changes that were made since the beginning of the last transaction point must be rolled back. An error should be reported. The remote manager therefore gets an atomic behavior, either all changes succeed or all fail. A manager should also be aware that if its own bundle, or any of its dependencies, is updated it will be stopped and will not be able to properly report the outcome to the management system, either a failure or success.

154.3.1 Bundle Life Cycle Example

For example, the following code installs my_bundle, updates up_bundle, and uninstalls old_bundle:

String $ = ... // get the OSGi node
DmtSession session = admin.getSession($ + "/Framework",
                DmtSession.LOCK_TYPE_ATOMIC);
try {
  session.createInteriorNode("Bundle/my_bundle");
  session.setNodeValue("Bundle/my_bundle/URL", new DmtData(
    "http://www.example.com/bundles/my_bundle.jar"));
  session.setNodeValue("Bundle/my_bundle/AutoStart",
    DmtData.TRUE_VALUE);
  session.setNodeValue("Bundle/my_bundle/RequestedState",
    new DmtData("ACTIVE"));

  session.setNodeValue("Bundle/up_bundle/URL", new DmtData(
    "http://www.example.com/bundles/up_bundle-2.jar"));

  session.setNodeValue("Bundle/old_bundle/RequestedState",
    new DmtData("UNINSTALLED"));
  try {
    session.commit();
  } catch (Exception e) {
     // failure ...
     log....
  }
} catch (Exception e) {
  session.rollback();
  log...
}

154.3.2 Framework Restart

There are no special operations for managing the life cycle of the Framework, these operations are done on the System Bundle, or bundle 0. The framework can be stopped or restarted:

  • Restart - Restarting is an update, requiring the URL to be set to a new URL. This must shutdown the framework after the commit has succeeded.

  • Stopping - Stopping is setting the RequestedState to INSTALLED

If the URL node has changed, the RequestedState will be ignored and the framework must only be restarted.

Sessions that modify nodes inside the Framework sub-tree must always be atomic and opened on the Framework node. The Data Plugin managing the Framework node is only required to handle a single simultaneous atomic session for its whole sub-tree.

For example, the following code restarts the framework after the commit has succeeded.

DmtSession session = admin.getSession($ +"/Framework",
                DmtSession.LOCK_TYPE_ATOMIC);
session.setNodeValue("Bundle/System Bundle/URL", 
  new DmtData(""));
session.commit();

154.3.3 Access to Wiring

During runtime a bundle is wired to several different entities, other bundles, fragments, packages, and services. The framework defines a general Requirement-Capability model and this model is reflected in the Wiring API in OSGi Core Release 8. The Requirement-Capability model maps to a very generic way of describing wires between requirers and providers that is applicable to all of the OSGi constructs.

The Core defines namespaces for:

  • osgi.wiring.bundle - The namespace for the Require-Bundle header. It wires the bundle with the Require-Bundle header to the bundle with the required Bundle-SymbolicName and Bundle-Version header.

  • osgi.wiring.host - The namespace for the Fragment-Host header. It wires from bundle with the Fragment-Host header to the bundle with the required Bundle-SymbolicName and Bundle-Version header.

  • osgi.wiring.package - The namespace for the Import/Export-Package header. It wires from bundle with the Import-Package header to the bundle with the Export-Package header.

In the Core API, the wiring is based on the Bundle revisions. However, this specification requires that all bundles are refreshed after a management operation to ensure a consistent wiring state. The management model therefore ignores the Bundle Revision and instead provides wiring only for bundles since the manager is unable to see different revision of a bundle anyway. The general Requirement-Capability model is depicted in Figure 154.2.

Figure 154.2 Requirements and Capabilities and their Wiring

Requirements and Capabilities and their Wiring

The core does not specify a namespace for services. However, services can also be modeled with requirements capabilities. The registrar is the provider and the service properties are the capability. The getter is the requirer, its filter is the requirement. This specification therefore also defines a namespaces for services:

osgi.wiring.rmt.service

This namespace is defined in osgi.wiring.rmt.service Namespace.

To access the wiring, each Bundle node has a Wires node. This is a MAP of LIST of Wire. The key of the MAP node is the name of the namespace, that is, the wires are organized by namespace. This provides convenient access to all wires of a given namespace. The value of the MAP node is a LIST node, providing sequential access to the actual wires.

A Wire node provides the following information:

  • Namespace - The namespace of the wire

  • Requirement - The requirement that cause the wire

  • Capability - The capability that satisfied the wire

  • Requirer - The location of the bundle that required the wire

  • Provider - The location of the bundle that satisfied the requirement

154.3.4 Wiring Example

The following example code demonstrates how the wires can be printed out:

String prefix ="Bundle/my_bundle/Wires/osgi.wiring.package";
String [] wires = session.getChildNodeNames(prefix);
for ( String wire : wires ) {
  String name = session.getNodeValue(prefix + "/" 
     + wire + "/Capability/Attribute/osgi.wiring.package").getString();
  String provider = session.getNodeValue(prefix + "/" 
     + wire + "/Provider" ).getString();
  String requirer = session.getNodeValue(prefix + "/" 
     + wire + "/Requirer" ).getString();
  System.out.printf("%-20s %-30s %s\n", name, provider, requirer);
}

154.4 Filtering

Frequently it is necessary to search through the tree of nodes for nodes matching specific criteria. Having to use Java to do this filtering can become cumbersome and impossible if the searching has to happen remotely. For that reason, the RMT contains a Filter node. This node allows a manager to specify a Target and a Filter. The Target is an absolute URI that defines a set of nodes that the Filter Plugin must search. This set is defined by allowing wildcards in the target. A single asterisk ('*' \u002A) matches a single level, the minus sign ('-' \u002C) specifies any number of levels and must not be used at the end of the URI. This implies that there is always a final node. The reason that a minus sign must not be last is that the final node's type would be undefined, any node on any sub-level would match.

The Target node must be specified as an absolute URI that must always end in a solidus ('/' \u002F) to signify that it represents a path to an interior node. The URI is absolute because the Filter is specified in a persistent node. It is possible to open a session, create the filter specification, close the session, and then open a new session, and use the earlier specified Target. As the two involved session do not have to have the same session, the base could differ, making it hard to use relative addressing. However, the result is always unique to a session. It is therefore possible to use relative URIs in the read out of the result.

For example, the tree in Figure 154.3 defines a sub-tree.

Figure 154.3 Example Sub-Tree

Example Sub-Tree

The following table shows a number of example targets on the previous sub-tree and their resulting final nodes, assuming the result is read in a session open on ./A.

Table 154.1 Example Target and results on a session opened on ./A

Target Final nodes
./A/*/ B, C
./A/*/E/*/ C/E/F, C/E/G
./A/-/G/ C/D/G, C/E/G
./A/*/*/*/ C/D/G, C/E/F, C/E/G
./A/-/*/

This is an error,./A/-/*/ is the same as ./A/-/, which is not allowed.

./A/*/*/ C/D, C/E

The Filter specifies a standard OSGi Filter expression that is applied to the final nodes. If no filter is specified then all final nodes match. However, when there is a filter specified it is applied against the final node and only the final nodes that are matching the filter as included in the result.

A node is matched against a filter by using some of its children as properties. The properties of a node are defined by:

  • Primitive child nodes, or

  • LIST nodes that have primitive as child nodes. Such nodes must be treated as multi-valued properties.

The matching rules in the filter must follow the standard OSGi Filter rules. If the filter matches such a node then it must be available as a session relative URI in the ResultUriList node. The relative URIs are listed in the ResultUriList.

The result nodes must only include nodes that satisfy the following conditions:

  • The node must match the Target node's URI specification

  • The node must be visible in the current session

  • The node must not reside in the Filter sub-tree

  • The node must be an interior node

  • The caller must have access to the node

  • It must be possible to get all the values of the child nodes that are necessary for filter matching

  • The node must match the filter if a filter is specified

The result is also available as a sub-tree under the Result node and can be traversed as sub-tree in Result. This tree contains all the result nodes and their sub-tree. The results under the Result node are a snapshot and cannot be modified, they are read only. This result can be removed after the session is closed.

154.4.1 Example

For example, the following code prints out the location of active bundles:

session.createInteriorNode("Filter/mq-1");
session.setNodeValue("Filter/mq-1/Target", 
  new DmtData($+"/Framework/Bundle/*/"));
session.setNodeValue("Filter/mq-1/Filter", new DmtData("(AutoStart=true)"));

String[] autostarted = session.getChildNodeNames(
   "Filter/mq-1/Result/Framework/Bundle");
System.out.println("Auto started bundles");
for ( String location : autostarted)
  System.out.println(location);

session.deleteNode("Filter/mq-1");

154.5 Log Access

The Log node provides access to the Log Service, the node contains a LIST of LogEntry nodes. The length of this list is implementation dependent. The list is sorted in most recent first order. This allows a manager to retrieve the latest logs. For example, the following code print out the latest 100 log entries:

DataSession session = admin.getSession($+"/Log/LogEntries");
try {
  for ( int i =0; i<100; i++ ) {
    Date date = session.getNodeValue( i+"/Time").getDateTime();
    String message = session.getNodeValue( i+"/Message").getString();
    System.out.println( date + " " + message );
  }
} finally {
  session.close();
}

154.6 osgi.wiring.rmt.service Namespace

This section defines a namespace for the Requirement-Capability model to maintain services through the standard wiring API. A service is a capability, the Capability attributes are the service properties. The bundle that gets the service has a requirement on that service.

The filter of the service requirement is not the original filter since this is not possible to obtain reliably. Instead the filter must assert of the service.id, for example: (service.id=123).

The resulting filter is specified as the filter: directive on the Requirement. This is depicted in Figure 154.4.

Figure 154.4 Requirements and Capabilities and their Wiring

Requirements and Capabilities and their Wiring

The osgi.wiring.rmt.service attributes are defined in the following table.

Table 154.2 osgi.wiring.rmt.service namespace

Attribute Name Type Syntax Description
osgi.wiring.rmt.service String service.id

The service id.

objectClass String[] fqn

Fully qualified name of the types under which this service is listed

* * *

Any service property


154.7 Tree Summary

$                                          _G__  NODE                      1   P

154.7.1 Filter


                                                                org.osgi/1.0/MAP
  Filter                                   _G__  MAP                     0,1   P
    [string]                               AG_D  NODE                   0..*   D
      Filter                               _GR_  string                    1   A
      Target                               _GR_  string                    1   A
      Limit                                _GR_  integer                   1   A
      Result                               _G__  Node                      1   A

                                                               org.osgi/1.0/LIST
      ResultUriList                        _G__  LIST                      1   A
        [list]                             _G__  string                 0..*   D
      InstanceId                           _G__  integer                   1   A

154.7.2 Framework

  Framework                                _G__  NODE                      1   P
    StartLevel                             _GR_  integer                   1   A
    InitialBundleStartLevel                _GR_  integer                   1   A

                                                                org.osgi/1.0/MAP
    Bundle                                 _G__  MAP                       1   A
      [string]                             AG__  NODE                   0..*   D
        StartLevel                         _GR_  integer                   1   A
        InstanceId                         _G__  integer                   1   A
        URL                                _GR_  string                    1   A
        AutoStart                          _GR_  boolean                   1   A
        FaultType                          _G__  integer                 0,1   A
        FaultMessage                       _G__  string                  0,1   A
        BundleId                           _G__  long                    0,1   A
        SymbolicName                       _G__  string                  0,1   A

                                                               org.osgi/1.0/LIST
        BundleType                         _G__  LIST                    0,1   A
          [list]                           _G__  string                 0..*   D

                                                                org.osgi/1.0/MAP
        Headers                            _G__  MAP                     0,1   A
          [string]                         _G__  string                 0..*   D
        Location                           _G__  string                    1   A
        RequestedState                     _GR_  string                    1   A
        LastModified                       _G__  date_time               0,1   A

                                                                org.osgi/1.0/MAP
        Wires                              _G__  MAP                     0,1   A

                                                               org.osgi/1.0/LIST
          [string]                         _G__  LIST                   0..*   D
            [list]                         _G__  NODE                   0..*   D
              InstanceId                   _G__  integer                   1   A
              Requirer                     _G__  string                    1   A
              Provider                     _G__  string                    1   A
              Requirement                  _G__  NODE                      1   A
                Filter                     _G__  string                    1   A

                                                                org.osgi/1.0/MAP
                Directive                  _G__  MAP                       1   A
                  [string]                 _G__  string                 0..*   D

                                                                org.osgi/1.0/MAP
                Attribute                  _G__  MAP                       1   A
                  [string]                 _G__  string                 0..*   D
              Capability                   _G__  NODE                      1   A

                                                                org.osgi/1.0/MAP
                Directive                  _G__  MAP                       1   A
                  [string]                 _G__  string                 0..*   D

                                                                org.osgi/1.0/MAP
                Attribute                  _G__  MAP                       1   A
                  [string]                 _G__  string                 0..*   D
              Namespace                    _G__  string                    1   A

                                                               org.osgi/1.0/LIST
        Signers                            _G__  LIST                    0,1   A
          [list]                           _G__  NODE                   0..*   D
            InstanceId                     _G__  integer                   1   A
            IsTrusted                      _G__  boolean                   1   A

                                                               org.osgi/1.0/LIST
            CertificateChain               _G__  LIST                      1   A
              [list]                       _G__  string                 0..*   D

                                                               org.osgi/1.0/LIST
        Entries                            _G__  LIST                    0,1   A
          [list]                           _G__  NODE                   0..*   D
            InstanceId                     _G__  integer                   1   A
            Path                           _G__  string                    1   A
            Content                        _G__  binary                    1   A
        State                              _G__  string                  0,1   A
        Version                            _G__  string                  0,1   A

                                                                org.osgi/1.0/MAP
    Property                               _G__  MAP                       1   A
      [string]                             _G__  string                 0..*   D

154.7.3 Log

  Log                                      _G__  NODE                    0,1   P

                                                               org.osgi/1.0/LIST
    LogEntries                             _G__  LIST                      1   A
      [list]                               _G__  NODE                   0..*   D
        Bundle                             _G__  string                    1   A
        Time                               _G__  date_time                 1   A
        Level                              _G__  integer                   1   A
        Message                            _G__  string                    1   A
        Exception                          _G__  string                  0,1   A

154.8 org.osgi.dmt.residential

Version 1.0

154.8.1 $

The $ describes the root node for OSGi Residential Management. The path to this node is defined in the system property: org.osgi.dmt.residential .

Table 154.3 Sub-tree Description for $

Name Act Type Card. S Description

Framework

Get Framework 1 P

The Framework node used to manage the local framework.

Filter

Get MAP 0,1 P

The Filter node searches the nodes in a tree that correspond to a target URI and an optional filter expression. A new Filter is created by adding a node to the Filter node. The name of the node is chosen by the remote manager. If multiple managers are active they must agree on a scheme to avoid conflicts or an atomic sessions must be used to claim exclusiveness.

Filter nodes are persistent but an implementation can remove the node after a suitable timeout that should at least be 1 hour.

If this functionality is not supported on this device then the node is not present.

  [String]

Add Del Get Filter 0..* D

Log

Get Log 0,1 P

Access to the optional Log.

If this functionality is not supported on this device then the node is not present.


154.8.2 Bundle

The management node for a Bundle. It provides access to the life cycle control of the bundle as well to its metadata, resources, and wiring.

To install a new bundle an instance of this node must be created. Since many of the sub-nodes are not yet valid as the information from the bundle is not yet available. These nodes are marked to be optional and will only exists after the bundle has been really installed.

154.8.2.1 FRAGMENT = "FRAGMENT"

The type returned for a fragment bundle.

154.8.2.2 INSTALLED = "INSTALLED"

The Bundle INSTALLED state.

154.8.2.3 RESOLVED = "RESOLVED"

The Bundle RESOLVED state.

154.8.2.4 STARTING = "STARTING"

The Bundle STARTING state.

154.8.2.5 ACTIVE = "ACTIVE"

The Bundle ACTIVE state.

154.8.2.6 STOPPING = "STOPPING"

The Bundle STOPPING state.

154.8.2.7 UNINSTALLED = "UNINSTALLED"

The Bundle UNINSTALLED state.

Table 154.4 Sub-tree Description for Bundle

Name Act Type Card. S Description

URL

Get Set string 1 A

The URL to download the archive from for this bundle. By default this is the empty string. In an atomic session this URL can be replaced to a new URL, which will trigger an update of this bundle during commit. If this value is set it must point to a valid JAR from which a URL can be downloaded, unless it is the system bundle. If it is the empty string no action must be taken except when it is the system bundle.

If the URL of Bundle 0 (The system bundle) is replaced to any value, including the empty string, then the framework will restart.

If both a the URL node has been set the bundle must be updated before any of the other aspects are handled like RequestedState and StartLevel.

AutoStart

Get Set boolean 1 A

Indicates if this Bundle must be started when the Framework is started.

If the AutoStart node is true then this bundle is started when the framework is started and its StartLevel is met.

If the AutoStart node is set to true and the bundle is not started then it will automatically be started if the start level permits it. If the AutoStart node is set to false then the bundle must not be stopped immediately.

If the AutoStart value of the System Bundle is changed then the operation must be ignored.

The default value for this node is true

FaultType

Get integer 0,1 A

The BundleException type associated with a failure on this bundle, -1 if no fault is associated with this bundle. If there was no Bundle Exception associated with the failure the code must be 0 (UNSPECIFIED). The FaultMessage provides a human readable message.

Only present after the bundle is installed.

FaultMessage

Get string 0,1 A

A human readable message detailing an error situation or an empty string if no fault is associated with this bundle.

Only present after the bundle is installed.

BundleId

Get long 0,1 A

The Bundle Id as defined by the getBundleId() method.

If there is no installed Bundle yet, then this node is not present.

SymbolicName

Get string 0,1 A

The Bundle Symbolic Name as defined by the Bundle getSymbolicName() method. If this result is null then the value of this node must be the empty string.

If there is no installed Bundle yet, then this node is not present.

Version

Get string 0,1 A

The Bundle's version as defined by the Bundle getVersion() method.

If there is no installed Bundle yet, then this node is not present.

BundleType

Get LIST 0,1 A

A list of the types of the bundle. Currently only a single type is provided:

If there is no installed Bundle yet, then this node is not present.

  [list]

Get string 0..* D

Headers

Get MAP 0,1 A

The Bundle getHeaders() method.

If there is no installed Bundle yet, then this node is not present.

  [String]

Get string 0..* D

Location

Get string 1 A

The Bundle's Location as defined by the Bundle getLocation() method.

The location is specified by the management agent when the bundle is installed. This location should be a unique name for a bundle chosen by the management system. The Bundle Location is immutable for the Bundle's life (it is not changed when the Bundle is updated). The Bundle Location is also part of the URI to this node.

State

Get string 0,1 A

Return the state of the current Bundle. The values can be:

If there is no installed Bundle yet, then this node is not present.

The default value is UNINSTALLED after creation.

RequestedState

Get Set string 1 A

Is the requested state the manager wants the bundle to be in. Can be:

  • INSTALLED - Ensure the bundle is stopped and refreshed.

  • RESOLVED - Ensure the bundle is resolved.

  • ACTIVE - Ensure the bundle is started.

  • UNINSTALLED - Uninstall the bundle.

The Requested State is a request. The management agent must attempt to achieve the desired state but there is a no guarantee that this state is achievable. For example,a Framework can resolve a bundle at any time or the active start level can prevent a bundle from running. Any errors must be reported on FaultType and FaultMessage.

If the AutoStart node is true then the bundle must be persistently started, otherwise it must be transiently started. If the StartLevel is not met then the commit must fail if AutoStart is false as a Bundle cannot be transiently started when the start level is not met.

If both a the URL node has been set as well as the RequestedState node then this must result in an update after which the bundle should go to the RequestedState.

The RequestedState must be stored persistently so that it contains the last requested state. The initial value of the RequestedState must be INSTALLED.

StartLevel

Get Set integer 1 A

The Bundle's current Start Level as defined by the BundleStartLevel adapt interface getStartLevel() method. Changing the StartLevel can change the Bundle State as a bundle can become eligible for starting or stopping.

If the URL node is set then a bundle must be updated before the start level is set,

LastModified

Get date_time 0,1 A

The Last Modified time of this bundle as defined by the Bundle getlastModified() method.

If there is no installed Bundle yet then this node is not present.

Wires

Get MAP 0,1 A

A MAP of name space -> to Wire. A Wire is a relation between to bundles where the type of the relation is defined by the name space. For example, osgi.wiring.package name space defines the exporting and importing of packages. Standard osgi name spaces are:

  • osgi.wiring.bundle

  • osgi.wiring.package

  • osgi.wiring.host

As the Core specification allows custom name spaces this list can be more extensive.

This specification adds one additional name space to reflect the services, this is the osgi.wiring.rmt.service name space. This name space will have a wire for each time a registered service by this Bundle was gotten for the first time by a bundle. A capability in the service name space holds all the registered service properties. The requirement has no attributes and a single filter directive that matches the service id property.

If there is no installed Bundle yet then this node is not present.

  [String]

Get LIST 0..* D

    [list]

Get Wire 0..* D

Signers

Get LIST 0,1 A

Return all signers of the bundle. See the Bundle getSignerCertificates() method with the SIGNERS_ALL parameter.

If there is no installed Bundle yet then this node is not present.

  [list]

Get Certificate 0..* D

Entries

Get LIST 0,1 A

An optional node providing access to the entries in the Bundle's JAR. This list must be created from the Bundle getEntryPaths() method called with an empty String. For each found entry, an Entry object must be made available.

If there is no installed Bundle yet then this node is not present.

  [list]

Get Entry 0..* D

InstanceId

Get integer 1 A

Instance Id used by foreign protocol adapters as a unique integer key not equal to 0. The instance id for a bundle must be (Bundle Id % 2^32) + 1.


154.8.3 Bundle.Certificate

Place holder for the Signers DN names.

Table 154.5 Sub-tree Description for Bundle.Certificate

Name Act Type Card. S Description

IsTrusted

Get boolean 1 A

Return if this Certificate is trusted.

CertificateChain

Get LIST 1 A

A list of signer DNs of the certificates in the chain.

  [list]

Get string 0..* D

InstanceId

Get integer 1 A

Instance Id to allow addressing by Instance Id.


154.8.4 Bundle.Entry

An Entry describes an entry in the Bundle, it combines the path of an entry with the content. Only entries that have content will be returned, that is, empty directories in the Bundle's archive are not returned.

Table 154.6 Sub-tree Description for Bundle.Entry

Name Act Type Card. S Description

Path

Get string 1 A

The path in the Bundle archive to the entry.

Content

Get binary 1 A

The binary content of the entry.

InstanceId

Get integer 1 A

Instance Id to allow addressing by Instance Id.


154.8.5 Filter

A Filter node can find the nodes in a given sub-tree that correspond to a given filter expression. This Filter node is a generic mechanism to select a part of the sub-tree (except itself).

Searching is done by treating an interior node as a map where its leaf nodes are attributes for a filter expression. That is, an interior node matches when a filter matches on its children. The matching nodes' URIs are gathered under a ResultUriList node and as a virtual sub-tree under the Result node.

The Filter node can specify the Target node. The Target is an absolute URI ending in a slash, potentially with wild cards. Only nodes that match the target node are included in the result.

There are two different wild cards:

  • Asterisk ('*' \u002A) - Specifies a wild card for one interior node name only. That is A/* / matches an interior nodes A/B, A/C, but not A/X/Y. The asterisk wild card can be used anywhere in the URI like A/* /C. Partial matches are not supported, that is a URI like A/xyz* is invalid.

  • Minus sign ('-' \u002D) - Specifies a wildcard for any number of descendant nodes. This is A/-/X/ matches A/B/X, A/C/X, but also A/X. Partial matches are not supported, that is a URI like A/xyz- is not supported. The - wild card must not be used at the last segment of a URI

The Target node selects a set of nodes N that can be viewed as a list of URIs or as a virtual sub-tree. The Result node is the virtual sub-tree (beginning at the session base) and the ResultUriList is a LIST of session relative URIs. The actual selection of the nodes must be postponed until either of these nodes (or one of their sub-nodes) is accessed for the first time. Either nodes represent a read-only snapshot that is valid until the end of the session.

It is possible to further refine the selection by specifying the Filter node. The Filter node is an LDAP filter expression or a simple wild card ('*') which selects all the nodes. As the wild card is the default, all nodes selected by the Target are selected by default.

The Filter must be applied to each of the nodes selected by target in the set N. By definition, these nodes are interior nodes only. LDAP expressions assert values depending on their key. In this case, the child leaf nodes of a node in set N are treated as the property on their parent node.

The attribute name in the LDAP filter can only reference a direct leaf node of the node in the set N or an interior node with the DDF type org.osgi.service.dmt.DmtConstants.DDF_LIST with leaf nodes as children, i.e. a LIST. A LIST of primitives must be treated in the filter as a multi valued property, any of its values satisfy an assertion on that attribute.

Attribute names must not contains a slash, that is, it is only possible to assert values directly below the node selected by the target.

Each of these leaf nodes and LISTs can be used in the LDAP Filter as a key/value pair. The comparison must be done with the type used in the Dmt Data object of the compared node. That is, if the Dmt Admin data is a number, then the comparison rules of the number must be used. The attributes given to the filter must be converted to the Java object that represents their type.

The set N must therefore consists only of nodes where the Filter matches.

It is allowed to change the Target or the Filter node after the results are read. In that case, the Result and ResultUriList must be cleared instantaneously and the search redone once either result node is read.

The initial value of Target is the empty string, which indicates no target.

Table 154.7 Sub-tree Description for Filter

Name Act Type Card. S Description

Target

Get Set string 1 A

An absolute URI always ending in a slash ('/'), with optional wildcards, selecting a set of sub-nodes N. Wildcards can be an asterisk ( '*' \u002A) or a minus sign ('-' \u002D). An asterisk can be used in place of a single node name in the URI, a minus sign stands for any number of consecutive node names. The default value of this node is the empty string, which indicates that no nodes must be selected. Changing this value must clear any existing results. If the Result() or ResultUriList is read to get N then a new search must be executed.

A URI must always end in '/' to indicate that the target can only select interior nodes.

Filter

Get Set string 1 A

An optional filter expression that filters nodes in the set N selected by Target. The filter expression is an LDAP filter or an asterisk ('*'). An asterisk is the default value and matches any node in set N. If an LDAP expression is set in the Filter node then the set N must only contain nodes that match the given filter. The values the filter asserts are the immediate leafs and LIST nodes of the nodes in set N. The name of these child nodes is the name of the attribute matched in the filter.

The nodes can be removed by the Filter implementation after a timeout defined by the implementation.

Limit

Get Set integer 1 A

Limits the number of results to the given number. If this node is not set there is no limit. The default value is not set, thus no limit.

Result

Get NODE 1 A

The Result tree is a virtual read-only tree of all nodes that were selected by the Target and matched the Filter, that is, all nodes in set N. The Result node acts as a parent instead of the session root for each node in N.

The Result node is a snapshot taken the first time it is accessed after a change in the Filter and/or the Target nodes.

ResultUriList

Get LIST 1 A

A list of URIs of nodes in the Device Management Tree from the node selected by the Target that match the Filter node. All URIs are relative to current session. The Result node is a snapshot taken the first time it is accessed after a change in the Filter and/or the Target nodes.

  [list]

Get string 0..* D

InstanceId

Get integer 1 A

Instance Id to allow addressing by Instance Id.


154.8.6 Framework

The Framework node represents the information about the Framework itself. The Framework node allows manipulation of the OSGi framework, start level, framework life cycle, and bundle life cycle.

All modifications to a Framework object must occur in an atomic session. All changes to the framework must occur during the commit.

The Framework node allows the manager to install (create a new child node in Bundle), to uninstall change the state of the bundle (see Bundle.RequestedState()), update the bundle (see URL ), start/stop bundles, and update the framework. The implementation must execute these actions in the following order during the commit of the session:

  1. Create a snapshot of the current installed bundles and their state.

  2. stop all bundles that will be uinstalled and updated

  3. Uninstall all the to be uninstalled bundles (bundles whose RequestedState is Bundle.UNINSTALLED)

  4. Update all bundles that have a modified URL with this URL using the Bundle update(InputStream) method in the order that the order that the URLs were last set.

  5. Install any new bundles from their URL in the order that the order that the URLs were last set.

  6. Refresh all bundles that were updated and installed

  7. Ensure that all the bundles have their correct start level

  8. If the RequestedState was set, follow this state. Otherwise ensure that any Bundles that have the AutoStart flag set to true are started persistently. Transiently started bundles that were stopped in this process are not restarted. The bundle id order must be used.

  9. Wait until the desired start level has been reached

  10. Return from the commit without error.

If any of the above steps runs in an error (except the restart) than the actions should be undone and the system state must be restored to the snapshot.

If the System Bundle was updated (its URL) node was modified, then after the commit has returned successfully, the OSGi Framework must be restarted.

Table 154.8 Sub-tree Description for Framework

Name Act Type Card. S Description

StartLevel

Get Set integer 1 A

The StartLevel manages the Framework's current Start Level. Maps to the Framework Start Level set/getStartLevel() methods.

This node can set the requested Framework's StartLevel, however it doesn't store the value. This node returns the Framework's StartLevel at the moment of the call.

InitialBundleStartLevel

Get Set integer 1 A

Configures the initial bundle start level, maps to the the FrameworkStartLevel set/getInitialBundleStartLevel() method.

Bundle

Get MAP 1 A

The MAP of location -> Bundle. Each Bundle is uniquely identified by its location. The location is a string that must be unique for each bundle and can be chosen by the management system.

The Bundles node will be automatically filled from the installed bundles, representing the actual state.

New bundles can be installed by creating a new node with a given location. At commit, this bundle will be installed from their Bundle.URL node.

The location of the System Bundle must be "System Bundle" (see the Core's Constants.SYSTEM_BUNDLE_LOCATION), this node cannot be uninstalled and most operations on this node have special meaning.

It is strongly recommended to use a logical name for the location of a bundle, for example reverse domain names or a UUID.

To uninstall a bundle, set the Bundle.RequestedState to UNINSTALLED, the nodes in Bundle cannot be deleted.

  [String]

Add Get Bundle 0..* D

Property

Get MAP 1 A

The Framework Properties.

The Framework properties come from the Bundle Context getProperty() method. However, this method does not provide the names of the available properties. If the handler of this node is aware of the framework properties then these should be used to provide the node names. If these properties are now known, the handler must synthesize the names from the following sources

  • System Properties (as they are backing the Framework properties)

  • Launching properties as defined in the OSGi Core specification

  • Properties in the residential specification

  • Other known properties

  [String]

Get string 0..* D

154.8.7 Wire

A Wire is a link between two bundles where the semantics of this link is defined by the used name space. This is closely modeled after the Wiring API in the Core Framework.

Table 154.9 Sub-tree Description for Wire

Name Act Type Card. S Description

Namespace

Get string 1 A

The name space of this wire. Can be:

  • osgi.wiring.bundle - Defined in the OSGi Core

  • osgi.wiring.package - Defined in the OSGi Core

  • osgi.wiring.host - Defined in the OSGi Core

  • osgi.wiring.rmt.service - Defined in this specification

  • * - Generic name spaces

The osgi.wiring.rmt.service name space is not defined by the OSGi Core as it is not part of the module layer. The name space has the following layout:

  • Requirement - A filter on the service.id service property.

  • Capability - All service properties as attributes. No defined directives.

  • Requirer - The bundle that has gotten the service

  • Provider - The bundle that has registered the service

There is a wire for each registration-get pair. That is, if a service is registered by A and gotten by B and C then there are two wires: B->A and C->A.

Requirement

Get Requirement 1 A

The Requirement that caused this wire.

Capability

Get Capability 1 A

The Capability that satisfied the requirement of this wire.

Requirer

Get string 1 A

The location of the Bundle that contains the requirement for this wire.

Provider

Get string 1 A

The location of the Bundle that provides the capability for this wire.

InstanceId

Get integer 1 A

Instance Id to allow addressing by Instance Id.


154.8.8 Wire.Capability

Describes a Capability.

Table 154.10 Sub-tree Description for Wire.Capability

Name Act Type Card. S Description

Directive

Get MAP 1 A

The Directives for this capability.

  [String]

Get string 0..* D

Attribute

Get MAP 1 A

The Attributes for this capability.

  [String]

Get string 0..* D

154.8.9 Wire.Requirement

Describes a Requirement.

Table 154.11 Sub-tree Description for Wire.Requirement

Name Act Type Card. S Description

Filter

Get string 1 A

The Filter string for this requirement.

Directive

Get MAP 1 A

The Directives for this requirement. These directives must contain the filter: directive as described by the Core.

  [String]

Get string 0..* D

Attribute

Get MAP 1 A

The Attributes for this requirement.

  [String]

Get string 0..* D

154.9 org.osgi.dmt.service.log

Version 1.0

154.9.1 Log

Provides access to the Log Entries of the Log Service.

Table 154.12 Sub-tree Description for Log

Name Act Type Card. S Description

LogEntries

Get LIST 1 A

A potentially long list of Log Entries. The length of this list is implementation dependent. The order of the list is most recent event at index 0 and later events with higher consecutive indexes. No new entries must be added to the log when there is an open exclusive or atomic session.

  [list]

Get LogEntry 0..* D

154.9.2 LogEntry

A Log Entry node is the representation of a LogEntry from the OSGi Log Service.

Table 154.13 Sub-tree Description for LogEntry

Name Act Type Card. S Description

Time

Get date_time 1 A

Time of the Log Entry.

Level

Get integer 1 A

The severity level of the log entry. The value is the same as the Log Service level values:

  • LOG_ERROR 1

  • LOG_WARNING 2

  • LOG_INFO 3

  • LOG_DEBUG 4

Other values are possible because the Log Service allows custom levels.

Message

Get string 1 A

Textual, human-readable description of the log entry.

Bundle

Get string 1 A

The location of the bundle that originated this log or an empty string.

Exception

Get string 0,1 A

Human readable information about an exception. Provides the exception information if any, optionally including the stack trace.