• Different Topologies
• Starting Grid
  • Using GridFactory
  • Using Loaders
    • Command Line Loader
    • GlassFish Loader
    • JBoss Loader
    • WebLogic Loader
    • WebSphere Loader
    • Servlet Loader
    • Memory Loader
• Configuring GridGain
• AOP Configuration
• External User Libraries
• GridGain Node as Linux or Windows Service
• Troubleshooting

Click on ^Javadoc link to open Javadoc documentation.

Different Topologies

Grid topology defines a collection of grid nodes with their respective physical location characteristics. GridGain support very rich set of grid topologies:

Starting Grid

Grid is configured via GridConfiguration ^Javadoc interface passed into GridFactory.start(GridConfiguration) method. GridConfiguration is a simple Java bean that can be configured either directly in code or via Spring IoC XML configuration (any other IoC container can be used as well) or any other IoC frameworks.

Using GridFactory

GridFactory ^Javadoc can be used directly to start, stop and access Grid ^Javadoc instances from Java code.

You can start grid without passing any configuration parameters by calling GridFactory.start() ^Javadoc method. In this case grid will start with default configuration which in most cases should be enough for development and testing. Default configuration parameters are described below.

If you need to change any of the configuration parameters, you can pass an instance of GridConfiguration ^Javadoc into GridFactory.start(GridConfiguration) ^Javadoc method. Note, that you only need to override those configuration parameters that are different from defaults. For convenience, you can use GridConfigurationAdapter ^Javadoc when creating custom configuration which acts as a bean.

Here is an example of starting grid with non-default configuration, which uses GridUriDeploymentSpi instead of default local deployment SPI.

GridConfigurationAdapter cfg = new GridConfigurationAdapter();

GridUriDeploymentSpi spi = new GridUriDeploymentSpi();

spi.setUriList(Collections.singltonList("file:///opt/gridgain/work/deployment/file/"));

cfg.setDeploymentSpi(spi);

GridFactory.start(cfg);

Multiple Grid Nodes in JVM You can to start multiple grid instances in the same Java VM process. Such functionality can come useful during testing, when it is desired to simulate multiples nodes during a single test. Note that you need to name different grid instances differently. See getGridName() method in GridConfiguration Javadoc .

Using Loaders

Grid loaders are used to start grid in different environments. Loaders provide basic boilerplate code for starting GridGain in various environments. For example, when starting within application servers such as JBoss, Weblogic or Websphere, provided loaders will configure GridGain to use "native" logging, JMX facility, discovery and execution services (JSR-237) which makes GridGain basically blend into hosting environment. Loaders do not need to implement any interface and their sole responsibility is to configure and start grid. Usually a loader is given a path of Spring configuration file which should be used for startup.

Here is an example of Spring 2.0 configuration that uses GridUriDeploymentSpi instead of default local deployment SPI.

<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:util="http://www.springframework.org/schema/util"
       xsi:schemaLocation="
        http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.0.xsd
        http://www.springframework.org/schema/util http://www.springframework.org/schema/util/spring-util-2.0.xsd">
    <description>Main Spring file for grid configuration.</description>

    <!--
        Grid conifiguration.
    -->
    <bean id="grid.cfg" class="org.gridgain.grid.GridConfigurationAdapter" scope="singleton">
        <property name="deploymentSpi">
            <bean class="org.gridgain.grid.spi.deployment.uri.GridUriDeploymentSpi">
                <property name="uriList">
                    <list>
                        <value>file:///opt/gridgain/work/deployment/file/</value>
                    </list>
                </property>
            </bean>
        </property>
    </bean>
</beans>

Command Line Loader

Command line loader located in org.gridgain.grid.loader.cmdline package.

Command line loader is used to start grid from a command line script. Grid comes with gridgain.[sh|bat] startup script located in ${GRIDGAIN_HOME}/bin folder. By default this script will use configuration defined in ${GRIDGAIN_HOME}/config/default-spring.xml. This configuration will pick default configuration for all grid internal components and SPI's which isbe sufficient for running examples and doing your own development and testing.

If you wish to provide your own configuration file, simply pass its path as parameter to the script.

gridgain.sh C:\myfolder\mygrid.xml

To stop grid, simply press CTRL-C which will initiate GridGain stop routine.

Script Startup Note that in addition to starting grid nodes on separate physical machines, GridGain supports starting multiple grid nodes on the same machine as well as in the same VM. The only requirement for default configuration is that IP-Multicast is supported.

Custom Jars Starting from 2.1.0 you can add your libraries to the class path without changing startup scripts. Just put them into the GRIDGAIN_HOME/libs/ext directory and GridGain will pick them up automatically.

GRIDGAIN_HOME Environment Variable If you get the following error: Exception in thread "main" java.lang.NoClassDefFoundError: org/gridgain/grid/loaders/cmdline/GridCommandLineLoader, then your GRIDGAIN_HOME environment variable is not set or is set incorrectly. Please set GRIDGAIN_HOME environment variable to your GridGain installation folder.

GlassFish Loader

GlassFish loader located in org.gridgain.grid.loaders.glassfish package.

GlassFish loader is used to start GridGain within GlassFish application server. GridGain loader implemented as GlassFish life-cycle listener module. GlassFish loader should be used to provide tight integration between GridGain and GlassFish AS. Current loader implementation works on both GlassFish v1 and GlassFish v2 servers.

The following steps should be taken to configure this loader:

1. Add GridGain libraries in GlassFish common loader.
   See GlassFish Class Loaders
2. Create life-cycle listener module.
   Use command line or administration GUI.
   asadmin> create-lifecycle-module --user admin --passwordfile ../adminpassword.txt --classname "org.gridgain.grid.loaders.glassfish.GridGlassfishLoader" --property cfgFilePath="config/default-spring.xml" GridGain

For more information consult GlassFish Project - Documentation Home Page

Note that GlassFish is not shipped with GridGain. If you don't have GlassFish, you need to download it separately. See https://glassfish.dev.java.net for more information.

JBoss Loader

JBoss loader located in org.gridgain.grid.loader.jboss package.

JBoss loader is used to start GridGain within JBoss as a JBoss service. Note that jboss-service.xml has a configuration parameter pointing to Spring XML configuration. At startup, JBoss loader will look for the Spring configuration XML file specified in jboss-service.xml.

GridGain ships with pre-built SAR directory. SAR directory located in [GRIDGAIN_HOME]/config/jboss folder. You can simply deploy GridGain into JBoss into 2 steps:

• Change the codebase in jboss-service.xml in META-INF sub-folder to point to correct location. See this file for instructions and examples.
• Copy entire SAR directory from [GRIDGAIN_HOME]/config/jboss folder to deploy directory of the JBoss.

Here is how [GRIDGAIN_HOME]/config/jboss/jboss-service.xml looks (note we use 1.5.0 version as an example):

<!DOCTYPE server PUBLIC "-//JBoss//DTD MBean Service 4.0//EN" "http://www.jboss.org/j2ee/dtd/jboss-service_4_0.dtd">

<!--
    JBoss service descriptor for GridGain JBoss Loader.

    Classpath should contain the following libraries:
    - $GRIDGAIN_HOME/libs/*.jar
    - $GRIDGAIN_HOME/gridgain_1.5.0.jar

    For example, if GridGain is installed into /opt/gridgain-1.5.0 then
    you can use the following classpath settings to includes all
    necessary JARs:

    <classpath codebase="/opt/gridgain-1.5.0/gridgain-1.5.0.jar"/>
    <classpath codebase="/opt/gridgain-1.5.0/libs" archives="*"/>
-->
<server>
    <classpath codebase=".." /> <!-- FIX IT BEFORE USING. -->

    <mbean code="org.gridgain.grid.loaders.jboss.GridJbossLoader" name="gridgain:service=loader">
        <!--
            config/default-spring.xml - Default GridGain configuration.
            config/jboss/ha/jboss-gridgain-ha-spring.xml - JBoss specific configuration that 
                will use JBoss SPIs for communication and discovery. Requires JBoss HA enabled.
        -->
        <attribute name="ConfigurationFile">config/default-spring.xml</attribute>
    </mbean>
</server>

JBoss HA Note that when using ha/jboss-spring.xml configuration file it requires JBoss configured with HA. JBoss 'default' and 'minimal' configuration are not set with HA support. Only 'all' JBoss configuration includes HA setup. Unless HA support is set GridGain will not start with ha/jboss-spring.xml configuration since it uses JBoss discovery SPI that's relying on HA. See this link for details on how to setup HA support in JBoss: http://www.jboss.org/wiki/Wiki.jsp?page=JBossHA

Click here (very big file) to see entire JBoss log running standard 'all' configuration with GridGain deployed. Use this for troubleshooting only.

WebLogic Loader

Weblogic loader located in org.gridgain.grid.loader.weblogic package.

Weblogic loader is used to start GridGain within Weblogic application server. GridGain loader for WebLogic implemented as a pair of start and shutdown classes. Please consult WebLogic documentation on how to configure startup classes in Weblogic. Weblogic loader is used for tight integration with Weblogic AS. Specifically, Weblogic loader integrates GridGain with Weblogic logging, MBean server, and work manager (JSR-237).

The following steps should be taken to configure startup and shutdown classes:

1. Add Startup and Shutdown Class in admin console (Environment -> Startup & Shutdown Classes -> New).
2. Add the following parameters for startup class:
   • Name: GridWeblogicStartup
   • Classname: org.gridgain.grid.loaders.weblogic.GridWeblogicStartup
   • Arguments: cfgFilePath=config/default-spring.xml
3. Add the following parameters for shutdown class:
   • Name: GridWeblogicShutdown
   • Classname: org.gridgain.grid.loaders.weblogic.GridWeblogicShutdown

• Change classpath for WebLogic server in startup script: CLASSPATH="${CLASSPATH}:${GRIDGAIN_HOME}/gridgain.jar:${GRIDGAIN_HOME}/libs/"

For more information on Weblogic start/shutdown classes see http://edocs.bea.com/wls/docs100/ConsoleHelp/taskhelp/startup_shutdown/UseStartupAndShutdownClasses.html.

Note that Weblogic is not shipped with GridGain. If you don't have Weblogic, you need to download it separately. See http://www.bea.com more information.

WebSphere Loader

Websphere loader located in org.gridgain.grid.loader.websphere package.

Websphere loader is used to start GridGain within Websphere application server. This is GridGain loader implemented as Websphere custom service (MBean). Websphere loader should is used to provide tight integration between GridGain and Websphere AS. Specifically, Websphere loader integrates GridGain with Websphere logging, MBean server and work manager (JSR-237).

The following steps should be taken to configure this loader:

1. Add CustomService in admin console (Application Servers -> server1 -> Custom Services -> New).
2. Add custom property for this service: cfgFilePath=config/default-spring.xml.
3. Add the following parameters:
   • Classname: org.gridgain.grid.loaders.websphere.GridWebsphereLoader
   • Display Name: GridGain
   • Classpath (replace ${GRIDGAIN_HOME} with absolute path): "${GRIDGAIN_HOME}/gridgain.jar:${GRIDGAIN_HOME}/libs/". Note that forward slash (/) at the end is critical.

For more information consult http://publib.boulder.ibm.com/infocenter/wasinfo/v6r1/index.jsp?topic=/com.ibm.websphere.base.doc/info/aes/ae/trun_customservice.html

Note that Websphere is not shipped with GridGain. If you don't have Websphere, you need to download it separately. See http://www.ibm.com/software/websphere/ for more information.

Servlet Loader

Servlet loader located in org.gridgain.grid.loader.servlet package.

This loader can be used to startup GridGain grid inside any web container as servlet. Loader must be defined in web.xml file.

<servlet>
     <servlet-name>GridGain</servlet-name>
     <servlet-class>org.gridgain.grid.loaders.servlet.GridServletLoader</servlet-class>
     <init-param>
         <param-name>cfgFilePath</param-name>
         <param-value>config/default-spring.xml</param-value>
     </init-param>
     <load-on-startup>1</load-on-startup>
 </servlet>

Servlet-based loader may be used in any web container like Tomcat, Jetty and etc.
Depending on the way this loader is deployed the GridGain instance can be accessed by either all web applications or by only one. See web container class loading architecture:

1. http://tomcat.apache.org/tomcat-5.5-doc/class-loader-howto.html
2. http://docs.codehaus.org/display/JETTY/Classloading

Tomcat
There are two ways to start GridGain on Tomcat.

1. Add GridGain libraries in Tomcat common loader. Add in file ${TOMCAT_HOME}/conf/catalina.properties for property common.loader the following ${GRIDGAIN_HOME}/gridgain.jar,${GRIDGAIN_HOME}/libs/*.jar (replace ${GRIDGAIN_HOME} with absolute path).
2. GridGain servlet-based loader in ${TOMCAT_HOME}/conf/web.xml

   <servlet>
       <servlet-name>GridGain</servlet-name>
       <servlet-class>org.gridgain.grid.loaders.servlet.GridServletLoader</servlet-class>
       <init-param>
           <param-name>cfgFilePath</param-name>
           <param-value>config/default-spring.xml</param-value>
       </init-param>
       <load-on-startup>1</load-on-startup>
   </servlet>

GridGain started from WAR-file and GridGain instance is accessible only to that web application.
Difference with approach described above is that all libraries should be added in WAR file without changes in Tomcat configuration files.

Jetty
Below is Java code example with Jetty API:

Server service = new Server();
 
 service.addListener("localhost:8090");
 
 ServletHttpContext ctx = (ServletHttpContext)service.getContext("/");
 
 ServletHolder servlet = ctx.addServlet("GridGain", "/GridGainLoader",
      "org.gridgain.grid.loaders.servlet.GridServletLoader");
 
 servlet.setInitParameter("cfgFilePath", "config/default-spring.xml");
 
 servlet.setInitOrder(1);
 
 servlet.start();
 
 service.start();

Memory Loader

Memory loader located in org.gridgain.grid.loader.memory package.

This loader can be used to startup GridGain grid from within Java code virtually within any environment. User should simply invoke GridMemoryLoader.loadGridGain(String) ^Javadoc method and pass path to Spring XML configuration file as a parameter. This path can either be absolute, or relative to GRIDGAIN_HOME folder.

Configuring GridGain

For information about GridGain configuration properties refer to Grid Configuration documentation.

AOP Configuration

In order to use annotation based @Gridify ^Javadoc AOP-based grid-enabling the following AOP configuration needs to be in place depending on which AOP implementation you choose to use. Note that you only need to pick one AOP implementation.

JBoss AOP

Standalone application

Note that GridGain is not shipped with JBoss and doesn't include necessary JBoss libraries. We assume that if you choose to use JBoss AOP you would have these libraries anyways. The following configuration needs to be applied to enable JBoss byte code weaving:

• The following JVM configuration must be present (make sure to replace com.foo.bar with your domain package):
  • -javaagent:[path to jboss-aop-jdk50-4.x.x.jar]
  • -Djboss.aop.class.path=[path to gridgain.jar]
  • -Djboss.aop.exclude=org,com -Djboss.aop.include=com.foo.bar
• The following JARs should be in a classpath:
  • javassist-4.x.x.jar
  • jboss-aop-jdk50-4.x.x.jar
  • jboss-aspect-library-jdk50-4.x.x.jar
  • jboss-common-4.x.x.jar
  • trove-1.0.x.jar

JBoss AOP with JBoss AS

• Install JBoss AOP deployer.
  • Remove the jboss-aop-jdk50.deployer directory of "server/your_server_name/deploy" in your JBoss AS
  • Download the latest stable version of JBoss AOP (1.5.5 GA)
  • Unzip it and make sure that all directories were unzipped case-sensitive.
  • Copy the appropriate jboss-aop-jdk50.deployer directory from your JBoss AOP installation to your "server/your_server_name/deploy"
  • Edit jboss-aop-jdk50.deployer/jboss-service.xml, setting "EnableLoadTimeWeaving" with a true value, like follows:

    <attribute name="EnableLoadtimeWeaving">true</attribute>
    <attribute name="Exclude">java,javax,org,com,net,sun,oracle,EDU,antlr</attribute>
    <attribute name="Include">com.foo.bar</attribute>

    Make sure to replace com.foo.bar with your domain package. Also make sure to edit the exclude list if it does not have some packages that you would not like to weave.
  • Follow the instructions of the jboss-aop-jdk50.deployer/ReadMe.txt file
  • Copy pluggable-instrumentor.jar file (located in the lib-50 directory of your JBoss AOP installation) to the bin directory of your server
  • Edit your run.sh or run.bat to include -javaagent:pluggable-instrumentor.jar in the JAVA_OPTS
• Deploy Gridgain as SAR.
  • Copy gridgain.sar directory from ${GRIDGAIN_HOME}/config/jboss folder into your "server/your_server_name/deploy" folder.
  • Make sure to update classpath in gridgain.sar/META-INF/jboss-service.xml to point to all libs under ${GRIDGAIN_HOME} and ${GRIDGAIN_HOME}/libs.

AspectJ AOP

The following configuration needs to be applied to enable AspectJ byte code weaving.

• JVM configuration should include: -javaagent:[GRIDGAIN_HOME]/libs/aspectjweaver-1.5.3.jar
• Classpath should contain the [GRIDGAIN_HOME]/config/aop/aspectj folder.

Spring AOP

Spring AOP framework is based on dynamic proxy implementation and doesn't require any specific runtime parameters for online weaving. All weaving is on-demand and should be performed by calling method GridifySpringEnhancer.enhance(Object) ^Javadoc for the object that has method with Gridify annotation.

Note that since this method of weaving requires manual enhancing of participating classes, it is rather inconvenient in most cases, and AspectJ or JbossAOP are recommended over it. Spring AOP can be used in situations when code augmentation is undesired and cannot be used. It also allows for very fine grained control of what gets weaved.

BEA Weblogic AS

Weblogic application server does not support AspectJ and JBoss AOP officially and the only way to use AOP is a Spring AOP. One needs to enhance classes as described above using Spring AOP. See http://springide.org/blog/2006/05/24/implementing-jee-with-spring-and-weblogic/ for details.