org.apache.river.start

Class NonActivatableServiceDescriptor

java.lang.Object

org.apache.river.start.NonActivatableServiceDescriptor

All Implemented Interfaces:

Serializable, ServiceDescriptor

Direct Known Subclasses:

SharedActivatableServiceDescriptor

public class NonActivatableServiceDescriptor
extends Object
implements ServiceDescriptor, Serializable

Class used to launch shared, non-activatable, in-process services. Clients construct this object with the details of the service to be launched, then call create(Configuration config) to launch the service in the invoking object's VM.

This class provides 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 VM, with each object maintaining distinct export codebase and security policy settings.

Services need to implement the following "non-activatable constructor":

<impl>(String[] args, LifeCycle lc)

where,

• args - are the service configuration arguments
• lc - is the hosting environment's LifeCycle reference.

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

1. if the service class implements ServiceProxyAccessor then return value of getServiceProxy will be used as the service proxy.
2. if the service class implements ProxyAccessor then the return value of getProxy will be used as the service proxy.
3. Otherwise null will be returned as the service proxy.

The following items are discussed below:

• Configuring NonActivatableServiceDescriptor
• Logging

Configuring NonActivatableServiceDescriptor

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

•	servicePreparer
	Type:	ProxyPreparer
	Default:	new BasicProxyPreparer()
	Description:	The default proxy preparer used to prepare the service proxy. This value should not be null. This entry is obtained during the invocation of create and is used to prepare the service proxy 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

This 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
SEVERE	for significant service creation problems
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	NonActivatableServiceDescriptor.Created Object returned by NonActivatableServiceDescriptor.create() method that returns the proxy and implementation references for the created service.

Field Summary

Fields

Modifier and Type	Field and Description
protected boolean	descCreated Flag indicating when create() has been called
protected Object	descCreatedLock Lock object for descCreated flag

Constructor Summary

Constructors

Constructor and Description
NonActivatableServiceDescriptor(String exportCodebase, String policy, String importCodebase, String implClassName, Configuration config, LifeCycle lifeCycle, ProxyPreparer preparer)
NonActivatableServiceDescriptor(String exportCodebase, String policy, String importCodebase, String implClassName, String[] serverConfigArgs) Convenience constructor.
NonActivatableServiceDescriptor(String exportCodebase, String policy, String importCodebase, String implClassName, String[] serverConfigArgs, LifeCycle lifeCycle) Convenience constructor.
NonActivatableServiceDescriptor(String exportCodebase, String policy, String importCodebase, String implClassName, String[] serverConfigArgs, LifeCycle lifeCycle, ProxyPreparer preparer) Main constructor.
NonActivatableServiceDescriptor(String exportCodebase, String policy, String importCodebase, String implClassName, String[] serverConfigArgs, ProxyPreparer preparer) Convenience constructor.

Method Summary

Modifier and Type	Method and Description
Object	create(Configuration config) Attempts to create a service instance based on the service description information provided via constructor parameters.
String	getExportCodebase() Codebase accessor method.
String	getImplClassName() Implementation class accessor method.
String	getImportCodebase() Classpath accessor method.
LifeCycle	getLifeCycle() LifeCycle accessor method.
String	getPolicy() Policy accessor method.
String[]	getServerConfigArgs() Service configuration arguments accessor method.
ProxyPreparer	getServicePreparer() ProxyPreparer accessor method.
void	setLifeCycle(LifeCycle lc) Sets the LifeCycle object for this descriptor.
void	setServicePreparer(ProxyPreparer serviceProxyPreparer) Sets the ProxyPreparer for this descriptor.
String	toString() Prints out a field summary

Methods inherited from class java.lang.Object

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

Field Detail

descCreated

protected transient boolean descCreated

Flag indicating when create() has been called

descCreatedLock

protected final Object descCreatedLock

Lock object for descCreated flag

Constructor Detail

NonActivatableServiceDescriptor

public NonActivatableServiceDescriptor(String exportCodebase,
                                       String policy,
                                       String importCodebase,
                                       String implClassName,
                                       String[] serverConfigArgs,
                                       LifeCycle lifeCycle,
                                       ProxyPreparer preparer)

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

serverConfigArgs - service configuration arguments. This parameter is passed as the String[] argument to the implementation's constructor.

lifeCycle - LifeCycle reference for hosting environment. This parameter is passed as the LifeCycle argument to the implementation's constructor. If this argument is null, then a default, no-op LifeCycle object will be assigned.

preparer - ProxyPreparer reference. This object will be used to prepare the service's proxy object, if any (see service proxy section for details). If this argument is null, then the default service preparer will be used.

NonActivatableServiceDescriptor

public NonActivatableServiceDescriptor(String exportCodebase,
                                       String policy,
                                       String importCodebase,
                                       String implClassName,
                                       Configuration config,
                                       LifeCycle lifeCycle,
                                       ProxyPreparer preparer)

NonActivatableServiceDescriptor

public NonActivatableServiceDescriptor(String exportCodebase,
                                       String policy,
                                       String importCodebase,
                                       String implClassName,
                                       String[] serverConfigArgs,
                                       LifeCycle lifeCycle)

Convenience constructor. Equivalent to calling this contructor with null for the preparer reference.

NonActivatableServiceDescriptor

public NonActivatableServiceDescriptor(String exportCodebase,
                                       String policy,
                                       String importCodebase,
                                       String implClassName,
                                       String[] serverConfigArgs)

Convenience constructor. Equivalent to calling this contructor with null for the lifeCycle and preparer references.

NonActivatableServiceDescriptor

public NonActivatableServiceDescriptor(String exportCodebase,
                                       String policy,
                                       String importCodebase,
                                       String implClassName,
                                       String[] serverConfigArgs,
                                       ProxyPreparer preparer)

Convenience constructor. Equivalent to calling this contructor with null for the lifeCycle reference.

Method Detail

getExportCodebase

public final String getExportCodebase()

Codebase accessor method.

Returns:

the export codebase string associated with this service descriptor.

getPolicy

public final String getPolicy()

Policy accessor method.

Returns:

the policy string associated with this service descriptor.

getImportCodebase

public final String getImportCodebase()

Classpath accessor method.

Returns:

the import codebase string associated with this service descriptor.

getImplClassName

public final String getImplClassName()

Implementation class accessor method.

Returns:

the implementation class string associated with this service descriptor.

getServerConfigArgs

public final String[] getServerConfigArgs()

Service configuration arguments accessor method.

Returns:

the service configuration arguments associated with this service descriptor.

getLifeCycle

public final LifeCycle getLifeCycle()

LifeCycle accessor method.

Returns:

the LifeCycle object associated with this service descriptor.

setLifeCycle

public final void setLifeCycle(LifeCycle lc)

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

Parameters:

lc - The LifeCycle object to be associated with this service descriptor.

Throws:

IllegalStateException - if called after create() is invoked

getServicePreparer

public final ProxyPreparer getServicePreparer()

ProxyPreparer accessor method.

Returns:

the ProxyPreparer object associated with this service descriptor.

setServicePreparer

public final void setServicePreparer(ProxyPreparer serviceProxyPreparer)

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

Parameters:

serviceProxyPreparer - The 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

Attempts to create a service instance based on the service description information provided via constructor parameters.

This method:

• installs an RMISecurityManager if no security manager is already in place
• installs an AggregatePolicyProvider as the VM-global policy object (upon the first invocation of this method)
• creates an ActivateWrapper.ExportClassLoader with the associated service's import codebase, export codebase and the current thread's context class loader as its arguments
• associates the newly created ExportClassLoader and the associated service's policy file with the AggregatePolicyProvider
• sets the newly created ExportClassLoader as the current thread's context class loader
• loads the service object's class and calls a constructor with the following signature:

  <impl>(String[], LifeCycle)

• obtains the service proxy by calling ServiceProxyAccessor.getServiceProxy() or ProxyAccessor.getProxy(), respectively, on the implementation instance. If neither interface is supported, the proxy reference is set to null
• resets the context class loader to the context classloader in effect when the method was called

Specified by:

create in interface ServiceDescriptor

Parameters:

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

Returns:

a Created instance with the service's proxy and implementation references.

Throws:

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

toString

public String toString()

Prints out a field summary

Overrides:

toString in class Object