119 Monitor Admin Service Specification

119.1 Introduction

Applications and services may publish status information that management systems can receive to monitor the status of the device. For example, a bundle could publish Status Variables for a number key VM variables like the amount of available memory, battery power, number of SMSs sent, etc.

Status Variables can be used in performance management, fault management as well as in customer relations management systems.

This specification outlines how a bundle can publish Status Variables and how administrative bundles can discover Status Variables as well as read and reset their values.

119.1.1 Entities

  • Status Variable - Application specific variables that a Status Variable Provider publishes with a Monitorable service to the Monitor Admin service. Status Variable values can be long, double, boolean or String objects.

  • Status Variable Provider - A bundle which has a number of Status Variables that it publishes with one or more Monitorable services.

  • Monitor Admin - Provides unified and secure access to available Status Variables as well as providing a function to create monitoring jobs to monitor the Status Variables.

  • Monitorable - A service that is registered by a Status Variable Provider to publish its Status Variables.

  • Monitor Job - An event or time based query of a given set of Status Variables. When a monitored Status Variable is updated, or the timer expires, the Monitor Admin must generate an event via the Event Admin service.

  • Local Administrator - A management application which uses the Monitor Admin service to query Status Variables and to initiate monitoring jobs.

  • Status Variable Name - The unique name, within a Monitorable service, of a Status Variable.

  • Status Variable Path - A string that uniquely identifies the Status Variable in an OSGi environment. It consists of the PID of the Monitorable service and the Status Variable name separated by a solidus ('/' \u002F).

Figure 119.1 Monitor Admin Diagram org.osgi.service.monitor package

Monitor Admin Diagram org.osgi.service.monitor package

119.1.2 Synopsis

A bundle that provides a Status Variable must register a Monitorable service. This service is used by the Monitor Admin to get Status Variables and provide meta information to clients.

Clients can use the Monitor Admin to obtain Status Variables in a protected way. Clients can also create Monitoring Jobs. These Monitoring Jobs send out notifications to the clients when the value changes or periodically.

119.2 Monitorable

A Status Variable is a simple scalar that represents some key indicator of the environment, for example amount of available memory. Status Variables are further discussed in Status Variable.

A Status Variable Provider must therefore register a Monitorable service with the service property service.pid set to a PID. This PID must have the following format:

monitorable-pid ::= symbolic-name    // See General Syntax Definitions in Core

The length of this PID must fit in 32 bytes when UTF-8 encoded.

Monitorable services are tracked by the Monitor Admin service. The Monitor Admin service can provide the local administrator unified access to all the Status Variables in the system. This is depicted in Figure 119.2.

Figure 119.2 Access to Status Variables

Access to Status Variables

The main responsibility of a Monitorable service is therefore to provide access to its own Status Variables as well as providing information about those Status Variables.

The Monitorable interface contains the following methods:

119.2.1 Providing Notifications

If a Monitorable service returns true for the notifiesOnChange(String) method then it must notify all Monitor Listener services when the related Status Variable changes. These Status Variables are called dynamic Status Variables.

After the value of a dynamic Status Variable is changed, the Monitorable service must get the singleton Monitor Listener service and call the updated(String,StatusVariable) method. The Monitor Admin service must use this notification mechanism to send out a generic event via the Event Admin service, as described in Monitoring events. The Monitor Admin can also use this information to signal a remote server in a proprietary way. Figure 119.3 shows a sequence diagram for such an update. This indirection is required for security reasons.

Figure 119.3 Notification on Update

Notification on Update

119.2.2 Example Monitorable Implementation

The following code shows how a bundle could provide a Status Variable that contains the current amount of memory.

public class MemoryMonitor
    implements BundleActivator, Monitorable {

    public void start(BundleContext context) {
        Hashtable ht = new Hashtable();
        ht.put("service.pid", "com.acme.foo");
        context.registerService(
            Monitorable.class.getName(), this, ht);
    }

    public void stop(BundleContext context) {}

    public String[] getStatusVariableNames() {
        return new String[] {"memory.free"};
    }

    public StatusVariable getStatusVariable(String name) 
        throws IllegalArgumentException {
        if ("memory.free".equals(name))
            return 
                new StatusVariable(name, 
                StatusVariable.CM_GAUGE,
                Runtime.getRuntime().freeMemory());
        else
            throw new IllegalArgumentException(
                "Invalid Status Variable name " + name);
    }

    public boolean notifiesOnChange(String name) 
        throws IllegalArgumentException {
        return false;
    }

    public boolean resetStatusVariable(String name) 
        throws IllegalArgumentException {
        return false;
    }

    public String getDescription(String name) 
        throws IllegalArgumentException {
      if ("memory.free".equals(name))
        return "current amount of free memory in the JVM"; 
      else
        throw new IllegalArgumentException(
                "Invalid Status Variable name " + name);
   }
}

119.3 Status Variable

A Status Variable is a simple value that is published from a Monitorable service. A Status Variable has a name, a value, a timestamp, and a collection method. Additionally, the Monitorable service that publishes the Status Variable can be used to reset the Status Variable and provide a description of it.

The OSGi Specification provides an implementation class for a Status Variable. This class is final and immutable, it must be treated as a value.

119.3.1 Name

Each Status Variable must have a unique identity in the scope of a Monitorable service. This identity can be obtained with the getID() method. A Status Variable identity must have the following syntax:

status-variable-name ::= symbolic-name // See General Syntax Definitions in Core

The name should be descriptive and concise. Additionally, it has the following limitations:

  • The length must be limited to 32 characters in UTF-8 encoded form.

  • It must be unique in the scope of the Monitorable service.

119.3.2 Value

A Status Variable provides the type of its value with the getType() method. The return value of this method can take the following values:

If a method is called that does not match the return value of the getType() method, the Status Variable must throw an Illegal State Exception.

119.3.3 Time Stamp

The time stamp must reflect the time that the measurement was taken from the standard Java System.currentTimeMillis method. The time stamp can be obtained with the getTimeStamp() method.

119.3.4 Collection Method

This specification is compatible with terminology used in [2] ETSI Performance Management [TS 132 403]. An important concept of a Status Variable is the way it was collected, this is called the collection method. The collection method is independent of how (if and when) the reporting of the Status Variables happens. The collection method is part of the Status Variable's definition and cannot be changed. The collection method of a Status Variable can be obtained with the getCollectionMethod() method.

The ETSI document defines the following collection methods:

  • CM_CC - A numeric counter whose value can only increase, except when the Status Variable is reset. An example of a CC is a variable which stores the number of incoming SMSs handled by the protocol driver since it was started or reset.

  • CM_GAUGE - A numeric counter whose value can vary up or down. An example of a GAUGE is a variable which stores the current battery level percentage. The value of the Status Variable must be the absolute value not a difference.

  • CM_DER - (Discrete Event Registration) A status variable (numeric or string) which can change when a certain event happens in the system one or more times. The event which fires the change of the Status Variable is typically some event like the arrival of an SMS. The definition of a DER counter contains an integer N which means how many events it takes for the counter to change its value. The most usual value for N is 1, but if N is greater than 1 then it means that the variable changes after each Nth event.

  • CM_SI - (Status Inspect) The most general status variable which can be a string or numeric. An example of an SI is a string variable which contains the name of the currently logged in user.

119.4 Using Monitor Admin Service

The Monitor Admin service is a singleton service that provides unified access to the Status Variables in the system. It provides security checking, resolution of the Status Variable paths and scheduling of periodic or event based Monitoring Jobs.

119.4.1 Discovery

The Monitor Admin manages the status variables from any registered Monitorable services. The Monitorable services can be discovered using the getMonitorableNames() method. This returns a sorted list of PIDs, potentially empty. This list can contain the PIDs of Monitorable services where the caller has no access to any of its Status Variables.

119.4.2 Status Variable Administration

The Monitor Admin provides the following methods for manipulating the Status Variables:

Figure 119.4 is the simple sequence diagram for getting a Status Variable from the Monitor Admin service. The caller requests a Status Variable from the Monitor Admin service with the getStatusVariable(String) method. Its sole argument specifies a path to the Status Variable. For example:

com.acme.foo/memory.free

The Monitor Admin service finds the associated Monitorable service by looking for a Monitorable service with the given PID (com.acme.foo). It will then query the Monitorable service for the Status Variable memory.free, which is then subsequently returned to the caller.

Figure 119.4 Status Variable request through the Monitor Admin service

Status Variable request through the Monitor Admin service

119.4.3 Notifications

The Monitor Admin service can receive events from Monitorable services as described in Providing Notifications. The Monitor Admin Service can control the sending of events with the switchEvents(String,boolean) method. The argument is a path to a Status Variable, with a possible wildcard character in place of the Status Variable or Monitorable PID. For example:

*/*
com.acme.sv.carots/*
*/received.packets

The use of wildcards is the same as described in Monitor Permission The Monitor Admin service must expand this wildcard to the set of Status Variable names at the time the events are switched. If the boolean argument is set to false, no more events will be sent to the Event Admin service.

The default state is sending events. The state of sending events must not be persistent, switching the events off must not be remembered between system restarts.

119.4.4 Monitoring jobs

A local administrator can create a monitoring job. A monitoring job consists of a set of Status Variables and reporting rules. According to these rules, the Monitor Admin service will send events to the Event Admin service. The same Status Variable can participate in any number of monitoring jobs.

There are two types of monitoring jobs, each created with a different method. One is based on periodic measurements and one based on changes in the value of the Status Variable. The results of the measurements are sent to the Event Admin service, these events are described in Monitoring events.

  • startScheduledJob(String,String[],int,int) - Start a job based on a periodic measurement. Both the period of measurements as well as the number of measurements can be given.

  • startJob(String,String[],int) - Start a job based on notifications. The load on the Event Admin service can be minimized by specifying that only every n-th measurement must be reported. Status Variables used with this monitoring job must support notifications, otherwise an Illegal Argument Exception must be thrown.

Both monitoring jobs take an identification String object as first argument. This identification is placed in the properties of the Event object under the key: listener.id. The initiator of the monitoring job should set this id to a unique value and so that it can discriminate the monitoring events that are related to his monitoring job.

The second argument is a list of paths to Status Variables.

The difference between the Time based monitoring and event based monitoring is further elucidated in Figure 119.5.

Figure 119.5 Time and event based monitoring job

Time and event based monitoring job

Monitoring jobs can be started also remotely by a management server through Device Management Tree operations. The monitoring job therefore has a boolean method which tells whether it was started locally or remotely: isLocal().

A monitoring job is transient, it must not survive a system restart. A monitoring job can be explicitly stopped with the stop() method.

119.4.4.1 Example Monitoring Job

For example, a bundle is interested in working with periodic samples of the com.acme.foo/memory.free Status Variable. It should therefore register an Event Handler with the correct topic and a filter on its Event Handler service. It then starts a monitoring job that is stopped in the BundleActivator stop method.

public class MemoryListener 
    implements BundleActivator, EventHandler {
    MonitoringJob job;

    public void start(BundleContext context) throws Exception {
        Hashtable p = new Hashtable();
        p.put(EventConstants.EVENT_TOPIC, 
            new String[] { "org/osgi/service/monitor" });
        p.put(EventConstants.EVENT_FILTER, 
            "(mon.listener.id=foo.bar)");

        context.registerService(
            EventHandler.class.getName(),this,p );

        job = getMonitorAdmin().startScheduledJob(
                "foo.bar",                  // listener.id
                 new String[] {"com.acme.foo/memory.free"},
                15,                 // seconds
                0                   // Forever
            );
    }

    public void stop(BundleContext ctxt) throws Exception {
        job.stop();
    }

    public void handleEvent(Event event) {
        String value = (String) event.getProperty(
            "mon.statusvariable.value");
        String name = (String) event.getProperty(
            "mon.statusvariable.name");
        System.out.println("Mon: " name + "=" value );
    }
    ...
}

After starting the job, the Monitor Admin queries the com.acme.foo/memory.free Status Variable every 15 seconds. At each acquisition, the Monitor Admin sends a org/osgi/service/monitor event to the Event Admin service. The event properties contain the mon.listener.id set to foo.bar. The Event Admin service updates the Event Handler service that is registered by the example bundle. After receiving the event, the bundle can get the updated value of the Status Variable from the event properties.

The events are therefore repeated once every 15 seconds until the bundle stops.

119.5 Monitoring events

The Monitor Admin must send an asynchronous event to the Event Admin service when:

  • A Monitorable reported the change on the Monitor Listener service

  • The Status Variable was explicitly reset to its starting value with the resetStatusVariable(String) method.

  • The Status Variable is queried from within a scheduled monitoring job by the Monitor Admin service.

Event sending in the first two cases can be switched on and off, but in the case of monitoring jobs, it cannot be disabled. Monitoring events must be sent asynchronously.

The topic of the event must be:

org/osgi/service/monitor/MonitorEvent

The properties of the event are:

  • mon.monitorable.pid - (String) The unique identifier of the Monitorable service which the changed Status Variable.

  • mon.statusvariable.name - (String) The name of the changed status variable.

  • mon.listener.id - (String|String[ ]) Name or names representing the initiators of any monitoring jobs in which the Status Variable was included. Listeners can use this field for filtering, so that they receive only events related to their own jobs. If the event is fired because of a notification on the MonitorListener interface of the Monitor Admin service (and not because of an measurement taken within a monitoring job) then this property is absent.

  • mon.statusvariable.value - (String) The value of the status variable in string format. The following methods must be used to format the String object.

    • long - Long.toString(long).

    • double - Double.toString(double).

    • boolean - Boolean.toString(boolean).

    • String - No conversion

119.6 Security

119.6.1 Monitor Permission

Registering Monitorable services, querying and resetting Status Variables and starting monitoring jobs requires a Monitor Permission. If the entity issuing the operation does not have this permission, a Security Exception must be thrown.

Unless noted otherwise, the target of the Monitor Permission identifies the Status Variable paths. It has the following format:

widldcard-path ::= wildcard-pid '/' wildcard-name
wildcard-pid   ::= pid '*'  | '*'
wildcard-name  ::= unique-id '*'  | '*'

Example:

*/*
com.acme.*/*
*/count
com.acme.foo/memory.free

The actions that can be used are:

  • READ -Reading of the value of the given Status Variables.

  • RESET - Resetting the given Status Variables.

  • PUBLISH - Publishing a Status Variable. This does not forbid the Status Variable Provider to register the Monitorable. However, the Monitor Admin must not show a Status Variables to any caller when the Status Variable Provider has no permission to publish that specific Status Variable.

  • STARTJOB - Initiating monitoring jobs involving the given Status Variables A minimal sampling interval can be optionally defined in the following form:

    startjob:n

    The n is the allowed minimal value of the schedule parameter of time based monitoring jobs. If n is not specified or zero then there is no lower limit for the minimum sampling interval specified. The purpose of the minimum sampling interval is to prevent the system from flooding. The target specifies the Status Variables that can be monitored.

  • SWITCHEVENTS - Switch event sending on or off for the notification of value changes for the given Status Variables.

The permissions must all be checked by the Monitor Admin.

Further, the different actors must have the permissions as specified in the following table to operate correctly.

Table 119.1 Permission for the different actors

ServicePermission Status Variable Provider Local Admin Monitor Admin
MonitorAdmin - GET REGISTER
UpdateListener GET - REGISTER
Monitorable REGISTER - GET

119.7 org.osgi.service.monitor

Version 1.0

Monitor Admin Package Version 1.0.

Bundles wishing to use this package must list the package in the Import-Package header of the bundle's manifest. This package has two types of users: the consumers that use the API in this package and the providers that implement the API in this package.

Example import for consumers using the API in this package:

Import-Package: org.osgi.service.monitor; version="[1.0,2.0)"

Example import for providers implementing the API in this package:

Import-Package: org.osgi.service.monitor; version="[1.0,1.1)"

119.7.1 Summary

  • Monitorable - A Monitorable can provide information about itself in the form of StatusVariables.

  • MonitorAdmin - The MonitorAdmin service is a singleton service that handles StatusVariable query requests and measurement job control requests.

  • MonitoringJob - A Monitoring Job is a request for scheduled or event based notifications on update of a set of StatusVariables.

  • MonitorListener - The MonitorListener is used by Monitorable services to send notifications when a StatusVariable value is changed.

  • MonitorPermission - Indicates the callers authority to publish, read or reset StatusVariables, to switch event sending on or off or to start monitoring jobs.

  • StatusVariable - A StatusVariable object represents the value of a status variable taken with a certain collection method at a certain point of time.

119.7.2 public interface Monitorable

A Monitorable can provide information about itself in the form of StatusVariables. Instances of this interface should register themselves at the OSGi Service Registry. The MonitorAdmin listens to the registration of Monitorable services, and makes the information they provide available also through the Device Management Tree (DMT) for remote access.

The monitorable service is identified by its PID string which must be a non- null, non-empty string that conforms to the "symbolic-name" definition in the OSGi core specification. This means that only the characters [-_.a-zA-Z0-9] may be used. The length of the PID must not exceed 32 characters.

A Monitorable may optionally support sending notifications when the status of its StatusVariables change. Support for change notifications can be defined per StatusVariable.

Publishing StatusVariables requires the presence of the MonitorPermission with the publish action string. This permission, however, is not checked during registration of the Monitorable service. Instead, the MonitorAdmin implementation must make sure that when a StatusVariable is queried, it is shown only if the Monitorable is authorized to publish the given StatusVariable.

119.7.2.1 public String getDescription(String id) throws IllegalArgumentException

the identifier of the StatusVariable, cannot be null

Returns a human readable description of a StatusVariable. This can be used by management systems on their GUI. The null return value is allowed if there is no description for the specified Status Variable.

The given identifier does not contain the Monitorable PID, i.e. it specifies the name and not the path of the Status Variable.

the human readable description of this StatusVariable or null if it is not set

IllegalArgumentException– if id points to a non-existing StatusVariable

119.7.2.2 public StatusVariable getStatusVariable(String id) throws IllegalArgumentException

the identifier of the StatusVariable, cannot be null

Returns the StatusVariable object addressed by its identifier. The StatusVariable will hold the value taken at the time of this method call.

The given identifier does not contain the Monitorable PID, i.e. it specifies the name and not the path of the Status Variable.

the StatusVariable object

IllegalArgumentException– if id points to a non-existing StatusVariable

119.7.2.3 public String[] getStatusVariableNames()

Returns the list of StatusVariable identifiers published by this Monitorable. A StatusVariable name is unique within the scope of a Monitorable. The array contains the elements in no particular order. The returned value must not be null.

the StatusVariable identifiers published by this object, or an empty array if none are published

119.7.2.4 public boolean notifiesOnChange(String id) throws IllegalArgumentException

the identifier of the StatusVariable, cannot be null

Tells whether the StatusVariable provider is able to send instant notifications when the given StatusVariable changes. If the Monitorable supports sending change updates it must notify the MonitorListener when the value of the StatusVariable changes. The Monitorable finds the MonitorListener service through the Service Registry.

The given identifier does not contain the Monitorable PID, i.e. it specifies the name and not the path of the Status Variable.

true if the Monitorable can send notification when the given StatusVariable changes, false otherwise

IllegalArgumentException– if id points to a non-existing StatusVariable

119.7.2.5 public boolean resetStatusVariable(String id) throws IllegalArgumentException

the identifier of the StatusVariable, cannot be null

Issues a request to reset a given StatusVariable. Depending on the semantics of the actual Status Variable this call may or may not succeed: it makes sense to reset a counter to its starting value, but for example a StatusVariable of type String might not have a meaningful default value. Note that for numeric StatusVariables the starting value may not necessarily be 0. Resetting a StatusVariable must trigger a monitor event.

The given identifier does not contain the Monitorable PID, i.e. it specifies the name and not the path of the Status Variable.

true if the Monitorable could successfully reset the given StatusVariable, false otherwise

IllegalArgumentException– if id points to a non-existing StatusVariable

119.7.3 public interface MonitorAdmin

The MonitorAdmin service is a singleton service that handles StatusVariable query requests and measurement job control requests.

Note that an alternative but not recommended way of obtaining StatusVariables is that applications having the required ServicePermissions can query the list of Monitorable services from the service registry and then query the list of StatusVariable names from the Monitorable services. This way all services which publish StatusVariables will be returned regardless of whether they do or do not hold the necessary MonitorPermission for publishing StatusVariables. By using the MonitorAdmin to obtain the StatusVariables it is guaranteed that only those Monitorable services will be accessed who are authorized to publish StatusVariables. It is the responsibility of the MonitorAdmin implementation to check the required permissions and show only those variables which pass this check.

The events posted by MonitorAdmin contain the following properties:

  • mon.monitorable.pid: The identifier of the Monitorable

  • mon.statusvariable.name: The identifier of the StatusVariable within the given Monitorable

  • mon.statusvariable.value: The value of the StatusVariable , represented as a String

  • mon.listener.id: The identifier of the initiator of the monitoring job (only present if the event was generated due to a monitoring job)

Most of the methods require either a Monitorable ID or a Status Variable path parameter, the latter in [Monitorable_ID]/[StatusVariable_ID] format. These parameters must not be null, and the IDs they contain must conform to their respective definitions in Monitorable and StatusVariable. If any of the restrictions are violated, the method must throw an IllegalArgumentException.

119.7.3.1 public String getDescription(String path) throws IllegalArgumentException, SecurityException

the full path of the StatusVariable in [Monitorable_ID]/[StatusVariable_ID] format

Returns a human readable description of the given StatusVariable. The null value may be returned if there is no description for the given StatusVariable.

The entity that queries a StatusVariable needs to hold MonitorPermission for the given target with the read action present.

the human readable description of this StatusVariable or null if it is not set

IllegalArgumentException– if path is null or otherwise invalid, or points to a non-existing StatusVariable

SecurityException– if the caller does not hold a MonitorPermission for the StatusVariable specified by path with the read action present

119.7.3.2 public String[] getMonitorableNames()

Returns the names of the Monitorable services that are currently registered. The Monitorable instances are not accessible through the MonitorAdmin, so that requests to individual status variables can be filtered with respect to the publishing rights of the Monitorable and the reading rights of the caller.

The returned array contains the names in alphabetical order. It cannot be null, an empty array is returned if no Monitorable services are registered.

the array of Monitorable names

119.7.3.3 public MonitoringJob[] getRunningJobs()

Returns the list of currently running MonitoringJobs. Jobs are only visible to callers that have the necessary permissions: to receive a Monitoring Job in the returned list, the caller must hold all permissions required for starting the job. This means that if the caller does not have MonitorPermission with the proper startjob action for all the Status Variables monitored by a job, then that job will be silently omitted from the results.

The returned array cannot be null, an empty array is returned if there are no running jobs visible to the caller at the time of the call.

the list of running jobs visible to the caller

119.7.3.4 public StatusVariable getStatusVariable(String path) throws IllegalArgumentException, SecurityException

the full path of the StatusVariable in [Monitorable_ID]/[StatusVariable_ID] format

Returns a StatusVariable addressed by its full path. The entity which queries a StatusVariable needs to hold MonitorPermission for the given target with the read action present.

the StatusVariable object

IllegalArgumentException– if path is null or otherwise invalid, or points to a non-existing StatusVariable

SecurityException– if the caller does not hold a MonitorPermission for the StatusVariable specified by path with the read action present

119.7.3.5 public String[] getStatusVariableNames(String monitorableId) throws IllegalArgumentException

the identifier of a Monitorable instance

Returns the list of StatusVariable names published by a Monitorable instance. Only those status variables are listed where the following two conditions are met:

  • the specified Monitorable holds a MonitorPermission for the status variable with the publish action present

  • the caller holds a MonitorPermission for the status variable with the read action present

All other status variables are silently ignored, their names are omitted from the list.

The returned array does not contain duplicates, and the elements are in alphabetical order. It cannot be null, an empty array is returned if no (authorized and readable) Status Variables are provided by the given Monitorable.

a list of StatusVariable objects names published by the specified Monitorable

IllegalArgumentException– if monitorableId is null or otherwise invalid, or points to a non-existing Monitorable

119.7.3.6 public StatusVariable[] getStatusVariables(String monitorableId) throws IllegalArgumentException

the identifier of a Monitorable instance

Returns the StatusVariable objects published by a Monitorable instance. The StatusVariables will hold the values taken at the time of this method call. Only those status variables are returned where the following two conditions are met:

  • the specified Monitorable holds a MonitorPermission for the status variable with the publish action present

  • the caller holds a MonitorPermission for the status variable with the read action present

All other status variables are silently ignored, they are omitted from the result.

The elements in the returned array are in no particular order. The return value cannot be null, an empty array is returned if no (authorized and readable) Status Variables are provided by the given Monitorable.

a list of StatusVariable objects published by the specified Monitorable

IllegalArgumentException– if monitorableId is null or otherwise invalid, or points to a non-existing Monitorable

119.7.3.7 public boolean resetStatusVariable(String path) throws IllegalArgumentException, SecurityException

the identifier of the StatusVariable in [Monitorable_id]/[StatusVariable_id] format

Issues a request to reset a given StatusVariable. Depending on the semantics of the StatusVariable this call may or may not succeed: it makes sense to reset a counter to its starting value, but e.g. a StatusVariable of type String might not have a meaningful default value. Note that for numeric StatusVariables the starting value may not necessarily be 0. Resetting a StatusVariable triggers a monitor event if the StatusVariable supports update notifications.

The entity that wants to reset the StatusVariable needs to hold MonitorPermission with the reset action present. The target field of the permission must match the StatusVariable name to be reset.

true if the Monitorable could successfully reset the given StatusVariable, false otherwise

IllegalArgumentException– if path is null or otherwise invalid, or points to a non-existing StatusVariable

SecurityException– if the caller does not hold MonitorPermission with the reset action or if the specified StatusVariable is not allowed to be reset as per the target field of the permission

119.7.3.8 public MonitoringJob startJob(String initiator, String[] statusVariables, int count) throws IllegalArgumentException, SecurityException

the identifier of the entity that initiated the job

the list of StatusVariables to be monitored, with each StatusVariable name given in [Monitorable_PID]/[StatusVariable_ID] format

the number of changes that must happen to a StatusVariable before a new notification is sent

Starts a change based MonitoringJob with the parameters provided. Monitoring events will be sent when the StatusVariables of this job are updated. All specified StatusVariables must exist when the job is started, and all must support update notifications. The initiator string is used in the mon.listener.id field of all events triggered by the job, to allow filtering the events based on the initiator.

The count parameter specifies the number of changes that must happen to a StatusVariable before a new notification is sent, this must be a positive integer.

The entity which initiates a MonitoringJob needs to hold MonitorPermission for all the specified target StatusVariables with the startjob action present.

the successfully started job object, cannot be null

IllegalArgumentException– if the list of StatusVariable names contains an invalid or non-existing StatusVariable, or one that does not support notifications; if the initiator is null or empty; or if count is invalid

SecurityException– if the caller does not hold MonitorPermission for all the specified StatusVariables, with the startjob action present

119.7.3.9 public MonitoringJob startScheduledJob(String initiator, String[] statusVariables, int schedule, int count) throws IllegalArgumentException, SecurityException

the identifier of the entity that initiated the job

the list of StatusVariables to be monitored, with each StatusVariable name given in [Monitorable_PID]/[StatusVariable_ID] format

the time in seconds between two measurements

the number of measurements to be taken, or 0 for the measurement to run until explicitly stopped

Starts a time based MonitoringJob with the parameters provided. Monitoring events will be sent according to the specified schedule. All specified StatusVariables must exist when the job is started. The initiator string is used in the mon.listener.id field of all events triggered by the job, to allow filtering the events based on the initiator.

The schedule parameter specifies the time in seconds between two measurements, it must be greater than 0. The first measurement will be taken when the timer expires for the first time, not when this method is called.

The count parameter defines the number of measurements to be taken, and must either be a positive integer, or 0 if the measurement is to run until explicitly stopped.

The entity which initiates a MonitoringJob needs to hold MonitorPermission for all the specified target StatusVariables with the startjob action present. If the permission's action string specifies a minimal sampling interval then the schedule parameter should be at least as great as the value in the action string.

the successfully started job object, cannot be null

IllegalArgumentException– if the list of StatusVariable names contains an invalid or non-existing StatusVariable; if initiator is null or empty; or if the schedule or count parameters are invalid

SecurityException– if the caller does not hold MonitorPermission for all the specified StatusVariables, with the startjob action present, or if the permission does not allow starting the job with the given frequency

119.7.3.10 public void switchEvents(String path, boolean on) throws IllegalArgumentException, SecurityException

the identifier of the StatusVariable(s) in [Monitorable_id]/[StatusVariable_id] format, possibly with the "*" wildcard at the end of either path fragment

false if event sending should be switched off, true if it should be switched on for the given path

Switches event sending on or off for the specified StatusVariable s. When the MonitorAdmin is notified about a StatusVariable being updated it sends an event unless this feature is switched off. Note that events within a monitoring job can not be switched off. The event sending state of the StatusVariables must not be persistently stored. When a StatusVariable is registered for the first time in a framework session, its event sending state is set to ON by default.

Usage of the "*" wildcard is allowed in the path argument of this method as a convenience feature. The wildcard can be used in either or both path fragments, but only at the end of the fragments. The semantics of the wildcard is that it stands for any matching StatusVariable at the time of the method call, it does not affect the event sending status of StatusVariables which are not yet registered. As an example, when the switchEvents("MyMonitorable/*", false) method is executed, event sending from all StatusVariables of the MyMonitorable service are switched off. However, if the MyMonitorable service starts to publish a new StatusVariable later, it's event sending status is on by default.

SecurityException– if the caller does not hold MonitorPermission with the switchevents action or if there is any StatusVariable in the path field for which it is not allowed to switch event sending on or off as per the target field of the permission

IllegalArgumentException– if path is null or otherwise invalid, or points to a non-existing StatusVariable

119.7.4 public interface MonitoringJob

A Monitoring Job is a request for scheduled or event based notifications on update of a set of StatusVariables. The job is a data structure that holds a non-empty list of StatusVariable names, an identification of the initiator of the job, and the sampling parameters. There are two kinds of monitoring jobs: time based and change based. Time based jobs take samples of all StatusVariables with a specified frequency. The number of samples to be taken before the job finishes may be specified. Change based jobs are only interested in the changes of the monitored StatusVariables. In this case, the number of changes that must take place between two notifications can be specified.

The job can be started on the MonitorAdmin interface. Running the job (querying the StatusVariables, listening to changes, and sending out notifications on updates) is the task of the MonitorAdmin implementation.

Whether a monitoring job keeps track dynamically of the StatusVariables it monitors is not specified. This means that if we monitor a StatusVariable of a Monitorable service which disappears and later reappears then it is implementation specific whether we still receive updates of the StatusVariable changes or not.

119.7.4.1 public String getInitiator()

Returns the identifier of the principal who initiated the job. This is set at the time when MonitorAdmin.startJob method is called. This string holds the ServerID if the operation was initiated from a remote manager, or an arbitrary ID of the initiator entity in the local case (used for addressing notification events).

the ID of the initiator, cannot be null

119.7.4.2 public int getReportCount()

Returns the number of times MonitorAdmin will query the StatusVariables (for time based jobs), or the number of changes of a StatusVariable between notifications (for change based jobs). Time based jobs with non-zero report count will take getReportCount()*getSchedule() time to finish. Time based jobs with 0 report count and change based jobs do not stop automatically, but all jobs can be stopped with the stop() method.

the number of measurements to be taken, or the number of changes between notifications

119.7.4.3 public int getSchedule()

Returns the delay (in seconds) between two samples. If this call returns N (greater than 0) then the MonitorAdmin queries each StatusVariable that belongs to this job every N seconds. The value 0 means that the job is not scheduled but event based: in this case instant notification on changes is requested (at every n-th change of the value, as specified by the report count parameter).

the delay (in seconds) between samples, or 0 for change based jobs

119.7.4.4 public String[] getStatusVariableNames()

Returns the list of StatusVariable names that are the targets of this measurement job. For time based jobs, the MonitorAdmin will iterate through this list and query all StatusVariables when its timer set by the job's frequency rate expires.

the target list of the measurement job in [Monitorable_ID]/[StatusVariable_ID] format, cannot be null

119.7.4.5 public boolean isLocal()

Returns whether the job was started locally or remotely. Jobs started by the clients of this API are always local, remote jobs can only be started using the Device Management Tree.

true if the job was started from the local device, false if the job was initiated from a management server through the device management tree

119.7.4.6 public boolean isRunning()

Returns whether the job is running. A job is running until it is explicitly stopped, or, in case of time based jobs with a finite report count, until the given number of measurements have been made.

true if the job is still running, false if it has finished

119.7.4.7 public void stop()

Stops a Monitoring Job. Note that a time based job can also stop automatically if the specified number of samples have been taken.

119.7.5 public interface MonitorListener

The MonitorListener is used by Monitorable services to send notifications when a StatusVariable value is changed. The MonitorListener should register itself as a service at the OSGi Service Registry. This interface must (only) be implemented by the Monitor Admin component.

119.7.5.1 public void updated(String monitorableId, StatusVariable statusVariable) throws IllegalArgumentException

the identifier of the Monitorable instance reporting the change

the StatusVariable that has changed

Callback for notification of a StatusVariable change.

IllegalArgumentException– if the specified monitorable ID is invalid (null, empty, or contains illegal characters) or points to a non-existing Monitorable, or if statusVariable is null

119.7.6 public class MonitorPermission
extends Permission

Indicates the callers authority to publish, read or reset StatusVariables, to switch event sending on or off or to start monitoring jobs. The target of the permission is the identifier of the StatusVariable, the action can be read, publish, reset, startjob, switchevents, or the combination of these separated by commas. Action names are interpreted case-insensitively, but the canonical action string returned by getActions() uses the forms defined by the action constants.

If the wildcard * appears in the actions field, all legal monitoring commands are allowed on the designated target(s) by the owner of the permission.

119.7.6.1 public static final String PUBLISH = "publish"

Holders of MonitorPermission with the publish action present are Monitorable services that are allowed to publish the StatusVariables specified in the permission's target field. Note, that this permission cannot be enforced when a Monitorable registers to the framework, because the Service Registry does not know about this permission. Instead, any StatusVariables published by a Monitorable without the corresponding publish permission are silently ignored by MonitorAdmin, and are therefore invisible to the users of the monitoring service.

119.7.6.2 public static final String READ = "read"

Holders of MonitorPermission with the read action present are allowed to read the value of the StatusVariables specified in the permission's target field.

119.7.6.3 public static final String RESET = "reset"

Holders of MonitorPermission with the reset action present are allowed to reset the value of the StatusVariables specified in the permission's target field.

119.7.6.4 public static final String STARTJOB = "startjob"

Holders of MonitorPermission with the startjob action present are allowed to initiate monitoring jobs involving the StatusVariables specified in the permission's target field.

A minimal sampling interval can be optionally defined in the following form: startjob:n. This allows the holder of the permission to initiate time based jobs with a measurement interval of at least n seconds. If n is not specified or 0 then the holder of this permission is allowed to start monitoring jobs specifying any frequency.

119.7.6.5 public static final String SWITCHEVENTS = "switchevents"

Holders of MonitorPermission with the switchevents action present are allowed to switch event sending on or off for the value of the StatusVariables specified in the permission's target field.

119.7.6.6 public MonitorPermission(String statusVariable, String actions) throws IllegalArgumentException

the identifier of the StatusVariable in [Monitorable_id]/[StatusVariable_id] format

the list of allowed actions separated by commas, or * for all actions

Create a MonitorPermission object, specifying the target and actions.

The statusVariable parameter is the target of the permission, defining one or more status variable names to which the specified actions apply. Multiple status variable names can be selected by using the wildcard * in the target string. The wildcard is allowed in both fragments, but only at the end of the fragments.

For example, the following targets are valid: com.mycomp.myapp/queue_length, com.mycomp.myapp/*, com.mycomp.*/*, */*, */queue_length, */queue*.

The following targets are invalid: *.myapp/queue_length, com.*.myapp/*, *.

The actions parameter specifies the allowed action(s): read, publish, startjob, reset, switchevents, or the combination of these separated by commas. String constants are defined in this class for each valid action. Passing "*" as the action string is equivalent to listing all actions.

IllegalArgumentException– if either parameter is null, or invalid with regard to the constraints defined above and in the documentation of the used actions

119.7.6.7 public boolean equals(Object o)

the object being compared for equality with this object

Determines the equality of two MonitorPermission objects. Two MonitorPermission objects are equal if their target strings are equal and the same set of actions are listed in their action strings.

true if the two permissions are equal

119.7.6.8 public String getActions()

Get the action string associated with this permission. The actions are returned in the following order: read, reset, publish, startjob, switchevents.

the allowed actions separated by commas, cannot be null

119.7.6.9 public int hashCode()

Create an integer hash of the object. The hash codes of MonitorPermissions p1 and p2 are the same if p1.equals(p2).

the hash of the object

119.7.6.10 public boolean implies(Permission p)

the permission to be checked

Determines if the specified permission is implied by this permission.

This method returns false if and only if at least one of the following conditions are fulfilled for the specified permission:

  • it is not a MonitorPermission

  • it has a broader set of actions allowed than this one

  • it allows initiating time based monitoring jobs with a lower minimal sampling interval

  • the target set of Monitorables is not the same nor a subset of the target set of Monitorables of this permission

  • the target set of StatusVariables is not the same nor a subset of the target set of StatusVariables of this permission

true if the given permission is implied by this permission

119.7.7 public final class StatusVariable

A StatusVariable object represents the value of a status variable taken with a certain collection method at a certain point of time. The type of the StatusVariable can be int, float, boolean or String.

A StatusVariable is identified by an ID string that is unique within the scope of a Monitorable. The ID must be a non- null, non-empty string that conforms to the "symbolic-name" definition in the OSGi core specification. This means that only the characters [-_.a-zA-Z0-9] may be used. The length of the ID must not exceed 32 bytes when UTF-8 encoded.

119.7.7.1 public static final int CM_CC = 0

Constant for identifying 'Cumulative Counter' data collection method.

119.7.7.2 public static final int CM_DER = 1

Constant for identifying 'Discrete Event Registration' data collection method.

119.7.7.3 public static final int CM_GAUGE = 2

Constant for identifying 'Gauge' data collection method.

119.7.7.4 public static final int CM_SI = 3

Constant for identifying 'Status Inspection' data collection method.

119.7.7.5 public static final int TYPE_BOOLEAN = 3

Constant for identifying boolean data type.

119.7.7.6 public static final int TYPE_FLOAT = 1

Constant for identifying float data type.

119.7.7.7 public static final int TYPE_INTEGER = 0

Constant for identifying int data type.

119.7.7.8 public static final int TYPE_STRING = 2

Constant for identifying String data type.

119.7.7.9 public StatusVariable(String id, int cm, int data)

the identifier of the StatusVariable

the collection method, one of the CM_ constants

the int value of the StatusVariable

Constructor for a StatusVariable of int type.

IllegalArgumentException– if the given id is not a valid StatusVariable name, or if cm is not one of the collection method constants

NullPointerException– if the id parameter is null

119.7.7.10 public StatusVariable(String id, int cm, float data)

the identifier of the StatusVariable

the collection method, one of the CM_ constants

the float value of the StatusVariable

Constructor for a StatusVariable of float type.

IllegalArgumentException– if the given id is not a valid StatusVariable name, or if cm is not one of the collection method constants

NullPointerException– if the id parameter is null

119.7.7.11 public StatusVariable(String id, int cm, boolean data)

the identifier of the StatusVariable

the collection method, one of the CM_ constants

the boolean value of the StatusVariable

Constructor for a StatusVariable of boolean type.

IllegalArgumentException– if the given id is not a valid StatusVariable name, or if cm is not one of the collection method constants

NullPointerException– if the id parameter is null

119.7.7.12 public StatusVariable(String id, int cm, String data)

the identifier of the StatusVariable

the collection method, one of the CM_ constants

the String value of the StatusVariable, can be null

Constructor for a StatusVariable of String type.

IllegalArgumentException– if the given id is not a valid StatusVariable name, or if cm is not one of the collection method constants

NullPointerException– if the id parameter is null

119.7.7.13 public boolean equals(Object obj)

the object to compare with this StatusVariable

Compares the specified object with this StatusVariable. Two StatusVariable objects are considered equal if their full path, collection method and type are identical, and the data (selected by their type) is equal.

true if the argument represents the same StatusVariable as this object

119.7.7.14 public boolean getBoolean() throws IllegalStateException

Returns the StatusVariable value if its type is boolean.

the StatusVariable value as a boolean

IllegalStateException– if the type of this StatusVariable is not boolean

119.7.7.15 public int getCollectionMethod()

Returns the collection method of this StatusVariable. See section 3.3 b) in [ETSI TS 132 403]

one of the CM_ constants

119.7.7.16 public float getFloat() throws IllegalStateException

Returns the StatusVariable value if its type is float.

the StatusVariable value as a float

IllegalStateException– if the type of this StatusVariable is not float

119.7.7.17 public String getID()

Returns the ID of this StatusVariable. The ID is unique within the scope of a Monitorable.

the ID of this StatusVariable

119.7.7.18 public int getInteger() throws IllegalStateException

Returns the StatusVariable value if its type is int.

the StatusVariable value as an int

IllegalStateException– if the type of this StatusVariable is not int

119.7.7.19 public String getString() throws IllegalStateException

Returns the StatusVariable value if its type is String.

the StatusVariable value as a String

IllegalStateException– if the type of the StatusVariable is not String

119.7.7.20 public Date getTimeStamp()

Returns the timestamp associated with the StatusVariable. The timestamp is stored when the StatusVariable instance is created, generally during the Monitorable.getStatusVariable(String) method call.

the time when the StatusVariable value was queried, cannot be null

119.7.7.21 public int getType()

Returns information on the data type of this StatusVariable.

one of the TYPE_ constants indicating the type of this StatusVariable

119.7.7.22 public int hashCode()

Returns the hash code value for this StatusVariable. The hash code is calculated based on the full path, collection method and value of the StatusVariable.

the hash code of this object

119.7.7.23 public String toString()

Returns a String representation of this StatusVariable. The returned String contains the full path, collection method, timestamp, type and value parameters of the StatusVariable in the following format:

 StatusVariable(<path>, <cm>, <timestamp>, <type>, <value>)

The collection method identifiers used in the string representation are "CC", "DER", "GAUGE" and "SI" (without the quotes). The format of the timestamp is defined by the Date.toString method, while the type is identified by one of the strings "INTEGER", "FLOAT", "STRING" and "BOOLEAN". The final field contains the string representation of the value of the status variable.

the String representation of this StatusVariable

119.8 References

[1]SyncML Device Management Tree Description

[3]RFC-2396 Uniform Resource Identifiers (URI): Generic Syntaxhttp://www.ietf.org/rfc/rfc2396.txt