DeploymentAdminPermission
Date: 2016-06-25

org.osgi.service.deploymentadmin

## Class DeploymentAdminPermission

- java.lang.Object
- - java.security.Permission
  - - org.osgi.service.deploymentadmin.DeploymentAdminPermission

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

      public final class DeploymentAdminPermission
      extends java.security.Permission

  DeploymentAdminPermission controls access to the Deployment Admin service.

  The permission uses a filter string formatted similarly to the `Filter`. The filter determines the target of the permission. The `DeploymentAdminPermission` uses the `name` and the `signer` filter attributes only. The value of the `signer` attribute is matched against the signer chain (represented with its semicolon separated Distinguished Name chain) of the Deployment Package, and the value of the `name` attribute is matched against the value of the "DeploymentPackage-Name" manifest header of the Deployment Package. Example:

  - (signer=cn = Bugs Bunny, o = ACME, c = US)
  - (name=org.osgi.ExampleApp)
  Wildcards also can be used:

       (signer=cn=*,o=ACME,c=*)

  "cn" and "c" may have an arbitrary value

       (signer=*, o=ACME, c=US)

  Only the value of "o" and "c" are significant

       (signer=* ; ou=S & V, o=Tweety Inc., c=US)

  The first element of the certificate chain is not important, only the second (the Distinguished Name of the root certificate)

       (signer=- ; *, o=Tweety Inc., c=US)

  The same as the previous but '-' represents zero or more certificates, whereas the asterisk only represents a single certificate

       (name=*)

  The name of the Deployment Package doesn't matter

       (name=org.osgi.*)

  The name has to begin with "org.osgi."

  The following actions are allowed:

  list

  A holder of this permission can access the inventory information of the deployment packages selected by the <filter> string. The filter selects the deployment packages on which the holder of the permission can acquire detailed inventory information. See `DeploymentAdmin.getDeploymentPackage(Bundle)`, `DeploymentAdmin.getDeploymentPackage(String)` and `DeploymentAdmin.listDeploymentPackages()`.

  install

  A holder of this permission can install/update deployment packages if the deployment package satisfies the <filter> string. See `DeploymentAdmin.installDeploymentPackage(java.io.InputStream)`.

  uninstall

  A holder of this permission can uninstall deployment packages if the deployment package satisfies the <filter> string. See `DeploymentPackage.uninstall()`.

  uninstall_forced

  A holder of this permission can forcefully uninstall deployment packages if the deployment package satisfies the <filter> string. See `DeploymentPackage.uninstallForced()`.

  cancel

  A holder of this permission can cancel an active deployment action. This action being canceled could correspond to the install, update or uninstall of a deployment package that satisfies the <filter> string. See `DeploymentAdmin.cancel()`

  metadata

  A holder of this permission is able to retrieve metadata information about a Deployment Package (e.g. is able to ask its manifest headers). See `DeploymentPackage.getBundle(String)`, `DeploymentPackage.getBundleInfos()`, `DeploymentPackage.getHeader(String)`, `DeploymentPackage.getResourceHeader(String, String)`, `DeploymentPackage.getResourceProcessor(String)`, `DeploymentPackage.getResources()`

  The actions string is converted to lower case before processing.

  See Also:
    Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `CANCEL` Constant String to the "cancel" action.
    `static java.lang.String` | `INSTALL` Constant String to the "install" action.
    `static java.lang.String` | `LIST` Constant String to the "list" action.
    `static java.lang.String` | `METADATA` Constant String to the "metadata" action.
    `static java.lang.String` | `UNINSTALL` Constant String to the "uninstall" action.
    `static java.lang.String` | `UNINSTALL_FORCED` Constant String to the "uninstall_forced" action.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `DeploymentAdminPermission(java.lang.String name, java.lang.String actions)` Creates a new `DeploymentAdminPermission` object for the given `name` and `action`.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `equals(java.lang.Object obj)` Checks two DeploymentAdminPermission objects for equality.
    `java.lang.String` | `getActions()` Returns the String representation of the action list.
    `int` | `hashCode()` Returns hash code for this permission object.
    `boolean` | `implies(java.security.Permission permission)` Checks if this DeploymentAdminPermission would imply the parameter permission.
    `java.security.PermissionCollection` | `newPermissionCollection()` Returns a new PermissionCollection object for storing DeploymentAdminPermission 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

    - #### INSTALL

          public static final java.lang.String INSTALL

      Constant String to the "install" action.

      See Also:
        `DeploymentAdmin.installDeploymentPackage(InputStream)`, Constant Field Values

    - #### LIST

          public static final java.lang.String LIST

      Constant String to the "list" action.

      See Also:
        `DeploymentAdmin.listDeploymentPackages()`, `DeploymentAdmin.getDeploymentPackage(String)`, `DeploymentAdmin.getDeploymentPackage(Bundle)`, Constant Field Values

    - #### UNINSTALL

          public static final java.lang.String UNINSTALL

      Constant String to the "uninstall" action.

      See Also:
        `DeploymentPackage.uninstall()`, Constant Field Values

    - #### UNINSTALL_FORCED

          public static final java.lang.String UNINSTALL_FORCED

      Constant String to the "uninstall_forced" action.

      See Also:
        `DeploymentPackage.uninstallForced()`, Constant Field Values

    - #### CANCEL

          public static final java.lang.String CANCEL

      Constant String to the "cancel" action.

      See Also:
        `DeploymentAdmin.cancel()`, Constant Field Values

    - #### METADATA

          public static final java.lang.String METADATA

      Constant String to the "metadata" action.

      See Also:
        `DeploymentPackage.getBundle(String)`, `DeploymentPackage.getBundleInfos()`, `DeploymentPackage.getHeader(String)`, `DeploymentPackage.getResourceHeader(String, String)`, `DeploymentPackage.getResourceProcessor(String)`, `DeploymentPackage.getResources()`, Constant Field Values

  - ### Constructor Detail

    - #### DeploymentAdminPermission

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

      Creates a new `DeploymentAdminPermission` object for the given `name` and `action`.

      The `name` parameter identifies the target deployment package the permission relates to. The `actions` parameter contains the comma separated list of allowed actions.

      Parameters:
        `name` - filter string, must not be null.
        `actions` - action string, must not be null. "*" means all the possible actions.
      Throws:
        `java.lang.IllegalArgumentException` - if the filter is invalid, the list of actions contains unknown operations or one of the parameters is null

  - ### Method Detail

    - #### equals

          public boolean equals(java.lang.Object obj)

      Checks two DeploymentAdminPermission objects for equality. Two permission objects are equal if:

      - their target filters are semantically equal and
      - their actions are the same
      Specified by:
        `equals` in class `java.security.Permission`
      Parameters:
        `obj` - The reference object with which to compare.
      Returns:
        true if the two objects are equal.
      See Also:
        `Object.equals(java.lang.Object)`

    - #### hashCode

          public int hashCode()

      Returns hash code for this permission object.
      Specified by:
        `hashCode` in class `java.security.Permission`
      Returns:
        Hash code for this permission object.
      See Also:
        `Object.hashCode()`

    - #### getActions

          public java.lang.String getActions()

      Returns the String representation of the action list.

      The method always gives back the actions in the following (alphabetical) order: `cancel, install, list, metadata, uninstall, uninstall_forced`

      Specified by:
        `getActions` in class `java.security.Permission`
      Returns:
        Action list of this permission instance. This is a comma-separated list that reflects the action parameter of the constructor.
      See Also:
        `Permission.getActions()`

    - #### implies

          public boolean implies(java.security.Permission permission)

      Checks if this DeploymentAdminPermission would imply the parameter permission.

      Precondition of the implication is that the action set of this permission is the superset of the action set of the other permission. Further rules of implication are determined by the `Filter` rules and the "OSGi Service Platform, Core Specification Release 4, Chapter Certificate Matching".

      The allowed attributes are: `name` (the symbolic name of the deployment package) and `signer` (the signer of the deployment package). In both cases wildcards can be used.

      Examples:

            1. DeploymentAdminPermission("(name=org.osgi.ExampleApp)", "list")
            2. DeploymentAdminPermission("(name=org.osgi.ExampleApp)", "list, install")
            3. DeploymentAdminPermission("(name=org.osgi.*)", "list")
            4. DeploymentAdminPermission("(signer=*, o=ACME, c=US)", "list")
            5. DeploymentAdminPermission("(signer=cn=Bugs Bunny, o=ACME, c=US)", "list")

            1. implies 1.
            2. implies 1.
            1. doesn't implies 2.
            3. implies 1.
            4. implies 5.

      Specified by:
        `implies` in class `java.security.Permission`
      Parameters:
        `permission` - Permission to check.
      Returns:
        true if this DeploymentAdminPermission object implies the specified permission.
      See Also:
        `Permission.implies(java.security.Permission)`, `Filter`

    - #### newPermissionCollection

          public java.security.PermissionCollection newPermissionCollection()

      Returns a new PermissionCollection object for storing DeploymentAdminPermission objects.
      Overrides:
        `newPermissionCollection` in class `java.security.Permission`
      Returns:
        The new PermissionCollection.
      See Also:
        `Permission.newPermissionCollection()`