net.jini.security
Class GrantPermission

java.lang.Object
  extended by java.security.Permission
      extended by 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

Nested Class Summary
(package private) static class GrantPermission.GrantPermissionCollection
          PermissionCollection variant returned by newPermissionCollection().
private static class GrantPermission.Implier
          Class for checking implication of contained permissions.
private static class GrantPermission.PermissionInfo
          Parsed information about a permission.
 
Field Summary
private  Permission[] grants
           
private  Integer hash
           
private  GrantPermission.Implier implier
           
private static Class[] PARAMS0
           
private static Class[] PARAMS1
           
private static Class[] PARAMS2
           
private static long serialVersionUID
           
private  boolean unserializable
           
 
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
private  int computeHashCode()
          Returns hash code computed by summing hash codes of each distinct permission class name.
private static String constructName(Permission[] pa)
          Constructs GrantPermission name/target string appropriate for given list of permissions.
private static StreamTokenizer createTokenizer(String s)
          Returns tokenizer for parsing given string.
 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.
private static Permission[] flatten(Permission[] pa)
          Returns an array containing all non-GrantPermission permissions in the given permission array, including those contained in nested GrantPermissions in the array.
 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.
private  void initFromName(String name)
          Initializes GrantPermission to contain permissions described in the given name.
private static int maxConsArgs(Class cl)
          Returns the maximum number of String parameters (up to 2) accepted by a constructor of the given class.
 PermissionCollection newPermissionCollection()
          Returns a newly created empty mutable permission collection for GrantPermission instances.
private static GrantPermission.PermissionInfo[] parsePermissions(String s)
          Parses permission information from given GrantPermission name string.
private static String quote(String s)
          Returns quoted string literal that, if parsed by java.io.StreamTokenizer, would yield the given string.
private  void readObject(ObjectInputStream in)
          Reconstitutes contained permissions based on the information in the target name.
private  void writeObject(ObjectOutputStream out)
          Writes target name representing contained permissions.
 
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

serialVersionUID

private static final long serialVersionUID
See Also:
Constant Field Values

PARAMS0

private static final Class[] PARAMS0

PARAMS1

private static final Class[] PARAMS1

PARAMS2

private static final Class[] PARAMS2

grants

private transient Permission[] grants

unserializable

private transient boolean unserializable

implier

private transient volatile GrantPermission.Implier implier

hash

private transient volatile Integer hash
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

computeHashCode

private int computeHashCode()
Returns hash code computed by summing hash codes of each distinct permission class name.


writeObject

private void writeObject(ObjectOutputStream out)
                  throws IOException
Writes target name representing contained permissions.

Throws:
NotSerializableException - if the GrantPermission was constructed explicitly with java.security.UnresolvedPermissions
IOException

readObject

private void readObject(ObjectInputStream in)
                 throws IOException,
                        ClassNotFoundException
Reconstitutes contained permissions based on the information in the target name.

Throws:
InvalidObjectException - if the target name is null or does not conform to the syntax specified in the documentation for GrantPermission
IOException
ClassNotFoundException

initFromName

private void initFromName(String name)
Initializes GrantPermission to contain permissions described in the given name. Throws an IllegalArgumentException if the name is misformatted, or specifies an invalid permission class. Throws a SecurityException if access to the class is not permitted.


parsePermissions

private static GrantPermission.PermissionInfo[] parsePermissions(String s)
Parses permission information from given GrantPermission name string. Throws an IllegalArgumentException if the name string is misformatted.


createTokenizer

private static StreamTokenizer createTokenizer(String s)
Returns tokenizer for parsing given string. The tokenizer is configured similarly to that used by sun.security.provider.PolicyParser, except that comments are disabled and no quote character is set (yet).


constructName

private static String constructName(Permission[] pa)
Constructs GrantPermission name/target string appropriate for given list of permissions.


maxConsArgs

private static int maxConsArgs(Class cl)
Returns the maximum number of String parameters (up to 2) accepted by a constructor of the given class. Returns -1 if no matching constructor (including no-arg constructor) is defined by given class.


quote

private static String quote(String s)
Returns quoted string literal that, if parsed by java.io.StreamTokenizer, would yield the given string. This method is essentially a copy of com.sun.jini.config.ConfigUtil.stringLiteral; the two methods are kept separate since ConfigUtil.stringLiteral could conceivably escape unicode characters, while such escaping would be incorrect for GrantPermission.


flatten

private static Permission[] flatten(Permission[] pa)
Returns an array containing all non-GrantPermission permissions in the given permission array, including those contained in nested GrantPermissions in the array.



Copyright 2007-2010, multiple authors.
Licensed under the Apache License, Version 2.0, see the NOTICE file for attributions.