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 BasicProxyPreparer

    java.lang.Object
      net.jini.security.BasicProxyPreparer

All Implemented Interfaces:
  ProxyPreparer, Serializable

public class BasicProxyPreparer
extends Object
implements ProxyPreparer, Serializable

A `ProxyPreparer` for verifying that proxies are trusted, granting them dynamic permissions, and setting their constraints, as well as for creating other proxy preparer subclasses that include those operations.

Applications and configurations can use this class to create proxy preparers for several common cases. Some examples include creating proxy preparers that:

- Verify trust, grant permissions, and set new constraints, to prepare a proxy received from an untrusted source.
- Use the proxy's existing constraints when verifying trust in the proxy, to prepare a trusted proxy received with integrity protection from a trusted source that supplies constraints, confirming that the proxy's implementation is trusted locally, but allowing the constraints to be downloaded from a third party.
- Set new constraints, to prepare a trusted proxy received with integrity protection from a trusted source that is not known to supply the appropriate constraints.
- Grant permissions, to prepare a trusted proxy received with integrity protection from a trusted source that supplies appropriate constraints, if the proxy needs permission grants.
- Do nothing, to use as a default when retrieving an optional configuration entry, or to prepare a non-secure proxy.

Since:
  2.0
See Also:
  Serialized Form

Field Summary
`protected MethodConstraints` | `methodConstraints` Method constraints to use when verifying if proxies are trusted and for setting their constraints, if `methodConstraintsSpecified` is `true`.
`protected boolean` | `methodConstraintsSpecified` Whether to use `methodConstraints` when verifying if proxies are trusted and for setting their constraints.
`protected Permission[]` | `permissions` Permissions to grant to proxies, or an empty array if no permissions should be granted.
`protected boolean` | `verify` Whether to verify if proxies are trusted.

Constructor Summary
`BasicProxyPreparer()` Creates a proxy preparer that specifies not to verify proxies, grant them permissions, or set their constraints.
`BasicProxyPreparer(boolean verify, MethodConstraints methodConstraints, Permission[] permissions)` Creates a proxy preparer that specifies whether proxies should be verified, specifies permissions to grant them, and specifies what method constraints to use when verifying and setting constraints.
`BasicProxyPreparer(boolean verify, Permission[] permissions)` Creates a proxy preparer that specifies whether proxies should be verified, using the constraints on the proxy by default, and specifies what permissions to grant to proxies.

Method Summary
`boolean` | `equals(Object object)` Returns `true` if the given object is an instance of the same class as this object, with the same value for `verify`, with method constraints that are `equals` or similarly not specified, and with `permissions` containing the same elements, independent of order.
`protected MethodConstraints` | `getMethodConstraints(Object proxy)` Returns the method constraints to use when verifying and setting constraints on the specified proxy.
`protected Permission[]` | `getPermissions(Object proxy)` Returns the permissions to grant to proxies, or an empty array if no permissions should be granted.
`protected void` | `grant(Object proxy)` Grants permissions to the proxy.
`int` | `hashCode()` Returns a hash code value for this object.
`Object` | `prepareProxy(Object proxy)` Performs operations on a proxy to prepare it for use, returning the prepared proxy, which may or may not be the argument itself.
`protected Object` | `setConstraints(Object proxy)` Sets constraints on the proxy.
`String` | `toString()` Returns a string representation of this object.
`protected void` | `verify(Object proxy)` Verifies that the proxy is trusted.

Methods inherited from class java.lang.Object
`clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

Field Detail

### verify

    protected final boolean verify

  Whether to verify if proxies are trusted.

### methodConstraintsSpecified

    protected final boolean methodConstraintsSpecified

  Whether to use `methodConstraints` when verifying if proxies are trusted and for setting their constraints.

### methodConstraints

    protected final MethodConstraints methodConstraints

  Method constraints to use when verifying if proxies are trusted and for setting their constraints, if `methodConstraintsSpecified` is `true`. Set to `null` if `methodConstraintsSpecified` is `false`.

### permissions

    protected final Permission[] permissions

  Permissions to grant to proxies, or an empty array if no permissions should be granted. The value is always non-`null`.

Constructor Detail

### BasicProxyPreparer

    public BasicProxyPreparer()

  Creates a proxy preparer that specifies not to verify proxies, grant them permissions, or set their constraints.

### BasicProxyPreparer

    public BasicProxyPreparer(boolean verify,
                              Permission[] permissions)

  Creates a proxy preparer that specifies whether proxies should be verified, using the constraints on the proxy by default, and specifies what permissions to grant to proxies.

Parameters:
  `verify` - whether to verify if proxies are trusted
  `permissions` - permissions to grant, or `null` if no permissions should be granted
Throws:
  `NullPointerException` - if `permissions` is not `null` and any of its elements are `null`

### BasicProxyPreparer

    public BasicProxyPreparer(boolean verify,
                              MethodConstraints methodConstraints,
                              Permission[] permissions)

  Creates a proxy preparer that specifies whether proxies should be verified, specifies permissions to grant them, and specifies what method constraints to use when verifying and setting constraints.

Parameters:
  `verify` - whether to verify if proxies are trusted
  `methodConstraints` - method constraints to use when verifying and setting constraints
  `permissions` - permissions to grant, or `null` if no permissions should be granted
Throws:
  `NullPointerException` - if `permissions` is not `null` and any of its elements are `null`

Method Detail

### getMethodConstraints

    protected MethodConstraints getMethodConstraints(Object proxy)

  Returns the method constraints to use when verifying and setting constraints on the specified proxy.

  The default implementation returns the value of `methodConstraints` if `methodConstraintsSpecified` is `true`, else returns the constraints on the specified proxy if it implements `RemoteMethodControl`, else returns `null`.

  Subclasses may wish to override this method, for example, to augment the existing constraints on the proxy rather than replacing them.

  Parameters:
    `proxy` - the proxy being prepared
  Returns:
    the method constraints to use when verifying and setting constraints on the proxy

### getPermissions

    protected Permission[] getPermissions(Object proxy)

  Returns the permissions to grant to proxies, or an empty array if no permissions should be granted. The return value need not be newly created, but cannot be `null`.

  The default implementation returns the value of `permissions`.

  Subclasses may wish to override this method, for example, to grant permissions that depend on principal constraints found on the proxy.

  Parameters:
    `proxy` - the proxy being prepared
  Returns:
    the permissions to grant to the proxy

### prepareProxy

    public Object prepareProxy(Object proxy)
                        throws RemoteException

  Performs operations on a proxy to prepare it for use, returning the prepared proxy, which may or may not be the argument itself.

  The default implementation provides the following behavior. If `proxy` is `null`, throws a `NullPointerException`. Otherwise, calls `verify` with `proxy`. If the `verify` call succeeds, calls `grant` with `proxy`. If the `grant` call succeeds, returns the result of calling `setConstraints` with `proxy`.

  Subclasses may wish to override this method, for example, to perform additional operations, typically calling the default implementation via `super`.

  Specified by:
    `prepareProxy` in interface `ProxyPreparer`
  Parameters:
    `proxy` - the proxy to prepare
  Returns:
    the prepared proxy
  Throws:
    `NullPointerException` - if `proxy` is `null`
    `RemoteException` - if a communication-related exception occurs
    `SecurityException` - if a security exception occurs
  See Also:
    `verify`, `grant`, `setConstraints`

### verify

    protected void verify(Object proxy)
                   throws RemoteException

  Verifies that the proxy is trusted. Called by the default implementation of `prepareProxy`.

  The default implementation provides the following behavior. If `proxy` is `null`, throws a `NullPointerException`. Otherwise, if `verify` is `true`, calls `Security.verifyObjectTrust`, with `proxy`, `null` for the class loader, and, for the context, a collection containing the result of calling `getMethodConstraints` with `proxy`, or an empty collection if the constraints are `null`.

  Subclasses may wish to override this method, for example, to specify a different class loader or context when verifying the proxy.

  Parameters:
    `proxy` - the proxy to verify
  Throws:
    `NullPointerException` - if `proxy` is `null`
    `RemoteException` - if a communication-related exception occurs
    `SecurityException` - if verifying that the proxy is trusted fails
  See Also:
    `prepareProxy`, `getMethodConstraints`, `Security.verifyObjectTrust`

### grant

    protected void grant(Object proxy)

  Grants permissions to the proxy. Called by the default implementation of `prepareProxy` unless `verify` throws an exception.

  The default implementation provides the following behavior. If `proxy` is `null`, throws a `NullPointerException`. Otherwise, calls `getPermissions` with `proxy` to determine what permissions should be granted. If the permissions are not empty, calls `Security.grant`, with the proxy's class as the class argument and those permissions. If `grant` discovers that dynamic permission grants are not supported and throws a `UnsupportedOperationException`, catches that exception and throws a `SecurityException`.

  Subclasses may wish to override this method, for example, to alter the principals for which permission grants are made.

  Parameters:
    `proxy` - the proxy to grant permissions
  Throws:
    `SecurityException` - if a security exception occurs
    `NullPointerException` - if proxy is `null`
  See Also:
    `prepareProxy`, `getPermissions`, `Security.grant`

### setConstraints

    protected Object setConstraints(Object proxy)

  Sets constraints on the proxy. Called by the default implementation of `prepareProxy` unless `verify` or `grant` throw an exception.

  The default implementation provides the following behavior. If `proxy` is `null`, throws a `NullPointerException`. Otherwise, if `methodConstraintsSpecified` is `false`, returns the proxy, else if object does not implement `RemoteMethodControl`, throws a `SecurityException`, else returns the result of calling `RemoteMethodControl.setConstraints` on the proxy, using the value returned from calling `getMethodConstraints` with `proxy`.

  Subclasses may wish to override this method, for example, to support verifying objects that do not implement `RemoteMethodControl`.

  Parameters:
    `proxy` - the proxy
  Returns:
    the proxy with updated constraints
  Throws:
    `NullPointerException` - if `proxy` is `null`
    `SecurityException` - if a security exception occurs
  See Also:
    `prepareProxy`, `getMethodConstraints`, `RemoteMethodControl.setConstraints`

### toString

    public String toString()

  Returns a string representation of this object.

### equals

    public boolean equals(Object object)

  Returns `true` if the given object is an instance of the same class as this object, with the same value for `verify`, with method constraints that are `equals` or similarly not specified, and with `permissions` containing the same elements, independent of order.

### hashCode

    public int hashCode()

  Returns a hash code value for this object.

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