BasicProxyPreparer (Apache River v3.0.0 Specification-only API Documentation)

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

All Implemented Interfaces:

Serializable, ProxyPreparer
```
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

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

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

All Methods Instance Methods Concrete 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)` 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.
    
    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

Class BasicProxyPreparer

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

verify

methodConstraintsSpecified

methodConstraints

permissions

Constructor Detail

BasicProxyPreparer

BasicProxyPreparer

BasicProxyPreparer

Method Detail

getMethodConstraints

getPermissions

prepareProxy

verify

grant

setConstraints

toString

equals

hashCode