org.apache.river.start

Class ActivateWrapper

java.lang.Object

org.apache.river.start.ActivateWrapper

All Implemented Interfaces:

Serializable, Remote

public class ActivateWrapper
extends Object
implements Remote, Serializable

A wrapper for activatable objects, providing separation of the import codebase (where the server classes are loaded from by the activation group) from the export codebase (where clients should load classes from for stubs, etc.) as well as providing an independent security policy file for each activatable object. This functionality allows multiple activatable objects to be placed in the same activation group, with each object maintaining a distinct codebase and policy.

This wrapper class is assumed to be available directly in the activation group VM; that is, it is assumed to be in the application classloader, the extension classloader, or the boot classloader, rather than being downloaded. Since this class also needs considerable permissions, the easiest thing to do is to make it an installed extension.

This wrapper class performs a security check to control what policy files can be used with a given codebase. It does this by querying the VM's (global) policy for SharedActivationPolicyPermission grants. The service's associated ActivateDesc.importLocation is used as the CodeSource for selecting the appropriate permission set to check against. If multiple codebases are used, then all the codebases must have the necessary SharedActivationPolicyPermission grants.

An example of how to use this wrapper:

 URL[] importURLs = new URL[] {new URL("http://myhost:8080/service.jar")};
 URL[] exportURLs = new URL[] {new URL("http://myhost:8080/service-dl.jar")};
 ActivationID aid 
     = ActivateWrapper.register(
                gid,
                new ActivateWrapper.ActivateDesc(
                        "foo.bar.ServiceImpl",
                        importURLs,
                        exportURLs,
                        "http://myhost:8080/service.policy",
                        new MarshalledObject(
                          new String[] { "/tmp/service.config" })
              ),
                true,
              activationSystem);
 

Clients of this wrapper service need to implement the following "activation constructor":

 <impl>(ActivationID activationID, MarshalledObject data)
 

where,

• activationID - is the object's activation identifier
• data - is the object's activation data

Clients of this wrapper service can also implement ProxyAccessor, which allows the service implementation to provide a remote reference of its choosing.

This implementation of ActivateWrapper supports the following Security property:

•	org.apache.river.start.servicePolicyProvider
	Default:	"net.jini.security.policy.DynamicPolicyProvider"
	Description:	The fully qualified class name of a dynamic policy provider (see DynamicPolicy) which will be used to "wrap" all service policy files. The implementation class needs to: implement the following constructor: public <impl>(Policy servicePolicy) where, servicePolicy - is the service policy object to be wrapped implement DynamicPolicy be a public, non-interface, non-abstract class A custom service policy provider can be very useful when trying to debug security related issues. org.apache.river.tool.DebugDynamicPolicyProvider is an example policy provider that provides this functionality and can be located via the following URL: http://starterkit-examples.jini.org/ Note:The custom policy implementation is assumed to be available from the system classloader of the virtual machine hosting the service. Its codebase should also be granted AllPermission.

Author:

Sun Microsystems, Inc.

See Also:

SharedActivationPolicyPermission, ActivationID, MarshalledObject, Remote, CodeSource, ProxyAccessor, Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	ActivateWrapper.ActivateDesc Descriptor for registering a "wrapped" activatable object.

Constructor Summary

Constructors

Constructor and Description
ActivateWrapper(ActivationID id, MarshalledObject data) Activatable constructor.

Method Summary

Modifier and Type	Method and Description
static ActivationID	register(ActivationGroupID gid, ActivateWrapper.ActivateDesc desc, boolean restart, ActivationSystem sys) Analog to Activatable.register() for activatable objects that want to use this wrapper mechanism.

Methods inherited from class java.lang.Object

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

Constructor Detail

ActivateWrapper

public ActivateWrapper(ActivationID id,
                       MarshalledObject data)
                throws Exception

Activatable constructor. This constructor:

• Retrieves an ActivateDesc from the provided data parameter.
• creates an ExportClassLoader using the import and export codebases obtained from the provided ActivateDesc,
• checks the import codebase(s) for the required SharedActivationPolicyPermission
• associates the newly created ExportClassLoader and the corresponding policy file obtained from the ActivateDesc with the AggregatePolicyProvider
• loads the "wrapped" activatable object's class and calls its activation constructor with the context classloader set to the newly created ExportClassLoader.
• resets the context class loader to the original context classloader

The first instance of this class will also replace the VM's existing Policy object, if any, with a AggregatePolicyProvider.

Parameters:

id - The ActivationID of this object

data - The activation data for this object

Throws:

Exception

See Also:

ActivateWrapper.ExportClassLoader, ActivateWrapper.ActivateDesc, AggregatePolicyProvider, SharedActivationPolicyPermission, Policy

Method Detail

register

public static ActivationID register(ActivationGroupID gid,
                                    ActivateWrapper.ActivateDesc desc,
                                    boolean restart,
                                    ActivationSystem sys)
                             throws ActivationException,
                                    RemoteException

Analog to Activatable.register() for activatable objects that want to use this wrapper mechanism.

Returns:

activation ID of the registered service

Throws:

ActivationException - if there was a problem registering the activatable class with the activation system

RemoteException - if there was a problem communicating with the activation system