SubsystemPermission
Date: 2016-06-25

org.osgi.service.subsystem

## Class SubsystemPermission

- java.lang.Object
- - java.security.Permission
  - - java.security.BasicPermission
    - - org.osgi.service.subsystem.SubsystemPermission

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

      public final class SubsystemPermission
      extends java.security.BasicPermission

  A bundle's authority to perform specific privileged administrative operations on or to get sensitive information about a subsystem. The actions for this permission are:

       Action    Methods
       context   Subsystem.getBundleContext
       execute   Subsystem.start
                 Subsystem.stop
       lifecycle Subsystem.install
                 Subsystem.uninstall
       metadata  Subsystem.getSubsystemHeaders
                 Subsystem.getLocation

  The name of this permission is a filter expression. The filter gives access to the following attributes:

  - location - The location of a subsystem.
  - id - The subsystem ID of the designated subsystem.
  - name - The symbolic name of a subsystem.
  Filter attribute names are processed in a case sensitive manner.
  See Also:
    Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `CONTEXT` The action string `context`.
    `static java.lang.String` | `EXECUTE` The action string `execute`.
    `static java.lang.String` | `LIFECYCLE` The action string `lifecycle`.
    `static java.lang.String` | `METADATA` The action string `metadata`.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `SubsystemPermission(java.lang.String filter, java.lang.String actions)` Create a new SubsystemPermission.
    `SubsystemPermission(Subsystem subsystem, java.lang.String actions)` Creates a new requested `SubsystemPermission` object to be used by the code that must perform `checkPermission`.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `equals(java.lang.Object obj)` Determines the equality of two `SubsystemPermission` objects.
    `java.lang.String` | `getActions()` Returns the canonical string representation of the `SubsystemPermission` actions.
    `int` | `hashCode()` Returns the hash code value for this object.
    `boolean` | `implies(java.security.Permission p)` Determines if the specified permission is implied by this object.
    `java.security.PermissionCollection` | `newPermissionCollection()` Returns a new `PermissionCollection` object suitable for storing `SubsystemPermission`s.

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

      `checkGuard, getName, toString`

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

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

- - ### Field Detail

    - #### EXECUTE

          public static final java.lang.String EXECUTE

      The action string `execute`.
      See Also:
        Constant Field Values

    - #### LIFECYCLE

          public static final java.lang.String LIFECYCLE

      The action string `lifecycle`.
      See Also:
        Constant Field Values

    - #### METADATA

          public static final java.lang.String METADATA

      The action string `metadata`.
      See Also:
        Constant Field Values

    - #### CONTEXT

          public static final java.lang.String CONTEXT

      The action string `context`.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### SubsystemPermission

          public SubsystemPermission(java.lang.String filter,
                             java.lang.String actions)

      Create a new SubsystemPermission. This constructor must only be used to create a permission that is going to be checked.

      Examples:

           (name=com.acme.*)(location=http://www.acme.com/subsystems/*))
           (id>=1)

      Parameters:
        `filter` - A filter expression that can use, location, id, and name keys. Filter attribute names are processed in a case sensitive manner. A special value of `"*"` can be used to match all subsystems.
        `actions` - `execute`, `lifecycle`, `metadata`, or `context`.
      Throws:
        `java.lang.IllegalArgumentException` - If the filter has an invalid syntax.

    - #### SubsystemPermission

          public SubsystemPermission(Subsystem subsystem,
                             java.lang.String actions)

      Creates a new requested `SubsystemPermission` object to be used by the code that must perform `checkPermission`. `SubsystemPermission` objects created with this constructor cannot be added to an `SubsystemPermission` permission collection.
      Parameters:
        `subsystem` - A subsystem.
        `actions` - `execute`, `lifecycle`, `metadata`, or `context`.

  - ### Method Detail

    - #### implies

          public boolean implies(java.security.Permission p)

      Determines if the specified permission is implied by this object. This method throws an exception if the specified permission was not constructed with a subsystem.

      This method returns `true` if the specified permission is a SubsystemPermission AND

      - this object's filter matches the specified permission's subsystem ID, subsystem symbolic name, and subsystem location OR
      - this object's filter is "*"
      AND this object's actions include all of the specified permission's actions.

      Special case: if the specified permission was constructed with "*" filter, then this method returns `true` if this object's filter is "*" and this object's actions include all of the specified permission's actions

      Overrides:
        `implies` in class `java.security.BasicPermission`
      Parameters:
        `p` - The requested permission.
      Returns:
        `true` if the specified permission is implied by this object; `false` otherwise.

    - #### getActions

          public java.lang.String getActions()

      Returns the canonical string representation of the `SubsystemPermission` actions.

      Always returns present `SubsystemPermission` actions in the following order: `execute`, `lifecycle`, `metadata`, `context`.

      Overrides:
        `getActions` in class `java.security.BasicPermission`
      Returns:
        Canonical string representation of the `SubsystemPermission` actions.

    - #### newPermissionCollection

          public java.security.PermissionCollection newPermissionCollection()

      Returns a new `PermissionCollection` object suitable for storing `SubsystemPermission`s.
      Overrides:
        `newPermissionCollection` in class `java.security.BasicPermission`
      Returns:
        A new `PermissionCollection` object.

    - #### equals

          public boolean equals(java.lang.Object obj)

      Determines the equality of two `SubsystemPermission` objects.
      Overrides:
        `equals` in class `java.security.BasicPermission`
      Parameters:
        `obj` - The object being compared for equality with this object.
      Returns:
        `true` if `obj` is equivalent to this `SubsystemPermission`; `false` otherwise.

    - #### hashCode

          public int hashCode()

      Returns the hash code value for this object.
      Overrides:
        `hashCode` in class `java.security.BasicPermission`
      Returns:
        Hash code value for this object.