GrantPermission (Apache River v3.0.0 API Documentation (internals))

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:
   DelimiterDeclaration_opt 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

Nested Classes
Modifier and Type	Class and Description
`(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

Fields
Modifier and Type	Field and Description
`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

Constructors
Constructor and Description
`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

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`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 org.apache.river.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.

Class GrantPermission

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.security.Permission

Methods inherited from class java.lang.Object

Field Detail

serialVersionUID

PARAMS0

PARAMS1

PARAMS2

grants

unserializable

implier

hash

Constructor Detail

GrantPermission

GrantPermission

GrantPermission

Method Detail

getActions

newPermissionCollection

implies

equals

hashCode

computeHashCode

writeObject

readObject

initFromName

parsePermissions

createTokenizer

constructName

maxConsArgs

quote

flatten