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 Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      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

        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

        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

        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

        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

        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