org.apache.river.start

Class SharedActivatableServiceDescriptor

java.lang.Object

org.apache.river.start.NonActivatableServiceDescriptor

org.apache.river.start.SharedActivatableServiceDescriptor

All Implemented Interfaces:

Serializable, ServiceDescriptor

public class SharedActivatableServiceDescriptor
extends NonActivatableServiceDescriptor

Class used to launch shared, activatable services. Clients construct this object with the details of the service to be launched, then call create(Configuration config) to launch the service in an existing shared activation group identified by the sharedGroupLog constructor parameter.

This class depends on ActivateWrapper to provide separation of the import codebase (where the service implementation classes are loaded from) from the export codebase (where service clients should load classes from, for example stubs) as well as providing an independent security policy file for each service object. This functionality allows multiple service objects to be placed in the same activation system group, with each object maintaining distinct export codebase and security policy settings.

Services need to implement the "activatable" constructor required by ActivateWrapper.

A service implementation can return its service proxy (via the proxy field of the Created object returned by create) in the following ways:

Return Inner Proxy

The service's inner proxy is the Remote object returned from ActivationID.activate(boolean) using ActivateWrapper to "wrap" and register the desired service with the activation system. A "wrapped" service's inner proxy is returned as follows:

• If the newly created service instance implements ProxyAccessor, a proxy is obtained by invoking the getProxy method on that instance. If the obtained proxy is not null, that proxy is returned in a MarshalledObject; otherwise, an InvalidObjectException is thrown.
• If the newly created instance does not implement ProxyAccessor, the instance is returned in a MarshalledObject. In this case, the instance must be serializable, and marshalling the instance must produce a suitable proxy for the remote object (for example, the object implements Serializable and defines a writeReplace method that returns the object's proxy).

Return Outer Proxy

The service's outer proxy is the object returned from invoking ServiceProxyAccessor.getServiceProxy() on the service's inner proxy.

The following items are discussed below:

• Configuring SharedActivatableServiceDescriptor
• Logging

Configuring SharedActivatableServiceDescriptor

SharedActivatableServiceDescriptor depends on ActivateWrapper, which can itself be configured. See ActivateWrapper's configuration information for details.

This implementation obtains its configuration entries from the Configuration object passed into the create method. The following configuration entries use the component prefix "org.apache.river.start":

•	activationIdPreparer
	Type:	ProxyPreparer
	Default:	new BasicProxyPreparer()
	Description:	The proxy preparer for the service's activation ID. The value should not be null. This class calls the activate method on instances of ActivationID when they need to re/activate the service.

•	activationSystemPreparer
	Type:	ProxyPreparer
	Default:	new BasicProxyPreparer()
	Description:	The proxy preparer for the proxy for the activation system. The value should not be null. The service starter calls the unregisterObject method on the ActivationSystem when there is a problem creating a service.

•	servicePreparer
	Type:	ProxyPreparer
	Default:	new BasicProxyPreparer()
	Description:	The default proxy preparer used to prepare service proxies. This value should not be null. This entry is obtained during the invocation of create and is used, to prepare the inner and outer service proxies returned by the service implementation (see service proxy section for details). This entry is superseded by explicitly passing a ProxyPreparer to one of the constructors that accept a proxy preparer argument.

Loggers and Logging Levels

The implementation uses the Logger, named org.apache.river.start.service.starter. The following table describes the type of information logged as well as the levels of information logged.

org.apache.river.start.service.starter

Level	Description
FINER	for high level service operation tracing
FINEST	for low level service operation tracing

Since:

2.0

Author:

Sun Microsystems, Inc.

See Also:

Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	SharedActivatableServiceDescriptor.Created Object returned by SharedActivatableServiceDescriptor.create() method that returns the associated proxy, activation group identifier, and activation identifier for the created service.

Field Summary

Fields inherited from class org.apache.river.start.NonActivatableServiceDescriptor

descCreated, descCreatedLock

Constructor Summary

Constructors

Constructor and Description
SharedActivatableServiceDescriptor(AtomicSerial.GetArg arg)
SharedActivatableServiceDescriptor(String exportCodebase, String policy, String importCodebase, String implClassName, String sharedGroupLog, String[] serverConfigArgs, boolean restart) Convenience constructor.
SharedActivatableServiceDescriptor(String exportCodebase, String policy, String importCodebase, String implClassName, String sharedGroupLog, String[] serverConfigArgs, boolean restart, String host, int port) Convenience constructor.
SharedActivatableServiceDescriptor(String exportCodebase, String policy, String importCodebase, String implClassName, String sharedGroupLog, String[] serverConfigArgs, ProxyPreparer innerProxyPreparer, ProxyPreparer outerProxyPreparer, boolean restart) Convenience constructor.
SharedActivatableServiceDescriptor(String exportCodebase, String policy, String importCodebase, String implClassName, String sharedGroupLog, String[] serverConfigArgs, ProxyPreparer innerProxyPreparer, ProxyPreparer outerProxyPreparer, boolean restart, String host, int port) Main constructor.

Method Summary

Modifier and Type	Method and Description
Object	create(Configuration config) Method that attempts to create a service based on the service description information provided via constructor parameters.
String	getActivationSystemHost() Activation system host accessor method.
int	getActivationSystemPort() Activation system port accessor method.
ProxyPreparer	getInnerProxyPreparer() ProxyPreparer accessor method.
boolean	getRestart() Restart accessor method.
String	getSharedGroupLog() Shared group log accessor method.
void	setInnerProxyPreparer(ProxyPreparer pp) Sets the inner ProxyPreparer for this descriptor.
String	toString() Prints out a field summary

Methods inherited from class org.apache.river.start.NonActivatableServiceDescriptor

getExportCodebase, getImplClassName, getImportCodebase, getLifeCycle, getPolicy, getServerConfigArgs, getServicePreparer, setLifeCycle, setServicePreparer

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

SharedActivatableServiceDescriptor

public SharedActivatableServiceDescriptor(AtomicSerial.GetArg arg)
                                   throws IOException

Throws:

IOException

SharedActivatableServiceDescriptor

public SharedActivatableServiceDescriptor(String exportCodebase,
                                          String policy,
                                          String importCodebase,
                                          String implClassName,
                                          String sharedGroupLog,
                                          String[] serverConfigArgs,
                                          boolean restart)

Convenience constructor. Equivalent to calling this constructor with the innerProxyPreparer, outerProxyPreparer and host arguments set to null and the port argument set to the currently configured activation system port. The activation system port defaults to ActivationSystem.SYSTEM_PORT unless it is overridden by the java.rmi.activation.port system property.

SharedActivatableServiceDescriptor

public SharedActivatableServiceDescriptor(String exportCodebase,
                                          String policy,
                                          String importCodebase,
                                          String implClassName,
                                          String sharedGroupLog,
                                          String[] serverConfigArgs,
                                          ProxyPreparer innerProxyPreparer,
                                          ProxyPreparer outerProxyPreparer,
                                          boolean restart)

Convenience constructor. Equivalent to calling this constructor with the host argument set to null and the port argument set to the currently configured activation system port. The activation system port defaults to ActivationSystem.SYSTEM_PORT unless it is overridden by the java.rmi.activation.port system property.

SharedActivatableServiceDescriptor

public SharedActivatableServiceDescriptor(String exportCodebase,
                                          String policy,
                                          String importCodebase,
                                          String implClassName,
                                          String sharedGroupLog,
                                          String[] serverConfigArgs,
                                          boolean restart,
                                          String host,
                                          int port)

Convenience constructor. Equivalent to calling this constructor with the innerProxyPreparer and outerProxyPreparer arguments set to null.

SharedActivatableServiceDescriptor

public SharedActivatableServiceDescriptor(String exportCodebase,
                                          String policy,
                                          String importCodebase,
                                          String implClassName,
                                          String sharedGroupLog,
                                          String[] serverConfigArgs,
                                          ProxyPreparer innerProxyPreparer,
                                          ProxyPreparer outerProxyPreparer,
                                          boolean restart,
                                          String host,
                                          int port)

Main constructor. Simply assigns given parameters to their associated, internal fields unless otherwise noted.

Parameters:

exportCodebase - location where clients can download required service-related classes (for example, stubs, proxies, etc.). Codebase components must be separated by spaces in which each component is in URL format.

policy - server policy filename or URL

importCodebase - location where server implementation classes can be found. This String assumed (in order) to be either 1) a space delimited set of URL(s) representing a codebase or 2) a File.pathSeparator delimited set of class paths.

implClassName - name of server implementation class

sharedGroupLog - location where the associated shared group identifier information is persisted

serverConfigArgs - service configuration arguments

innerProxyPreparer - ProxyPreparer reference. This object will be used to prepare the service's inner proxy. If the inner proxy implements ServiceProxyAccessor it will then be used to invoke ServiceProxyAccessor.getServiceProxy() in order to get the service's outer proxy.

outerProxyPreparer - ProxyPreparer reference. This object will be used to prepare the service's outer proxy before it is returned to the caller of create(net.jini.config.Configuration).

restart - boolean flag passed through as the restart parameter to the ActivationDesc constructor used to register the service with the activation system.

host - hostname of desired activation system. If null, defaults to the localhost.

port - port of desired activation system. If value is <= 0, then defaults to ActivationSystem.SYSTEM_PORT.

Method Detail

getSharedGroupLog

public final String getSharedGroupLog()

Shared group log accessor method.

Returns:

the Shared group log associated with this service descriptor.

getRestart

public final boolean getRestart()

Restart accessor method.

Returns:

the restart mode associated with this service descriptor.

getActivationSystemHost

public final String getActivationSystemHost()

Activation system host accessor method.

Returns:

the activation system host associated with this service descriptor.

getActivationSystemPort

public final int getActivationSystemPort()

Activation system port accessor method.

Returns:

the activation system port associated with this service descriptor.

getInnerProxyPreparer

public final ProxyPreparer getInnerProxyPreparer()

ProxyPreparer accessor method.

Returns:

the inner proxy preparer associated with this service descriptor.

setInnerProxyPreparer

public final void setInnerProxyPreparer(ProxyPreparer pp)

Sets the inner ProxyPreparer for this descriptor. This needs to be called on the service descriptor prior to calling create(). Useful for (re-)setting the the associated inner ProxyPreparer upon deserialization of the descriptor.

Parameters:

pp - The inner ProxyPreparer object to be associated with this service descriptor.

Throws:

IllegalStateException - if called after create() is invoked

create

public Object create(Configuration config)
              throws Exception

Method that attempts to create a service based on the service description information provided via constructor parameters.

This method:

• creates an ActivateWrapper.ActivateDesc with the provided constructor parameter information for the desired service
• retrieves the group identifier associated with the provided shared group log.
• invokes ActivateWrapper.register() with the provided information.
• obtains an inner proxy by calling activate(true) on the object returned from ActivateWrapper.register(), which also activates the service instance.
• obtains the service proxy in the following order of precedence:
  • if the inner proxy implements ServiceProxyAccessor then the return value of getServiceProxy is used
  • if the inner proxy is not null then it is used
  • Otherwise, null is used

Specified by:

create in interface ServiceDescriptor

Overrides:

create in class NonActivatableServiceDescriptor

Parameters:

config - The Configuration object used to configure the creation of the returned object.

Returns:

a Created object that contains the group identifier, activation ID, and proxy associated with the newly created service instance.

Throws:

Exception - Thrown if there was any problem creating the object.

toString

public String toString()

Description copied from class: NonActivatableServiceDescriptor

Prints out a field summary

Overrides:

toString in class NonActivatableServiceDescriptor