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.
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.
-
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.
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.residentialFor this specifications, the RMT Consists of the following top level nodes:
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.
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...
}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();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.
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.serviceThis 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
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);
}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.
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/*/*/ |
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
-
LISTnodes 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.
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");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();
}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.
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 |
$ _G__ NODE 1 P
org.osgi/1.0/MAP
Filter _G__ MAP 0,1 P
[string] AG_D NODE 0..* D
Filter _GR_ string 1 A
InstanceId _G__ integer 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
Target _GR_ string 1 A
Framework _G__ NODE 1 P
org.osgi/1.0/MAP
Bundle _G__ MAP 1 A
[string] AG__ NODE 0..* D
AutoStart _GR_ boolean 1 A
BundleId _G__ long 0,1 A
org.osgi/1.0/LIST
BundleType _G__ LIST 0,1 A
[list] _G__ string 0..* D
org.osgi/1.0/LIST
Entries _G__ LIST 0,1 A
[list] _G__ NODE 0..* D
Content _G__ binary 1 A
InstanceId _G__ integer 1 A
Path _G__ string 1 A
FaultMessage _G__ string 0,1 A
FaultType _G__ integer 0,1 A
org.osgi/1.0/MAP
Headers _G__ MAP 0,1 A
[string] _G__ string 0..* D
InstanceId _G__ integer 1 A
LastModified _G__ date_time 0,1 A
Location _G__ string 1 A
RequestedState _GR_ string 1 A
org.osgi/1.0/LIST
Signers _G__ LIST 0,1 A
[list] _G__ NODE 0..* D
org.osgi/1.0/LIST
CertificateChain _G__ LIST 1 A
[list] _G__ string 0..* D
InstanceId _G__ integer 1 A
IsTrusted _G__ boolean 1 A
StartLevel _GR_ integer 1 A
State _G__ string 0,1 A
SymbolicName _G__ string 0,1 A
URL _GR_ string 1 A
Version _G__ string 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
Capability _G__ NODE 1 A
org.osgi/1.0/MAP
Attribute _G__ MAP 1 A
[string] _G__ string 0..* D
org.osgi/1.0/MAP
Directive _G__ MAP 1 A
[string] _G__ string 0..* D
InstanceId _G__ integer 1 A
Namespace _G__ string 1 A
Provider _G__ string 1 A
Requirement _G__ NODE 1 A
org.osgi/1.0/MAP
Attribute _G__ MAP 1 A
[string] _G__ string 0..* D
org.osgi/1.0/MAP
Directive _G__ MAP 1 A
[string] _G__ string 0..* D
Filter _G__ string 1 A
Requirer _G__ string 1 A
InitialBundleStartLevel _GR_ integer 1 A
org.osgi/1.0/MAP
Property _G__ MAP 1 A
[string] _G__ string 0..* D
StartLevel _GR_ integer 1 A
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 |
|---|---|---|---|---|---|
Get
|
Framework
|
1
|
P
|
The Framework node used to manage the local framework. |
|
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. |
|
|
|
Add Del Get
|
Filter
|
0..*
|
D
|
|
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. |
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.
The Bundle UNINSTALLED state.
Table 154.4 Sub-tree Description for Bundle
| Name | Act | Type | Card. | S | Description |
|---|---|---|---|---|---|
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. |
|
Get Set
|
boolean
|
1
|
A
|
Indicates if this Bundle must be started when the Framework is started.
If the AutoStart node is
If the
If the
The default value for this node is |
|
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. |
|
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. |
|
Get
|
long
|
0,1
|
A
|
The Bundle Id as defined by the If there is no installed Bundle yet, then this node is not present. |
|
Get
|
string
|
0,1
|
A
|
The Bundle Symbolic Name as defined by the Bundle
If there is no installed Bundle yet, then this node is not present. |
|
Get
|
string
|
0,1
|
A
|
The Bundle's version as defined by the Bundle If there is no installed Bundle yet, then this node is not present. |
|
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. |
|
|
|
Get
|
string
|
0..*
|
D
|
|
Get
|
MAP
|
0,1
|
A
|
The Bundle If there is no installed Bundle yet, then this node is not present. |
|
|
|
Get
|
string
|
0..*
|
D
|
|
Get
|
string
|
1
|
A
|
The Bundle's Location as defined by the Bundle 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. |
|
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. |
|
Get Set
|
string
|
1
|
A
|
Is the requested state the manager wants the bundle to be in. Can be:
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 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. |
|
Get Set
|
integer
|
1
|
A
|
The Bundle's current Start Level as defined by the BundleStartLevel adapt
interface If the URL node is set then a bundle must be updated before the start level is set, |
|
Get
|
date_time
|
0,1
|
A
|
The Last Modified time of this bundle as defined by the Bundle
If there is no installed Bundle yet then this node is not present. |
|
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,
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 If there is no installed Bundle yet then this node is not present. |
|
|
|
Get
|
LIST
|
0..*
|
D
|
|
|
|
Get
|
Wire
|
0..*
|
D
|
|
Get
|
LIST
|
0,1
|
A
|
Return all signers of the bundle. See the Bundle
If there is no installed Bundle yet then this node is not present. |
|
|
|
Get
|
Certificate
|
0..*
|
D
|
|
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 If there is no installed Bundle yet then this node is not present. |
|
|
|
Get
|
Entry
|
0..*
|
D
|
|
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. |
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.
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 isA/*/matches an interior nodesA/B,A/C, but notA/X/Y. The asterisk wild card can be used anywhere in the URI likeA/*/C. Partial matches are not supported, that is a URI likeA/xyz*is invalid. -
Minus sign (
'-'\u002D) - Specifies a wildcard for any number of descendant nodes. This isA/-/X/matchesA/B/X,A/C/X, but alsoA/X. Partial matches are not supported, that is a URI likeA/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 |
|---|---|---|---|---|---|
Get Set
|
string
|
1
|
A
|
An absolute URI always ending in a slash ('/'), with optional wildcards,
selecting a set of sub-nodes A URI must always end in '/' to indicate that the target can only select interior nodes. |
|
Get Set
|
string
|
1
|
A
|
An optional filter expression that filters nodes in the set The nodes can be removed by the Filter implementation after a timeout defined by the implementation. |
|
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. |
|
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
The Result node is a snapshot taken the first time it
is accessed after a change in the |
|
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 |
|
|
|
Get
|
string
|
0..*
|
D
|
|
Get
|
integer
|
1
|
A
|
Instance Id to allow addressing by Instance Id. |
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:
-
Create a snapshot of the current installed bundles and their state.
-
stop all bundles that will be uinstalled and updated
-
Uninstall all the to be uninstalled bundles (bundles whose RequestedState is Bundle.UNINSTALLED)
-
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. -
Install any new bundles from their URL in the order that the order that the URLs were last set.
-
Refresh all bundles that were updated and installed
-
Ensure that all the bundles have their correct start level
-
If the RequestedState was set, follow this state. Otherwise ensure that any Bundles that have the AutoStart flag set to
trueare started persistently. Transiently started bundles that were stopped in this process are not restarted. The bundle id order must be used. -
Wait until the desired start level has been reached
-
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 |
|---|---|---|---|---|---|
Get Set
|
integer
|
1
|
A
|
The StartLevel manages the Framework's current Start Level. Maps to the
Framework Start Level 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. |
|
Get Set
|
integer
|
1
|
A
|
Configures the initial bundle start level, maps to the the
FrameworkStartLevel |
|
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
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
|
|
|
|
Add Get
|
Bundle
|
0..*
|
D
|
|
Get
|
MAP
|
1
|
A
|
The Framework Properties.
The Framework properties come from the Bundle Context
|
|
|
|
Get
|
string
|
0..*
|
D
|
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 |
|---|---|---|---|---|---|
Get
|
string
|
1
|
A
|
The name space of this wire. Can be:
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:
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:
|
|
Get
|
Requirement
|
1
|
A
|
The Requirement that caused this wire. |
|
Get
|
Capability
|
1
|
A
|
The Capability that satisfied the requirement of this wire. |
|
Get
|
string
|
1
|
A
|
The location of the Bundle that contains the requirement for this wire. |
|
Get
|
string
|
1
|
A
|
The location of the Bundle that provides the capability for this wire. |
|
Get
|
integer
|
1
|
A
|
Instance Id to allow addressing by Instance Id. |
Describes a Requirement.
Table 154.11 Sub-tree Description for Wire.Requirement
| Name | Act | Type | Card. | S | Description |
|---|---|---|---|---|---|
Get
|
string
|
1
|
A
|
The Filter string for this requirement. |
|
Get
|
MAP
|
1
|
A
|
The Directives for this requirement. These directives must contain the filter: directive as described by the Core. |
|
|
|
Get
|
string
|
0..*
|
D
|
|
Get
|
MAP
|
1
|
A
|
The Attributes for this requirement. |
|
|
|
Get
|
string
|
0..*
|
D
|
Provides access to the Log Entries of the Log Service.
Table 154.12 Sub-tree Description for Log
| Name | Act | Type | Card. | S | Description |
|---|---|---|---|---|---|
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. |
|
|
|
Get
|
LogEntry
|
0..*
|
D
|
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 |
|---|---|---|---|---|---|
Get
|
date_time
|
1
|
A
|
Time of the Log Entry. |
|
Get
|
integer
|
1
|
A
|
The severity level of the log entry. The value is the same as the Log Service level values:
Other values are possible because the Log Service allows custom levels. |
|
Get
|
string
|
1
|
A
|
Textual, human-readable description of the log entry. |
|
Get
|
string
|
1
|
A
|
The location of the bundle that originated this log or an empty string. |
|
Get
|
string
|
0,1
|
A
|
Human readable information about an exception. Provides the exception information if any, optionally including the stack trace. |