Package net.jini.security

Class GrantPermission

java.lang.Object
java.security.Permission
net.jini.security.GrantPermission
All Implemented Interfaces:
Serializable, Guard
public final class GrantPermission extends Permission
Permission required to dynamically grant permissions by security policy providers which implement the DynamicPolicy interface. Each GrantPermission instance contains a set of permissions that can be granted by code authorized with the GrantPermission. When the DynamicPolicy.grant method is invoked, the checkPermission method of the installed security manager (if any) is called with a GrantPermission containing the permissions to grant; if the calling context does not have any permissions which imply the GrantPermission, then the grant operation will fail.

In addition to authorizing granting of contained permissions, each GrantPermission also authorizes granting of GrantPermissions for contained permissions, as well as granting of permissions contained within nested GrantPermissions. For example, if GrantPermission g1 contains Permission p, g1 authorizes granting of both p and GrantPermission(p); if GrantPermission g2 contains GrantPermission(p), then g2 also authorizes granting of both p and GrantPermission(p).

The name (also referred to as the "target name") of each GrantPermission instance carries a string representation of the permissions contained by the GrantPermission, while the actions string of each GrantPermission is always the empty string. If a GrantPermission is serialized, only its name string is sent (i.e., contained permissions are not themselves serialized). Upon deserialization, the set of contained permissions is reconstituted based on information in the name string. GrantPermissions constructed explicitly with UnresolvedPermissions (through either the GrantPermission(Permission) or GrantPermission(Permission[]) constructor) will have incomplete target names that cannot be used to instantiate other GrantPermissions, and will not be serializable--attempting to serialize such a GrantPermission will cause a java.io.NotSerializableException to be thrown.

The syntax of the target name approximates that used for specifying permissions in the default security policy file; it is listed below using the same grammar notation employed by The Java(TM) Language Specification: 

 Target:
   DelimiterDeclarationopt Permissions ;opt

 DelimiterDeclaration:
   delim = DelimiterCharacter

 Permissions:
   Permission
   Permissions ; Permission

 Permission:
   PermissionClassName
   PermissionClassName Name
   PermissionClassName Name , Actions

 PermissionClassName:
   ClassName

 Name:
   DelimitedString

 Actions:
   DelimitedString
The production for ClassName is the same as that used in The Java Language Specification. DelimiterCharacter can be any unquoted non-whitespace character other than ';' (single and double-quote characters themselves are allowed). If DelimiterCharacter is not specified, then the double-quote character is the default delimiter. DelimitedString is the same as the StringLiteral production in The Java Language Specification, except that it is delimited by the DelimiterDeclaration-specified (or default) delimiter character instead of the double-quote character exclusively.

Note that if the double-quote character is used as the delimiter and the name or actions strings of specified permissions themselves contain nested double-quote characters, then those characters must be escaped (or in some cases doubly-escaped) appropriately. For example, the following policy file entry would yield a GrantPermission containing a FooPermission in which the target name would include the word "quoted" surrounded by double-quote characters: 

 permission net.jini.security.GrantPermission
     "FooPermission \"a \\\"quoted\\\" string\"";
For comparison, the following policy file entry which uses a custom delimiter would yield an equivalent GrantPermission: 
 permission net.jini.security.GrantPermission
     "delim=| FooPermission |a \"quoted\" string|";
Some additional example policy file permissions: 
 // allow granting of permission to listen for and accept connections
 permission net.jini.security.GrantPermission
     "java.net.SocketPermission \"localhost:1024-\", \"accept,listen\"";

 // allow granting of permissions to read files under /foo, /bar directories
 permission net.jini.security.GrantPermission
     "delim=' java.io.FilePermission '/foo/-', 'read'; java.io.FilePermission '/bar/-', 'read'";

 // allow granting of permission for client authentication as jack, with or without delegation,
 to
 any server
 permission net.jini.security.GrantPermission
     "delim=| net.jini.security.AuthenticationPermission |javax.security.auth.x500.X500Principal
 \"CN=jack\"|, |delegate|";
Since:
2.0
Author:
Sun Microsystems, Inc.
See Also:

  • Constructor Details

    • GrantPermission

      public GrantPermission(String name)
      Creates a GrantPermission for the permission(s) specified in the name string.
      Parameters:
      name - string describing contained permissions
      Throws:
      NullPointerException - if name is null
      IllegalArgumentException - if unable to parse target name

    • GrantPermission

      public GrantPermission(Permission permission)
      Creates a GrantPermission for the given permission.
      Parameters:
      permission - permission to allow to be granted
      Throws:
      NullPointerException - if permission is null

    • GrantPermission

      public GrantPermission(Permission[] permissions)
      Creates a GrantPermission for the given permissions. The permissions array passed in is neither modified nor retained; subsequent changes to the array have no effect on the GrantPermission.
      Parameters:
      permissions - permissions to allow to be granted
      Throws:
      NullPointerException - if permissions array or any element of permissions array is null

  • Method Details

    • getActions

      public String getActions()
      Returns canonical string representation of this permission's actions, which for GrantPermission is always the empty string "".
      Specified by:
      getActions in class Permission
      Returns:
      the empty string ""

    • newPermissionCollection

      public PermissionCollection newPermissionCollection()
      Returns a newly created empty mutable permission collection for GrantPermission instances. The implies method of the returned PermissionCollection instance is defined as follows: for a given GrantPermission g, let c(g) denote the set of all permissions contained within g or within arbitrarily nested GrantPermissions inside g, excluding nested GrantPermissions themselves. Then, a GrantPermission g is implied by the PermissionCollection pc if and only if each permission in c(g) is implied by the union of c(p) for all p in pc.

      Implication of contained java.security.UnresolvedPermissions is special-cased: an UnresolvedPermission p1 is taken to imply another UnresolvedPermission p2 if and only if the serialized representations of p1 and p2 are identical.

      Overrides:
      newPermissionCollection in class Permission
      Returns:
      newly created empty mutable permission collection for GrantPermissions

    • implies

      public boolean implies(Permission permission)
      Returns true if the given permission is a GrantPermission implied by this permission, or false otherwise. Implication is defined as follows: for a given GrantPermission g, let c(g) denote the set of all permissions contained within g or within arbitrarily nested GrantPermissions inside g, excluding nested GrantPermissions themselves. Then, a GrantPermission g1 is implied by another GrantPermission g2 if and only if each permission in c(g1) is implied by c(g2).

      Implication of contained java.security.UnresolvedPermissions is special-cased: an UnresolvedPermission p1 is taken to imply another UnresolvedPermission p2 if and only if the serialized representations of p1 and p2 are identical.

      Specified by:
      implies in class Permission
      Parameters:
      permission - permission to check
      Returns:
      true if given permission is implied by this permission, false otherwise

    • equals

      public boolean equals(Object obj)
      Returns true if the given object is a GrantPermission which both implies and is implied by this permission; returns false otherwise.
      Specified by:
      equals in class Permission
      Parameters:
      obj - object to compare against
      Returns:
      true if given object is a GrantPermission which both implies and is implied by this permission, false otherwise

    • hashCode

      public int hashCode()
      Specified by:
      hashCode in class Permission