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.
-
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,booleanorStringobjects. -
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).
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.
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 CoreThe 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.
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:
-
getStatusVariableNames() - Provides a list of the Status Variable names. The status variables can subsequently be acquired with the getStatusVariable(String) method.
-
getStatusVariable(String) - Given the name of a Status Variable, return the
StatusVariableobject, if exists. -
resetStatusVariable(String) - Reset the given Status Variable if there is a reasonable reset value. If the Status Variable could not be reset,
falseis returned. Otherwisetrueis returned. Resetting a Status Variable triggers a Monitor Event, as described in Monitoring events. -
notifiesOnChange(String) - Tells whether the given Status Variable sends a notification when its value changes or when it is reset. This is further discussed in Providing Notifications.
-
getDescription(String) - Provide a non-localized description of the given Status Variable.
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.
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);
}
}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.
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 CoreThe 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.
A Status Variable provides the type of its value with the getType() method. The return value of this method can take the following values:
-
TYPE_BOOLEAN - A
booleanvalue. The associated method to retrieve the value is getBoolean(). The corresponding constructor is StatusVariable(String,int,boolean). -
TYPE_INTEGER - A signed numeric value that fits in a Java
inttype. The associated method to retrieve the value is getInteger(). The corresponding constructor is StatusVariable(String,int,int). -
TYPE_FLOAT - A floating point value that fits in a Java
floattype. The associated method to retrieve the value is getFloat(). The corresponding constructor is StatusVariable(String,int,float). -
TYPE_STRING - A
Stringobject. The associated method to retrieve the value is getString().The corresponding constructor is StatusVariable(String,int,String)
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.
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.
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
GAUGEis 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.
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.
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.
The Monitor Admin provides the following methods for manipulating the Status Variables:
-
getStatusVariable(String) - Return a Status Variable given a Status Variable path. A path must have the following syntax:
status-variable-path ::= pid '/' status-variable-name -
getStatusVariableNames(String) - Returns the Status Variable names given the PID of a Monitorable service.
-
getStatusVariables(String) - Returns an array of Status Variable objects given the PID of a Monitorable service.
-
resetStatusVariable(String) - Reset the value of a Status Variable.
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.freeThe 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.
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.packetsThe 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.
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.
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.
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.
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/MonitorEventThe 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 theMonitorListenerinterface 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 theStringobject.-
long-Long.toString(long). -
double-Double.toString(double). -
boolean-Boolean.toString(boolean). -
String- No conversion
-
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.freeThe 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:nThe
nis the allowed minimal value of the schedule parameter of time based monitoring jobs. Ifnis 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 |
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)"
-
Monitorable- AMonitorablecan provide information about itself in the form ofStatusVariables. -
MonitorAdmin- TheMonitorAdminservice is a singleton service that handlesStatusVariablequery requests and measurement job control requests. -
MonitoringJob- A Monitoring Job is a request for scheduled or event based notifications on update of a set ofStatusVariables. -
MonitorListener- TheMonitorListeneris used byMonitorableservices to send notifications when aStatusVariablevalue is changed. -
MonitorPermission- Indicates the callers authority to publish, read or resetStatusVariables, to switch event sending on or off or to start monitoring jobs. -
StatusVariable- AStatusVariableobject represents the value of a status variable taken with a certain collection method at a certain point of time.
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.
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
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
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
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
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
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 theMonitorable -
mon.statusvariable.name: The identifier of theStatusVariablewithin the givenMonitorable -
mon.statusvariable.value: The value of theStatusVariable, represented as aString -
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.
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
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
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
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
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
Monitorableholds aMonitorPermissionfor the status variable with thepublishaction present -
the caller holds a
MonitorPermissionfor the status variable with thereadaction 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
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
Monitorableholds aMonitorPermissionfor the status variable with thepublishaction present -
the caller holds a
MonitorPermissionfor the status variable with thereadaction 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
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
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
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
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
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.
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
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
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
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
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
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
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.
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
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.
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.
Holders of MonitorPermission with the read action present
are allowed to read the value of the StatusVariables specified in
the permission's target field.
Holders of MonitorPermission with the reset action
present are allowed to reset the value of the StatusVariables
specified in the permission's target field.
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.
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.
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
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
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
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
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 ofMonitorables of this permission -
the target set of
StatusVariables is not the same nor a subset of the target set ofStatusVariables of this permission
true if the given permission is implied by this
permission
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.
Constant for identifying 'Cumulative Counter' data collection method.
Constant for identifying 'Discrete Event Registration' data collection method.
Constant for identifying 'Gauge' data collection method.
Constant for identifying 'Status Inspection' data collection method.
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
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
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
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
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
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
Returns the collection method of this StatusVariable. See section
3.3 b) in [ETSI TS 132 403]
one of the CM_ constants
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
Returns the ID of this StatusVariable. The ID is unique within
the scope of a Monitorable.
the ID of this StatusVariable
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
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
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
Returns information on the data type of this StatusVariable.
one of the TYPE_ constants indicating the type of this
StatusVariable
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
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
[2]ETSI Performance Management [TS 132 403]http://www.etsi.org/deliver/etsi_ts/132400_132499/132403/04.01.00_60/ts_132403v040100p.pdf
[3]RFC-2396 Uniform Resource Identifiers (URI): Generic Syntaxhttp://www.ietf.org/rfc/rfc2396.txt