CapabilityPermission
Date: 2016-06-24

org.osgi.framework

## Class CapabilityPermission

- java.lang.Object
- - java.security.Permission
  - - java.security.BasicPermission
    - - org.osgi.framework.CapabilityPermission

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

      public final class CapabilityPermission
      extends java.security.BasicPermission

  A bundle's authority to provide or require a capability.
  - The `provide` action allows a bundle to provide a capability matching the specified filter.
  - The `require` action allows a bundle to require a capability matching the specified filter.
  Since:
    1.6
  See Also:
    Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `PROVIDE` The action string `provide`.
    `static java.lang.String` | `REQUIRE` The action string `require`.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `CapabilityPermission(java.lang.String namespace, java.util.Map<java.lang.String,?> attributes, Bundle providingBundle, java.lang.String actions)` Creates a new requested `CapabilityPermission` object to be used by code that must perform `checkPermission` for the `require` action.
    `CapabilityPermission(java.lang.String name, java.lang.String actions)` Create a new CapabilityPermission.

  - ### Method Summary

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

    - ### 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

    - #### REQUIRE

          public static final java.lang.String REQUIRE

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

    - #### PROVIDE

          public static final java.lang.String PROVIDE

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

  - ### Constructor Detail

    - #### CapabilityPermission

          public CapabilityPermission(java.lang.String name,
                              java.lang.String actions)

      Create a new CapabilityPermission.

      The name is specified as a dot-separated string. Wildcards may be used.

           name ::= <namespace> | <namespace ending in ".*"> | *

      Examples:

           com.acme.capability.*
           org.foo.capability
           *

      For the `require` action, the name can also be a filter expression. The filter gives access to the capability attributes as well as the following attributes:
      - signer - A Distinguished Name chain used to sign the bundle providing the capability. Wildcards in a DN are not matched according to the filter string rules, but according to the rules defined for a DN chain.
      - location - The location of the bundle providing the capability.
      - id - The bundle ID of the bundle providing the capability.
      - name - The symbolic name of the bundle providing the capability.
      - capability.namespace - The namespace of the required capability.
      Since the above attribute names may conflict with attribute names of a capability, you can prefix an attribute name with '@' in the filter expression to match against the capability attributes and not one of the above attributes. Filter attribute names are processed in a case sensitive manner.

      There are two possible actions: `require` and `provide`. The `require` permission allows the owner of this permission to require a capability matching the attributes. The `provide` permission allows the bundle to provide a capability in the specified capability namespace.

      Parameters:
        `name` - The capability namespace or a filter over the attributes.
        `actions` - `require`,`provide` (canonical order)
      Throws:
        `java.lang.IllegalArgumentException` - If the specified name is a filter expression and either the specified action is not `require` or the filter has an invalid syntax.

    - #### CapabilityPermission

          public CapabilityPermission(java.lang.String namespace,
                              java.util.Map<java.lang.String,?> attributes,
                              Bundle providingBundle,
                              java.lang.String actions)

      Creates a new requested `CapabilityPermission` object to be used by code that must perform `checkPermission` for the `require` action. `CapabilityPermission` objects created with this constructor cannot be added to a `CapabilityPermission` permission collection.
      Parameters:
        `namespace` - The requested capability namespace.
        `attributes` - The requested capability attributes.
        `providingBundle` - The bundle providing the requested capability.
        `actions` - The action `require`.
      Throws:
        `java.lang.IllegalArgumentException` - If the specified action is not `require` or attributes or providingBundle are `null` .

  - ### Method Detail

    - #### implies

          public boolean implies(java.security.Permission p)

      Determines if a `CapabilityPermission` object "implies" the specified permission.
      Overrides:
        `implies` in class `java.security.BasicPermission`
      Parameters:
        `p` - The target permission to check.
      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 actions. Always returns present actions in the following order: `require`, `provide`.
      Overrides:
        `getActions` in class `java.security.BasicPermission`
      Returns:
        The canonical string representation of the actions.

    - #### newPermissionCollection

          public java.security.PermissionCollection newPermissionCollection()

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

    - #### equals

          public boolean equals(java.lang.Object obj)

      Determines the equality of two CapabilityPermission objects. Checks that specified object has the same name and action as this `CapabilityPermission`.
      Overrides:
        `equals` in class `java.security.BasicPermission`
      Parameters:
        `obj` - The object to test for equality.
      Returns:
        true if obj is a `CapabilityPermission`, and has the same name and actions as this `CapabilityPermission` object; `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.