BasicProxyPreparer (Module :: JGDMS Jini Platform 3.0-SNAPSHOT API)

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

All Implemented Interfaces:

Serializable, ProxyPreparer
```
public class BasicProxyPreparer
extends Object
implements ProxyPreparer, Serializable
```
A ProxyPreparer for granting dynamic permissions and setting proxy 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:
- Grant permissions, and set new constraints, to prepare a proxy before invoking calls on it's methods.
- 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 and atomic input validation protection from a trusted source that is not known to supply the appropriate constraints.
- Grant permissions, to prepare a trusted proxy received with integrity and atomic input validation protection from a trusted source that supplies appropriate constraints, if the proxy needs permission grants. Permissions may be either passed explicitly via a constructor or if null may be advised by the proxy using AdvisoryDynamicPermissions
- Do nothing, to use as a default when retrieving an optional configuration entry, or to prepare a non-secure proxy.
Since:

2.0

Author:

Sun Microsystems, Inc.

See Also:

Serialized Form

Field Summary

Fields
Modifier and Type	Field and Description
`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 boolean`	`verify` Whether to verify if proxies are trusted.

Constructor Summary

Constructors
Modifier	Constructor and Description
	`BasicProxyPreparer()` Creates a proxy preparer that specifies not to verify proxies, grant them permissions, or set their constraints.
`protected`	`BasicProxyPreparer(AtomicSerial.GetArg arg)` AtomicSerial constructor
	`BasicProxyPreparer(boolean verify, MethodConstraints methodConstraints, Permission[] permissions)` Deprecated.
	`BasicProxyPreparer(boolean verify, Permission[] permissions)` Deprecated.
	`BasicProxyPreparer(MethodConstraints methodConstraints, Permission[] permissions)` Creates a proxy preparer that specifies what method constraints to use when verifying and setting constraints and permissions to grant to proxy.
	`BasicProxyPreparer(Permission[] permissions)` Creates a proxy preparer that specifies what permissions to grant to proxies.

Method Summary

All Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`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)` Deprecated.

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.
- 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(Permission[] permissions)
```
    Creates a proxy preparer that specifies what permissions to grant to proxies.
    
    Parameters:
    
    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
    
    Since:
    
    3.1
  - BasicProxyPreparer
```
@Deprecated
public BasicProxyPreparer(boolean verify,
                                       Permission[] permissions)
```
    Deprecated.
    
    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
```
@Deprecated
public BasicProxyPreparer(boolean verify,
                                       MethodConstraints methodConstraints,
                                       Permission[] permissions)
```
    Deprecated.
    
    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
  - BasicProxyPreparer
```
public BasicProxyPreparer(MethodConstraints methodConstraints,
                          Permission[] permissions)
```
    Creates a proxy preparer that specifies what method constraints to use when verifying and setting constraints and permissions to grant to proxy.
    
    Parameters:
    
    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
    
    Since:
    
    3.1
  - BasicProxyPreparer
```
protected BasicProxyPreparer(AtomicSerial.GetArg arg)
                      throws IOException
```
    AtomicSerial constructor
    
    Parameters:
    
    arg -
    
    Throws:
    
    IOException
- 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. Note if no permissions have been specified, this method attempts to detect any advisory permissions.
    
    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.
    Note the grant call will only dynamically grant permissions if the current context has the relevant GrantPermission's in a security policy file. 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
```
@Deprecated
protected void verify(Object proxy)
                            throws RemoteException
```
    Deprecated.
    
    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.
    
    Overrides:
    
    toString in class 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.
    
    Overrides:
    
    equals in class Object
  - hashCode
```
public int hashCode()
```
    Returns a hash code value for this object.
    
    Overrides:
    
    hashCode in class Object

JGDMS Project 3.0-SNAPSHOT API Documentation

Class BasicProxyPreparer

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

verify

methodConstraintsSpecified

methodConstraints

Constructor Detail

BasicProxyPreparer

BasicProxyPreparer

BasicProxyPreparer

BasicProxyPreparer

BasicProxyPreparer

BasicProxyPreparer

Method Detail

getMethodConstraints

getPermissions

prepareProxy

verify

grant

setConstraints

toString

equals

hashCode