Dashboard > GridGain User Guide > Table Of Contents > Developers Guide > Grid Deployment
GridGain User Guide
Grid Deployment
Added by architect, last edited by morpheus on Dec 23, 2008  (view change)
Labels: 
(None)


Prior to being used, a Grid Task needs to be deployed:

  • If peer class loading is enabled (see property GridConfiguration.isPeerClassLoadingEnabled() in Grid Configuration):
    • Task class loaded from local class path if it is not defined as P2P loaded
    • If there is no task class in local class path or task class needs to be peer loaded it is downloaded from task originating node.
  • If peer class loading is disabled:
    • Check that task class was deployed. If you are using GAR Deployment, then your task will be implicitly deployed every time GAR file or directory is changed. Otherwise, task can be deployed explicitly in code via Grid.deployTask(Class<? extends GridTask<?>>) Javadoc method.
    • If task class was not deployed then we try to find it in local class path by task name. If you are not using @GridTaskName Javadoc annotation to provide a custom task name, then your task name will default to the actual class name of the task and the task will be auto-deployed first time it's executed (no explicit deployment step is required in this case).
    • If task has custom name (that does not correspond task class name), and this task was not deployed before, then exception will be thrown.

Peer Class Loading

Peer class loading (P2P) is turned on by default. To turn it off set GridConfiguration.isPeerClassLoadingEnabled() Javadoc property to false in Grid Configuration.

Although internals of peer class loading are rather complex, what it means in a nutshell is that when a JVM on the remote node needs to find a certain class as part of the grid task execution, it will check the local class loader first and if such class cannot be found, it will ask the node that originated grid task execution (one that should have this class by design) to provide it. In an essence, GridGain class loading becomes grid-aware.

This technique is invaluable during grid application development. It allows for absolutely grid-transparent development cycle: you write your application as you normally do (in a single node environment of Eclipse, IDEA, etc.), compile and run it - and it seamlessly runs on the grid without any extra deployment or build steps what-so-ever. More over, GridGain supports hot-redeployment so you don't have to restart GridGain every time you change the grid task code - again, just modify the code, compile and run and all your changes will be picked up on the grid.

Peer class loading sequence works as follows:

  1. GridGain will check if class was loaded at system startup, and if it was, it will be returned. No class loading from a peer node will take place in this case.
  2. If class is not locally loaded, then a request will be sent to task originating node to provide class definition. Originating node will send class byte code definition and the class will be loaded on a peer node.

Peer class loading should be used in most situations, especially during development with Java IDEs. It allows to dramatically reduce overhead of grid-enabled application development effectively making it as quick and productive as local application development. You simply change code and run - and your modified application seamlessly runs on the grid.

Performance

When utilizing peer class loading, you should be aware of the libraries that get loaded from peer nodes vs. libraries that are already available locally in the class path. Our suggestion is to include all 3rd party libraries into class path of every node. This way you will not transfer megabytes of 3rd party classes to remote nodes every time you change a line of code.

Error messages

Some frameworks like Spring or CGLib ask for the certain classes to identify whether another frameworks are available or not. For example Spring being started looks for the Groovy framework and thus when peer-to-peer feature is on this class/resource request might be sent to remote node. If there is no such class/resource available then you may get message "Requested resource not found" on remote (task originating node) and "Failed to get resource due to remote failure" on local node. They are printed out for your information only.

Local P2P Exclude

Note that giving preference to local deployment (as GridGain does by default) does not always work. For example, GridGain utilizes Spring for its own implementation, so Spring is always loaded locally by system class loader at startup. This may create a problem if user also utilizes Spring to load some beans reflectively. For example, Spring Hibernate support will attempt to load Hibernate classes with its own class loader (system class loader in this case) and if Hibernate is not in local class path, class definitions will not be found.

There are 2 ways to solve this problem:

  1. Include Hibernate jars into class path on every node. This will perform better, as Hibernate jars will not have to be loaded with every task deployment.
  2. If above does not work, you can make sure that Spring and Hibernate classes will always be loaded from a peer node by specifying their packages in GridConfiguration.getP2PLocalClassPathExclude() Javadoc configuration property in Grid Configuration.

Deployment Modes

Deployment mode is specified at grid startup via GridConfiguration.getDeploymentMode() Javadoc configuration property (it can also be specified in Spring XML configuration file). The main difference between all deployment modes is how classes and user resources are loaded on remote nodes via peer-class-loading mechanism. User resources can be instances of caches, databased connections, or any other class specified by user with @GridUserResource annotation. Refer to GridUserResource Javadoc documentation and examples for more information on how user resources are created and injected.

The following deployment modes are supported:

Mode Description
GridDeploymentMode.PRIVATE Javadoc In this mode deployed classes do not share user resources (see GridUserResource Javadoc ). Basicaly, user resources are created once per deployed task class and then get reused for all executions.
Note that classes deployed within the same class loader on master node, will still share the same class loader remotely on worker nodes. However, tasks deployed from different master nodes will not share the same class loader on worker nodes, which is useful in development when different developers can be working on different versions of the same classes.
Also note that resources are associated with task deployment, not task execution. If the same deployed task gets executed multiple times, then it will keep reusing the same user resources every time.
GridDeploymentMode.ISOLATED Javadoc Unlike GridDeploymentMode.PRIVATE mode, where different deployed tasks will never use the same instance of user resources, in ISOLATED mode, tasks or classes deployed within the same class loader will share the same instances of user resources (see GridUserResource Javadoc ). This means that if multiple tasks classes are loaded by the same class loader on master node, then they will share instances of user resources on worker nodes. In other words, user resources get initialized once per class loader and then get reused for all consequent executions.
Note that classes deployed within the same class loader on master node, will still share the same class loader remotely on worker nodes. However, tasks deployed from different master nodes will not share the same class loader on worker nodes, which is especially useful when different developers can be working on different versions of the same classes.
ISOLATED deployment mode is default mode used by the grid.
GridDeploymentMode.SHARED Javadoc Same as GridDeploymentMode.ISOLATED, but now tasks from different master nodes with the same user version and same class loader will share the same class loader on remote nodes. Classes will be undeployed whenever all master nodes leave grid or user version changes.
The advantage of this approach is that it allows tasks coming from different master nodes share the same instances of user resources (see GridUserResource Javadoc ) on worker nodes. This allows for all tasks executing on remote nodes to reuse, for example, the same instances of connection pools or caches. When using this mode, you can startup multiple stand-alone GridGain worker nodes, define user resources on master nodes and have them initialize once on worker nodes regardless of which master node they came from.
This method is specifically useful in production as, in comparison to GridDeploymentMode.ISOLATED deployment mode, which has a scope of single class loader on a single master node, GridDeploymentMode.SHARED mode broadens the deployment scope to all master nodes.
Note that classes deployed in GridDeploymentMode.SHARED mode will be undeployed if all master nodes left grid or if user version changed. User version can be specified in META-INF/gridgain.xml file as a Spring bean property with name userVersion. This file has to be in the class path of the class used for task execution.
GridDeploymentMode.CONTINUOUS Javadoc Same as GridDeploymentMode.SHARED deployment mode, but user resources (see GridUserResource Javadoc ) will not be undeployed even after all master nodes left grid. Tasks from different master nodes with the same user version and same class loader will share the same class loader on remote worker nodes. Classes will be undeployed whenever user version changes.
The advantage of this approach is that it allows tasks coming for different master nodes share the same instances of user resources (see GridUserResource Javadoc ) on worker nodes. This allows for all tasks executing on remote nodes to reuse, for example, the same instances of connection pools or caches. When using this mode, you can startup multiple stand-alone GridGain worker nodes, define user resources on master nodes and have them initialize once on worker nodes regardless of which master node they came from.
This method is specifically useful in production as, in comparison to GridDeploymentMode.ISOLATED deployment mode, which has a scope of single class loader on a single master node, GridDeploymentMode.CONTINUOUS mode broadens the deployment scope to all master nodes.
Note that classes deployed in GridDeploymentMode.CONTINUOUS mode will be undeployed only if user version changes. User version can be specified in META-INF/gridgain.xml file as a Spring bean property with name userVersion. This file has to be in the class path of the class used for task execution.

User Version

User version comes into play whenever you would like to redeploy tasks deployed in GridDeploymentMode.SHARED or GridDeploymentMode.CONTINUOUS modes. By default, GridGain will automatically detect if class-loader changed or a node is restarted. However, if you would like to change and redeploy code on a subset of nodes, or in case of GridDeploymentMode.CONTINUOUS mode to kill the ever living deployment, you should change ther user version.

User version is specified in META-INF/gridgain.xml file as follows: 

<!-- User version. -->  
 <bean id="userVersion" class="java.lang.String">  
     <constructor-arg value="0"/>  
 </bean>

By default, all gridgain startup scripts (gridgain.sh or gridgain.bat) pick up user version from GRIDGAIN_HOME/config/userversion folder. Usually, it is just enough to update user version under that folder, however, in case of GAR or JAR deployment, you should remember to provide META-INF/gridgain.xml file with desired user version in it.

Always-Local Development

GridGain deployment (regardless of mode) allows you to develop everything as you would locally. You never need to specifically write any kind of code for remote nodes. For example, if you need to use a distributed cache from your GridJob, then you can the following:

  1. Simply startup stand-alone GridGain nodes by executing {{GRIDGAIN_HOME/gridgain.{sh|bat} }} scripts.
  2. Inject your cache instance into your jobs via @GridUserResource Javadoc annotation. The cache can be initialized and destroyed with @GridUserResourceOnDeployed Javadoc and @GridUserResourceOnUndeployed Javadoc annotations.
  3. Now, all jobs executing locally or remotely can have a single instance of cache on every node, and all jobs can access instances stored by any other job without any need for explicit deployment.

JEE Deployment

When deploying grid tasks into JEE container, you can keep using standard JEE deployment artifacts. For example, if you are deploying a WAR file into JEE container, simply add your grid task classes to the WAR file and that's it.

GAR Deployment

GAR deployment is a traditional deployment model, similar to JAR/WAR/EAR deployment in JEE, where you create the G rid AR chive file that contains all necessary classes for the grid task and deploy it. GridGain comes with URL-based deployment SPI Javadoc implementation so that you can deploy your GAR files on any URLs accessible via FTP, HTTP(S), POP3 or FILE protocols.

For example, when properly configured, you can just drop your GARs into certain folder on your web server and they will be deployed on the grid.

GAR File

GAR file is a deployable unit used by URI-based deployment SPI Javadoc . GAR file is based on ZLIB compression format like simple JAR file and its structure is similar to WAR archive. GAR file has .gar extension.

GAR file structure (file or directory ending with '.gar'):

META-INF/
        |
        - gridgain.xml
        - ...
lib/
   |
   -some-lib.jar
   - ...
xyz.class
...
  • META-INF entry may contain gridgain.xml file which is a task descriptor XML file. The purpose of task descriptor XML file is to specify all tasks to be deployed. This file is a regular Spring XML definition file. META-INF entry may also contain any other file specified by JAR format.
  • lib entry contains all library dependencies.
  • Compiled Java classes must be placed in the root of a GAR file.

GAR file may be deployed without descriptor file. If there is no descriptor file, URI-based deployment SPI Javadoc will scan all classes in archive and instantiate those that implement GridTask Javadoc interface. In that case, all grid task classes must have a public no-argument constructor (you can alwway use GridTaskAdapter Javadoc adapter for convenience when creating grid tasks).

gridgain.xml

GAR Descriptor gridgain.xml is optional. If not provided - URI-based deployment SPI Javadoc will scan all classes in GAR archive.

By default, all downloaded GAR files that have digital signature in META-INF folder will be verified and and deployed only if signature is valid.

gridgain.xml

gridgain.xml GAR descriptor file is a standard Spring XML that should contain zero or more java.util.List beans. Each list should contain fully qualified class names for grid tasks. Here's an example of gridgain.xml:

<?xml version="1.0" encoding="UTF-8"?>

<!--
    Spring configuration file for test classes in gar-file.
-->
<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>Gridgain Spring configuration file in gar-file.</description>

    <!--
        Test tasks specification.
    -->
    <util:list id="tasks">
        <value>foo.bar.SomeGridTask1</value>
        <value>foo.bar.SomeGridTask2</value>
    </util:list>
</beans>

Ant GAR Task Javadoc

GridGain is shipped with gar Javadoc Ant task: org.gridgain.grid.tools.ant.gar.GridGarAntTask. This task extends zip Ant task and can be used exactly like standard jar Ant task. gar Ant task allows to archive class files and necessary dependencies (like resource files and libraries) with optional descriptor file (gridgain.xml). GridGain comes with an example of using GAr deployment including build.xml. Here's an example of how to use gar Javadoc Ant task in typical build.xml (from example):

<!--
    Special task for creating GAR files.
-->
<taskdef name="gar" classname="org.gridgain.grid.tools.ant.gar.GridGarAntTask"
    classpathref="gg.libs.path"/>

<!-- Create GAR file. -->
<gar destfile="${examples.gar.deploy.dir}/${gar.name}"
    descrdir="${examples.gar.dir}/META-INF"
    basedir="${examples.gar.deploy.dir}/tmpgar"/>

Deployment SPIs

GridGain comes with 2 deployment SPIs:
Powered by Atlassian Confluence, the Enterprise Wiki. (Version: 2.2.10 Build:#528 Nov 29, 2006) - Bug/feature request - Contact Administrators