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

  • Method Details

    • getStatusVariableNames

      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

      StatusVariable getStatusVariable(String id) throws 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:
      IllegalArgumentException - if id points to a non-existing StatusVariable

    • notifiesOnChange

      boolean notifiesOnChange(String id) throws 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:
      IllegalArgumentException - if id points to a non-existing StatusVariable

    • resetStatusVariable

      boolean resetStatusVariable(String id) throws 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:
      IllegalArgumentException - if id points to a non-existing StatusVariable

    • getDescription

      String getDescription(String id) throws 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:
      IllegalArgumentException - if id points to a non-existing StatusVariable