PermissionAdmin
Date: 2016-06-24

org.osgi.service.permissionadmin

## Interface PermissionAdmin

-     @ProviderType
      public interface PermissionAdmin

  The Permission Admin service allows management agents to manage the permissions of bundles. There is at most one Permission Admin service present in the OSGi environment.

  Access to the Permission Admin service is protected by corresponding `ServicePermission`. In addition `AdminPermission` is required to actually set permissions.

  Bundle permissions are managed using a permission table. A bundle's location serves as the key into this permission table. The value of a table entry is the set of permissions (of type `PermissionInfo`) granted to the bundle named by the given location. A bundle may have an entry in the permission table prior to being installed in the Framework.

  The permissions specified in `setDefaultPermissions` are used as the default permissions which are granted to all bundles that do not have an entry in the permission table.

  Any changes to a bundle's permissions in the permission table will take effect no later than when bundle's `java.security.ProtectionDomain` is next involved in a permission check, and will be made persistent.

  Only permission classes on the system classpath or from an exported package are considered during a permission check. Additionally, only permission classes that are subclasses of `java.security.Permission` and define a 2-argument constructor that takes a name string and an actions string can be used.

  Permissions implicitly granted by the Framework (for example, a bundle's permission to access its persistent storage area) cannot be changed, and are not reflected in the permissions returned by `getPermissions` and `getDefaultPermissions`.

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `PermissionInfo[]` | `getDefaultPermissions()` Gets the default permissions.
    `java.lang.String[]` | `getLocations()` Returns the bundle locations that have permissions assigned to them, that is, bundle locations for which an entry exists in the permission table.
    `PermissionInfo[]` | `getPermissions(java.lang.String location)` Gets the permissions assigned to the bundle with the specified location.
    `void` | `setDefaultPermissions(PermissionInfo[] permissions)` Sets the default permissions.
    `void` | `setPermissions(java.lang.String location, PermissionInfo[] permissions)` Assigns the specified permissions to the bundle with the specified location.

- - ### Method Detail

    - #### getPermissions

          PermissionInfo[] getPermissions(java.lang.String location)

      Gets the permissions assigned to the bundle with the specified location.
      Parameters:
        `location` - The location of the bundle whose permissions are to be returned.
      Returns:
        The permissions assigned to the bundle with the specified location, or `null` if that bundle has not been assigned any permissions.

    - #### setPermissions

          void setPermissions(java.lang.String location,
                            PermissionInfo[] permissions)

      Assigns the specified permissions to the bundle with the specified location.
      Parameters:
        `location` - The location of the bundle that will be assigned the permissions.
        `permissions` - The permissions to be assigned, or `null` if the specified location is to be removed from the permission table.
      Throws:
        `java.lang.SecurityException` - If the caller does not have `AllPermission`.

    - #### getLocations

          java.lang.String[] getLocations()

      Returns the bundle locations that have permissions assigned to them, that is, bundle locations for which an entry exists in the permission table.
      Returns:
        The locations of bundles that have been assigned any permissions, or `null` if the permission table is empty.

    - #### getDefaultPermissions

          PermissionInfo[] getDefaultPermissions()

      Gets the default permissions.

      These are the permissions granted to any bundle that does not have permissions assigned to its location.

      Returns:
        The default permissions, or `null` if no default permissions are set.

    - #### setDefaultPermissions

          void setDefaultPermissions(PermissionInfo[] permissions)

      Sets the default permissions.

      These are the permissions granted to any bundle that does not have permissions assigned to its location.

      Parameters:
        `permissions` - The default permissions, or `null` if the default permissions are to be removed from the permission table.
      Throws:
        `java.lang.SecurityException` - If the caller does not have `AllPermission`.