net.jini.jeri

Class AbstractILFactory

java.lang.Object

net.jini.jeri.AbstractILFactory

All Implemented Interfaces:

InvocationLayerFactory

Direct Known Subclasses:

BasicILFactory

public abstract class AbstractILFactory
extends Object
implements InvocationLayerFactory

An abstract implementation of InvocationLayerFactory that provides a convenient way for subclasses to create proxies and invocation dispatchers for remote objects. A subclass must provide an implementation for at least the createInvocationHandler and createInvocationDispatcher methods. A subclass can override the getProxyInterfaces method if its proxies need to implement a different set of interfaces than the default set (all remote interfaces of the remote object).

Since:

2.0

Author:

Sun Microsystems, Inc.

Nested Class Summary

Nested classes/interfaces inherited from interface net.jini.jeri.InvocationLayerFactory

InvocationLayerFactory.Instances

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	AbstractILFactory() Constructs an AbstractILFactory instance with a null class loader.
protected	AbstractILFactory(ClassLoader loader) Constructs an AbstractILFactory instance with the specified class loader.

Method Summary

Methods

Modifier and Type	Method and Description
InvocationLayerFactory.Instances	createInstances(Remote impl, ObjectEndpoint oe, ServerCapabilities caps) Returns a compatible proxy and invocation dispatcher for a remote object being exported.
protected abstract InvocationDispatcher	createInvocationDispatcher(Collection methods, Remote impl, ServerCapabilities caps) Returns an invocation dispatcher to receive incoming remote calls for the specified methods to the specified remote object, for a server and transport with the specified capabilities.
protected abstract InvocationHandler	createInvocationHandler(Class[] interfaces, Remote impl, ObjectEndpoint oe) Returns an invocation handler to use with a Proxy instance implementing the specified interfaces, communicating with the specified remote object using the specified object endpoint.
boolean	equals(Object obj) Compares the specified object with this invocation layer factory for equality.
protected ClassLoader	getClassLoader() Returns the class loader specified during construction.
protected Class[]	getExtraProxyInterfaces(Remote impl) Returns a new array containing any additional interfaces that the proxy should implement, beyond the interfaces obtained by passing impl to the getRemoteInterfaces method.
protected Collection	getInvocationDispatcherMethods(Remote impl) Returns a new, modifiable collection of Method objects, containing all remote methods for which the invocation dispatcher should accept incoming remote calls.
protected Class[]	getProxyInterfaces(Remote impl) Returns a new array containing the interfaces for the proxy to implement.
protected Class[]	getRemoteInterfaces(Remote impl) Returns a new array containing the remote interfaces that should be implemented by the proxy.
int	hashCode() Returns a hash code value for this factory.
String	toString() Returns a string representation for this factory.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

AbstractILFactory

protected AbstractILFactory()

Constructs an AbstractILFactory instance with a null class loader.

AbstractILFactory

protected AbstractILFactory(ClassLoader loader)

Constructs an AbstractILFactory instance with the specified class loader. The createInstances method uses the specified loader to define a proxy class.

Parameters:

loader - the class loader, or null

Method Detail

getClassLoader

protected final ClassLoader getClassLoader()

Returns the class loader specified during construction.

Returns:

the class loader

getProxyInterfaces

protected Class[] getProxyInterfaces(Remote impl)
                              throws ExportException

Returns a new array containing the interfaces for the proxy to implement.

AbstractILFactory implements this method to return an array containing all of the interfaces obtained by passing impl to the getRemoteInterfaces method plus the interfaces obtained by calling the getExtraProxyInterfaces method, in that order, with duplicate interfaces (that is, duplicates after the first occurrence of an interface) eliminated.

A subclass can override this method if its proxies need to implement a different set of interfaces than the default.

Parameters:

impl - the remote object

Returns:

the proxy interfaces

Throws:

ExportException - if there is a problem obtaining the proxy interfaces or if impl does not satisfy the requirements of this factory

NullPointerException - if impl is null

getRemoteInterfaces

protected Class[] getRemoteInterfaces(Remote impl)
                               throws ExportException

Returns a new array containing the remote interfaces that should be implemented by the proxy. All of the methods of a remote interface are implemented as remote invocations, so all of the methods must declare RemoteException or one of its superclasses in their throws clauses.

AbstractILFactory implements this method to return an array containing the following ordered list of interfaces:

• for each superclass of impl's class starting with java.lang.Object and following with each direct subclass to the direct superclass of impl's class, all of the direct superinterfaces of the given superclass that extend Remote and that do not appear previously in the list, in declaration order (the order in which they are declared in the class's implements clause), followed by
• all of the direct superinterfaces of impl's class that extend Remote and that do not appear previously in the list, in declaration order.

and throws an ExportException if any method of those interfaces does not have a conforming throws clause.

A subclass can override this method if its proxies need a set of remote interfaces other than the default.

Parameters:

impl - the remote object

Returns:

the remote interfaces implemented by impl

Throws:

NullPointerException - if impl is null

ExportException - if there is a problem obtaining the remote interfaces or if impl does not satisfy the requirements of this factory

getExtraProxyInterfaces

protected Class[] getExtraProxyInterfaces(Remote impl)
                                   throws ExportException

Returns a new array containing any additional interfaces that the proxy should implement, beyond the interfaces obtained by passing impl to the getRemoteInterfaces method.

AbstractILFactory implements this method to return an array containing the RemoteMethodControl interface.

A subclass can override this method if its proxies need to implement a different set of extra interfaces than the default.

Parameters:

impl - the remote object

Returns:

the extra proxy interfaces

Throws:

NullPointerException - if impl is null

ExportException - if there is a problem obtaining the additional interfaces or if impl does not satisfy the requirements of this factory

getInvocationDispatcherMethods

protected Collection getInvocationDispatcherMethods(Remote impl)
                                             throws ExportException

Returns a new, modifiable collection of Method objects, containing all remote methods for which the invocation dispatcher should accept incoming remote calls.

AbstractILFactory implements this method to return a Set containing all of the methods of the interfaces obtained by passing impl to the getRemoteInterfaces method and satisfying the following requirements:

• No duplicate methods with the same signature and return type are contained in the set returned. If the interfaces contain more than one method with the same signature and return type, the method in the returned collection will be a member of the foremost of the interfaces that contains a method with that signature and return type.
• For each interface, if a security manager exists, its checkPackageAccess method is invoked with the package name of the interface; this invocation may throw a SecurityException.
• For each interface, if the interface is non-public and a security manager exists, the security manager's checkPermission method is invoked with the permission (@link ExportPermission} constructed with the string "exportRemoteInterface." concatenated with the fully qualified interface name; this invocation may throw a SecurityException. If the security check passes, each Method object of the non-public interface has its accessibility flag set to suppress language access checks.

A subclass can override this method if it needs to control the selection of the set of methods for the dispatcher to handle, or if it needs to control the implementation of the collection returned.

Parameters:

impl - the remote object

Returns:

the remote methods

Throws:

NullPointerException - if impl is null

ExportException - if there is a problem obtaining the remote methods or if impl does not satisfy the requirements of this factory

createInvocationHandler

protected abstract InvocationHandler createInvocationHandler(Class[] interfaces,
                                        Remote impl,
                                        ObjectEndpoint oe)
                                                      throws ExportException

Returns an invocation handler to use with a Proxy instance implementing the specified interfaces, communicating with the specified remote object using the specified object endpoint.

A subclass must override this method to create an InvocationHandler for the specified interfaces, remote object, and object endpoint.

Parameters:

interfaces - an array of proxy interfaces

impl - a remote object this invocation handler is being created for

oe - an object endpoint used to communicate with the remote object

Returns:

the invocation handler for the remote object's proxy

Throws:

ExportException - if there is a problem creating the invocation handler

NullPointerException - if any argument is null, or if interfaces contains a null element

createInvocationDispatcher

protected abstract InvocationDispatcher createInvocationDispatcher(Collection methods,
                                              Remote impl,
                                              ServerCapabilities caps)
                                                            throws ExportException

Returns an invocation dispatcher to receive incoming remote calls for the specified methods to the specified remote object, for a server and transport with the specified capabilities.

A subclass must override this method to create an InvocationDispatcher for the specified methods, remote object, and server capabilities.

Parameters:

methods - a collection of Method instances for the remote methods

impl - a remote object that the dispatcher is being created for

caps - the transport capabilities of the server

Returns:

the invocation dispatcher for the remote object

Throws:

ExportException - if there is a problem creating the dispatcher

IllegalArgumentException - if methods contains an element that is not a Method instance

NullPointerException - if any argument is null, or if methods contains a null element

createInstances

public InvocationLayerFactory.Instances createInstances(Remote impl,
                                               ObjectEndpoint oe,
                                               ServerCapabilities caps)
                                                 throws ExportException

Returns a compatible proxy and invocation dispatcher for a remote object being exported. The proxy and invocation dispatcher are returned in an InvocationLayerFactory.Instances container object. The proxy sends calls to the remote object using the supplied ObjectEndpoint.

The returned proxy implements an implementation-specific set of remote interfaces of impl and may implement additional implementation-specific interfaces.

A given Exporter implementation should only call this method once per export. An invocation dispatcher constructed for a previous export should not be reused.

AbstractILFactory implements this method to return a Proxy instance where:

• If the class loader specified during construction is not null, the proxy's class is defined by the specified loader. Otherwise, if a security manager exists, its checkPermission method is invoked with the RuntimePermission("getClassLoader") permission; this invocation may throw a SecurityException. If the above security check succeeds, the proxy's class is defined by the class loader of impl's class.
• The proxy implements the set of interfaces obtained by calling the getProxyInterfaces method, passing impl as the argument. If a security manager exists, for each interface returned from the getProxyInterfaces method, the security manager's checkPackageAccess method is invoked with the package name of the interface. Such an invocation may throw a SecurityException.
• The invocation handler of the proxy instance is obtained by calling the createInvocationHandler method, passing the proxy interfaces (as above), impl, and oe as arguments.

The returned invocation dispatcher is obtained by calling the createInvocationDispatcher method, passing a collection of methods, impl, and caps as arguments. The collection of methods is obtained by calling the getInvocationDispatcherMethods method, passing impl as the argument.

Specified by:

createInstances in interface InvocationLayerFactory

Parameters:

impl - the remote object that the proxy is being created for

oe - the object endpoint used to communicate with the remote object

caps - the transport capabilities of the server

Returns:

a proxy and invocation dispatcher contained in an Instances object

Throws:

NullPointerException - if any argument is null

ExportException - if there is a problem creating the proxy or dispatcher

hashCode

public int hashCode()

Returns a hash code value for this factory.

Overrides:

hashCode in class Object

equals

public boolean equals(Object obj)

Compares the specified object with this invocation layer factory for equality.

AbstractILFactory implements this method to return true if and only if the specified object has the same class as this object and the loader in the specified object is equal to the loader in this object.

A subclass should override this method if it adds instance state that affects equality.

Overrides:

equals in class Object

toString

public String toString()

Returns a string representation for this factory.

Overrides:

toString in class Object