Configuring the Environment Variables
This topic explains how the GigaSpaces and GigaSpaces environments are configured, and how to customize them to suit your specific application needs.
GigaSpaces
The GigaSpaces environment configuration is maintained by a configuration script file called setenv, located in the XAP/bin directory. Each GigaSpaces script invokes this script to load the GigaSpaces configuration. If you are developing a standalone GigaSpaces client, it is recommended to use the setenv utility to derive the commonly used GigaSpaces libraries and setup environment.
To use this utility, you can simply call it from within your script file.
GigaSpaces
The GigaSpaces environment configuration is maintained by a configuration script file called insightedge-env, located in the XAP/insightedge/conf directory. Each GigaSpaces script invokes this script to load the GigaSpaces configuration. Additionally, insightedge-env starts by invoking the GigaSpaces setenv configuration script, so all of the GigaSpaces environment configuration is also applied.
Customizing the Environment Variables
During the initial development stages, it is usually unnecessary to change any of the default GigaSpaces environment values. However, at some point the environment will need customization to suit your specific requirements (such as the Grid Service Container heap size).
Do not make changes to the original setenv script, as it complicates upgrading GigaSpaces later on. Instead, use the setenv-overrides script, which is automatically called by setenv and is intended for specifying custom overrides in a safe manner.
GigaSpaces Environment Variables
The following list describes GigaSpaces-related environment variables:
| Name | Description | Default Value |
|---|---|---|
| JAVA_HOME | The directory in which Java is installed. | |
| XAP_HOME | The GigaSpaces GigaSpaces home directory. | Automatically set via the folder structure |
| XAP_LICENSE | License key (for Premium and Enterprise editions). | |
| XAP_LOOKUP_GROUPS | Lookup Service groups used for multicast discovery. | xap-14.0.1 |
| XAP_LOOKUP_LOCATORS | Lookup Service Locators used for unicast discovery. | |
| XAP_NIC_ADDRESS | The network interface card that will be used by GigaSpaces. | Automatically set to the host name |
| XAP_SECURITY_POLICY | The default policy file. | XAP_HOME/policy/policy.all |
| XAP_LOGS_CONFIG_FILE | The location of the GigaSpaces logging configuration. | XAP_HOME/config/log/xap_logging.properties |
| XAP_MANAGER_SERVERS | Set the list of Manager servers that other machines can connect to. | |
| XAP_PUBLIC_HOST | Define the public IP address for the Docker host machine. | |
| XAP_MANAGER_OPTIONS | Java options for the GigaSpaces Manager. | |
| XAP_GSC_OPTIONS | Java options for the Grid Service Container (GSC). | |
| XAP_GSM_OPTIONS | Java options for the Grid Service Manager (GSM). | |
| XAP_GSA_OPTIONS | Java options for the Grid Service Agent (GSA) | |
| XAP_LUS_OPTIONS | Java options for the Lookup Service (LUS). | |
| XAP_ESM_OPTIONS | Java options for the Elastic Service Manager (ESM). | |
| XAP_GUI_OPTIONS | Java options for the GigaSpaces Management Center. | |
| XAP_WEBUI_OPTIONS | Java options for the Web Management Console. |
When running in ./gs-agent --manager configuration, this environment variable is ignored.
GigaSpaces Environment Variables
The following list describes GigaSpaces-related environment variables:
| Name | Description | Default Value |
|---|---|---|
| SPARK_HOME | The directory where Spark is installed | XAP_HOME/insightedge
|
| INSIGHTEDGE_CLASSPATH_EXT | Extra classpath to append to GigaSpaces components | |
| INSIGHTEDGE_SPACE_NAME | Space name to use in GigaSpaces scripts and examples | demo
|
In addition, you can also use standard Spark environment variables. The GigaSpaces Platform loads Spark components in a manner that preserves their usage. For example, set SPARK_MASTER_PORT to override the default 7077 port.
Upgrading from Previous Versions
In previous versions, environment variable names were inconsistent, which occasionally led to confusion. Starting with GigaSpaces 11.0, all GigaSpaces-related environment variables were renamed with a XAP_ prefix, so they're easier to identify. The following table maps the pre-11.0 names to the current names:
| Name before 11.0 | Name in 12.0 and higher |
|---|---|
| JSHOMEDIR | XAP_HOME |
| LOOKUPGROUPS | XAP_LOOKUP_GROUPS |
| LOOKUPLOCATORS | XAP_LOOKUP_LOCATORS |
| NIC_ADDR | XAP_NIC_ADDRESS |
| POLICY | XAP_SECURITY_POLICY |
| GS_LOGGING_CONFIG_FILE | XAP_LOGS_CONFIG_FILE |
| GSC_JAVA_OPTIONS | XAP_GSC_OPTIONS |
| GSM_JAVA_OPTIONS | XAP_GSM_OPTIONS |
| GSA_JAVA_OPTIONS | XAP_GSA_OPTIONS |
| LUS_JAVA_OPTIONS | XAP_LUS_OPTIONS |
| ESM_JAVA_OPTIONS | XAP_ESM_OPTIONS |
If you'd rather postpone or avoid changing your scripts to the new names, you can use the setenv-overrides script to map the corresponding values. For example, suppose you customized the lookup groups and the GSC options. If you followed GigaSpaces best practices, you created a custom script to set those environment variables before calling the original script, for example:
export LOOKUPGROUPS=foo
export GSC_JAVA_OPTIONS=-Xms1024m -Xmx1024m
./gs-agent.sh
set LOOKUPGROUPS=foo
set GSC_JAVA_OPTIONS=-Xms1024m -Xmx1024m
call gs-agent.bat
The gs-agent script calls the setenv script to set up the environment, which in turn calls the setenv-overrides script mentioned above to implement any customization that overrides the default values. You can modify setenv-overrides to propagate the old variables to the new ones, for example:
export XAP_LOOKUP_GROUPS=$LOOKUPGROUPS
export XAP_GSC_OPTIONS=$GSC_JAVA_OPTIONS
set XAP_LOOKUP_GROUPS=%LOOKUPGROUPS%
set XAP_GSC_OPTIONS=%GSC_JAVA_OPTIONS%
