Interface Monitorable
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
20 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
.
- Version:
- $Revision: 7940 $
-
Method Summary
Modifier and TypeMethodDescriptiongetDescription
(String id) Returns a human readable description of aStatusVariable
.Returns theStatusVariable
object addressed by its identifier.String[]
Returns the list ofStatusVariable
identifiers published by thisMonitorable
.boolean
Tells whether theStatusVariable
provider is able to send instant notifications when the givenStatusVariable
changes.boolean
Issues a request to reset a givenStatusVariable
.
-
Method Details
-
getStatusVariableNames
String[] getStatusVariableNames()Returns the list ofStatusVariable
identifiers published by thisMonitorable
. AStatusVariable
name is unique within the scope of aMonitorable
. The array contains the elements in no particular order. The returned value must not benull
.- Returns:
- the
StatusVariable
identifiers published by this object, or an empty array if none are published
-
getStatusVariable
Returns theStatusVariable
object addressed by its identifier. TheStatusVariable
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.
- Parameters:
id
- the identifier of theStatusVariable
, cannot benull
- Returns:
- the
StatusVariable
object - Throws:
IllegalArgumentException
- ifid
points to a non-existingStatusVariable
-
notifiesOnChange
Tells whether theStatusVariable
provider is able to send instant notifications when the givenStatusVariable
changes. If theMonitorable
supports sending change updates it must notify theMonitorListener
when the value of theStatusVariable
changes. TheMonitorable
finds theMonitorListener
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.
- Parameters:
id
- the identifier of theStatusVariable
, cannot benull
- Returns:
true
if theMonitorable
can send notification when the givenStatusVariable
changes,false
otherwise- Throws:
IllegalArgumentException
- ifid
points to a non-existingStatusVariable
-
resetStatusVariable
Issues a request to reset a givenStatusVariable
. 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 aStatusVariable
of typeString
might not have a meaningful default value. Note that for numericStatusVariables
the starting value may not necessarily be 0. Resetting aStatusVariable
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.
- Parameters:
id
- the identifier of theStatusVariable
, cannot benull
- Returns:
true
if theMonitorable
could successfully reset the givenStatusVariable
,false
otherwise- Throws:
IllegalArgumentException
- ifid
points to a non-existingStatusVariable
-
getDescription
Returns a human readable description of aStatusVariable
. This can be used by management systems on their GUI. Thenull
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.
- Parameters:
id
- the identifier of theStatusVariable
, cannot benull
- Returns:
- the human readable description of this
StatusVariable
ornull
if it is not set - Throws:
IllegalArgumentException
- ifid
points to a non-existingStatusVariable
-