DmtPrincipalPermission
Date: 2016-06-25

org.osgi.service.dmt.security

## Class DmtPrincipalPermission

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

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

      public class DmtPrincipalPermission
      extends java.security.Permission

  Indicates the callers authority to create DMT sessions on behalf of a remote management server. Only protocol adapters communicating with management servers should be granted this permission.

  `DmtPrincipalPermission` has a target string which controls the name of the principal on whose behalf the protocol adapter can act. A wildcard is allowed at the end of the target string, to allow using any principal name with the given prefix. The "*" target means the adapter can create a session in the name of any principal.

  See Also:
    Serialized Form

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `DmtPrincipalPermission(java.lang.String target)` Creates a new `DmtPrincipalPermission` object with its name set to the target string.
    `DmtPrincipalPermission(java.lang.String target, java.lang.String actions)` Creates a new `DmtPrincipalPermission` object using the 'canonical' two argument constructor.

  - ### Method Summary

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

- - ### Constructor Detail

    - #### DmtPrincipalPermission

          public DmtPrincipalPermission(java.lang.String target)

      Creates a new `DmtPrincipalPermission` object with its name set to the target string. Name must be non-null and non-empty.
      Parameters:
        `target` - the name of the principal, can end with `*` to match any principal with the given prefix
      Throws:
        `java.lang.NullPointerException` - if `name` is `null`
        `java.lang.IllegalArgumentException` - if `name` is empty

    - #### DmtPrincipalPermission

          public DmtPrincipalPermission(java.lang.String target,
                                java.lang.String actions)

      Creates a new `DmtPrincipalPermission` object using the 'canonical' two argument constructor. In this version this class does not define any actions, the second argument of this constructor must be "*" so that this class can later be extended in a backward compatible way.
      Parameters:
        `target` - the name of the principal, can end with `*` to match any principal with the given prefix
        `actions` - no actions defined, must be "*" for forward compatibility
      Throws:
        `java.lang.NullPointerException` - if `name` or `actions` is `null`
        `java.lang.IllegalArgumentException` - if `name` is empty or `actions` is not "*"

  - ### Method Detail

    - #### equals

          public boolean equals(java.lang.Object obj)

      Checks whether the given object is equal to this DmtPrincipalPermission instance. Two DmtPrincipalPermission instances are equal if they have the same target string.
      Specified by:
        `equals` in class `java.security.Permission`
      Parameters:
        `obj` - the object to compare to this DmtPrincipalPermission instance
      Returns:
        `true` if the parameter represents the same permissions as this instance

    - #### getActions

          public java.lang.String getActions()

      Returns the action list (always `*` in the current version).
      Specified by:
        `getActions` in class `java.security.Permission`
      Returns:
        the action string "*"

    - #### hashCode

          public int hashCode()

      Returns the hash code for this permission object. If two DmtPrincipalPermission objects are equal according to the `equals(Object)` method, then calling this method on each of the two DmtPrincipalPermission 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 DmtPrincipalPermission object implies the specified permission. Another DmtPrincipalPermission instance is implied by this permission either if the target strings are identical, or if this target can be made identical to the other target by replacing a trailing "*" with any string.
      Specified by:
        `implies` in class `java.security.Permission`
      Parameters:
        `p` - the permission to check for implication
      Returns:
        true if this DmtPrincipalPermission instance implies the specified permission

    - #### newPermissionCollection

          public java.security.PermissionCollection newPermissionCollection()

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