java.rmi.server
Interface RemoteCallControl

All Known Implementing Classes:
BasicCallController

public interface RemoteCallControl

Defines the interface for performing preinvocation access control for incoming secure RMI calls, and for exercising control over parameter unmarshalling and result marshalling for those calls. A remote object that exports itself as a SecureUnicastRemoteObject or SecureActivatable object can exercise control by implementing this interface.

Since:
1.4

Method Summary
 void controlRemoteCall(java.lang.reflect.Method method, java.security.PrivilegedExceptionAction action)
          Performs preinvocation access control and exercises control over parameter unmarshalling for incoming remote calls.
 void controlRemoteResult(java.lang.reflect.Method method, java.security.PrivilegedExceptionAction action)
          Exercises control over result marshalling for incoming remote calls.
 

Method Detail

controlRemoteCall

public void controlRemoteCall(java.lang.reflect.Method method,
                              java.security.PrivilegedExceptionAction action)
Performs preinvocation access control and exercises control over parameter unmarshalling for incoming remote calls. This method will be called prior to each invocation of a remote method, before the parameters of the remote call are unmarshalled. The first parameter is the remote method that will be invoked. The second parameter is an action that can be executed to unmarshal and obtain the parameters of the remote call. To prevent invocation of the remote method, this method should throw a runtime exception; the exception will be propagated back to the client, and will take precedence over any exception that may have been thrown during parameter unmarshalling. To allow the invocation to proceed, this method should return normally (but if parameter unmarshalling throws an exception, the remote method will not be invoked).

Control over parameter unmarshalling can be exercised by executing the action in the desired context. For example, the action could be executed using AccessController.doPrivileged, Subject.doAs, or Subject.doAsPrivileged. The action returns the unmarshalled parameters as an array of type Object[]. Although not normally recommended, the actual parameters that will be passed to the remote method can be changed by storing new elements into the array. If an exception is thrown during parameter unmarshalling, the action throws that exception; the exception will not yet have been wrapped in a java.rmi.ServerException or java.rmi.ServerError. The action will only attempt to unmarshal the parameters once; if the action is executed again, it will again return the identical array or rethrow the identical exception. If the action is not executed by this method, it will be executed after this method returns, in the same context in which this method was invoked.

If an implementation executes the action in a special context, the security implications of providing access to instances of that implementation should be carefully considered, as this is a public method that could be invoked with an arbitrary action. This should rarely be an issue, since in general an implementation instance should never be given to untrusted code.

SecureRemoteServer methods can be called from within this method.

Parameters:
method - the remote method that will be invoked
action - the action that can be executed in the desired context to cause the parameters of the remote call to be unmarshalled in that context
Throws:
java.lang.RuntimeException - if the call should not be performed. This exception will be propagated back to the caller. Normally a SecurityException should be thrown.
NullPointerException - if any parameter is null

controlRemoteResult

public void controlRemoteResult(java.lang.reflect.Method method,
                                java.security.PrivilegedExceptionAction action)
Exercises control over result marshalling for incoming remote calls. This method will be called after each invocation of a remote method (or after unmarshalling the parameters of a remote call, if an exception is thrown during parameter unmarshalling), before the result (if any) is marshalled. The first parameter is the remote method that was invoked. The second parameter is an action that can be executed to marshal the return value or the exception thrown by the remote method (if any). Control over result marshalling can be exercised by executing the action in the desired context. For example, the action could be executed using AccessController.doPrivileged, Subject.doAs, or Subject.doAsPrivileged. The action always returns null. If an exception is thrown during result marshalling, the action throws that exception. The action will only attempt to marshal the result once; if the action is executed again, it will again return null or rethrow the identical exception. If the action is not executed by this method, it will be executed after this method returns, in the same context in which this method was invoked.

If an implementation executes the action in a special context, the security implications of providing access to instances of that implementation should be carefully considered, as this is a public method that could be invoked with an arbitrary action. This should rarely be an issue, since in general an implementation instance should never be given to untrusted code.

SecureRemoteServer methods can be called from within this method.

Parameters:
method - the remote method that was invoked
action - the action that can be executed in the desired context to cause the result of the remote call to be marshalled in that context
Throws:
NullPointerException - if any parameter is null


Copyright © 2000 Sun Microsystems, Inc. All rights reserved