DmtPermission
Date: 2016-06-25

org.osgi.service.dmt.security

## Class DmtPermission

- java.lang.Object
- - java.security.Permission
  - - org.osgi.service.dmt.security.DmtPermission

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

      public class DmtPermission
      extends java.security.Permission

  Controls access to management objects in the Device Management Tree (DMT). It is intended to control local access to the DMT. DmtPermission target string identifies the management object URI and the action field lists the OMA DM commands that are permitted on the management object. Example:

       DmtPermission("./OSGi/bundles", "Add,Replace,Get");

  This means that owner of this permission can execute Add, Replace and Get commands on the ./OSGi/bundles management object. It is possible to use wildcards in both the target and the actions field. Wildcard in the target field means that the owner of the permission can access children nodes of the target node. Example:

       DmtPermission("./OSGi/bundles/*", "Get");

  This means that owner of this permission has Get access on every child node of ./OSGi/bundles. The asterisk does not necessarily have to follow a '/' character. For example the `"./OSGi/a*"` target matches the `./OSGi/applications` subtree.

  If wildcard is present in the actions field, all legal OMA DM commands are allowed on the designated nodes(s) by the owner of the permission. Action names are interpreted case-insensitively, but the canonical action string returned by `getActions()` uses the forms defined by the action constants.

  See Also:
    Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `ADD` Holders of DmtPermission with the Add action present can create new nodes in the DMT, that is they are authorized to execute the createInteriorNode() and createLeafNode() methods of the DmtSession.
    `static java.lang.String` | `DELETE` Holders of DmtPermission with the Delete action present can delete nodes from the DMT, that is they are authorized to execute the deleteNode() method of the DmtSession.
    `static java.lang.String` | `EXEC` Holders of DmtPermission with the Exec action present can execute nodes in the DMT, that is they are authorized to call the execute() method of the DmtSession.
    `static java.lang.String` | `GET` Holders of DmtPermission with the Get action present can query DMT node value or properties, that is they are authorized to execute the isLeafNode(), getNodeAcl(), getEffectiveNodeAcl(), getMetaNode(), getNodeValue(), getChildNodeNames(), getNodeTitle(), getNodeVersion(), getNodeTimeStamp(), getNodeSize() and getNodeType() methods of the DmtSession.
    `static java.lang.String` | `REPLACE` Holders of DmtPermission with the Replace action present can update DMT node value or properties, that is they are authorized to execute the setNodeAcl(), setNodeTitle(), setNodeValue(), setNodeType() and renameNode() methods of the DmtSession.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `DmtPermission(java.lang.String dmtUri, java.lang.String actions)` Creates a new DmtPermission object for the specified DMT URI with the specified actions.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `equals(java.lang.Object obj)` Checks whether the given object is equal to this DmtPermission instance.
    `java.lang.String` | `getActions()` Returns the String representation of the action list.
    `int` | `hashCode()` Returns the hash code for this permission object.
    `boolean` | `implies(java.security.Permission p)` Checks if this DmtPermission object "implies" the specified permission.
    `java.security.PermissionCollection` | `newPermissionCollection()` Returns a new PermissionCollection object for storing DmtPermission 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

    - #### ADD

          public static final java.lang.String ADD

      Holders of DmtPermission with the Add action present can create new nodes in the DMT, that is they are authorized to execute the createInteriorNode() and createLeafNode() methods of the DmtSession. This action is also required for the copy() command, which needs to perform node creation operations (among others).
      See Also:
        Constant Field Values

    - #### DELETE

          public static final java.lang.String DELETE

      Holders of DmtPermission with the Delete action present can delete nodes from the DMT, that is they are authorized to execute the deleteNode() method of the DmtSession.
      See Also:
        Constant Field Values

    - #### EXEC

          public static final java.lang.String EXEC

      Holders of DmtPermission with the Exec action present can execute nodes in the DMT, that is they are authorized to call the execute() method of the DmtSession.
      See Also:
        Constant Field Values

    - #### GET

          public static final java.lang.String GET

      Holders of DmtPermission with the Get action present can query DMT node value or properties, that is they are authorized to execute the isLeafNode(), getNodeAcl(), getEffectiveNodeAcl(), getMetaNode(), getNodeValue(), getChildNodeNames(), getNodeTitle(), getNodeVersion(), getNodeTimeStamp(), getNodeSize() and getNodeType() methods of the DmtSession. This action is also required for the copy() command, which needs to perform node query operations (among others).
      See Also:
        Constant Field Values

    - #### REPLACE

          public static final java.lang.String REPLACE

      Holders of DmtPermission with the Replace action present can update DMT node value or properties, that is they are authorized to execute the setNodeAcl(), setNodeTitle(), setNodeValue(), setNodeType() and renameNode() methods of the DmtSession. This action is also be required for the copy() command if the original node had a title property (which must be set in the new node).
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### DmtPermission

          public DmtPermission(java.lang.String dmtUri,
                       java.lang.String actions)

      Creates a new DmtPermission object for the specified DMT URI with the specified actions. The given URI can be:
      - `"*"`, which matches all valid (see `Uri.isValidUri(String)`) absolute URIs;
      - the prefix of an absolute URI followed by the `*` character (for example `"./OSGi/L*"`), which matches all valid absolute URIs beginning with the given prefix;
      - a valid absolute URI, which matches itself.

      Since the `*` character is itself a valid URI character, it can appear as the last character of a valid absolute URI. To distinguish this case from using `*` as a wildcard, the `*` character at the end of the URI must be escaped with the `\` character. For example the URI `"./a*"` matches `"./a"`, `"./aa"`, `"./a/b"` etc. while `"./a\*"` matches `"./a*"` only.

      The actions string must either be "*" to allow all actions, or it must contain a non-empty subset of the valid actions, defined as constants in this class.

      Parameters:
        `dmtUri` - URI of the management object (or subtree)
        `actions` - OMA DM actions allowed
      Throws:
        `java.lang.NullPointerException` - if any of the parameters are `null`
        `java.lang.IllegalArgumentException` - if any of the parameters are invalid

  - ### Method Detail

    - #### equals

          public boolean equals(java.lang.Object obj)

      Checks whether the given object is equal to this DmtPermission instance. Two DmtPermission instances are equal if they have the same target string and the same action mask. The "*" action mask is considered equal to a mask containing all actions.
      Specified by:
        `equals` in class `java.security.Permission`
      Parameters:
        `obj` - the object to compare to this DmtPermission instance
      Returns:
        `true` if the parameter represents the same permissions as this instance

    - #### getActions

          public java.lang.String getActions()

      Returns the String representation of the action list. The allowed actions are listed in the following order: Add, Delete, Exec, Get, Replace. The wildcard character is not used in the returned string, even if the class was created using the "*" wildcard.
      Specified by:
        `getActions` in class `java.security.Permission`
      Returns:
        canonical action list for this permission object

    - #### hashCode

          public int hashCode()

      Returns the hash code for this permission object. If two DmtPermission objects are equal according to the `equals(Object)` method, then calling this method on each of the two DmtPermission objects must produce the same integer result.
      Specified by:
        `hashCode` in class `java.security.Permission`
      Returns:
        hash code for this permission object

    - #### implies

          public boolean implies(java.security.Permission p)

      Checks if this DmtPermission object "implies" the specified permission. This method returns `false` if and only if at least one of the following conditions are fulfilled for the specified permission:
      - it is not a DmtPermission
      - its set of actions contains an action not allowed by this permission
      - the set of nodes defined by its path contains a node not defined by the path of this permission
      Specified by:
        `implies` in class `java.security.Permission`
      Parameters:
        `p` - the permission to check for implication
      Returns:
        true if this DmtPermission instance implies the specified permission

    - #### newPermissionCollection

          public java.security.PermissionCollection newPermissionCollection()

      Returns a new PermissionCollection object for storing DmtPermission objects.
      Overrides:
        `newPermissionCollection` in class `java.security.Permission`
      Returns:
        the new PermissionCollection