ApplicationAdminPermission
Date: 2016-06-25

org.osgi.service.application

## Class ApplicationAdminPermission

- java.lang.Object
- - java.security.Permission
  - - org.osgi.service.application.ApplicationAdminPermission

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

      public class ApplicationAdminPermission
      extends java.security.Permission

  This class implements permissions for manipulating applications and their instances.

  ApplicationAdminPermission can be targeted to applications that matches the specified filter.

  ApplicationAdminPermission may be granted for different actions: `lifecycle`, `schedule` and `lock`. The permission `schedule` implies the permission `lifecycle`.

  See Also:
    Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `LIFECYCLE_ACTION` Allows the lifecycle management of the target applications.
    `static java.lang.String` | `LOCK_ACTION` Allows setting/unsetting the locking state of the target applications.
    `static java.lang.String` | `SCHEDULE_ACTION` Allows scheduling of the target applications.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ApplicationAdminPermission(ApplicationDescriptor application, java.lang.String actions)` This constructor should be used when creating `ApplicationAdminPermission` instance for `checkPermission` call.
    `ApplicationAdminPermission(java.lang.String filter, java.lang.String actions)` Constructs an ApplicationAdminPermission.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `equals(java.lang.Object with)`
    `java.lang.String` | `getActions()` Returns the actions of this permission.
    `int` | `hashCode()`
    `boolean` | `implies(java.security.Permission otherPermission)` Checks if the specified `permission` is implied by this permission.
    `ApplicationAdminPermission` | `setCurrentApplicationId(java.lang.String applicationId)` This method can be used in the `ProtectionDomain` implementation in the `implies` method to insert the application ID of the current application into the permission being checked.

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

    - #### LIFECYCLE_ACTION

          public static final java.lang.String LIFECYCLE_ACTION

      Allows the lifecycle management of the target applications.
      See Also:
        Constant Field Values

    - #### SCHEDULE_ACTION

          public static final java.lang.String SCHEDULE_ACTION

      Allows scheduling of the target applications. The permission to schedule an application implies that the scheduler can also manage the lifecycle of that application i.e. `schedule` implies `lifecycle`
      See Also:
        Constant Field Values

    - #### LOCK_ACTION

          public static final java.lang.String LOCK_ACTION

      Allows setting/unsetting the locking state of the target applications.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### ApplicationAdminPermission

          public ApplicationAdminPermission(java.lang.String filter,
                                    java.lang.String actions)
                                     throws org.osgi.framework.InvalidSyntaxException

      Constructs an ApplicationAdminPermission. The `filter` specifies the target application. The `filter` is an LDAP-style filter, the recognized properties are `signer` and `pid`. The pattern specified in the `signer` is matched with the Distinguished Name chain used to sign the application. Wildcards in a DN are not matched according to the filter string rules, but according to the rules defined for a DN chain. The attribute `pid` is matched with the PID of the application according to the filter string rules.

      If the `filter` is `null` then it matches `"*"`. If `actions` is `"*"` then it identifies all the possible actions.

      Parameters:
        `filter` - filter to identify application. The value `null` is equivalent to `"*"` and it indicates "all application".
        `actions` - comma-separated list of the desired actions granted on the applications or "*" means all the actions. It must not be `null`. The order of the actions in the list is not significant.
      Throws:
        `org.osgi.framework.InvalidSyntaxException` - is thrown if the specified `filter` is not syntactically correct.
        `java.lang.NullPointerException` - is thrown if the actions parameter is `null`
      See Also:
        `ApplicationDescriptor`, `AdminPermission`

    - #### ApplicationAdminPermission

          public ApplicationAdminPermission(ApplicationDescriptor application,
                                    java.lang.String actions)

      This constructor should be used when creating `ApplicationAdminPermission` instance for `checkPermission` call.
      Parameters:
        `application` - The target of the operation, it must not be `null`.
        `actions` - The required operation, it must not be `null`.
      Throws:
        `java.lang.NullPointerException` - If any of the arguments is null.

  - ### Method Detail

    - #### setCurrentApplicationId

          public ApplicationAdminPermission setCurrentApplicationId(java.lang.String applicationId)

      This method can be used in the `ProtectionDomain` implementation in the `implies` method to insert the application ID of the current application into the permission being checked. This enables the evaluation of the `<<SELF>>` pseudo targets.
      Parameters:
        `applicationId` - the ID of the current application.
      Returns:
        the permission updated with the ID of the current application

    - #### implies

          public boolean implies(java.security.Permission otherPermission)

      Checks if the specified `permission` is implied by this permission. The method returns true under the following conditions:
      - This permission was created by specifying a filter (see `ApplicationAdminPermission(String, String)`)
      - The implied `otherPermission` was created for a particular `ApplicationDescriptor` (see `ApplicationAdminPermission(ApplicationDescriptor, String)`)
      - The `filter` of this permission matches the `ApplicationDescriptor` specified in the `otherPermission`. If the filter in this permission is the `<<SELF>>` pseudo target, then the currentApplicationId set in the `otherPermission` is compared to the application Id of the target `ApplicationDescriptor`.
      - The list of permitted actions in this permission contains all actions required in the `otherPermission`
      Otherwise the method returns false.
      Specified by:
        `implies` in class `java.security.Permission`
      Parameters:
        `otherPermission` - the implied permission
      Returns:
        true if this permission implies the `otherPermission`, false otherwise.

    - #### equals

          public boolean equals(java.lang.Object with)

      Specified by:
        `equals` in class `java.security.Permission`

    - #### hashCode

          public int hashCode()

      Specified by:
        `hashCode` in class `java.security.Permission`

    - #### getActions

          public java.lang.String getActions()

      Returns the actions of this permission.
      Specified by:
        `getActions` in class `java.security.Permission`
      Returns:
        the actions specified when this permission was created