java.rmi.server
Class SecureExportDesc

java.lang.Object
  |
  +--java.rmi.server.SecureExportDesc

public class SecureExportDesc
extends java.lang.Object

Specifies security information when exporting secure remote objects. The semantics of the constructor parameters are:

In general, portable implementations will not use the constructor that takes endpoints, and most developers do not need to be concerned with the detailed semantics of endpoints.

Given a secure RMI stub for a remote object that was exported with this export descriptor, the getServerConstraints method on that stub will return the constraints given in methodConstraints if there is a match, otherwise the default constraints will be returned.

If endpoints are not specified in the constructor, an ordered list of endpoints is obtained as follows. First, an ordered list of endpoint factories is obtained from the providers returned by the getProviders method of java.security.Security. Each provider is considered in order, and if a provider has a property named "rmi.factory", and the property value is the name of a class that implements SecureServerEndpointFactory and has a no-arg constructor, and no instance of that class already exists in the factory list, then an instance of that class is created and added to the end of the list. An ordered list of endpoints is then obtained by invoking the getServerEndpoint method of each factory to generate an endpoint, passing the serverSubject as a parameter. If getServerEndpoint returns an endpoint, that endpoint is added to the list if the endpoint's supportsConstraints method returns true when invoked with at least one of the specified (default or method-specific) server constraints. The endpoints remain in the same order as their corresponding factories.

If endpoints are specified in the constructor, then for each endpoint, the endpoint's supportsConstraints method must return true when invoked with at least one of the specified (default or method-specific) server constraints, or an IllegalArgumentException is thrown.

Regardless of whether the endpoints are specified or generated, it must also be the case that for each of the specified (default and method-specific) server constraints, there is at least one endpoint for which the supportsConstraints method returns true when invoked with those constraints, otherwise an UnsupportedSecurityException is thrown.

Multiple objects can be exported on the same endpoint. Exported objects that have some endpoints in common are not required to have all endpoints in common.

Two instances of this class are equal only if they are references to the same (==) object.

The server endpoints are not transmitted in the remote reference; only the derived client endpoints are transmitted. The order of endpoints is significant. When a remote call is attempted, a secure call context is created for each derived client endpoint using the endpoint's getCallContext method. Endpoints that do not support all of the requirements are then ignored. Of the remaining endpoints, the endpoint used for the call will be the first endpoint in the list such that no other endpoint has a larger maximum number of supported preference types (as given by the corresponding context's getMaxPreferenceTypes method), and no other endpoint with the same maximum has a larger minimum number of supported preference types (as given by the corresponding context's getMinPreferenceTypes method). If there are existing idle connections for that endpoint, the endpoint's chooseConnection method is used to select one. If chooseConnection returns null but at least one of the connections supports switching to the desired context, one of those connections is reused. If there are no suitable idle connections for use or reuse, a new connection is opened. If an IOException or a SecurityException is thrown while obtaining a connection from the endpoint, the next best client endpoint is tried, and the process is repeated until a connection is obtained or all usable endpoints have been tried.

An RMI implementation may impose additional requirements on both client and server endpoint implementations, such as requiring code to be signed by trusted entities, but only to the extent required by government encryption control regulations.

Since:
1.4

Constructor Summary
SecureExportDesc(SecurityConstraints defaultConstraints)
          Creates a secure export descriptor.
SecureExportDesc(SecurityConstraints defaultConstraints, MethodConstraints[] methodConstraints, SecureServerEndpoint[] endpoints)
          Creates a secure export descriptor.
SecureExportDesc(SecurityConstraints defaultConstraints, MethodConstraints[] methodConstraints, javax.security.auth.Subject serverSubject)
          Creates a secure export descriptor.
 
Method Summary
 SecurityConstraints getDefaultConstraints()
          Returns the default server constraints as a non-null value.
 SecureServerEndpoint[] getEndpoints()
          Returns the endpoints.
 MethodConstraints[] getMethodConstraints()
          Returns the method-specific server constraints.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

SecureExportDesc

public SecureExportDesc(SecurityConstraints defaultConstraints)
                 throws UnsupportedSecurityException
Creates a secure export descriptor. See the comments at the beginning of this class for details.
Parameters:
constraints - the default server constraints, or null
Throws:
UnsupportedSecurityException - if the specified constraints cannot be satisfied by the endpoint of any factory or the calling thread does not have the requisite permissions (such as AuthenticationPermission) to satisfy the specified constraints

SecureExportDesc

public SecureExportDesc(SecurityConstraints defaultConstraints,
                        MethodConstraints[] methodConstraints,
                        javax.security.auth.Subject serverSubject)
                 throws UnsupportedSecurityException
Creates a secure export descriptor. See the comments at the beginning of this class for details. The array passed to the constructor is neither modified nor retained; subsequent changes to that array have no effect on the instance created.
Parameters:
defaultConstraints - the default server constraints, or null
methodConstraints - the method-specific server constraints, or null
serverSubject - the server subject, or null
Throws:
UnsupportedSecurityException - if the default server constraints or any of the method-specific constraints cannot be satisfied by the endpoint of any factory or the calling thread does not have the requisite permissions (such as AuthenticationPermission) to satisfy those constraints
NullPointerException - if any element of methodConstraints is null
java.lang.IllegalArgumentException - if any two elements of methodConstraints specify the same method name and parameter types
java.lang.SecurityException - if the calling thread does not have permission to get the current executing subject

SecureExportDesc

public SecureExportDesc(SecurityConstraints defaultConstraints,
                        MethodConstraints[] methodConstraints,
                        SecureServerEndpoint[] endpoints)
                 throws UnsupportedSecurityException
Creates a secure export descriptor. See the comments at the beginning of this class for details. The arrays passed to the constructor are neither modified nor retained; subsequent changes to those arrays have no effect on the instance created.
Parameters:
defaultConstraints - the default server constraints, or null
methodConstraints - the method-specific constraints, or null
endpoints - the endpoints to use
Throws:
UnsupportedSecurityException - if the default server constraints or any of the method-specific constraints cannot be satisfied by any of the specified endpoints or the calling thread does not have the requisite permissions (such as AuthenticationPermission) to satisfy those constraints
NullPointerException - if the endpoints parameter is null, or any element of endpoints or methodConstraints is null
java.lang.IllegalArgumentException - if any two elements of methodConstraints specify the same method name and parameter types, or an endpoint is specified that does not support any of the specified constraints
Method Detail

getDefaultConstraints

public SecurityConstraints getDefaultConstraints()
Returns the default server constraints as a non-null value.
Returns:
the default server constraints as a non-null value

getMethodConstraints

public MethodConstraints[] getMethodConstraints()
Returns the method-specific server constraints. Returns a new non-null array every time it is called.

Returns:
the method-specific server constraints as a new non-null array

getEndpoints

public SecureServerEndpoint[] getEndpoints()
Returns the endpoints. Returns a new non-null array every time it is called.
Returns:
the endpoints as a new non-null array


Copyright © 2000 Sun Microsystems, Inc. All rights reserved