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:

DynamicPolicy.grant(Class, Principal[], Permission[]), Serialized Form

Constructor Summary

GrantPermission(Permission permission)
Creates a GrantPermission for the given permission.

GrantPermission(Permission[] permissions)
Creates a GrantPermission for the given permissions.

GrantPermission(String name)
Creates a GrantPermission for the permission(s) specified in the name string.

Method Summary

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.
String	getActions() Returns canonical string representation of this permission's actions, which for GrantPermission is always the empty string "".
int	hashCode()
boolean	implies(Permission permission) Returns true if the given permission is a GrantPermission implied by this permission, or false otherwise.
PermissionCollection	newPermissionCollection() Returns a newly created empty mutable permission collection for GrantPermission instances.

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

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 Detail

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