Rio Project 4.2 API Documentation

Package org.rioproject.boot

Provides utilities to bootstrap and initialize the Rio operational environment.

See:
Description

Class Summary

ActivateWrapper	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.
ActivateWrapper.ActivateDesc	Descriptor for registering a "wrapped" activatable object.
BootUtil	Provides static convenience methods for use in configuration files.
ClassAnnotator	Provides support to annotate classes required for dynamic class loading in RMI
CommonClassLoader	The CommonClassLoader implements ComponentLoader interface and is created by the RioServiceDescriptor or RioActivatableServiceDescriptor when starting a Rio service and contains common declared platform JARs to be made available to its children.
InstrumentationHook	Allows the instrumentation class to be accessed
MulticastStatus	Class which can be used to determine whether multicast is available.
PlatformLoader	Parses platform configuration documents
RioActivatableServiceDescriptor	Class used to launch shared, activatable services.
RioActivatableServiceDescriptor.Created	Object returned by RioActivatableServiceDescriptor.create() method that returns the proxy, group identifier, and activation identifier for the created service.
RioServiceDescriptor	The RioServiceDescriptor class is a utility that conforms to the Jini™ technology ServiceStarter framework, and will start a service using the CommonClassLoader as a shared, non-activatable, in-process service.
RioServiceDescriptor.Created	Object returned by RioServiceDescriptor.create() method that returns the proxy and implementation references for the created service.
ServiceClassLoader	The ServiceClassLoader overrides getURLs(), ensuring all classes that need to be annotated with specific location(s) are returned appropriately
ServiceDescriptorUtil	Holds static attributes used during the startup of services and provides utilities to obtain ServiceDescriptor instances for Rio services
ServiceStarter	This class provides the main routine for starting shared groups, non-activatable services, and activatable services.
ServiceStarter.ServiceReference	Object returned by ServiceStarter.start(java.lang.String...)

Package org.rioproject.boot Description

Provides utilities to bootstrap and initialize the Rio operational environment. Rio uses the Jini™ Technology Configuration approach to define the platform and components to create and initialize. This package document persents the following information:

• Understanding the classpath
• Configuring Boot Attributes

Classpath
When Rio starts, the classpath is set the to the following: boot.jar (which has a Class-Path manifest entry to start.jar) and start.jar (which has a Class-Path manifest entry to jsk-platform.jar). The remaining jars are dynamically loaded by the CommonClassLoader based on the platform configuration. The default platform configuration is loaded as a resource fro boot.jar (META-INF/platform.xml) declares the following:

JARs	Location Loaded From	Description
rio.jar	${RIO_HOME}/lib	Rio core technology platform classes
platform-capabilities.jar	${RIO_HOME}/lib	Platform capability classes
jsk-lib.jar	${JINI_LIB}	The Jini 2.1 technology required platform classes. More information on Jini technology can be found here

Additional jars can be added to the platform by working with the Platform configuration. Platform configuration files are used as follows:

• Provides attributes for creating PlatformCapability classes and declaring what jars will be common across all service classloaders. If jars are common they are loaded by the CommonClassLoader, and are in the classpath of all child class loaders. By default Rio and Jini technology jars are commonacross all service classloaders.
• For platform capabilities that are not loaded by the common classloader, services that declare that dependency will have the capability loaded by the service's classloader.
• Provides a manifest of the platform jars that can be loaded.

Platform configuration files are loaded when Rio starts. The contents of the org.rioproject.boot.platformDir directory will be scanned at startup time. Each .xml file will be parsed for <platform> declarations.

It is important to understand the class loader hierarchy. The approach is to enable a platform oriented framework conducive towards creating a layered product. The resulting capabilities allow the declaration of JARs that are added to a CommonClassLoader, making the classes accessible by all ClassLoader instances that delegate to the CommonClassLoader. In this fashion a platform can be declared, initialized and made available.

The ClassLoader hierarchy when starting Rio is as follows:

                  AppCL
                    |
            CommonClassLoader (http:// URLs of common JARs)
                    +
                    |
                    +
            +-------+-------+----...---+
            |               |          |
        Service-1CL   Service-2CL  Service-nCL
        

AppCL - Contains the main() class of the container. Main-Class in manifest points to com.sun.jini.start.ServiceStarter
Classpath: boot.jar, start.jar, jsk-platform.jar
Codebase: none

CommonClassLoader - Contains the common Rio and Jini technology classes (and other declared common platform JARs) to be made available to its children.
Classpath: Common JARs such as rio.jar
Codebase: Context dependent. The codebase returned is the codebase of the specific child CL that is the current context of the request.

Service-nCL - Contains the service specific implementation classes.
Classpath: serviceImpl.jar
Codebase: "serviceX-dl.jar rio-dl.jar jsk-lib-dl.jar"


Configuring Boot Attributes
The Rio boot environment supports the following configuration entries; where each configuration entry name is associated with the component name org.rioproject.boot

• platformDir

  Type:	String
  Default:	${RIO_HOME}${/}config${/}platform
  Description:	The platformDir property is scanned at system startup time. For each file ending in .xml, the file is parsed for Platform Configuration declarations. The platform element contains capability declarations that document the qualitative capabilities a compute resource will advertise and make available for services to use.

• createShutdownHook
  

  Type:	Boolean
  Default:	true
  Description:	Creates a shutdown hook. This will result in the registration of a virtual-machine shutdown hook. The shutdown hook will provide an orderly shutdown of all ServiceBean instances the Cybernode has instantiated by calling the ServiceBean's destroy method

• verifyMulticast

  Type:	Boolean
  Default:	false
  Description:	Determines if a Multicast socket can be created and a Request announcement can be sent. Note that it is still possible that multicast does not work outside the host

Default Platform Configuration
The 'platform' defines the support and technology that Rio core services (Cybernode & Provisioner) include as part of their environment. Configuring the platform involves working with the RIO_HOME/config/platform directory.

This directory contains platform configuration files. The Platform configuration file is used as follows:

• Provides attributes for creating PlatformCapability classes and declaring what jars will be common across all service classloaders. If jars are common they are loaded by the CommonClassLoader, and are in the classpath of all child class loaders. By default Rio and Jini technology jars are common across all service classloaders. For platform capabilities that are not loaded by the common classloader, services that declare that dependency will have the capability loaded by the service's classloader, providing a level of isolation from other services.
  
  
• Provides a manifest of the platform jars that can be loaded.

Platform configuration files are loaded when Rio starts. The contents of this directory will be scanned at startup time. Each .xml file will be parsed for <platform> declarations.

The default platform configuration is included in the boot.jar file and defines the core jars required for Rio. It's content is as follows:

<?xml version="1.0" encoding="UTF-8"?>
<!--
Default platform configuration
-->
<platform>
<!--
Rio jars to load into the common classloader.
-->
<capability name="Rio"
class="org.rioproject.system.capability.software.RioSupport"
common="yes">
<version>4.0 M2</version>
<classpath>${RIO_HOME}/lib/rio.jar</classpath>
</capability>

<!--
River (Jini) jars to load into the common classloader.
-->
<capability name="River" common="yes">
<version>2.1.1</version>
<manufacturer>Apache Software Foundation</manufacturer>
<classpath>${JINI_HOME}/lib/jsk-lib.jar</classpath>
</capability>

</platform>