Summary: This page describes the processing unit directory structure

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 can be also specified at the deploy time via the deploy CLI or deploy API

    .

    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.
  • User class files: Your processing unit's classes (here under the com.mycompany.myproject package)
  • lib: Other jars on which your processing unit depends, e.g. commons-math.jar or jars that contain common classes across many processing units.
You may add your own jars into the runtime (GSC) classpath by using the PRE_CLASSPATH and POST_CLASSPATH variables. These should point to your application jars.

Sharing Libraries Between Multiple Processing Units

In some cases, multiple processing units use the same jar files. In such cases it makes sense to place these jar files in a central location accessible by all processing unit not repackage each of processing unit separately. Note that this is also useful for decreasing the deployment time in case your processing units contain a lot of 3rd party jars files. since it save a lot of the network overhead associated with downloading these jars to each of the GSCs. There are two options to achieve this:

  1. The <GigaSpaces root>/lib/optional/pu-common directory: Placing jars in this directory means they will be loaded by each processing unit instance its own separate classloader (called the service classloader, see the Class Loaders section below). You can either place these jars in each GigaSpaces installation in your network, or point the pu-common directory to a shared location on your network by specifying this location in the com.gs.pu-common system property in each of the GSCs on your network.
  2. The <GigaSpaces root>/lib/platform/ext directory: Placing jars in this directory means they will be loaded once by the GSC-wide classloader and not separately by each processing unit instance (this classloader is called the common classloader, see the Class Loaders section below). You can either place these jars in each GigaSpaces installation in your network, or point the platform/lib/ext directory to a shared location on your network by specifying this location in the com.gigaspaces.lib.platform.ext system property in each of the GSCs on your network.
    For Database 3rd party jars (e.g. JDBC driver) we recommend using the second option (GSC-wide classloader)

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

In general, classloaders are created dynamically when deploying a PU into a GSC. You should not add your classes into the GSC CLASSPATH. Classes are loaded dynamically into the generated classloader in the following cases:

  • When the GSM sending classes into the GSC when the application deployed and when GSC is restarted.
  • When the GSM sending classes into the GSC when the application scales.
  • When a Task class or Distributed Task class and its dependencies are executed (space execute operation).
  • When space domain classes and their dependencies (Data model) are used (space write/read operations)

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:

Class Loader User Locations Built in Jar Files
Common [GSRoot]/lib/platform/ext/*.jar gs-runtime.jar
Processing Unit Instance (Service Class Loader) [PU]/, [PU]/lib/.jar,[GSRoot]/lib/optional/pu-common/.jar gs-openspaces.jar, org.springframework*.jar

In terms of class loader delegation model, the service (PU instance) 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.

Native Library Usage

When deploying applications using native libraries you should place the Java libraries (jar files) loading the native libraries under the GSRoot/lib/platform/ext folder. This will load the native libraries once into the common class loader.

Permanent Generation Space

For applications that are using relatively large amount of third party libraries (PU using large amount of jars) the default permanent generation space size may not be adequate. In such a case, you should increase the permanent generation space size. Here are suggested values:

-XX:PermSize=512m -XX:MaxPermSize=512m
GigaSpaces.com - Legal Notice - 3rd Party Licenses - Site Map - API Docs - Forum - Downloads - Blog - White Papers - Contact Tech Writing - Gen. by Atlassian Confluence