com.sun.jini.start
Class ActivateWrapper

java.lang.Object
  extended by 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, 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
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
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
ActivateWrapper(ActivationID id, MarshalledObject data)
          Activatable constructor.
 
Method Summary
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: 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


Copyright 2007-2010, multiple authors.
Licensed under the Apache License, Version 2.0, see the NOTICE file for attributions.