com.sun.jini.start

Class ActivateWrapper

java.lang.Object

com.sun.jini.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:

•	com.sun.jini.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. com.sun.jini.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.
(package private) static class	ActivateWrapper.ExportClassLoader A simple subclass of PreferredClassLoader that overrides getURLs to return the URLs of the provided export codebase.

Field Summary

Fields

Modifier and Type	Field and Description
private static Class[]	actTypes The parameter types for the "activation constructor".
private static AggregatePolicyProvider	globalPolicy The Policy object that aggregates the individual service policy objects.
private Object	impl The "wrapped" activatable object.
private static Policy	initialGlobalPolicy The Policy object in effect at startup.
(package private) static Logger	logger Configure logger
private static Class[]	policyTypes The parameter types for the "custom, service policy constructor".
private static String	servicePolicyProvider Fully qualified name of custom, service policy provider

Constructor Summary

Constructors

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

Method Summary

Methods

Modifier and Type	Method and Description
private static void	checkPolicyPermission(String policy, URL[] urls) Checks that all the provided URLs have permission to use the given policy.
(package private) static Policy	getServicePolicyProvider(Policy service_policy)
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.
private static String	urlsToPath(URL[] urls) Utility method that converts a URL[] into a corresponding, space-separated string with the same array elements.
private Object	writeReplace() Return a reference to service being wrapped in place of this object.

Methods inherited from class java.lang.Object

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

Field Detail

logger

static final Logger logger

Configure logger

globalPolicy

private static AggregatePolicyProvider globalPolicy

The Policy object that aggregates the individual service policy objects.

initialGlobalPolicy

private static Policy initialGlobalPolicy

The Policy object in effect at startup.

impl

private Object impl

The "wrapped" activatable object.

actTypes

private static final Class[] actTypes

The parameter types for the "activation constructor".

servicePolicyProvider

private static String servicePolicyProvider

Fully qualified name of custom, service policy provider

policyTypes

private static final Class[] policyTypes

The parameter types for the "custom, service policy constructor".

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

writeReplace

private Object writeReplace()
                     throws ObjectStreamException

Return a reference to service being wrapped in place of this object.

Throws:

ObjectStreamException

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

checkPolicyPermission

private static void checkPolicyPermission(String policy,
                         URL[] urls)

Checks that all the provided URLs have permission to use the given policy.

urlsToPath

private static String urlsToPath(URL[] urls)

Utility method that converts a URL[] into a corresponding, space-separated string with the same array elements. Note that if the array has zero elements, the return value is null, not the empty string.

getServicePolicyProvider

static Policy getServicePolicyProvider(Policy service_policy)
                                throws Exception

Throws:

Exception