Overriding Default Configuration

Added by Gershon Diner, last edited by Uri Cohen on Jun 28, 2009  (view change)
Search XAP 7.0
Searching XAP 7.0.X Documentation
Browse XAP 7.0
Quick Start Guide
Product Overview
Programmer's Guide
Administrator's Guide
Offline Documentation

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

                                                              

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.

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 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.
    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.

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
IMPORTANT: This is an old version of GigaSpaces XAP. Click here for the latest version.

Labels

 
(None)