The Processing Unit Jar File

Much like a JEE web application or an OSGi bundle, The Processing Unit is packaged as a .jar file and follows a certain directory structure which enables the GigaSpaces runtime environment to easily locate the deployment descriptor and load its classes and the libraries it depends on. A typical processing unit looks as follows:

|----META-INF
|--------spring
|------------pu.xml
|------------pu.properties
|------------sla.xml
|----com
|--------mycompany
|------------myproject
|----------------MyClass1.class
|----------------MyClass2.class
|----lib
|--------hibernate3.jar
|--------....
|--------commons-math.jar

The processing unit jar file is composed of several key elements:

• META-INF/spring/pu.xml (mandatory): This is the processing unit's deployment descriptor, which is in fact a Spring context XML configuration with a number of GigaSpaces-specific namespace bindings. These bindings include GigaSpaces specific components (such as the space for example). The pu.xml file typically contains definitions of GigaSpaces components (space, event containers, remote service exporters) and user defined beans which would typically interact with those components (e.g. an event handler to which the event containers delegate the events, or a service beans which is exposed to remote clients by a remote service exporter).

• META-INF/spring/sla.xml (not mandatory): This file contains SLA definitions for the processing unit (i.e. number of instances, number of backup and deployment requirements). Note that this is optional, and can be replaced with an <os:sla> definition in the pu.xml file. If neither is present, the default SLA will be applied. Note, the sla.xml can also be placed at the root of the processing unit.

SLA definitions are only enforced when deploying the processing unit to the GigaSpaces service grid, since this environment actively manages and controls the deployment using the GSM. When running within your IDE or in standalone mode these definitions are ignored.

• META-INF/spring/pu.properties (not mandatory): Enables you to externalize properties included in the pu.xml file (e.g. database connection username and password), and also set system-level deployment properties and overrides, such as JEE related deployment properties (see this page for more details) or space properties (when defining a space inside your processing unit). Note, the pu.properties can also be placed at the root of the processing unit.

• Your processing unit's classes (here under the com.mycompany.myproject package)

• lib: External jars on which your processing unit depends, e.g. commons-math.jar).

In 6.x the structure included the shared-lib directory as well. It is still supported, however it is highly recommended that you move all the jar files previously located under shared-lib jar to lib, and not use it anymore. By default, in 7.x, jar files placed in shared-lib are automatically added as if they were placed in lib allowing for seamless backward compatibility.

Runtime Modes

The processing unit can run in multiple modes.

When deployed on to the GigaSpaces runtime environment or when running in standalone mode, all the jars under the lib directory of your processing unit jar, will be automatically added to the processing unit's classpath.

When running within your IDE, it is similar to any other Java application, i.e. you should make sure all the dependent jars are part of your project classpath.

Deploying the Processing Unit to the GigaSpaces Service Grid

When deploying the processing unit to GigaSpaces Service Grid, the processing unit jar file is uploaded to the GigaSpaces Manager (GSM) and extracted to the deploy directory of the local GigaSpaces installation (located by default under <GigaSpaces Root>/deploy).

Once extracted, the GSM processes the deployment descriptor and based on that provisions processing unit instances to the running GigaSpaces containers.

Each GSC to which a certain instance was provisioned, downloads the processing unit jar file from the GSM, extracts it to its local work directory (located by default under <GigaSpaces Root>/work/deployed-processing-units) and starts the processing unit instance.

Deploying Data Only Processing Units

In some cases, your processing unit contains only a Space and no custom code.

One way to package such processing unit is to use the standard processing unit packaging described above, and create a processing unit jar file which only includes a deployment descriptor with the required space definitions and SLA.

GigaSpaces also provides a simpler option via its built-in data-only processing unit templates (located under <GigaSpaces Root>/deploy/templates/datagrid. Using these templates you can deploy and run data only processing unit without creating a dedicated jar for them.

For more information please refer to this section

Class Loaders

Here is the structure of the class loaders when several processing units are deployed on the Service Grid (GSC):

Bootstrap (Java)
                  |
               System (Java)
                  |
               Common (Service Grid)
             /        \
    Service CL1     Service CL2

The following table shows which user controlled locations end up in which class loader, and the important JAR files that exist within each one:

In terms of class loader delegation model, the service class loader uses a parent last delegation mode. This means that the processing unit instance class loader will first try and load classes from its own class loader, and only if they are not found, will delegate up to the parent class loader.