public 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
.
Modifier and Type | Method and Description |
---|---|
String |
getDescription(String id)
Returns a human readable description of a
StatusVariable . |
StatusVariable |
getStatusVariable(String id)
Returns the
StatusVariable object addressed by its
identifier. |
String[] |
getStatusVariableNames()
Returns the list of
StatusVariable identifiers published
by this Monitorable . |
boolean |
notifiesOnChange(String id)
Tells whether the
StatusVariable provider is able to send
instant notifications when the given StatusVariable
changes. |
boolean |
resetStatusVariable(String id)
Issues a request to reset a given
StatusVariable . |
String[] getStatusVariableNames()
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
.StatusVariable identifiers published by this
object, or an empty array if none are published
StatusVariable getStatusVariable(String id) throws IllegalArgumentException
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.
id
- the identifier of the StatusVariable
, cannot be
null
StatusVariable
objectIllegalArgumentException
- if id
points to a
non-existing StatusVariable
boolean notifiesOnChange(String id) throws IllegalArgumentException
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.
id
- the identifier of the StatusVariable
, cannot be
null
true
if the Monitorable
can send
notification when the given StatusVariable
changes, false
otherwiseIllegalArgumentException
- if id
points to a
non-existing StatusVariable
boolean resetStatusVariable(String id) throws IllegalArgumentException
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.
id
- the identifier of the StatusVariable
, cannot be
null
true
if the Monitorable
could
successfully reset the given StatusVariable
,
false
otherwiseIllegalArgumentException
- if id
points to a
non-existing StatusVariable
String getDescription(String id) throws IllegalArgumentException
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.
id
- the identifier of the StatusVariable
, cannot be
null
StatusVariable
or null
if it is not
setIllegalArgumentException
- if id
points to a
non-existing StatusVariable
Copyright © 2006–2017 OSGi Alliance. All rights reserved.