MonitorPermission
Date: 2016-06-25

org.osgi.service.monitor

## Class MonitorPermission

- java.lang.Object
- - java.security.Permission
  - - org.osgi.service.monitor.MonitorPermission

- All Implemented Interfaces:
    java.io.Serializable, java.security.Guard

      public class MonitorPermission
      extends java.security.Permission

  Indicates the callers authority to publish, read or reset `StatusVariable`s, to switch event sending on or off or to start monitoring jobs. The target of the permission is the identifier of the `StatusVariable`, the action can be `read`, `publish`, `reset`, `startjob`, `switchevents`, or the combination of these separated by commas. Action names are interpreted case-insensitively, but the canonical action string returned by `getActions()` uses the forms defined by the action constants.

  If the wildcard `*` appears in the actions field, all legal monitoring commands are allowed on the designated target(s) by the owner of the permission.

  See Also:
    Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `PUBLISH` Holders of `MonitorPermission` with the `publish` action present are `Monitorable` services that are allowed to publish the `StatusVariable`s specified in the permission's target field.
    `static java.lang.String` | `READ` Holders of `MonitorPermission` with the `read` action present are allowed to read the value of the `StatusVariable`s specified in the permission's target field.
    `static java.lang.String` | `RESET` Holders of `MonitorPermission` with the `reset` action present are allowed to reset the value of the `StatusVariable`s specified in the permission's target field.
    `static java.lang.String` | `STARTJOB` Holders of `MonitorPermission` with the `startjob` action present are allowed to initiate monitoring jobs involving the `StatusVariable`s specified in the permission's target field.
    `static java.lang.String` | `SWITCHEVENTS` Holders of `MonitorPermission` with the `switchevents` action present are allowed to switch event sending on or off for the value of the `StatusVariable`s specified in the permission's target field.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `MonitorPermission(java.lang.String statusVariable, java.lang.String actions)` Create a `MonitorPermission` object, specifying the target and actions.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `equals(java.lang.Object o)` Determines the equality of two `MonitorPermission` objects.
    `java.lang.String` | `getActions()` Get the action string associated with this permission.
    `int` | `hashCode()` Create an integer hash of the object.
    `boolean` | `implies(java.security.Permission p)` Determines if the specified permission is implied by this permission.

    - ### Methods inherited from class java.security.Permission

      `checkGuard, getName, newPermissionCollection, toString`

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### READ

          public static final java.lang.String READ

      Holders of `MonitorPermission` with the `read` action present are allowed to read the value of the `StatusVariable`s specified in the permission's target field.
      See Also:
        Constant Field Values

    - #### RESET

          public static final java.lang.String RESET

      Holders of `MonitorPermission` with the `reset` action present are allowed to reset the value of the `StatusVariable`s specified in the permission's target field.
      See Also:
        Constant Field Values

    - #### PUBLISH

          public static final java.lang.String PUBLISH

      Holders of `MonitorPermission` with the `publish` action present are `Monitorable` services that are allowed to publish the `StatusVariable`s specified in the permission's target field. Note, that this permission cannot be enforced when a `Monitorable` registers to the framework, because the Service Registry does not know about this permission. Instead, any `StatusVariable`s published by a `Monitorable` without the corresponding `publish` permission are silently ignored by `MonitorAdmin`, and are therefore invisible to the users of the monitoring service.
      See Also:
        Constant Field Values

    - #### STARTJOB

          public static final java.lang.String STARTJOB

      Holders of `MonitorPermission` with the `startjob` action present are allowed to initiate monitoring jobs involving the `StatusVariable`s specified in the permission's target field.

      A minimal sampling interval can be optionally defined in the following form: `startjob:n`. This allows the holder of the permission to initiate time based jobs with a measurement interval of at least `n` seconds. If `n` is not specified or 0 then the holder of this permission is allowed to start monitoring jobs specifying any frequency.

      See Also:
        Constant Field Values

    - #### SWITCHEVENTS

          public static final java.lang.String SWITCHEVENTS

      Holders of `MonitorPermission` with the `switchevents` action present are allowed to switch event sending on or off for the value of the `StatusVariable`s specified in the permission's target field.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### MonitorPermission

          public MonitorPermission(java.lang.String statusVariable,
                           java.lang.String actions)
                            throws java.lang.IllegalArgumentException

      Create a `MonitorPermission` object, specifying the target and actions.

      The `statusVariable` parameter is the target of the permission, defining one or more status variable names to which the specified actions apply. Multiple status variable names can be selected by using the wildcard `*` in the target string. The wildcard is allowed in both fragments, but only at the end of the fragments.

      For example, the following targets are valid: `com.mycomp.myapp/queue_length`, `com.mycomp.myapp/*`, `com.mycomp.*/*`, `*/*`, `*/queue_length`, `*/queue*`.

      The following targets are invalid: `*.myapp/queue_length`, `com.*.myapp/*`, `*`.

      The `actions` parameter specifies the allowed action(s): `read`, `publish`, `startjob`, `reset`, `switchevents`, or the combination of these separated by commas. String constants are defined in this class for each valid action. Passing `"*"` as the action string is equivalent to listing all actions.

      Parameters:
        `statusVariable` - the identifier of the `StatusVariable` in [Monitorable_id]/[StatusVariable_id] format
        `actions` - the list of allowed actions separated by commas, or `*` for all actions
      Throws:
        `java.lang.IllegalArgumentException` - if either parameter is `null`, or invalid with regard to the constraints defined above and in the documentation of the used actions

  - ### Method Detail

    - #### hashCode

          public int hashCode()

      Create an integer hash of the object. The hash codes of `MonitorPermission`s `p1` and `p2` are the same if `p1.equals(p2)`.
      Specified by:
        `hashCode` in class `java.security.Permission`
      Returns:
        the hash of the object

    - #### equals

          public boolean equals(java.lang.Object o)

      Determines the equality of two `MonitorPermission` objects. Two `MonitorPermission` objects are equal if their target strings are equal and the same set of actions are listed in their action strings.
      Specified by:
        `equals` in class `java.security.Permission`
      Parameters:
        `o` - the object being compared for equality with this object
      Returns:
        `true` if the two permissions are equal

    - #### getActions

          public java.lang.String getActions()

      Get the action string associated with this permission. The actions are returned in the following order: `read`, `reset`, `publish`, `startjob`, `switchevents`.
      Specified by:
        `getActions` in class `java.security.Permission`
      Returns:
        the allowed actions separated by commas, cannot be `null`

    - #### implies

          public boolean implies(java.security.Permission p)

      Determines if the specified permission is implied by this permission.

      This method returns `false` if and only if at least one of the following conditions are fulfilled for the specified permission:

      - it is not a `MonitorPermission`
      - it has a broader set of actions allowed than this one
      - it allows initiating time based monitoring jobs with a lower minimal sampling interval
      - the target set of `Monitorable`s is not the same nor a subset of the target set of `Monitorable`s of this permission
      - the target set of `StatusVariable`s is not the same nor a subset of the target set of `StatusVariable`s of this permission
      Specified by:
        `implies` in class `java.security.Permission`
      Parameters:
        `p` - the permission to be checked
      Returns:
        `true` if the given permission is implied by this permission