Overview

The cluster can be constructed in a dynamic or a static way. The dynamic mode does not enforce you to have any files on disk, or to specify the location of the cluster members beforehand. You just need to launch a space with the appropriate cluster schema, and the number of the cluster's total members. With static mode, you are required to specify the cluster members beforehand with an existing cluster schema, or define the full cluster configuration file from scratch without using a preexisting cluster schema. You should use the space browser cluster wizard to build a static cluster configuration.

A running example for a cluster using static cluster configuration can be found at: <GigaSpaces Root>\examples\Advanced\Data_Grid\multi-site.

Dynamic Construction

This option provides maximum flexibility in terms of deployment and maintenance. You specify the cluster topology directly from the space URL used to start the space. The URL itself includes the relevant properties that allow GigaSpaces to construct the cluster configuration when the space is started. Following are the relevant URL properties you might need to use to start a cluster with the dynamic approach.

For more details on dynamic construction, refer to the following sections: Replicated Space Topology Partitioned Space Topology

schema

The schema property space defines the schema name that is used and loaded while creating the space and its container. If the space or container already has a configuration file, the requested schema is not applied. If the configuration file exists, it will overwrite the default configuration defined by the schema. When using the create URL property with java:// protocol, the system creates a container space, and uses the default space and container configuration schema file: (default-space-schema.xml and default-container-schema.xml).

For example, when specifying schema=cache, cache-space-schema.xml is used for the space configuration, and cache-container-schema.xml is used for the container configuration.

cluster_schema

The cluster_schema property specifies the cluster schema XSL file name that is used to set up a cluster configuration on the fly in memory. If the cluster_schema is used - e.g., ?cluster_schema=sync -_is replicated, GigaSpaces will use the sync_replicated-cluster-schema.xsl together with the user's inputs, such as the number of members, number of backup members, etc.

total_members

The total_members property in the space URL stands for the maximum total active spaces inside the cluster. This number is used to create the list of members participating in the cluster on the fly, based on the space name convention. The number of actual running space instances can vary dynamically between 1<=total_members.

For example:

gsInstance</b>"/./mySpace?cluster_schema=partitioned&total_members=4,2&id=1"

in case the total_members property is used in the partitioned topology. In a partitioned space, each instance contains a different segment of the total information. With this topology, data may be lost once the space is brought down or fails. To ensure the high availability of each partition, a backup instance is set per partition.

Setting up a partitioned space with two primary partitions and one backup per primary partition is done using the following setup:

Partition 1
gsInstance "/./mySpace?cluster_schema=partitioned-sync2backup&total_members=2,1&id=1" 
Partition 2
gsInstance "/./mySpace?cluster_schema=partitioned-sync2backup&total_members=2,1&id=2" 
Partition 1 backup
gsInstance "/./mySpace?cluster_schema=partitioned-sync2backup&total_members=2,1&id=1&backup_id=1" 
Partition 2 backup
gsInstance "/./mySpace?cluster_schema=partitioned-sync2backup&total_members=2,1&id=2&backup_id=1"

total_members={number of primary instances, number of backup instances per primary} - e.g., total_members=2,1, means that this cluster contains two partitions having one backup instance each.

The backup_id attribute is used to define whether the instance is a backup instance or not. If this attribute is not defined, the instance will be considered as a primary instance.

properties

The properties property allows you to use a properties file to store the URL properties, as well as space, container, and cluster properties. You may also define system properties using this file. The properties defined as part of the properties file override the schema's space, container, or cluster values that are defined in the relevant schema file.

For more details, refer to the Overwriting Default Configuration section.

gsInstance "/./mySpace?properties=myproperties"

groups

The Jini Lookup group.

id

The id attribute is used to distinguish between the different space members in the cluster. The id can take any value greater than zero. The maximum value for the id property can be the total_members value.

gsInstance"/./space?schema=cache&cluster_schema=partitioned&total_members=2&id=1&groups=gigaspaces"
gsInstance"/./space?schema=cache&cluster_schema=partitioned&total_members=2&id=1&groups=gigaspaces"

backup_id

The backup_id property is used with a partitioned space, to form the partitioned with backup topology. The backup_id property is used to define whether the instance is a backup instance or not. If this attribute is not defined, the instance will be considered as a primary space instance.

gsInstance"/./space?schema=cache&cluster_schema=partitioned-sync2backup&total_members=2,1&id=1&groups=gigaspaces" 
gsInstance"/./space?schema=cache&cluster_schema=partitioned-sync2backup&total_members=2,1&id=2&groups=gigaspaces" 
gsInstance"/./space?schema=cache&cluster_schema=partitioned-sync2backup&total_members=
2,1&id=1&backup_id=1&groups=gigaspaces" 
gsInstance"/./space?schema=cache&cluster_schema=partitioned-sync2backup&total_members=
2,1&id=2&backup_id=1&groups=gigaspaces"

useLocalCache

Starts a local cache in the client application process. The local cache is used to speed up the read operation's performance.

IJSpace space =
(IJSpace)SpaceFinder.find("jini://*/./mySpace?useLocalCache")

Static Construction with Schema

This option allows you to define the cluster members beforehand, and to use an existing cluster schema. The cluster members should be defined as part of a separate file that should be used as part of the space schema URL property.

There are scenarios where you would like to specify the cluster members beforehand and not via URL total_members and id properties. This scenario is very common in WAN deployments, where the distributed Jini Lookup Service cannot register the remote nodes for dynamic discovery due to multicast problems or security conflicts.

To achieve this, you should create a cluster members configuration file called xxx-cluster.xml in the /config folder, and specify this cluster members file as part of the space schema file's <config-url> property.

The following demonstrates the cluster members configuration file structure with 3 nodes using the async_replicated cluster schema topology. mySpace is the space name and mySpace-container<id> is the container name. machine1 is the host:port combination.

<?xml version="1.0" encoding="UTF-8"?>
<cluster-config>
      <cluster-schema-name>async_replicated</cluster-schema-name>
      <cluster-name>My_Cluster</cluster-name>
      <dist-cache>
                  <config-name></config-name>
      </dist-cache>
      <jms>
                  <config-name></config-name>
      </jms>
      <cluster-members>
                  <member>
                              <member-name>mySpace_container1:mySpace</member-name>
                              <member-url>rmi://machine1/mySpace_container1/mySpace</member-url>
                  </member>
                  <member>
                              <member-name>mySpace_container2:mySpace</member-name>
                              <member-url>rmi://machine2/mySpace_container2/mySpace</member-url>
                  </member>
                  <member>
                              <member-name>mySpace_container3:mySpace</member-name>
                              <member-url>rmi://machine3/mySpace_container3/mySpace</member-url>
                  </member>
      </cluster-members>
</cluster-config>

Element	Description	Default Value
<cluster-schema-name>	This property instructs the system to use the cluster schema file to construct the cluster topology. This may be partitioned, sync_replicated, or any other user-defined xsl file name, located in the space VM classpath, under a folder called /config/schemas.
<cluster-name>	The cluster name. Used to identify and locate the cluster.
<member-name>	Each space node is identified by a unique name. The <member-name> indicates the cluster node name. There should be a unique member name for each cluster node, meaning you can't have the same <member-name> value for several cluster nodes. The <member-name> value format should be: Container Name:Space Name.
<member-url>	The <member-url> tag includes the space URL. In WAN environments, you may need to specify the machine's IP instead of the machine's host name. For more details on the URL's structure, refer to the Space URL section.

Space Cluster Configuration

The space schema file used to start the space should include the following:

<cluster>
     <enabled>true</enabled>
     <config-url>/config/myTopology</config-url>

As a convention, it must start with /config/, following with the prefix cluster members XML file name. For example, if your cluster members configuration file name is myTopology-cluster.xml, you should have the following as the <cluster-url> value:

<config-url>/config/myTopology</config-url>

or you can use the system property and define:

<cluster>
    <enabled>${com.gs.cluster.cluster_enabled}</enabled>
    <config-url>${com.gs.cluster.config-url}</config-url>

with the -Dcom.gs.cluster.cluster_enabled=true and -Dcom.gs.cluster.config-url=/config/myTopology system properties for the JVM running the spaces.

In this case, use only the space schema property as part of the space URL. You do not need the cluster_schema property. The cluster schema will be retrieved from the cluster member file.

Static Construction without Schema

This option allows you to specify a fixed cluster members list together with cluster replication, load-balancing, and failover groups in the same configuration file. The space schema file should be configured to use this cluster configuration file. In this case, the cluster configuration file should be accessible to all cluster space members.

You can copy the configuration file to the local directory of each space server, but the drawback is that you have to distribute it yourself. You can put it in a shared network directory, or on a web server, but you must ensure that this location is available at run time to every machine running a space in the cluster.

A better option is to place the cluster configuration file on more than one central server (for example: two web servers) and provide alternative URLs (multiple URLs separated with ;) when creating the space. If a space cannot access the configuration file using one URL, it tries the others.

In any case, there should be a single logical copy of the cluster configuration file (or in other words, all physical copies of the configuration should be identical), to avoid any conflicts.
In general, all source/target pairs utilize common replication parameters. You can override the common replication parameters by using the replication transmission matrix to define different replication modes, replication filters, and specific operations to be replicated per source or target pair.

The example below demonstrates a cluster configuration file that includes both members and cluster replication groups:

<cluster-config>
       <cluster-name>replication-example</cluster-name>
       <cluster-members>
              <member>
                    <member-name>container1:sp1</member-name>
                    <member-url>rmi://localhost/container1/sp1</member-url>
              </member>
              <member>
                    <member-name>container2:sp2</member-name>
                    <member-url>rmi://localhost/container2/sp2</member-url>
              </member>
       </cluster-members>
       <groups>
              <group>
                    <group-name>repl-group</group-name>
                    <group-members>
                           <member>
                                  <member-name>container1:sp1</member-name>
                           </member>
                           <member>
                                  <member-name>container2:sp2</member-name>
                           </member>
                    </group-members>
<repl-policy>
                          <replication-mode>async</replication-mode>
                           <policy-type>full-replication</policy-type>
                           <recovery>true</recovery>
                           <replicate-notify-templates>false</replicate-notify-templates>
                           <trigger-notify-templates>true</trigger-notify-templates>
                           <repl-find-timeout>5000</repl-find-timeout>
                           <repl-find-report-interval>30000</repl-find-report-interval>
                            <repl-original-state>false</repl-original-state>
                          <communication-mode>unicast</communication-mode>                     
                          <redo-log-capacity>-1</redo-log-capacity>
                           <async-replication>
                                   <sync-on-commit>false</sync-on-commit>
                                   <sync-on-commit-timeout>300000</sync-on-commit-timeout>
                                   <repl-chunk-size>500</repl-chunk-size>
                                   <repl-interval-millis>3000</repl-interval-millis>
                                   <repl-interval-opers>500</repl-interval-opers>
                           </async-replication>
                           <sync-replication>
                                   <todo-queue-timeout>1500</todo-queue-timeout>
                                   <unicast>
                                           <min-work-threads>4</min-work-threads>
                                           <max-work-threads>16</max-work-threads>
                                   </unicast>
                                   <multicast>
                                           <ip-group>224.0.0.1</ip-group>
                                           <port>28672</port>
                                           <ttl>4</ttl>
                                           <min-work-threads>4</min-work-threads>
                                           <max-work-threads>16</max-work-threads>
                                   </multicast>
                           </sync-replication>
                    </repl-policy>
              </group>
       </groups>
</cluster-config>

The GigaSpaces Browser allows you to build static cluster configuration files very easily.

For more details, refer to the Creating Static Cluster section.

When deploying a clustered space using static configuration without the cluster schema, you must supply the cluster configuration file as a parameter of the createSpace command, or enter the path to the configuration file in the space's settings in the GigaSpaces Browser (see Creating a space).

You may supply more than one path. This is useful if you stored the cluster configuration file in multiple directories which are accessible by the space.

When a space is initialized, it follows this cluster configuration URL, parses the configuration file, and builds an internal representation of it in memory.