Summary: Overriding default configuration using a properties file or the Properties Java object.

How Properties Affect Configuration

In GigaSpaces, properties are used to populate (or override out-of-the-box) schema file configuration parameter values (space, space container, space proxy and cluster XML/XSL schema files). In these schema files, each configuration parameter can either have an absolute value, or be populated from a property.

GigaSpaces configuration override file (known as the custom properties file/object) is used to override various components such as:
Space, space container, cluster schema properties, space proxy, space URL attributes, and other system and environment properties.

Properties in configuration schemas can be populated from several sources:

  • The OpenSpaces Space component configuration
  • The default properties file (hard-coded inside the space, space container, and cluster XML/XSL schema files).
  • A custom properties file (user-defined, can be loaded by the server or client startup script.
  • A Java java.util.Properties object that is passed into the SpaceFinder call.
  • System properties (called in the Java command of the server startup scripts).

Override Configuration using OpenSpaces UrlSpaceFactoryBean

The OpenSpaces space allows you to override specific schema configuration element values using the Properties object, that uses an XPath-like navigation as the name value. The UrlSpaceFactoryBean allows you to set the Properties object, specifying it within the Spring configuration.

Namespace
<os-core:space id="space" url="/./space">
    <os-core:properties>
        <props>
            <prop key="space-config.serialization-type">1</prop>
        </props>
    </os-core:properties>
</os-core:space>

Plain XML
<bean id="space" class="org.openspaces.core.space.UrlSpaceFactoryBean">
    <property name="url" value="/./space" />
    <property name="properties">
        <props>
            <prop key="space-config.serialization-type">1</prop>
        </props>
    </property>
</bean>

Code
UrlSpaceConfigurer spaceConfigurer = 
              new UrlSpaceConfigurer("/./space").addProperty("space-config.serialization-type", "1");
IJSpace space = spaceConfigurer.space();

// ...

// shutting down / closing the Space
spaceConfigurer.destroy();

The GigaSpaces out-of-the-box installation provides the default <GigaSpaces Root>\config\gs.properties file, which is an example for a custom properties file used to override common configuration.

  • If a custom properties file is not loaded, and no system properties are called, the default values are used for all properties in the schema files.
  • If a custom properties file is loaded, and no system properties are called, the values provided in the custom properties file override the default values; and properties that are not set in the custom property file still receive the default values.
  • If a custom properties file is loaded, and system properties are called:
    • The values set in the system properties override the values in the custom properties file.
    • If there are properties that were not set as a system property, but were set in the properties file, the properties file values are used.
    • Properties that were set neither as a system property nor in the custom properties file get the default values.
  • If only system properties are called (and a property file is not loaded), then:
    • The values set in the system properties override the default values.
    • Properties that were not set as a system property get the default values.
    • If any properties were set in a custom properties file, they are not used, because the file is not loaded.

When properties are loaded and XPath overrides are used, XPath values have the highest override priority; even if system properties are set for the same configuration element.

The properties file can be shared across all spaces and clients, and can be downloaded from an HTTP server. For example, if you want the gs.properties file to be downloaded from an HTTP server running on myhost:someport, simply add the following to the space URL:

?properties=http://myhost:someport/somedirector/gs.properties

Environment variables are another source for configuring property values. Remember that the GigaSpaces environment variables are loaded by the setenv.bat file. Very often, the property values set in system properties and in properties files are actually environment variables.

It is recommended to use a custom properties file or object instead of system properties, because system properties are limited to the same JVM. This might be problematic in distributed environments (Service Grid GSCs shouldn't use system properties), and requires granting of Java security permissions. You can load a custom properties file by adding ?properties=propertiesFileName to your space URL. For example:

java -classpath ${myroot}:${myclasspath} com.j_spaces.
core.client.SpaceFinder"/./mySpace?schema=default&properties=gs"

The above URL uses a file named gs.properties located under the ${myroot}\config folder as the custom properties file.

Custom Properties File (<GigaSpaces Root>\config\gs.properties)

A custom properties file sets custom (user-defined) values for some or all of the default space and space container configuration; values in the custom properties file override the default values. The custom values only take effect when the custom properties file is loaded explicitly.

You can define whether to load a properties file and call system properties in the gsInstance server startup script, by adding ?properties=propertiesFileName to your space URL.

Define the following logging levels

com.gigaspaces.common.spaceurl.level = ALL 
com.gigaspaces.common.resourceloader.level = FINE

in order to verify that the properties file is found and parsed properly.

How to override Configuration

GigaSpaces configuration override file is used to override various components such as the space, space container, cluster schema properties, space proxy, space URL, and other system and environment properties.

If a client requests to load a properties file (or passes a Properties Java object); the system attempts to load the properties file from the <GigaSpaces Root>\config directory (if <GigaSpaces Root> is in the classpath), or from an HTTP URL. If the properties file is found, it is loaded to the system, and its attributes are set in the SpaceURL properties data structure.

Any system property that is set overrides other settings. Then, the properties file (or a user-defined Properties object) is parsed, its properties are injected into the system, and are later used to override the space/container/cluster configuration, as well as other VM system properties.

The following types of properties are supported for the properties object/file:

  • Space, space proxy/client, space container configurationthe property key is the XPath-like navigation as the name value of the element, as set in the space or space container schema XML file.
    Space configuration example:
    space-config.lrmi-stub-handler.protocol-name=rmi

    Container configuration example:

    com.j_spaces.core.container.directory_services.jini_lus.enabled=false
  • Cluster configuration – the property key is the system property which needs to be set in the cluster schema XML file. For example, if you specify $elementname instead of one of the cluster configuration elements (you need to do it in advance), the user needs to set -Delementname=somevalue on the space side once the cluster starts in order to override it.

    The ability to override cluster configuration schema settings using custom properties injection (through XPath settings in the gs.properties file, Java Properties object, or OpenSpaces pu.xml file) is new in GigaSpaces version 6.5.

  • System properties – the key must begin with -D, which instructs the system to set that key/value as a system property.
  • SpaceURL attributes – the key must begin with: gs.space.url.arg.attribute name, for example:
    gs.space.url.arg.total_members=111

    or:

    gs.space.url.arg_line=schema=persistent&cluster_schema=async_replicated&total_members=3&id=2&nowritelease=true&fifo=true&create

    Space URL arguments should all be in lower case.
    Using the $xxx setting via a system property is valid in any scenario, but is overwritten if the first option (space, space proxy/client, space container configuration) is used.

Cluster XPath Properties

The best practice is to use the cluster schema (which is provided out of the box) as-is, and override specific configuration elements in runtime. This ensures no changes to XML/XSL files, easier deployment/upgrades (especially in enterprise deployments), and provides a single way to override most product components. Additionally, there is usually no need for a static cluster, since the members' elements are simply overridden.

For a full list of XPath-like keys required to override cluster configuration, see the Cluster Configuration XPath Overrides section.

Usage

You can either use a standard XPath syntax (/ – slash notation) or use the GigaSpaces custom syntax (that uses an XPath-like navigation as the name value – dot notation). GigaSpaces supports the use of standard XPath syntax, using the slash syntax.

Every cluster configuration override must begin with cluster-config (same as with space-config for the space schema and com.j_spaces.core.container for the space container).

For example, if you are working with a partitioned-sync2backup cluster with 2 primaries and 1 backup for each primary, and you want to set other space URLs in the member-url element for each cluster member; set the following for each occurrence of member-url:

First member URL:

/cluster-config/cluster-members/member[1]/member-url=rmi://some_host1:10081/mySpace_container1/mySpace

Second member URL:

/cluster-config/cluster-members/member[2]/member-url=rmi://some_host2:10082/mySpace_container1_1/mySpace

Third member URL:

/cluster-config/cluster-members/member[3]/member-url=rmi://some_host3:10083/mySpace_container2/mySpace

Forth member URL:

/cluster-config/cluster-members/member[4]/member-url=rmi://some_host4:10084/mySpace_container2_1/mySpace

To override the load-balancer minimum thread-pool size:

cluster-config.groups.group.load-bal-policy.proxy-broadcast-threadpool-min-size=33

To disable notify recovery:

cluster-config.notify-recovery=false

To enable the failover failback option:

cluster-config.groups.group.fail-over-policy.fail-back=true

Space and Space Container XPath Properties

Refer to the Container Schema and Space Configuration*** sections for details.

For a full list of XPath-like keys required to override space container and space configuration, see the Space Container Configuration XPath Overrides and Space Configuration XPath Overrides sections.

To enable the cluster:

space-config.cluster.enabled=true

The static members cluster XML file needs to be located in the <GigaSpaces Root>\config directory, for example: c:\myFolder\config\multi-site, where c:\myFolder needs to include space-config.cluster.config-url=/config/multi-site.

To disable the RMIRegistry, which is started when setting the space container:

com.j_spaces.core.container.directory_services.jndi.enabled=false

To disable the GigaSpaces shutdown hook:

com.j_spaces.core.container.shutdown_hook=false

To disable an embedded Webster HTTPD:

com.j_spaces.core.container.embedded-services.httpd.enabled=false

The host port used by the server socket HTTPD (Webster):

com.j_spaces.core.container.embedded-services.httpd.explicit-binding-port=9813

Default value is port 9813, however, if this port is busy, an anonymous port is generated. You can override the port number using the following settings.

The Jini Lookup Service settings inside the container schemas

com.j_spaces.core.container.directory_services.jini_lus.start-embedded-lus=false
com.j_spaces.core.container.directory_services.jini_lus.enabled=false
com.j_spaces.core.container.directory_services.jini_lus.unicast_discovery.enabled=true
com.j_spaces.core.container.directory_services.jini_lus.unicast_discovery.lus_host=host:port

If true, starts an embedded Mahalo Jini Transaction Manager. Default value is false:

com.j_spaces.core.container.embedded-services.mahalo.start-embedded-mahalo=true

To override the space configuration implicit-indexes, add the following line:

space-config.number-implicit-indexes=-1

To override the space configuration LRMI protocol:

space-config.lrmi-stub-handler.protocol-name=rmi

To override the space configuration serialization type add the following line:

space-config.serialization-type=0

Enable the space SecurityFilter by setting:

space-config.filters.DefaultSecurityFilter.enabled=true

If true, enables Gigaspaces JMS support by registering the JMS administrated objects in the directory service. Default value is false.

com.j_spaces.core.container.directory_services.jms_services.enabled = true

System Properties

You can set any system properties using -Delementname=somevalue.

These system properties are set only after the properties file is initialized and parsed. Therefore, system properties required to be set with the VM launch should be placed only in the Java command line.

For more details, refer to the System Properties List section.

Common RMI-related system properties – when it is necessary to ensure that DGC clean calls for unreachable remote references are delivered in a timely fashion, the value of this property represents the maximum interval (in milliseconds) that the Java RMI runtime allows between garbage collections of the local heap.

Default value is 60000 milliseconds (60 seconds). Below, it is set it to 1 hour.

-Dsun.rmi.dgc.client.gcInterval=36000000
-Dsun.rmi.dgc.server.gcInterval=36000000
-Djava.rmi.server.RMIClassLoaderSpi=default

If this value is true, incoming calls and exceptions thrown from incoming calls are logged to System.err. Setting this property to true greatly assists you in debugging your RMI programs.

-Djava.rmi.server.logCalls=true

If this value is true, details of RMI logging activity are sent to System.err.

-Dsun.rmi.log.debug=true
-Dcom.gs.onewaywrite=true

Common Debugging Logging Options

The following prints a runtime configuration report of the overall system configuration (space, container, cluster) system environment, system properties, etc.

-Dcom.gs.env.report=true

Space URL Attributes

For more details, refer to the Space URL section.

gs.space.url.arg.total_members=10
gs.space.url.arg.id=2
gs.space.url.arg.schema=persistent
gs.space.url.arg.nowritelease=true

Other optional attributes (add each to the gs.space.url.arg. prefix):

  • backup_id
  • clustergroup
  • clustername
  • cluster
  • cluster_schema
  • groups
  • fifo
  • updatemode
  • versioned
  • uselocalcache
  • timeout
  • securitymanager
  • nocache
  • create
  • destroy

Below is an example of how to set a list of space URL attributes:

gs.space.url.arg_line=schema=persistent&id=2&total_members=10&Create

Space Proxy Attributes

The following defines the maximum thread pool size used by the proxy for FIFO and batch notifications:

space-config.proxy.notify.maxThreadPoolSize=20

The following defines the minimum thread pool size used by the proxy for FIFO and batch notifications:

space-config.proxy.notify.minThreadPoolSize=10

Default gs.properties File Example

When specifying a space URL, you can use the properties file, or include the <properties> tag in your container schema. This should include a properties file location with a list of properties that override the cluster, container, and space default values as discussed above.

#================================================================================================================
# Refer to wiki docs for more information. 
#
# GigaSpaces configuration overriding file is used to override various components such as the 
# space, space container, cluster schema properties, as well as space proxy, space url 
# and other system and environment properties.
#
# The best practices is to use the schema files (that comes of of the box) as is and override
# specific configuration elements in runtime. It minimizes changes to xml/xsl files, ease 
# deployment/upgrades (especially in enterprise deployments) and provides single means for overriding 
# most of the product components. It also removes the need for static cluster for most cases, 
# by simply override the members elements. Properties can also be set through the OpenSpaces pu.xml file.
#
# If a client has requested to load a properties file 
#(or passed a Properties Java object), the system attempts to load the properties file from the 
# <GigaSpaces Root>\config directory (if <GigaSpaces Root> is in the classpath), or from an HTTP URL. 
# If the properties file is found, it is loaded to the system, and its attributes are set in the 
# SpaceURL properties data structure.
# Any system property that is set overrides other settings. Then, the properties are parsed and its 
# properties injected into the system and are later used to override the space/container/cluster configuration, 
# as well as other VM system properties.


# Supported Types of Properties for Properties Object/File:
# ========================================================
# * Space, space proxy/client, space container configuration - the property key is the XPath-like 
# navigation as the name value of the element as set in the space or space container schema XML file.
# * Cluster configuration - the property key is the system property which needs to be set 
# in the cluster schema XML file, e.g. if you specify $elementname instead of one of the cluster config elements 
# (you need to do it in advance), then in order to override it, user needs to set -Delementname=somevalue in 
# the space side once the cluster starts.
# 
# The ability to override cluster configuration schema settings using custom properties injection 
# (through a XPath set in the gs.properties file, Java Properties object or OpenSpaces PU xml file) 
# is new in GigaSpaces version 6.5.
# * System properties - the key must begin with -D, which instructs the system to set that key/value 
# as a system property.
# * SpaceURL attributes - the key must begin with: gs.space.url.arg.attribute name. The space URL arguments 
# should be all in lower case. Using of the $xxx setting via a system property is valid in any scenario, 
# but is overwritten if the first option (space, space proxy/client, space container configuration) is used.
#
# * When Properties are loaded and XPath overrides are used, they will be with highest override priority, 
# even if System Properties are set for same configuration element.
# * The Properties file can be shared cross all spaces and clients and put under http server. 
# If you want to have the gs.properties file to be downloaded from an http server running on myhost:someport 
# then simply add the following to the SpaceURL: ?properties=http://myhost:someport/somedirector/gs.properties
#

#===================================================
# Cluster Configuration XPath:
#===================================================
# You can either use a standard XPath syntax ("/" slash notation) or use same GigaSpaces custom syntax 
# (that uses an XPath-like navigation as the name value - "dot" notation)
# 
# Every cluster configuration override must start with cluster-config (same as with space-config for 
# space schema and com.j_spaces.core.container for space container).
# Supporting using standard XPath syntax, using the slash syntax - 
# E.g. If we have a partitioned-sync2backup 2,1 cluster with 2 primaries and 1 backup per each primary 
# and we want to set other space urls in the <member-url> for each cluster member, 
# we will set the following for each of the occurrences of the member-url:

# For the first member-url
#/cluster-config/cluster-members/member[1]/member-url=rmi://some_host1:10081/mySpace_container1/mySpace
# For the second member-url
#/cluster-config/cluster-members/member[2]/member-url=rmi://some_host2:10082/mySpace_container1_1/mySpace
# For the third member-url
#/cluster-config/cluster-members/member[3]/member-url=rmi://some_host3:10083/mySpace_container2/mySpace
# For the forth member-url
#/cluster-config/cluster-members/member[4]/member-url=rmi://some_host4:10084/mySpace_container2_1/mySpace

## Usage examples of the XPath-like navigation to override cluster configuration
#cluster-config.notify-recovery=false
#cluster-config.groups.group.load-bal-policy.proxy-broadcast-threadpool-min-size=33
#cluster-config.groups.group.fail-over-policy.fail-back=true
#cluster-config.cache-loader.external-data-source=true
#-Dcom.gs.cluster.cache-loader.external-data-source=true
#cluster-config.groups.group.repl-policy.sync-replication.multicast.ip-group=10.9.8.7

#
#===================================================
# Space and Space Container XPath:
#===================================================
## Cluster config related settings in space schema:
# To enable the cluster 
#space-config.cluster.enabled=true
#The static members cluster xml file needs to be located in <root dir>/config folder, e.g. 
#c:/myFloder/config/multi-site and the c:/myFloder needs to be added
#space-config.cluster.config-url=/config/multi-site
#### Examples for other optional cluster config urls:
#space-config.cluster.config-url=/config/myTest-cluster-config.xml /config/myTest2-cluster.xml 
#space-config.cluster.config-url=D:\\myFolder\\config\\default-cluster.xml
#space-config.cluster.config-url=/config/default
#space-config.cluster.config-url=/config/myAsyncRepl-cluster.xml
# To disable GigaSpaces shutdown hook
#com.j_spaces.core.container.shutdown_hook=false
#
# To disable embedded Webster HTTPD.
#com.j_spaces.core.container.embedded-services.httpd.enabled=false

# The host and port the server socket HTTPD (Webster) is using is bound to.  
# Default value: port 9813 but if that is busy it generates an anonymous port. 
# Using the following you may override the port number: 
# com.j_spaces.core.container.embedded-services.httpd.explicit-binding-port=9813
##### Jini Lookup service container config related:
#com.j_spaces.core.container.directory_services.jini_lus.start-embedded-lus=false
#com.j_spaces.core.container.directory_services.jini_lus.enabled=false
#com.j_spaces.core.container.directory_services.jini_lus.unicast_discovery.enabled=true
#com.j_spaces.core.container.directory_services.jini_lus.unicast_discovery.lus_host=host:port

# If true, will start an embedded Mahalo Jini Transaction Manager. Default value: false
#com.j_spaces.core.container.embedded-services.mahalo.start-embedded-mahalo=true

#to override the space config implicit-indexes just add the line:
#space-config.number-implicit-indexes=-1

#to override the space config lrmi protocol
#space-config.lrmi-stub-handler.protocol-name=rmi

#to override the space config serialization-type just add the line:
#space-config.serialization-type=0

# Enable the space SecurityFilter by setting:
#space-config.filters.DefaultSecurityFilter.enabled=true

# Turn on the jms services - if true we enable Gigaspaces jms support by registering the jms administrated objects
# in the directory service. Default value: false
#com.j_spaces.core.container.directory_services.jms_services.enabled = true

#===================================================
# SYSTEM PROPERTIES:
#===================================================
# RECOMMENDED: Common RMI related system properties settings
#
#When it is necessary to ensure that DGC clean calls for unreachable remote references 
#are delivered in a timely fashion, the value of this property represents the maximum interval 
#(in milliseconds) that the Java RMI runtime will allow between garbage collections of the local heap. 
#The default value is 60000 milliseconds (60 seconds). We set it to 1 hour.
#-Dsun.rmi.dgc.client.gcInterval=36000000
#-Dsun.rmi.dgc.server.gcInterval=36000000
#-Djava.rmi.server.RMIClassLoaderSpi=default
#if this value is true, incoming calls and exceptions thrown from incoming calls will be logged to System.err. 
#Setting this property to true will greatly assist you in debugging your RMI programs.
#-Djava.rmi.server.logCalls=true
#If this value is true, details of rmid's logging activity are sent to System.err.
#-Dsun.rmi.log.debug=true
#-Dcom.gs.onewaywrite=true
## Common debugging logging options:
#-Djava.security.debug=access
#-Dnet.jini.discovery.debug=1
# Runtime configuration report of the overall system configurations (spaces, container, cluster)
# system env, system properties etc.
#-Dcom.gs.env.report=true
# Prints the cluster schema and configuration report
#-Dcom.gs.clusterXML.debug=true

#===================================================
# Space URL attributes:
#===================================================
#gs.space.url.arg.total_members=10
#gs.space.url.arg.id=2
#gs.space.url.arg.schema=persistent
#gs.space.url.arg.nowritelease=true
#Other optional attributes (add each to the gs.space.url.arg. prefix):
#backup_id, clustergroup, clustername, cluster, cluster_schema, groups, fifo
#updatemode, versioned, uselocalcache, timeout, securitymanager, nocache, create, destroy
# Example how to set a list of Space URL attributes:
#gs.space.url.arg_line=schema=persistent&id=2&total_members=10&Create

***Link required

GigaSpaces.com - Legal Notice - 3rd Party Licenses - Site Map - API Docs - Forum - Downloads - Blog - White Papers - Contact Tech Writing - Gen. by Atlassian Confluence