Package org.osgi.service.dmt

Class Acl

java.lang.Object
org.osgi.service.dmt.Acl
public final class Acl extends 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
    Description
    static final int
    ADD
    Principals holding this permission can issue ADD commands on the node having this ACL.
    static final int
    ALL_PERMISSION
    Principals holding this permission can issue any command on the node having this ACL.
    private static final String
    ALL_PRINCIPALS
     
    static final int
    DELETE
    Principals holding this permission can issue DELETE commands on the node having this ACL.
    static final int
    EXEC
    Principals holding this permission can issue EXEC commands on the node having this ACL.
    static final int
    GET
    Principals holding this permission can issue GET command on the node having this ACL.
    private final int
    globalPermissions
     
    private static final int[]
    PERMISSION_CODES
     
    private static final String[]
    PERMISSION_NAMES
     
    private final TreeMap<String,Integer>
    principalPermissions
     
    static final int
    REPLACE
    Principals holding this permission can issue REPLACE commands on the node having this ACL.

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
     
    Acl(String acl)
    Create an instance of the ACL from its canonical string representation.
     
    Acl(String[] principals, int[] permissions)
    Creates an instance with a specified list of principals and the permissions they hold.
    private
    Acl(Acl base, String principal, int permissions)
    Creates an instance identical to the base ACL except for the permissions of the given principal, which are overwritten with the given permissions.

  • Method Summary

    Modifier and Type
    Method
    Description
    Acl
    addPermission(String principal, int permissions)
    Create a new Acl instance from this Acl with the given permission added for the given principal.
    private static String
    appendEntry(String base, char separator, String entry)
     
    private static void
    checkPermissions(int perm)
     
    private static void
    checkPrincipal(String principal)
     
    private static void
    checkServerId(String serverId, String errorText)
     
    private static void
    deleteFromAll(TreeMap<String,Integer> principalPermissions, int perm)
     
    Acl
    deletePermission(String principal, int permissions)
    Create a new Acl instance from this Acl with the given permission revoked from the given principal.
    boolean
    equals(Object obj)
    Checks whether the given object is equal to this Acl instance.
    int
    getPermissions(String principal)
    Get the permissions associated to a given principal.
    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(String principal, int permissions)
    Check whether the given permissions are granted to a certain principal.
    private static int
    parseCommand(String command)
     
    Acl
    setPermission(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.
    private static void
    setPrincipalPermission(TreeMap<String,Integer> principalPermissions, String principal, int perm)
     
    private static String[]
    split(String input, char sep, int limit)
     
    String
    toString()
    Give the canonical string representation of this ACL.
    private static String
    writeCommands(int command)
     
    private String
    writeEntry(int command, String acl)
     

    Methods inherited from class java.lang.Object

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

  • Field Details

    • GET

      public static final int GET
      Principals holding this permission can issue GET command on the node having this ACL.
      See Also:

    • ADD

      public static final int ADD
      Principals holding this permission can issue ADD commands on the node having this ACL.
      See Also:

    • REPLACE

      public static final int REPLACE
      Principals holding this permission can issue REPLACE commands on the node having this ACL.
      See Also:

    • DELETE

      public static final int DELETE
      Principals holding this permission can issue DELETE commands on the node having this ACL.
      See Also:

    • EXEC

      public static final int EXEC
      Principals holding this permission can issue EXEC commands on the node having this ACL.
      See Also:

    • 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:

    • PERMISSION_CODES

      private static final int[] PERMISSION_CODES

    • PERMISSION_NAMES

      private static final String[] PERMISSION_NAMES

    • ALL_PRINCIPALS

      private static final String ALL_PRINCIPALS
      See Also:

    • principalPermissions

      private final TreeMap<String,Integer> principalPermissions

    • globalPermissions

      private final int globalPermissions

  • Constructor Details

    • Acl

      public Acl(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:
      IllegalArgumentException - if acl is not a valid OMA DM ACL string

    • Acl

      public Acl(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:
      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

    • Acl

      private Acl(Acl base, String principal, int permissions)
      Creates an instance identical to the base ACL except for the permissions of the given principal, which are overwritten with the given permissions.

      Assumes that the permissions parameter has been checked. All modifications of an Acl (add, delete, set) are done through this method.

      Parameters:
      base - The ACL that provides all permissions except for permissions of the given principal.
      principal - The entity to which permission should be granted.
      permissions - The set of permissions to be given. The parameter can be a logical or of the permission constants defined in this class.

  • Method Details

    • equals

      public boolean equals(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 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 Object
      Returns:
      hash code for this ACL

    • addPermission

      public Acl addPermission(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:
      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(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:
      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(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:
      IllegalArgumentException - if principal is not a valid principal name

    • isPermitted

      public boolean isPermitted(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:
      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(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:
      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 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 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 Object
      Returns:
      The string representation as defined in OMA DM.

    • writeEntry

      private String writeEntry(int command, String acl)

    • deleteFromAll

      private static void deleteFromAll(TreeMap<String,Integer> principalPermissions, int perm)

    • setPrincipalPermission

      private static void setPrincipalPermission(TreeMap<String,Integer> principalPermissions, String principal, int perm)

    • writeCommands

      private static String writeCommands(int command)

    • appendEntry

      private static String appendEntry(String base, char separator, String entry)

    • parseCommand

      private static int parseCommand(String command)

    • checkPermissions

      private static void checkPermissions(int perm)

    • checkPrincipal

      private static void checkPrincipal(String principal)

    • checkServerId

      private static void checkServerId(String serverId, String errorText)

    • split

      private static String[] split(String input, char sep, int limit)