Package com.gigaspaces.start

Provides bootstrapping support for the GigaSpaces Service Grid.

See:
Description

Class Summary

Locator	The Locator class derives the location of GigaSpaces Technologies system directories and provides various utilities for finding files and directories
SystemBoot	Provides bootstrapping support for the GigaSpaces Service Grid.
SystemConfig	Provides system configuration support.
SystemConfig.JMXServiceDescriptor	Initialize RMI Registry and JMX Platform MBeanServer

Package com.gigaspaces.start Description

Provides bootstrapping support for the GigaSpaces Service Grid. The GigaSpaces Service Grid uses the Jini^TM Technology Configuration approach augmented by using XML-based Configuration declarations as configuration overrides. This means that the default configuration attributes are loaded unless specific configuration file is provided, or specific XML-based configuration overrides are used. The GigaSpaces Service Grid startup loads all configuration entries with the component name of com.gigaspaces.start

Directory Structure Derivation
As previously explained, the Service Grid derives the runtime product directory structure at system initialization time. This approach is based on simple well-known and expected patterns. The intent is to remove additional configuration burdens made visible by environment setup constructs, and provide a simplified and effective product experience.

The Locator class will derive the location of the following values and return a Properties object to the calling class containing the following name/value pairs:

Key	Description
com.gs.home	Root directory of the EE, the canonical path of the parent directory of the sub-directory where JSpaces.jar is located
com.gigaspaces.lib	Directory where JSpaces.jar is located
com.gigaspaces.grid.home	Root directory of the Service Grid, the canonical path of the parent directory of the sub-directory where gs-service.jar is located
com.gigaspaces.grid.lib	The directory where gs-service.jar is located in the product distribution
com.gigaspaces.grid.boot.lib	The directory where gs-boot.jar is located in the product distribution
com.gigaspaces.jini.lib	The directory where jsk-platform.jar is located in the product distribution

System Properties
Based on the derived directory structure, and minimal system information, the following system properties are set the SystemBoot class, as determined by invoking the SystemConfig.getSystemProperties() method:

Name	Value	Description
java.protocol.handler.pkgs	net.jini.url	Provides support for HTTPMD based URLs
com.gs.home	Derived from the Locator class
com.gs.localhost.name	InetAddress.getHostAddress()
com.gs.container.name	InetAddress.getHostName()
com.gs.jini_lus.groups	“gigaspaces-“+ PlatformVersion.V_NUM	The group name is the concatenation of the text “gigaspaces-“ with the version number of the current release. Note: this property will only be populated if the com.j_spaces.kernel.PlatformVersion can be loaded
com.gigaspaces.grid.groups	gs-grid	Can be overridden by setting the com.gigaspaces.grid.groups property
com.gigaspaces.grid.home	Derived from the Locator class
com.gigaspaces.lib	Derived from the Locator class
com.gigaspaces.grid.lib	Derived from the Locator class

Once the system initializes, the following properties are additionally added to the system :

Name	Description
com.gigaspaces.system.codeserver	Indicates the address and port of the Webster instance created by this utility, in the form of : http://address:port
com.gigaspaces.system.registryPort	System property set when this utility starts an RMI Registry. Refer to the registryPort and registryRetries properties for additional infomration on configuring RMI Registry
com.gigaspaces.system.jmxServiceURL	System property set when this utility binds the JMX PlatformMBeanServer to the RMI Registry

Classpath
When the Service Grid starts, the classpath is set the to the following: gs-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 configuration property com.gigaspaces.start.platformJARs. The default JARs are as follows:

JARs	Location Loaded From	Description
JSpaces.jar	${com.gigaspaces.lib}	GigaSpaces Technology platform
gs-space-framework.jar	${com.gigaspaces.grid.lib}	Service Grid platform support for GigaSpaces framework
gsc-capabilities.jar	${com.gigaspaces.grid.lib}	Service Grid platform policies
gs-lib.jar	${com.gigaspaces.grid.boot.lib}	Service Grid boot core
backport-util-concurrent.jar	${com.gigaspaces.lib}/common	This package is the backport of java.util.concurrent API, introduced in Java 5.0, to Java 1.4.
xalan.jar xerxesImpl.jar xml-apis.jar	${com.gigaspaces.lib}/xml	XML parsing and API support. All jars that are in this directory are loaded
jsk-lib.jar	${com.gigaspaces.jini.lib}	The Jini 2.1 technology required platform classes. More information on Jini technology can be found here
ant.jar ant-launcher.jar ant-commons-net.jar commons-net-1.4.0.jar jakarta-oro-2.0.8.jar	${com.gigaspaces.lib}/ant	Ant support. All jars that are in this directory are loaded. For more information on Ant go here.

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 the Service Grid is as follows:

AppCL
|
CommonCL (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.gigaspaces.start.SystemBoot
Classpath: gs-boot.jar, start.jar, jsk-platform.jar
Codebase: none

CommonClassLoader - Contains the common GigaSpaces (Service Grid) and Jini technology classes (and other declared common platform JARs) to be made available to its children.
Classpath: Common JARs such as gs-lib.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 gs-lib-dl-dl.jar jsk-lib-dl.jar"

Configuration
The Service Grid module additionally strives to simplify the configuration file requirements for the product. At this time all Jini technology service configuration files are located in one file called services.config, located in the config/services directory. There are no start-xxx.config files in the Service Grid distribution. All services that need to be created are considered service built-ins, and have their specific service starter com.sun.jini.start.ServiceDescriptor classes loaded from the product based on derived product directory locations.

The approach towards configuration attribute modification being taken is discourage the direct modification of the services.config file. Configuration property changes are accomplished instead by using configuration overrides.

A configuration override is accomplished either by specifying the property=value on the command line when starting the Service Grid, or by creating an XML document which includes the configuration properties being override, The declared values will be used to override the properties declared in services.config, or used to override default attribute in the specific (sub-)component. All software components which use the Jini technology configuration mechanism can be modified using this technique. A simple example follows:

<override>
<component Name="com.gigaspaces.start">
<parameter Name="httpPort" Value="9010"/>
<parameter Name="systemProperties">
<![CDATA[
new String[] { "com.gs.protocol", "RMI" }
]]>
</parameter>
</component>
<component Name="com.gigaspaces.grid">
<parameter Name="groups">
<![CDATA[
new String[] { "use-custom-group" }
]]>
</parameter>
</component>
</override>

There are three overrides in this example:

1. com.gigaspaces.start.httpPort will indicate to SystemConfig to use 9010 as the port number to start the Webster instance
2. com.gigaspaces.start.systemProperty will be used to add the com.gs.protocol=RMI as a system property
3. com.gigaspaces.grid.groups declares the group name of "use-custom-group should override the default gs-grid group name

Configuration Properties
The Service Grid supports the following configuration entries; where each configuration entry name is associated with the component names com.gigaspaces.start and com.gigaspaces.grid

• Configuration entries specific to com.gigaspaces.start
• Configuration entries specific to com.gigaspaces.grid


Configuration entries specific to com.gigaspaces.start
The Service Grid com.gigaspaces.start package supports the following configuration entries; where each configuration entry name is associated with the component name com.gigaspaces.start. The following configuration entries provide the opportunity to declaratively modify the operational behavior of the Service Grid

• addHttpRoots

  Type:	String
  Default:	null
  Description:	This entry will be read at initialization and provides the ability to add HTTP roots to the HTTP server that is started by the SystemConfig utility

• addPlatformJARs

  Type:	URL[]
  Default:	null
  Description:	This entry will be read at initialization and provides the ability to add jars to load into the platform. This allows administrators the flexibility to use the default platform jars and just add to it, instead of redefining the entire stack SystemConfig utility

• gsConfig

  Type:	String
  Default:	${com.gigaspaces.grid.home}${/}config${/}services${/}services.config
  Description:	This entry will be read at initialization and provides support to declare a GigaSpaces service configuration file to be used to run the GigaSpace

• gscConfig

  Type:	String
  Default:	${com.gigaspaces.grid.home}${/}config${/}services${/}services.config
  Description:	This entry will be read at initialization and provides support to declare a Grid Service Container (GSC) service configuration file to be used to run the GSC

• gsmConfig

  Type:	String
  Default:	${com.gigaspaces.grid.home}${/}config${/}services${/}services.config
  Description:	This entry will be read at initialization and provides support to declare a Grid Service Monitor (GSM) service configuration file to be used to run the GSM

• gsc.classpath

  Type:	String
  Default:	${com.gigaspaces.grid.lib}${/}gs-service.jar
  Description:	This entry will be read at initialization and provides support to declare a space delimited String of jars that will compose the Grid Service Container's (GSC's) classpath

• gsm.classpath

  Type:	String
  Default:	${com.gigaspaces.grid.lib}${/}gs-service.jar
  Description:	This entry will be read at initialization and provides support to declare a space delimited String of jars that will compose the Grid Service Monitor's (GSM's) classpath

• hostAddress

  Type:	String
  Default:	If the java.rmi.server.hostname property is set, use this as the default, otherwise use the value returned by InetAddress.getLocalHost()
  Description:	This entry will be read at initialization and sets the host address to use for the HTTP server instance as well as the host address to use when constructing the platform MBeanServer

• httpPort

  Type:	int
  Default:	0
  Description:	This entry will be read at initialization and provides the ability to configure the port the HTTP server uses to accept inbound requests. The default port of 0 results in an anonymous port being used.

• httpRoots

  Type:	String
  Default:	${com.gigaspaces.lib};${com.gigaspaces.grid.lib}; ${com.gigaspaces.jini.lib};${com.gigaspaces.lib}/common;${com.gigaspaces.grid.home}/deploy
  Description:	This entry will be read at initialization and provides the ability to set HTTP roots to the HTTP server that is started by the SystemConfig utility

• httpServerRetries

  Type:	int
  Default:	10
  Description:	This entry will be read at initialization and provides the ability to recover from HTTP server creation failure by incrementing the port the HTTP server instance will accept requests on. The port provided by the httpPort property is used as a basis to increment from. If retries are needed, the httpPort is incremented by one each time until either the HTTP server is created without exceptions, or the http server retries have been exhausted

• platformJARs

  Type:	URL[]
  Default:	BootUtil.toURLs(java.lang.String[])( "${com.gigaspaces.lib}/JSpaces.jar", "${com.gigaspaces.grid.lib}/gsc-capabilities.jar", "${com.gigaspaces.grid.boot.lib}/gs-lib.jar", "${com.gigaspaces.lib}/common/backport-util-concurrent.jar", "${com.gigaspaces.lib}/xml", "${com.gigaspaces.jini.lib}/jsk-lib.jar", "${com.gigaspaces.lib}/ant"};
  Description:	This entry will be read at initialization and dynamically adds jars to the CommonClassLoader (refer to the discussion on classloading for details)

• reggieConfig

  Type:	String
  Default:	${com.gigaspaces.grid.home}${/}config${/}services${/}services.config
  Description:	This entry will be read at initialization and provides support to declare a Jini technology configuration file to be used to run the Jini technology Lookup service (reggie)

• registryPort

  Type:	int
  Default:	10098
  Description:	The port to use when creating the RMI Registry. This entry will be read at initialization, and based on the value provided by the registryRetries property, will be incremented

• registryRetries

  Type:	int
  Default:	10
  Description:	This entry will be read at initialization and provides the ability to recover from RMI Registry creation failure by incrementing the port the RMI Registry instance will accept requests on. The port provided by the registryPort property is used as a basis to increment from. If retries are needed, the registryPort is incremented by one each time until either the RMI Registry is created without exceptions, or the registry retries have been exhausted

• services

  Type:
  

  String
  

  Default:
  

  "GSC"
  

  Description:
  

  A comma delimited string of identifiers which provide context as to which services are to be started by the Service Grid. This entry will be read at initialization. The possible options here are as follows :
  
  

  LH	Triggers the start of the Lookup Handler
  GSC	Triggers the start of the Grid Service Container
  GSM	Triggers the start of the Grid Service Monitor
  GS	Triggers the start of the GigaSpace
  NO_HTTP	Indicates that an HTTP server should not be started
  NO_JMX	Indicates that the JMX MBeanServer (and required infrastructure such as the RMI Registry) should not be started

  
  Note: An autonomous lookup service and a HTTP server are by default started by the Service Grid
  

• systemProperties

  Type:	String[]
  Default:	new String[] { "java.protocol.handler.pkgs", "net.jini.url", "com.gs.home", Locator.GS_HOME, "com.gs.localhost.name", BootUtil.getHostAddress(), "com.gs.container.name", BootUtil.getHostName(), "com.gs.jini_lus.groups", "gigaspaces-"+PlatformVersion.V_NUM, "com.gigaspaces.grid.groups", groups, "com.gigaspaces.grid.home", com.gigaspaces.start.Locator#GS_GRID_HOME};
  Description:	This entry will be read at initialization and provides the ability to add system properties to the runtime. The following example override approach shows how the the com.gs.jini_lus.groups can be overriden and a new propety added: <overrides> <component Name="com.gigaspaces.start"> <parameter Name="systemProperties"> <![CDATA[ new String[] { "com.gs.jini_lus.groups", "custom", "new.property", "some.value"} ]]> </parameter> </component> </overrides>

Configuration entries specific to com.gigaspaces.grid
The Service Grid com.gigaspaces.grid package supports the following configuration entries; where each configuration entry name is associated with the component name com.gigaspaces.grid. The following configuration entries provide the opportunity to declaratively modify the operational behavior of the Service Grid

• groups

  Type:	String[]
  Default:	new String[] {"gs-grid"}
  Description:	This entry will be read at initialization and configures the discovery groups the Service Grid will use to federate itself. This group should not be confused with application focused groups, and is used for GSCs to discover GSMs. This property is also read by the LookupHandler utility