Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## net.jini.security
Class GrantPermission

    java.lang.Object
      java.security.Permission
          net.jini.security.GrantPermission

All Implemented Interfaces:
  Guard, Serializable

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 `GrantPermission`s for contained permissions, as well as granting of permissions contained within nested `GrantPermission`s. 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. `GrantPermission`s constructed explicitly with `UnresolvedPermission`s (through either the `GrantPermission(Permission)` or `GrantPermission(Permission[])` constructor) will have incomplete target names that cannot be used to instantiate other `GrantPermission`s, 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
See Also:
  `DynamicPolicy.grant(Class, Principal[], Permission[])`, Serialized Form
Implementation Specifics:
  This implementation uses the `Logger` named `net.jini.security.policy` to log information at the following levels:

  Level | Description
  --- | ---
  `FINE` | failure to instantiate contained permission
  `FINEST` | resolution of contained permissions

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 `""`.

  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 `GrantPermission`s inside `g`, excluding nested `GrantPermission`s 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.UnresolvedPermission`s 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.

  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 `GrantPermission`s inside `g`, excluding nested `GrantPermission`s 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.UnresolvedPermission`s 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.

  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.

  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()

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2004 Sun Microsystems, Inc. All rights reserved