Acl
Date: 2016-06-25

org.osgi.service.dmt

## Class Acl

- java.lang.Object
- - org.osgi.service.dmt.Acl

-     public final class Acl
      extends java.lang.Object

  `Acl` is an immutable class representing structured access to DMT ACLs. Under OMA DM the ACLs are defined as strings with an internal syntax.

  The methods of this class taking a principal as parameter accept remote server IDs (as passed to `DmtAdmin.getSession`), as well as " `*` " indicating any principal.

  The syntax for valid remote server IDs:

  <server-identifier> ::= All printable characters except `'='`, `'&'`, `'*'`, `'+'` or white-space characters.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `ADD` Principals holding this permission can issue ADD commands on the node having this ACL.
    `static int` | `ALL_PERMISSION` Principals holding this permission can issue any command on the node having this ACL.
    `static int` | `DELETE` Principals holding this permission can issue DELETE commands on the node having this ACL.
    `static int` | `EXEC` Principals holding this permission can issue EXEC commands on the node having this ACL.
    `static int` | `GET` Principals holding this permission can issue GET command on the node having this ACL.
    `static int` | `REPLACE` Principals holding this permission can issue REPLACE commands on the node having this ACL.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Acl(java.lang.String acl)` Create an instance of the ACL from its canonical string representation.
    `Acl(java.lang.String[] principals, int[] permissions)` Creates an instance with a specified list of principals and the permissions they hold.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `Acl` | `addPermission(java.lang.String principal, int permissions)` Create a new `Acl` instance from this `Acl` with the given permission added for the given principal.
    `Acl` | `deletePermission(java.lang.String principal, int permissions)` Create a new `Acl` instance from this `Acl` with the given permission revoked from the given principal.
    `boolean` | `equals(java.lang.Object obj)` Checks whether the given object is equal to this `Acl` instance.
    `int` | `getPermissions(java.lang.String principal)` Get the permissions associated to a given principal.
    `java.lang.String[]` | `getPrincipals()` Get the list of principals who have any kind of permissions on this node.
    `int` | `hashCode()` Returns the hash code for this ACL instance.
    `boolean` | `isPermitted(java.lang.String principal, int permissions)` Check whether the given permissions are granted to a certain principal.
    `Acl` | `setPermission(java.lang.String principal, int permissions)` Create a new `Acl` instance from this `Acl` where all permissions for the given principal are overwritten with the given permissions.
    `java.lang.String` | `toString()` Give the canonical string representation of this ACL.

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

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

- - ### Field Detail

    - #### GET

          public static final int GET

      Principals holding this permission can issue GET command on the node having this ACL.
      See Also:
        Constant Field Values

    - #### ADD

          public static final int ADD

      Principals holding this permission can issue ADD commands on the node having this ACL.
      See Also:
        Constant Field Values

    - #### REPLACE

          public static final int REPLACE

      Principals holding this permission can issue REPLACE commands on the node having this ACL.
      See Also:
        Constant Field Values

    - #### DELETE

          public static final int DELETE

      Principals holding this permission can issue DELETE commands on the node having this ACL.
      See Also:
        Constant Field Values

    - #### EXEC

          public static final int EXEC

      Principals holding this permission can issue EXEC commands on the node having this ACL.
      See Also:
        Constant Field Values

    - #### ALL_PERMISSION

          public static final int ALL_PERMISSION

      Principals holding this permission can issue any command on the node having this ACL. This permission is the logical OR of `ADD`, `DELETE`, `EXEC`, `GET` and `REPLACE` permissions.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### Acl

          public Acl(java.lang.String acl)

      Create an instance of the ACL from its canonical string representation.
      Parameters:
        `acl` - The string representation of the ACL as defined in OMA DM. If `null` or empty then it represents an empty list of principals with no permissions.
      Throws:
        `java.lang.IllegalArgumentException` - if acl is not a valid OMA DM ACL string

    - #### Acl

          public Acl(java.lang.String[] principals,
             int[] permissions)

      Creates an instance with a specified list of principals and the permissions they hold. The two arrays run in parallel, that is `principals[i]` will hold `permissions[i]` in the ACL.

      A principal name may not appear multiple times in the 'principals' argument. If the "*" principal appears in the array, the corresponding permissions will be granted to all principals (regardless of whether they appear in the array or not).

      Parameters:
        `principals` - The array of principals
        `permissions` - The array of permissions
      Throws:
        `java.lang.IllegalArgumentException` - if the length of the two arrays are not the same, if any array element is invalid, or if a principal appears multiple times in the `principals` array

  - ### Method Detail

    - #### equals

          public boolean equals(java.lang.Object obj)

      Checks whether the given object is equal to this `Acl` instance. Two `Acl` instances are equal if they allow the same set of permissions for the same set of principals.
      Overrides:
        `equals` in class `java.lang.Object`
      Parameters:
        `obj` - the object to compare with this `Acl` instance
      Returns:
        `true` if the parameter represents the same ACL as this instance

    - #### hashCode

          public int hashCode()

      Returns the hash code for this ACL instance. If two `Acl` instances are equal according to the `equals(Object)` method, then calling this method on each of them must produce the same integer result.
      Overrides:
        `hashCode` in class `java.lang.Object`
      Returns:
        hash code for this ACL

    - #### addPermission

          public Acl addPermission(java.lang.String principal,
                          int permissions)

      Create a new `Acl` instance from this `Acl` with the given permission added for the given principal. The already existing permissions of the principal are not affected.
      Parameters:
        `principal` - The entity to which permissions should be granted, or "*" to grant permissions to all principals.
        `permissions` - The permissions to be given. The parameter can be a logical `or` of more permission constants defined in this class.
      Returns:
        a new `Acl` instance
      Throws:
        `java.lang.IllegalArgumentException` - if `principal` is not a valid principal name or if `permissions` is not a valid combination of the permission constants defined in this class

    - #### deletePermission

          public Acl deletePermission(java.lang.String principal,
                             int permissions)

      Create a new `Acl` instance from this `Acl` with the given permission revoked from the given principal. Other permissions of the principal are not affected.

      Note, that it is not valid to revoke a permission from a specific principal if that permission is granted globally to all principals.

      Parameters:
        `principal` - The entity from which permissions should be revoked, or "*" to revoke permissions from all principals.
        `permissions` - The permissions to be revoked. The parameter can be a logical `or` of more permission constants defined in this class.
      Returns:
        a new `Acl` instance
      Throws:
        `java.lang.IllegalArgumentException` - if `principal` is not a valid principal name, if `permissions` is not a valid combination of the permission constants defined in this class, or if a globally granted permission would have been revoked from a specific principal

    - #### getPermissions

          public int getPermissions(java.lang.String principal)

      Get the permissions associated to a given principal.
      Parameters:
        `principal` - The entity whose permissions to query, or "*" to query the permissions that are granted globally, to all principals
      Returns:
        The permissions of the given principal. The returned `int` is a bitmask of the permission constants defined in this class
      Throws:
        `java.lang.IllegalArgumentException` - if `principal` is not a valid principal name

    - #### isPermitted

          public boolean isPermitted(java.lang.String principal,
                            int permissions)

      Check whether the given permissions are granted to a certain principal. The requested permissions are specified as a bitfield, for example `(Acl.ADD | Acl.DELETE | Acl.GET)`.
      Parameters:
        `principal` - The entity to check, or "*" to check whether the given permissions are granted to all principals globally
        `permissions` - The permissions to check
      Returns:
        `true` if the principal holds all the given permissions
      Throws:
        `java.lang.IllegalArgumentException` - if `principal` is not a valid principal name or if `permissions` is not a valid combination of the permission constants defined in this class

    - #### setPermission

          public Acl setPermission(java.lang.String principal,
                          int permissions)

      Create a new `Acl` instance from this `Acl` where all permissions for the given principal are overwritten with the given permissions.

      Note, that when changing the permissions of a specific principal, it is not allowed to specify a set of permissions stricter than the global set of permissions (that apply to all principals).

      Parameters:
        `principal` - The entity to which permissions should be granted, or "*" to globally grant permissions to all principals.
        `permissions` - The set of permissions to be given. The parameter is a bitmask of the permission constants defined in this class.
      Returns:
        a new `Acl` instance
      Throws:
        `java.lang.IllegalArgumentException` - if `principal` is not a valid principal name, if `permissions` is not a valid combination of the permission constants defined in this class, or if a globally granted permission would have been revoked from a specific principal

    - #### getPrincipals

          public java.lang.String[] getPrincipals()

      Get the list of principals who have any kind of permissions on this node. The list only includes those principals that have been explicitly assigned permissions (so "*" is never returned), globally set permissions naturally apply to all other principals as well.
      Returns:
        The array of principals having permissions on this node.

    - #### toString

          public java.lang.String toString()

      Give the canonical string representation of this ACL. The operations are in the following order: {Add, Delete, Exec, Get, Replace}, principal names are sorted alphabetically.
      Overrides:
        `toString` in class `java.lang.Object`
      Returns:
        The string representation as defined in OMA DM.