org.osgi.service.monitor
Interface Monitorable

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 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 implemenatation must make sure that when a StatusVariable is queried, it is shown only if the Monitorable is authorized to publish the given StatusVariable.

Method Summary

java.lang.String	getDescription(java.lang.String id) Returns a human readable description of a StatusVariable.
StatusVariable	getStatusVariable(java.lang.String id) Returns the StatusVariable object addressed by its identifier.
java.lang.String[]	getStatusVariableNames() Returns the list of StatusVariable identifiers published by this Monitorable.
boolean	notifiesOnChange(java.lang.String id) Tells whether the StatusVariable provider is able to send instant notifications when the given StatusVariable changes.
boolean	resetStatusVariable(java.lang.String id) Issues a request to reset a given StatusVariable.

Method Detail

getStatusVariableNames

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

Returns:

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

getStatusVariable

public StatusVariable getStatusVariable(java.lang.String id)
                                 throws java.lang.IllegalArgumentException

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.

Parameters:

id - the identifier of the StatusVariable, cannot be null

Returns:

the StatusVariable object

Throws:

java.lang.IllegalArgumentException - if id points to a non-existing StatusVariable

notifiesOnChange

public boolean notifiesOnChange(java.lang.String id)
                         throws java.lang.IllegalArgumentException

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.

Parameters:

id - the identifier of the StatusVariable, cannot be null

Returns:

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

Throws:

java.lang.IllegalArgumentException - if id points to a non-existing StatusVariable

resetStatusVariable

public boolean resetStatusVariable(java.lang.String id)
                            throws java.lang.IllegalArgumentException

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.

Parameters:

id - the identifier of the StatusVariable, cannot be null

Returns:

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

Throws:

java.lang.IllegalArgumentException - if id points to a non-existing StatusVariable

getDescription

public java.lang.String getDescription(java.lang.String id)
                                throws java.lang.IllegalArgumentException

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.

Parameters:

id - the identifier of the StatusVariable, cannot be null

Returns:

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

Throws:

java.lang.IllegalArgumentException - if id points to a non-existing StatusVariable