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 can also place the jars on which your processing unit depends in the <GigaSpaces root>/lib/optional/pu-common directory. This is useful in case you want multiple processing units to use the same jar files and do not want to repackage each processing unit whenever one of these jars changes.

The pu-common folder is also useful to decrease the deployment time in case your processing unit contains a lot of 3rd party jars files. In such case, each GSC will download the processing unit jar file (along with all the jars it depends on) to its local working directory from the GSM, and in case of large deployments spanning tens or hundreds of GSCs this can be quite time consuming. In such cases you should consider placing the jars on which your processing unit depends in a shared location on your network, and then point the pu-common directory to this location. This can be done by setting the system property com.gs.pu-common to point to the shared location when starting each GSC.

If you would like multiple processing unit instances loaded into the same GSC to share the same classloader you should place the relevant libraries under the <GigaSpaces root>/lib/platform/ext folder. Third party libraries such as database JDBC drivers jars,logging libraries, etc., should be placed within this folder.
since 7.1.4 You can also 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.
XAP 6.x support the shared-lib directory to place shared libraries. It is still supported, however it is highly recommended that you move all the jar files previously located under shared-lib to the lib folder, and not use it anymore. By default, in XAP 7.x and above, 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

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, spring/*.jar
To avoid loading the same classes used my different PU instances into multiple different class loaders within the JVM hosting the GSC, place your shared jars within the GSROOT/lib/platform/ext folder.

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