org.osgi.service.monitor
Interface MonitoringJob

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.

Method Summary

java.lang.String

getInitiator()
Returns the identifier of the principal who initiated the job.

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).

stop

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.

getInitiator

java.lang.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).

Returns:

the ID of the initiator, cannot be null

getStatusVariableNames

java.lang.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.

Returns:

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

getSchedule

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).

Returns:

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

getReportCount

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.

Returns:

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

isLocal

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.

Returns:

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

isRunning

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.