XAP7 == "XAP9NET" || XAP7 == "XAP9" || XAP7 == "XAP9NET")

The GigaSpaces Agent

Search XAP 7.0
Searching XAP 7.0.X Documentation
Browse XAP 7.0
Offline Documentation

Download latest offline documentation in HTML format:
xap-7.0.2-documentation.zip (12.3MB)


Summary: A process manager that manages Service Grid processes such as GSM, GSC and LUS


The GigaSpaces Agent (GSA) acts as a process manager that can spawn and manage Service Grid processes (Operating System level processes) such as The GigaSpaces Manager, The GigaSpaces Container, and Lookup Service.

Usually, a single GSA is run per machine (on a lookup group or lookup locator level, see more in the Lookup Service). The GSA allows to spawn a GigaSpaces Manager, GigaSpaces Container, Lookup Service, and custom processes. Once spawned, the GSA assigns a unique id for it and manages its lifecycle. The GSA will restart the process if it exits, or if a specific console output has been encountered (for example, OutOfMemoryError).

The GSA exposes the ability to start, restart, and kill a process either using the Administration and Monitoring API or the GigaSpaces UI.

Although The GigaSpaces Manager, The GigaSpaces Container, and The Lookup Service can be started on their own using their respective scripts, it is preferable that they will be started using the GSA thus allowing to easily monitor and manage them.

Process Management

The GSA manages Operating System processes. There are two types of process management, local and global.

Local processes simply start the process type (for example, a GigaSpaces Container) without taking into account any other process types running by different GSAs.

Global processes take into account the number of process types (GigaSpaces Manager for example) that are currently running by other GSAs (within the same lookup groups or lookup locators). It will automatically try and run at least X number of processes across all the different GSAs (with a maximum of 1 process type per GSA). If a GSA running a process type that is managed globally fails, another GSA will identify the failure and start it in order to maintain at least X number of global process types.

Starting the GSA

In order to start the GSA, the <GSHOME>/bin/gs-agent.(sh/bat) can be used. The GSA, by default, will start 2 local GigaSpaces Containers, and manage 2 global GigaSpaces Managers and 2 global Lookup Services.

GSA Script Parameters

GSA parameters include controlling how many local process the GSA will spawn on startup (per process type), and the number of globally managed process the GSA will maintain (in cooperation with other GSAs) (per process type).

By default, the GSA is started with 2 local GigaSpaces Containers, and manage 2 global GigaSpaces Manager and 2 global Lookup Service. This is the equivalent of starting the GSA with the following parameters:

gs-agent.(sh/bat) gsa.gsc 2 gsa.global.gsm 2 gsa.global.lus 2

In order to, for example, start 3 local GSCs, 2 global GSMs, and no global LUS, the following command can be used:

gs-agent.(sh/bat) gsa.gsc 3 gsa.global.gsm 2 gsa.global.lus 0

In general, the gsa.[process type] followed by a number controls the number of local processes of the specific process type that will be spawned by the GSA. The gsa.global.[process type] following by a number controls the number of globally managed processes of the specific process type.

Process Type Configuration

GSA manages different process types. Each process type is defined within the <GSHOME>\config\gsa directory in an xml file that identifies the process type by its name.

You can change the default location of the GSA configuration files using the com.gigaspaces.grid.gsa.config-directory system property.

The following are the process types that come out of the box:

Processes Type Description XML config file name Properties file name
gsc Defines a GigaSpaces Container gsc.xml gsc.properties
gsm Defines a GigaSpaces Manager gsm.xml gsm.properties
lus Defines a Lookup Service lus.xml lus.properties
gsm_lus Defines a GigaSpaces Manager and Lookup Service within the same JVM gsm_lus.xml gsm_lus.properties

Here is an example of the gsc xml configuration file:

<process initial-instances="script">
    <script enable="true" work-dir="${com.gs.home}/bin"
            windows="${com.gs.home}/bin/gsc.bat" unix="${com.gs.home}/bin/gsc.sh">
    <vm enable="true" work-dir="${com.gs.home}/bin" main-class="com.gigaspaces.start.SystemBoot">

The GSA can either spawn a script based process, or a pure JVM (with its arguments) process. The GSC for example, allows for both types of process spawning.

  • The initial-instnaces parameter controls what type of spawning will be performed when the GSA spawns processes by itself (and not on demand by the Admin API).
  • The restart-regex (there can be more than one element) is applied to each console output line of the managed process, and if there is a match, the GSA will automatically restart the process. By default, the GSC will be restarted if there is an OutOfMemoryError.

Lookup Service Considerations

When starting a Lookup Service and other services in unicast mode (not multicast), it means that specific machines will be the ones that will run the Lookup Service. This means that on the machines running the LUS, the following command will be used (assuming other defaults are used for GSM and GSC):

gs-agent.(sh/bat) gsa.global.lus 0 gsa.lus 1

And machines that will not run the LUS, the following command should be used:

gs-agent.(sh/bat) gsa.global.lus 0
IMPORTANT: This is an old version of GigaSpaces XAP. Click here for the latest version.