Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES

## Package net.jini.jeri

Provides the fundamental abstractions and standard implementation classes for Jini(TM) extensible remote invocation (Jini ERI).

See:
Description

Interface Summary
Endpoint | Represents a remote communication endpoint to send requests to.
InboundRequest | Represents a request that is being received and the corresponding response to be sent in reply.
InvocationDispatcher | An abstraction used to handle incoming call requests for a remote object.
InvocationLayerFactory | A factory for creating a compatible proxy and invocation dispatcher for a remote object being exported.
ObjectEndpoint | References a remote object at a remote communication endpoint to send requests to.
OutboundRequest | Represents a request that is being sent and the corresponding response received in reply.
OutboundRequestIterator | Produces `OutboundRequest` instances to use for attempting to send a particular request to a remote communication endpoint.
RequestDispatcher | A callback object for processing inbound requests.
ServerCapabilities | Represents the constraint support capabilities of a server-side transport layer implementation.
ServerEndpoint | Represents one or more communication endpoints on the current (local) host to listen for and receive requests on and a template for producing an `Endpoint` instance to send requests to those communication endpoints.
ServerEndpoint.ListenContext | A callback object for passing to `ServerEndpoint.enumerateListenEndpoints` to receive the enumerated `ListenEndpoint` instances and to choose an active listen operation for each of them on behalf of the caller of `enumerateListenEndpoints`.
ServerEndpoint.ListenCookie | A cookie to identify a listen operation as the return value of the `ListenContext.addListenEndpoint` method.
ServerEndpoint.ListenEndpoint | Represents a communication endpoint on the current (local) host to listen for and receive requests on.
ServerEndpoint.ListenHandle | Represents a listen operation that has been started on a `ListenEndpoint`.

Class Summary
AbstractILFactory | An abstract implementation of `InvocationLayerFactory` that provides a convenient way for subclasses to create proxies and invocation dispatchers for remote objects.
BasicILFactory | A basic implementation of an `InvocationLayerFactory`.
BasicInvocationDispatcher | A basic implementation of the `InvocationDispatcher` interface, providing preinvocation access control for remote objects exported using `BasicJeriExporter`.
BasicInvocationHandler | A basic implementation of the `InvocationHandler` interface.
BasicJeriExporter | An `Exporter` implementation for exporting a remote object to use Jini(TM) extensible remote invocation (Jini ERI).
BasicJeriTrustVerifier | Trust verifier for dynamic proxies and object endpoints used in Jini(TM) extensible remote invocation (Jini ERI).
BasicObjectEndpoint | References a remote object with an `Endpoint` for sending requests to the object and a `Uuid` to identify the object at that `Endpoint`.
InvocationLayerFactory.Instances | A container for the proxy and invocation dispatcher instances returned by `InvocationLayerFactory.createInstances`.
ProxyTrustILFactory | Invocation layer factory for remote objects exported to use Jini(TM) extensible remote invocation (Jini ERI) that produces proxies that additionally implement the `ProxyTrust` interface.

## Package net.jini.jeri Description

Provides the fundamental abstractions and standard implementation classes for Jini(TM) extensible remote invocation (Jini ERI).

Jini ERI is an implementation of the Java(TM) Remote Method Invocation (RMI) programming model that supports the following features:

- The remote object export model defined in the `net.jini.export` package
- The invocation constraint and remote method control model defined in the `net.jini.core.constraint` package
- The trust model defined in the `net.jini.security` package
- Customization of client-side and server-side remote invocation behavior in a variety of ways, including customization of the content and format of the data communicated for remote invocations and pre- and post-invocation processing
- Use of a variety of communication transports, including transports that are not connection-based and transports that are not IP-based
- Use of dynamic proxy classes for client-side proxies, so that build-time generation of stub classes is not required
- Optional use of distributed garbage collection
- Control of all customizable features per exported remote object

In addition, Jini ERI supports full RMI dynamic class loading semantics.

This package includes the standard class for exporting remote objects with Jini ERI, the interfaces that define the Jini ERI architectural elements, standard implementation classes for some of those interfaces, and a standard trust verifier class.

## Programming Model

In general, applications are not expected to program directly to Jini ERI APIs for exporting remote objects; instead, applications should program to the `Exporter` interface, and exporters should normally be obtained from a `Configuration`. The application developer should document the requirements that a given configurable exporter must satisfy, so that the application deployer can provide an exporter that meets those requirements. See the `net.jini.config` package documentation for examples of configurable exporting.

Server-side remote method authorization checks should generally be implemented by the exporter, not by the remote object implementation, so that the authorization policy can be customized by the application deployer.

Clients should program to the `RemoteMethodControl` interface for setting invocation constraints on proxies and generally should not make assumptions about how proxies are implemented.

## Protocol Stack

The Jini ERI architecture has a protocol stack with three layers as shown in the following table, with interfaces representing the abstractions of each layer on the client side and the server side as shown:

Layer | Client-side abstractions | Server-side abstractions
--- | --- | ---
Invocation layer | `InvocationHandler` | `InvocationDispatcher`
Object identification layer | `ObjectEndpoint` | `RequestDispatcher`
Transport layer | `Endpoint`, `OutboundRequestIterator`, `OutboundRequest` | `ServerCapabilities`, `ServerEndpoint`, `InboundRequest`

The client-side and server-side implementations of each layer are chosen for a particular remote object as part of exporting the remote object. The design is intended to allow plugging in different implementations of one layer without affecting the implementations of the other layers.

The client side abstractions correspond to the structure of the client-side proxy for a remote object exported with Jini ERI, with the invocation layer implementation containing the object identification layer implementation and that, in turn, containing the transport layer implementation.

Which invocation constraints are supported for remote invocations to a particular remote object exported with Jini ERI is partially dependent on the particular implementations of these layers used for the remote object (most especially the transport layer implementation).

## Exporter

An `Exporter` exports a remote object and returns a proxy for making remote invocations on the exported remote object. The standard Jini ERI exporter class is `BasicJeriExporter`, which is suitable for most applications. `BasicJeriExporter` by itself exports non-activatable remote objects; to export an activatable remote object with Jini ERI, an `ActivationExporter` can be used with a `BasicJeriExporter` as its underlying exporter.

A `BasicJeriExporter` is constructed with the information for controlling the client-side and server-side implementations of all layers of the Jini ERI protocol stack for the remote object to be exported:

- An `InvocationLayerFactory`, which is used to produce the proxy (containing an invocation handler) for the client-side invocation layer and the `InvocationDispatcher` for the server-side invocation layer
- An object identifier (a `Uuid`) and flags for enabling DGC and controlling virtual machine liveness, which are used to construct a `BasicObjectEndpoint` for the client-side object identification layer and to configure the `RequestDispatcher` for the server-side object identification layer
- A `ServerEndpoint`, used for the server-side transport layer and used to produce the `Endpoint` for the client-side transport layer

`BasicJeriExporter` implies use of a particular implementation of the object identification layer: `BasicObjectEndpoint` as the `ObjectEndpoint` implementation on the client side and an internal `RequestDispatcher` implementation on the server side. The object identifier and flags of a `BasicJeriExporter` control features of this standard object identification layer implementation. The nature of the object identification layer is such that the need to use a different implementation should be rare. In order to use a different implementation of the object identification layer, a deployer needs to use a custom Jini ERI exporter class, which should support specifying an `InvocationLayerFactory` and `ServerEndpoint` for controlling the invocation and transport layer implementations.

For a given remote object exported with Jini ERI, the client-side and server-side counterparts at each layer of the protocol stack must be compatible in order for remote invocations to succeed. At the transport layer, obtaining the client-side `Endpoint` from the supplied server-side `ServerEndpoint` ensures compatibility. At the object identification layer, `BasicJeriExporter` always uses compatible `ObjectEndpoint` and `RequestDispatcher` implementations. At the invocation layer, the `InvocationLayerFactory` abstraction is used to facilitate generation of compatible `InvocationHandler` and `InvocationDispatcher` pairs.

The proxy returned by a `BasicJeriExporter` (a Jini ERI proxy) is an instance of a dynamic proxy class with the following typical structure:

- `Proxy`
  - `InvocationHandler`
    - `BasicObjectEndpoint`
      - `Endpoint`
      - object identifier (`Uuid`)
    - client `MethodConstraints`
    - server `MethodConstraints`

The proxy object is ultimately created by the `InvocationLayerFactory` supplied to the exporter. The proxy class typically implements all of the remote interfaces of the remote object's implementation class, plus `RemoteMethodControl` and any extra interfaces chosen by the factory. The server constraints in the invocation handler are set by the factory, which typically allows specifying them with a constructor argument. The client constraints are initially `null` and can be set using `RemoteMethodControl.setConstraints` on the proxy.

The `BasicObjectEndpoint` is constructed with the object identifier in the exporter and the `Endpoint`, which is obtained from the `ServerEndpoint` by invoking its `enumerateListenEndpoints` method.

## Invocation Layer

The invocation layer deals with the concepts of methods, arguments, return values, and exceptions; marshalling and unmarshalling objects; and remote invocation semantics generally. The invocation layer drives the remote invocation process on the client side.

On the client side, when a remote method is invoked on a Jini ERI proxy, it reflectively dispatches the method invocation to the contained invocation handler. The invocation handler for a Jini ERI proxy typically performs the following steps to carry out its role in processing a remote call:

- Compute the complete, absolute constraints for the remote call by combining `InvocationConstraints` for the invoked method from both the client and server `MethodConstraints` and converting relative time constraints to absolute time constraints.
- Invoke the `ObjectEndpoint`'s `newCall` method, passing the computed constraints, to obtain an `OutboundRequestIterator` to use to make attempts to communicate the remote call.
- Obtain an `OutboundRequest` from the iterator to represent an attempt to communicate the remote call.
- Enforce the constraints that the `OutboundRequest` indicates must be implemented by the invocation layer.
- Create a marshal output stream (see `MarshalOutputStream`) on top of the request output stream of the `OutboundRequest`.
- Marshal an encoding of which remote method is being invoked.
- Marshal the arguments.
- Invoke the `ObjectEndpoint`'s `executeCall` method to execute the remote call and wait for the response.
- Create a marshal input stream (see `MarshalInputStream`) on top of the response input stream of the `OutboundRequest`.
- Unmarshal the result of the remote call and return the return value or throw the exception as appropriate.
- If a communication failure occurs and the remote call can be safely retried without violating at most once semantics, then if the iterator's `hasNext` method returns `true`, obtain another `OutboundRequest` from the iterator and make another attempt to communicate the remote call.

On the server side, when the `RequestDispatcher` receives a remote call request for a particular remote object, it dispatches that request to the `InvocationDispatcher` that the remote object was exported with, passing the remote object, an `InboundRequest` for performing I/O on the request, and a collection of server context elements. An invocation dispatcher typically performs the following steps to carry out its role in processing a remote call:

- Create a marshal input stream on top of the request input stream of the `InboundRequest`.
- Unmarshal and decode which remote method is being invoked.
- Verify that the server constraints for that method are satisfied by the transport layer, and enforce the constraints that the `InboundRequest` indicates must be implemented by the invocation layer.
- Perform any authorization checks.
- Unmarshal the arguments.
- Reflectively invoke the method on the remote object implementation with those arguments.
- Create a marshal output stream on top of the response output stream of the `InboundRequest`.
- Marshal the return value or exception that resulted from invoking the method.

Authorization checks are made before any arguments are unmarshalled in order to avoid denial of service attacks that could be mounted using serialization mechanisms or dynamically loaded classes.

If the `Integrity.YES` constraint is being enforced for a remote call, the marshal input streams created on both sides enforce code integrity using `Security.verifyCodebaseIntegrity`.

`BasicInvocationHandler` and `BasicInvocationDispatcher` are standard invocation handler and invocation dispatcher classes that are suitable for most applications. Both `BasicInvocationHandler` and `BasicInvocationDispatcher` are designed to be extensible so that subclasses can augment or replace how many of the above steps are performed. For example, a subclass could perform additional authorization checks based on the actual arguments; marshal or unmarshal data in an alternate context; perform pre- or post-processing on the arguments, return value, or exception; or cooperate with a corresponding subclass to marshal and unmarshal additional implicit data with a remote call.

As described above, the `InvocationLayerFactory` interface is an abstraction for an object that produces the client-side and server-side implementations of the invocation layer for a remote object at export time. An `InvocationLayerFactory` must produce compatible client-side and server-side invocation layer implementations. `BasicILFactory` is a standard implementation of `InvocationLayerFactory` that produces a proxy with a `BasicInvocationHandler` and an invocation dispatcher that is a `BasicInvocationDispatcher`. A `BasicILFactory` is sufficient when no customizations of `BasicInvocationHandler` and `BasicInvocationDispatcher` are desired. Custom invocation handler and invocation dispatcher implementations (such as subclasses of `BasicInvocationHandler` and `BasicInvocationDispatcher`) can be used by passing a custom `InvocationLayerFactory` to the exporter. `AbstractILFactory` is a convenience class for writing such custom `InvocationLayerFactory` implementations.

The authorization mechanism provided by `BasicInvocationDispatcher` uses the standard `Permission` model. A permission class can be specified to the `BasicILFactory` constructor and is passed to the `BasicInvocationDispatcher` constructor at export time. The permission class is typically a simple subclass of `AccessPermission`. The invocation dispatcher constructs an instance of the specified permission class based on the remote method being invoked. For each incoming remote call, the client subject must be granted the permission for that remote method or the remote call will be refused.

## Object Identification Layer

The object identification layer identifies distinct remote objects that are exported to a given transport endpoint and implements behavior that is specific to individual exported remote objects (but not to the remote invocation semantics of those objects), such as distributed garbage collection.

Typically, an `ObjectEndpoint` contains an object identifier for the remote object as well as the `Endpoint` for communicating requests to the remote object, and a `RequestDispatcher` contains a table mapping object identifiers to exported remote objects.

On the client side, an `ObjectEndpoint` typically prepends the object identifier to the remote call request data for reading by the corresponding `RequestDispatcher`. The `executeCall` method typically reads from the beginning of the response an indication from the `RequestDispatcher` of whether or not the identified object was found, and if it was not, returns a `NoSuchObjectException` for the remote invocation to throw.

On the server side, when the transport layer receives a request, it dispatches that request to the `RequestDispatcher` for the communication endpoint that the request was received on, passing an `InboundRequest` for performing I/O on the request. The `RequestDispatcher` typically reads the object identifier from the beginning of the request data and looks for a remote object with that identifier in its table of exported objects. If such an object is found, the associated `InvocationDispatcher` is invoked with the remote object, the `InboundRequest`, and a server context collection populated by the `InboundRequest`. If no such object is found, an indication is written to the response output stream for reading by the corresponding `ObjectEndpoint`.

The invocation dispatcher is invoked inside an invocation of `ServerContext.doWithServerContext` with an unmodifiable view of the server context collection described above, so that the context is available to the remote object implementation.

`BasicJeriExporter` uses `BasicObjectEndpoint` instances for the client-side object identification layer implementation and instances of an internal `RequestDispatcher` class for the server-side object identification layer implementation. This object identification layer implementation supports distributed garbage collection, as described below.

## Transport Layer

The transport layer communicates requests and responses over the network. The transport layer drives the dispatching of remote call requests on the server side, and thus it controls the server-side threading model.

The transport layer provides abstractions for request/response-based communication, where a request and its corresponding response are each a binary sequence of bytes. While the transport communication is represented to higher layers as discrete requests and responses, connection-oriented communication will be a common implementation technique. The `net.jini.jeri.connection` package provides support for implementing connection-based transport layer providers.

An `OutboundRequest` represents a request being sent, providing an `OutputStream` for writing the request and an `InputStream` for reading the response. An `InboundRequest` represents a request being received, providing an `InputStream` for reading the request and an `OutputStream` for writing the response.

The `ServerEndpoint` interface is the server-side transport layer abstraction for one or more communication endpoints on the local host to listen for and receive requests on. The individual communication endpoints are represented as `ListenEndpoint` instances during an invocation of the `ServerEndpoint.enumerateListenEndpoints` method. A `ServerEndpoint` contains the network location for receiving remote call requests. For example, a TCP-based `ServerEndpoint` typically contains the TCP port to bind to. A `ServerEndpoint` that supports authentication typically contains the `Subject` to use for server authentication. The subject is normally obtained from the current thread when the server endpoint is constructed.

The `Endpoint` interface is the client-side transport layer abstraction for a remote communication endpoint to sent requests to. An `Endpoint` contains the network location for the remote object. For example, a TCP-based `Endpoint` typically contains the remote host address and TCP port to connect to.

The `enumerateListenEndpoints` method is invoked on a `ServerEndpoint` by an exporter at export time to start or reuse listen operations on the communication endpoints represented by the `ServerEndpoint`. The exporter's `ListenContext`, which is passed to `enumerateListenEndpoints`, starts new listen operations when necessary by passing a `RequestDispatcher` to the `ListenEndpoint` instances that are enumerated. The `enumerateListenEndpoints` invocation returns an `Endpoint` that corresponds to the listen operations started or chosen by the exporter, and that `Endpoint` is used in the Jini ERI proxy produced by the export. When a request is received for any active listen operation, an `InboundRequest` is created to communicate that request and is passed to the `RequestDispatcher` associated with the listen operation.

When the `Endpoint.newRequest` method is invoked to send a new request, it returns an `OutboundRequestIterator`, which may be able to produce one or more `OutboundRequest` instances for attempting to send the request. `OutboundRequestIterator` is designed to allow an `Endpoint` implementation to offer multiple communication mechanism alternatives to try or to otherwise signal to higher layers that a request should be retried.

The `net.jini.jeri.tcp` package provides transport over TCP/IP. The `net.jini.jeri.http` package provides HTTP transport over TCP/IP, for use through firewalls. The `net.jini.jeri.ssl` package provides two TLS/SSL-based transports: TLS/SSL transport over TCP/IP, and HTTPS (HTTP over TLS/SSL) transport over TCP/IP, for use through firewalls. The `net.jini.jeri.kerberos` package provides Kerberos-based transport over TCP/IP.

## Invocation Constraints

As described above, a Jini ERI proxy is typically an instance of `RemoteMethodControl` and contains client and server `MethodConstraints` for controlling the `InvocationConstraints` that apply to each remote method. When a remote method is invoked on the proxy, the invocation handler combines the `InvocationConstraints` for that method from the client and the server `MethodConstraints` and converts relative time constraints to absolute time constraints, to form the `InvocationConstraints` to use for the remote call. If any of the requirements cannot be satisfied, the remote invocation throws an `UnsupportedConstraintException`.

The server `MethodConstraints` are specified at export time, via the `InvocationLayerFactory` supplied to the exporter, and are stored in the invocation dispatcher on the server side and in the invocation handler on the client side. The `ServerCapabilities` interface represents the server-side transport layer implementation to the invocation dispatcher for the purpose of verifying, at export time, that the entire implementation of the protocol stack supports the server constraints that that remote object is being exported with. (Otherwise, constraint misconfigurations could go undetected on the server side.) `ServerEndpoint` extends `ServerCapabilities` so that an invocation dispatcher does not need to be programmed to the `ServerEndpoint` API explicitly. At export time, the `ServerEndpoint` is passed to the `InvocationLayerFactory` as a `ServerCapabilities`, and the `InvocationDispatcher` created by the factory invokes `ServerCapabilities.checkConstraints` with all possible `InvocationConstraints` in the server `MethodConstraints`.

The initial client `MethodConstraints` of a Jini ERI proxy, upon return from an exporter, are `null`. Client `MethodConstraints` can be set for a Jini ERI proxy by invoking `RemoteMethodControl.setConstraints` on the proxy to obtain a new copy of the proxy with the specified client `MethodConstraints`.

Most constraints are fully implemented by the transport layer, but there is limited support for constraints being implemented by higher layers. For any given constraint, there must be a clear delineation of which aspects (if any) must be implemented by the transport layer. Most of the constraints in the `net.jini.core.constraint` package must be fully implemented by the transport layer; the one exception is `Integrity`, for which the transport layer is responsible for the data integrity aspect and the invocation layer is responsible for the code integrity aspect.

On both sides, the transport layer is first given the opportunity to implement the constraints in force for a given remote call. The transport layer returns to the invocation layer any constraints that must be at least partially implemented by higher layers: on the client side, as the return value of `OutboundRequest.getUnfulfilledConstraints`, which is invoked by the invocation handler before marshalling the remote call, and on the server side, as the return value of `InboundRequest.checkConstraints`, which is invoked by the invocation dispatcher before unmarshalling the remote call.

## Proxy Trust

On the client side, secure proxies need to be trusted to correctly carry out remote calls. `Security.verifyObjectTrust` is used by clients to verify that a proxy can be trusted. `BasicJeriTrustVerifier` can be used as a trust verifier for Jini ERI proxies that use `BasicInvocationHandler` and `BasicObjectEndpoint`. The `Endpoint` also needs to be trusted to correctly carry out communication. `SslTrustVerifier` can be used as a trust verifier for `SslEndpoint` and `HttpsEndpoint` instances. `KerberosTrustVerifier` can be used as a trust verifier for `KerberosEndpoint` instances.

If a Jini ERI proxy that will be trusted directly by clients is used inside a proxy that will not be trusted directly by clients, the `ProxyTrustILFactory` can be used to cause the trusted proxy to additionally be an instance of `ProxyTrust`. The outer proxy can then be implemented to conform to the requirements specified by `ProxyTrustVerifier`, such that the client can use `ProxyTrustVerifier` to verify that the outer proxy can be trusted.

If a Jini ERI proxy contains a custom invocation handler or custom `Endpoint` that will not be trusted directly by clients, `ProxyTrustExporter` can be used to combine that proxy with a trustable bootstrap proxy, such that the client can use `ProxyTrustVerifier` to verify that the aggregate proxy can be trusted.

## Distributed Garbage Collection

`BasicJeriExporter` supports exporting remote objects that participate in distributed garbage collection (DGC).

DGC uses a two-stage reference counting algorithm to maintain referential integrity across virtual machines, for remote objects exported with DGC enabled:

- A client-side DGC implementation (called the DGC client) tracks the existence and reachability of live remote references (`BasicObjectEndpoint` instances that participate in DGC) for a `BasicObjectEndpoint` class in a given virtual machine. When the number of live remote references to a given remote object transitions from zero to greater than zero, a dirty call is sent to the server-side DGC implementation associated with the remote object, indicating that the remote object is referenced by the client. When the number transitions from greater than zero back to zero, a clean call is sent, indicating that the remote object is no longer referenced by the client.
- A server-side DGC implementation tracks the number of DGC clients that are known to have live remote references to an exported remote object (according to dirty and clean calls received). When that number is greater than zero, the implementation strongly references the exported remote object, preventing it from being garbage collected. When that number is zero, the implementation only weakly references the exported remote object, so that it can be garbage collected (if it is not otherwise strongly reachable locally). If the remote object is garbage collected, it becomes effectively unexported.

Because a reference counting algorithm is used, collection of unreachable cycles of remote references is not supported.

If a remote object that is an instance of `Unreferenced` is exported with DGC enabled, then whenever the number of DGC clients that are known to have live remote references to the remote object transitions from greater than zero to zero, the remote object's `unreferenced` method is invoked (before the server-side implementation's strong reference is dropped).

The referential integrity of the live remote references tracked by a given DGC client to a given server-side DGC implementation is leased for finite durations of time. The lease duration is chosen by the server-side implementation and conveyed in dirty call responses. The DGC client is responsible for renewing its lease with the server (with successive dirty calls) as long as it has live remote references for that server. If the server-side DGC implementation detects a lease expiration, it no longer considers the DGC client to have live remote references to any of its exported remote objects. This leasing model is designed to allow server-side cleanup and garbage collection in the event of client failure, at the expense of possible loss of referential integrity in the event of communication failure.

See the `BasicObjectEndpoint` and `BasicJeriExporter` specifications for more information about client-side and server-side DGC processing.

Since:
  2.0

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES

Copyright © 2004 Sun Microsystems, Inc. All rights reserved