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

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:

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

Other constraints defined in this package are:

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:

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