Package net.jini.export

Provides generic abstractions for exporting remote objects (Exporter), obtaining a proxy from an exported remote object (ProxyAccessor), obtaining the server-side context information for an executing remote call (ServerContext), and defining export permissions (ExportPermission).

See: Description

Interface Summary

Interface	Description
Exporter	An abstraction for exporting a single remote object such that it can receive remote method invocations, and later for unexporting that same remote object.
ProxyAccessor	Provides a means to obtain a proxy from an exported remote object.
ServerContext.Spi	Defines the interface for server context providers, which are consulted by ServerContext.getServerContext() if no server context has been explicitly associated with the current thread via a previous call to ServerContext.doWithServerContext(java.lang.Runnable, java.util.Collection).

Class Summary

Class	Description
ExportPermission	Defines runtime permissions for Exporter implementations.
ServerContext	The ServerContext class contains static methods to execute some action within an appropriate server context for the current thread and to obtain the server context for the current thread.

Package net.jini.export Description

Provides generic abstractions for exporting remote objects (Exporter), obtaining a proxy from an exported remote object (ProxyAccessor), obtaining the server-side context information for an executing remote call (ServerContext), and defining export permissions (ExportPermission). These abstractions are independent of communication protocols, remote invocation semantics, and other details of remote object behavior.

Requirements

The Exporter abstraction is intended to satisfy the following requirements:

• support a variety of implementations for exporting and unexporting remote objects using a protocol independent API
• support exporting a given remote object to multiple runtimes

Exporter

The interface Exporter is a high-level API for both exporting a single remote object so that it can receive remote method invocations, and unexporting that same remote object. Applications can use a Configuration provider together with the Exporter interface to export remote objects in a way that can be configured and deployed at run-time to use specific implementations of the Exporter interface. See the net.jini.config package documentation for examples on configurable exporting.

Several implementations of the Exporter interface are provided:

JrmpExporter	Exports an object using the Java(TM) Remote Method Invocation (Java RMI) implementation in Java 2, SDK, Standard Edition (J2SE(TM)). The behavior of remote objects exported via a JrmpExporter are the same as the behavior of objects exported via equivalent exportObject methods of the java.rmi.server.UnicastRemoteObject and java.rmi.activation.Activatable classes.
IiopExporter	Exports an object using the Java Remote Method Invocation over Internet-ORB Protocol technology (RMI-IIOP) in J2SE. The behavior of remote objects exported via an IiopExporter are the same as the behavior of objects exported via the exportObject method of the class javax.rmi.PortableRemoteObject and (where appropriate) connected to an ORB via the connect method of javax.rmi.CORBA.Stub.
BasicJeriExporter	Exports an object to use Jini extensible remote invocation (Jini ERI). A remote object exported with BasicJeriExporter can have associated custom remote invocation and dispatch behavior, as well as a customized communication protocol.

The details of export and unexport behavior, including communication protocols used for remote invocation and additional invocation semantics, are defined by the particular implementation of the Exporter interface.

To export a remote object, an application needs to either construct a new instance of an Exporter implementation explicitly or use the Configuration.getEntry method to obtain a new instance of an Exporter implementation. It is preferable to obtain exporters via the Configuration provider because doing so eliminates application code dependency on specific Exporter implementations. Only a single object can be exported per Exporter instance. Since an exporter hides all the details of export behavior (for example, an object or activation identifier) and such information in many cases is only applicable to a single object, it simplifies the abstraction and the programming model to require a new exporter per export.

The export method exports a remote object and returns a proxy that implements all the remote interfaces of the remote object and that can be used to invoke remote methods on that exported remote object. The caller should not make any assumptions about the behavior of the Exporter implementation to which the object was exported, the implementation of the returned proxy (for example, it need not be a "stub" class as defined in the Java RMI specification), or the communication protocols used by the returned proxy to invoke remote methods.

A remote object exported via a given Exporter instance can later be unexported by invoking the unexport method of that Exporter instance.

ProxyAccessor

The interface ProxyAccessor provides a means to obtain a proxy for an exported remote object and is typically used in conjunction with activatable remote objects. An activatable remote object should implement this interface so that the activation group can obtain the remote object's proxy once the remote object is created (activated) and exported. If an activatable remote object does not implement this interface, it must define a constructor that takes as arguments an ActivationID and a MarshalledObject, and it must be serializable and marshalling the object produces a suitable proxy for the remote object.

ServerContext

The class ServerContext provides a generic API for associating and obtaining server context information for a remote call executing in the current thread. The class contains static methods for obtaining the server context for the current thread (ServerContext.getServerContext) and for executing some action within a given server context (ServerContext.doWithServerContext). In addition, the ServerContext class provides the interface ServerContext.Spi for server context providers that are consulted to obtain a server context if one is not already associated with the current thread via the ServerContext.doWithServerContext method.

The context information available from a given element of the collection is determined by that element's type. Examples of types that a given element might implement include:

• ClientHost
• ClientSubject
• IntegrityEnforcement

A remote object does not itself set up a ServerContext, rather the Exporter implementation that dispatches incoming calls to its exported remote objects may establish one for each call that it services.

For supplying context information for remote method execution, the BasicJeriExporter implementation uses the method doWithServerContext and the JrmpExporter implementation uses the provider interface ServerContext.Spi. The IiopExporter implementation does not support the ServerContext API in supplying context information for incoming calls dispatched to its exported objects.

ExportPermission

The class ExportPermission defines runtime permissions associated with export-related operations. When invoking AbstractILFactory.getInvocationDispatcherMethods(java.rmi.Remote), the calling context must have been granted the permission ExportPermission("exportRemoteInterface.interfaceName") for each non-public remote interface the supplied remote object implements.

Since:

2.0

Version:

1.1