Package net.jini.core.constraint

Defines constraints and collections of constraints that can be used to control method invocation, and an interface that proxies implement to allow clients to specify constraints for remote method calls.

See: Description

Interface Summary

Interface	Description
InvocationConstraint	The marker interface used to identify constraints for method invocations.
MethodConstraints	Defines an immutable mapping from Method to InvocationConstraints, used to specify per-method constraints.
RelativeTimeConstraint	Implemented by constraints that are expressed in terms of relative time, to support conversion to absolute time constraints.
RemoteMethodControl	Defines an interface to proxies for setting constraints to control remote method calls.

Class Summary

Class	Description
ClientAuthentication	Represents a constraint on authentication of the client to the server.
ClientMaxPrincipal	Represents a constraint on the client, such that if the client authenticates itself, then it may only authenticate itself as one or more of the specified principals.
ClientMaxPrincipalType	Represents a constraint on the client, such that if the client authenticates itself, then it may only authenticate itself as principals that are instances of one or more of the specified classes.
ClientMinPrincipal	Represents a constraint on the client, such that if the client authenticates itself, then it must authenticate itself as at least all of the specified principals.
ClientMinPrincipalType	Represents a constraint on the client, such that if the client authenticates itself, then it must authenticate itself such that, for each specified class, at least one authenticated principal is an instance of that class.
Confidentiality	Represents a constraint on the confidentiality of message contents.
ConnectionAbsoluteTime	Represents a constraint on the absolute time by which a network connection must be established.
ConnectionRelativeTime	Represents a constraint on the maximum amount of time to wait for a network connection to be established.
ConstraintAlternatives	Combines two or more constraint alternatives into a single overall constraint.
Delegation	Represents a constraint on delegation from the client to the server.
DelegationAbsoluteTime	Represents a constraint on delegation, such that if delegation is permitted, it be permitted only for a range of absolute times.
DelegationRelativeTime	Represents a constraint on delegation, such that if delegation is permitted, it be permitted only for a range of time measured relative to the start of the remote call.
Integrity	Represents a constraint on the integrity of message contents, covering not only data transmitted in band as part of the remote call itself, but also out-of-band downloaded code.
InvocationConstraints	An immutable aggregation of constraints into a set of requirements and a set of preferences.
ServerAuthentication	Represents a constraint on authentication of the server to the client.
ServerMinPrincipal	Represents a constraint on the server, such that if the server authenticates itself, then it must authenticate itself as at least all of the specified principals.

Package net.jini.core.constraint Description

Defines constraints and collections of constraints that can be used to control method invocation, and an interface that proxies implement to allow clients to specify constraints for remote method calls. Clients control remote calls using constraints. The client attaches the constraints to a proxy by calling a method on the RemoteMethodControl interface implemented by the proxy. At each remote call through a proxy, the proxy implementation is responsible for using communication mechanisms that satisfy the client's constraints. If the constraints cannot be satisfied, the proxy throws a ConnectIOException.

Invocation Constraints

All constraint classes implement the InvocationConstraint interface. The constraint mechanism is designed to be extensible; the constraint classes defined in this package should be adequate for many applications, but additional constraint classes, either generic in nature or specific to a particular mechanism or service, can be defined as necessary. By design, the constraints defined in this package express what control is desired, not how that control should be achieved; the constraints are not tied to specific algorithms, mechanisms, or protocols. Although most of the constraints defined in this package are related to trust mechanisms, it is intended and expected that a wide variety of constraints will be defined, particularly in the area of quality of service.

The basic trust-related constraints are very simple:

• Integrity - to make sure that the messages and objects (not just data, but also downloaded code) sent over the network are not tampered with by third parties
• ServerAuthentication - to prove to the client that the server is executing on behalf of some subject, so that the call can be terminated if the subject is not trusted by the client. The flip side of this is anonymity: to allow a server to remain anonymous when it wants to be.
• ClientAuthentication - to prove to the server that the client is executing on behalf of some subject, so that the server can perform only those tasks for which the subject is authorized. The flip side of this is anonymity: to allow a client to remain anonymous when it wants to be.
• Delegation - to allow the server to authenticate as the client in remote calls made and received by the server, to allow the server to act on a client's behalf when dealing with third parties, in cases where the identity of the client (not the server) is what matters to those parties.

There are also constraints to control which principals of a client or server subject must be authenticated, and which principals of a client are permitted to be authenticated:

• ClientMinPrincipal - to require a client to authenticate as at least some specific principals
• ClientMaxPrincipal - to require a client to authenticate as at most some specific principals
• ClientMinPrincipalType - to require a client to authenticate as at least some specific types of principals
• ClientMaxPrincipalType - to require a client to authenticate as at most some specific types of principals
• ServerMinPrincipal - to require a server to authenticate as at least some specific principals

(There is no ServerMaxPrincipal constraint; a client should not need to impose such a maximum, and a server can impose a maximum by limiting the contents of the subject it uses for network authentication.)

There are also constraints to control the time during which a server is permitted to exercise delegation:

• DelegationAbsoluteTime - to specify a range of absolute times
• DelegationRelativeTime - to specify a range of times relative to the start of the remote call

Other constraints defined in this package are:

• ConnectionRelativeTime - to control the maximum amount of time to wait for a network connection to be established
• ConnectionAbsoluteTime - to control the maximum absolute time by which a network connection must be established
• Confidentiality - to make sure that the data sent over the network cannot be interpreted by third parties

There are no explicit don't care constraints; a don't care condition is expressed by the absence of constraints.

Constraints can be combined using ConstraintAlternatives to express alternatives, such that at least one of the individual constraints must be satisfied (but not all have to be satisfied) for the aggregate constraint to be satisfied.

InvocationConstraints aggregates constraints into a set of requirements and a set of preferences. A requirement is a mandatory constraint that must be satisfied. A preference is a desired constraint, to be satisfied if possible, but it will not be satisfied if it conflicts with a requirement. If two preferences conflict, it is arbitrary as to which one will be satisfied. If a constraint is not understood, due to lack of knowledge of the type of the constraint or the contents of the constraint, then the constraint cannot be satisfied.

Finally, MethodConstraints defines a mapping from Method to InvocationConstraints, allowing different constraints to be specified for different methods. For example, a client might require client authentication for write operations but not for read operations, or a client might care about the confidentiality of some remote calls but not others.

Although the emphasis in this discussion has been on how clients use constraints, constraints typically are also used by servers to specify their minimum requirements for remote calls. When a remote object is exported, the server's constraints normally are copied from the exporter into the returned proxy, so that the proxy knows the minimum constraints required to communicate with the server. Note that constraints are not used to specify server-side authorization (access control) policy.

RemoteMethodControl interface

Proxies implement the RemoteMethodControl interface to allow clients to impose constraints on remote calls. If a proxy implements this interface, then the semantics of this interface apply to all calls through all remote methods defined by the proxy; there is no mechanism to exempt remote methods or remote interfaces from these semantics.

Constraints for a remote call come from two sources:

• Client constraints placed on a proxy
• Constraints imposed by the server (including any minimum constraints imposed by the communication mechanism used between the proxy and server)

The client constraints placed on a proxy are specified with a MethodConstraints instance, so the client can specify different constraints for each remote method. Client constraints placed directly on a proxy apply to all remote calls made through that particular proxy by any thread. The server constraints are controlled by the proxy implementation; they are not exposed to the client, and might vary in ways unknown to the client (for example, vary by method or over time). The client should set the constraints it wants rather than assuming that the server imposes particular constraints.

A remote call will be performed only if the combined requirements (from both sources) can be satisfied. If the requirements cannot be satisfied, the proxy throws a ConnectIOException, typically containing (but not required to contain) a nested UnsupportedConstraintException. In addition to the requirements, both client and server preferences will be satisfied, to the extent possible. Note that it is possible to specify conflicting constraints, meaning they cannot be simultaneously satisfied. Preferences that conflict with requirements are ignored, and if preferences conflict with each other it is arbitrary as to which (if any) are satisfied, but if there are conflicting requirements the remote call will not be made.

Since:

2.0

Version:

2.0