Monitorable
Date: 2016-06-25

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

    Methods
    Modifier and Type | Method and 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`