Summary: This page describes the processing unit directory structure
The Processing Unit Jar FileMuch 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 |--------MANIFEST.MF |----com |--------mycompany |------------myproject |----------------MyClass1.class |----------------MyClass2.class |----lib |--------hibernate3.jar |--------.... |--------commons-math.jar The processing unit jar file is composed of several key elements:
Sharing Libraries Between Multiple Processing UnitsIn 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 the Processing Units rather than packaging them individually with each of the Processing Units. 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 saves a lot of the network overhead associated with downloading these JARs to each of the GSCs. lib/optional/pu-common directoryJAR files placed in the <GigaSpaces root>/lib/optional/pu-common directory will be loaded by each Processing Unit instance in its own separate classloader (called the Service Classloader, see the Class Loaders section below). This means they are not shared between Processing Units on the same JVM, which provides an isolation quality often required for JARs containing the application's proprietary business-logic. On the other hand this option consumes more PermGen memory (due to potentially multiple instances per JVM). You can place these JARs in each XAP installation in your network, but it is more common to share this folder on your network and point the pu-common directory to the shared location by specifying this location in the com.gs.pu-common system property in each of the GSCs on your network. When a new JAR needs to be loaded, just place the new JAR in pu-common directory and restart the Processing Unit. Note: if different Processing Units use different versions of the same JAR (under same JAR file name) then pu-common should not be used. META-INF/MANIFEST.MF descriptorJAR files specified in the Processing Unit's META-INF/MANIFEST.MF descriptor file will be loaded by each Processing Unit instance in its own separate classloader (called the Service Classloader, see the Class Loaders section below). This option achieves similar behavior to the lib/optional/pu-common option above, but allows a more fine-grained control by enabling to specify specific JAR files (each in its own location) rather than an entire folder (and only a single folder). For more information see Manifest Based Classpath section below. lib/platform/ext directoryJAR files placed in the <GigaSpaces root>/lib/platform/ext directory 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). This means they are shared between Processing Units on the same JVM and thereby offer no isolation. On the other hand this option consumes less PermGen memory (one instance per JVM). This method is recommended for 3rd party libraries that have no requirement for isolation or different versions for different Processing Units, and are upgraded rather infrequently, such as JDBC driver. You can place these jars in each XAP installation in your network, but it is more common to share this folder on your network and point the platform/lib/ext directory to the 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. When a new JAR needs to be loaded, place the new JAR in lib/platform/ext directory and restart the relevant GSCs (on which an instance of the PU was running). ConsiderationsWhen coming to choose the right option for your system, the following should be considered:
Runtime ModesThe 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 GridWhen 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 UnitsIn 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 the Deploying and Running the Processing Unit section. Class LoadersIn 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:
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 (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 UsageWhen 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 SpaceFor 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 Manifest Based ClasspathYou may add additional jars to the processing unit classpath by having a manifest file located at META-INF/MANIFEST.MF and defining the property Class-Path as shown in the following example (using a simple MANIFEST.MF file): Manifest-Version: 1.0
Class-Path: /home/user1/java/libs/user-lib.jar
lib/platform/jdbc/hsqldb.jar
${MY_LIBS_DIRECTORY}/user-lib2.jar
file:/home/user2/libs/lib.jar
[REQUIRED EMPTY NEW LINE AT EOF]
In the previous example, the Class-Path property contains 4 different entries:
The pu-common DirectoryThe pu-common directory may contain a jar file with a manifest file as described above located at META-INF/MANIFEST.MF. The classpath defined in this manifest will be shared by all processing units as described in Sharing libraries. Further details
Further details about the manifest file can be found here. |
![]() |
GigaSpaces.com - Legal Notice - 3rd Party Licenses - Site Map - API Docs - Forum - Downloads - Blog - White Papers - Contact Tech Writing - Gen. by Atlassian Confluence |