Configuration

The following section contains details on configuration as well as samples illustrating how to use the API. For further reading on the APIs, please visist our JavaDocs.

Connecting to ScaleOut

The ScaleOut client library uses parameters in a connection string to determine how to connect to hosts in a distributed ScaleOut in-memory data grid. A connection string is supplied to the GridConnection’s static connect(String) method.

A ScaleOut in-memory data grid (also known as a distributed data grid) is a cluster of servers that work together to provide a scalable, high-performance distributed cache. A data grid can host many separate namespaces, referred to as caches, for grouping logically related objects.

A GridConnection instance represents multiplexed connections to all of the servers in a ScaleOut in-memory data grid. A GridConnection instance is thread-safe and maintains a pool of TCP connections to ScaleOut hosts. Multiple CacheBuilders should use the same GridConnection instance if they are connecting to the same ScaleOut cluster. (Since most applications only connect to a single ScaleOut cluster, most applications should only use a single GridConnection instance.)

Connection Strings

A connection string is a list of parameters delimited by a semicolon and typically takes the following form:

bootstrapGateways=ServerOne:721,ServerTwo:721;useSecure=false;maxPoolsize=16

Connection String Parameters

The following parameters can be set in a connection string.

bootstrapGateways - Required. A comma-separated list of host:port pairs pointing to ScaleOut hosts. This list is used for bootstrapping the first connection to the data grid. At least one of the hosts in the list needs to be active–the gateways are checked in order, and, once a connection is established, the current grid membership is retrieved from that server for subsequent connections.

Each bootstrapGateway entry in the comma-delimited host list consists of two values, separated by a colon:

host - Required. The address (DNS name or IP) of a system running the ScaleOut service.

Note

The DNS name needs to be resolvable from the server where the application is running.

port - Required. The TCP port used by the ScaleOut service to serve client requests (the server’s svr_port parameter). Use the host’s secure_svr_port parameter if useSecure is enabled for this data grid connection.

useSecure - Optional. Specifies whether the library will use secure, TLS-encrypted connections when communicating with servers in the ScaleOut data grid. The default value is false (disabled). Note

If enabled, the servers in the ScaleOut data grid must be configured with accept_secure set to 1 in their soss_params.txt files. Also, this in-memory data grid configuration must use the hosts’ secure_svr_port value (instead of svr_port) in each of the bootstrapGateways entries.

maxPoolSize - Optional. Sets the maximum number of TCP connections that the library may open to each ScaleOut host in the data grid. The default value is 16 connections per host, and the maximum allowed value is 128.

maxRequestRetries - Optional. Specifies the maximum number of retries that a client will make to connect to a ScaleOut server or to retry a request once connected. The default is 2 retries.

Cache Policies

When a CacheBuilder is used to create a Cache instance, custom policies can be configured. The default policies used on the cache, notably the CreatePolicy and ReadPolicy, are created by the CacheBuilder.

The following configuration parameter are availabe through the CacheBuilder.

The CacheBuilder takes as parameter in the constructor, a GridConnection (defined above), a String name to logically identify the cache, and a class representing the Key type. Alternatively, the CacheBuilder constructor takes as parameters a GridConnection, a String name, and a custom KeyEncoder<K> implementation.

timeout - The lifetime of objects in this cache, with a minimum granularity of one second. Use 00:00:00 for an infinite timeout.

Default is 00:00:00 (infinite).

If the value is not infinite, the maximum allowed timeout is 48.13:05:03 (48 days, 13 hours, 5 minutes, 3 seconds).

Timeouts for individual objects can override this setting when they are added to the cache using a custom CreatePolicy.

timeoutType - The conditions under which an object’s timeout will be reset. The value must be one of the following:

  • “Absolute” - Default. An object’s timeout is never reset.

  • “Sliding” - An object’s timeout is reset every time an object is accessed (either updated or read).

  • “ResetOnUpdate” - An object’s timeout is reset when the object is updated, but it is not reset if the object is read.

clientCacheSize - Specifies the size, in bytes, of the in-process client cache.

  • Default value is 100,000. Set to zero to disable the client cache.

preemptionPriority - The preemption priority for objects in the cache, which specifies whether the least recently accessed objects may be evicted when the ScaleOut service runs low on memory. The value must be one of the following:

  • “Normal” - Default. Objects may be removed from the cache if needed by the ScaleOut service when running under low-memory conditions.

  • “NotRemovable” - Objects must remain in the ScaleOut service until its expiration is reached or the object is explicitly removed.

geoServerPushPolicy - Specifies whether the cache participates in GeoServer Push replication. (GeoServer DR must be licensed and the ScaleOut service must be configured for GeoServer Push replication, otherwise this parameter is ignored). The value must be one of the following:

  • “AllowReplication” - Default. The cache will participate in GeoServer replication (if enabled), replicating objects to a remote ScaleOut cluster.

  • “Disabled” - GeoServer replication will not be performed for this cache.

geoServerPullPolicy - Specifies whether the cache participates in GeoServer Pull replication. (GeoServer Pro must be licensed and the ScaleOut service must be configured for GeoServer Pull replication, otherwise this parameter is ignored). The value must be one of the following:

  • “Disabled” - Default. Remote stores will not be allowed to access objects in this cache via GeoServer Pull replication.

  • “AllowRemoteAccess” - Remote access will be allowed.

geoServerCoherencyPolicy - Sets the policy for how GeoServer remote stores should refresh their proxies to objects in the cache when GeoServer Pull replication is being used. (GeoServer Pro must be licensed and the ScaleOut service must be configured for GeoServer Pull replication, otherwise this parameter is ignored). The value must be one of the following:

  • “NoAutoRefresh” - Default. Proxy objects in other stores should not be refreshed automatically.

  • “Poll” - Proxy objects will be periodically refreshed in remote stores. Use the geoServerCoherencyInterval value to specify the frequency.

  • “Notify” - Remote stores will be notified of changes to the object so they can refresh their proxy object.

geoServerCoherencyInterval - Specifies how often GeoServer remote stores will refresh their proxies to objects in the cache if the Poll policy is used with GeoServer pull replication. The default value is four minutes.

Configuring a Cache From Properties

Alternatively, a Cache can be built from a properties configuration file. The following sample illustrates how to load a Cache from a properties configuration file located in the JARs resource folder:

package com.scaleout.client.samples.caching;
import com.scaleout.client.GridConnection;
import com.scaleout.client.caching.*;
public class Main {
        public static void main(String[] args) throws Exception {
        String cacheConf = "cache.properties";
        ClassLoader loader = Thread.currentThread().getContextClassLoader();
        Properties properties = new Properties();
        try (InputStream resourceStream = loader.getResourceAsStream(cacheConf)) {
    // load the properties file
    prop.load(input);

} catch (IOException ex) {
    ex.printStackTrace();
        }
        GridConnection connection = GridConnection.connect("bootstrapGateways=server1:721,server2:721;");
        Properties properties = new Properties(
        Cache<Integer, String> cache = new CacheBuilder<Integer, String>(connection, "example", Integer.class, properties)
                        .build();
        }
}

object.timeout - The lifetime of objects in this cache, with a minimum granularity of one second. Use 00:00:00 for an infinite timeout.

Default is “0” (infinite).

The timeout value is a string that will be read in as Duration.ofSeconds();

Timeouts for individual objects can override this setting when they are added to the cache using a custom CreatePolicy.

object.timeout.type - The conditions under which an object’s timeout will be reset. The value must be one of the following:

  • “absolute” - Default. An object’s timeout is never reset.

  • “sliding” - An object’s timeout is reset every time an object is accessed (either updated or read).

  • “reset” - An object’s timeout is reset when the object is updated, but it is not reset if the object is read.

object.client.cache.size - Specifies the size, in bytes, of the in-process client cache.

  • Default value is “100000”. Set to zero to disable the client cache.

mem.preemption.priority - The preemption priority for objects in the cache, which specifies whether the least recently accessed objects may be evicted when the ScaleOut service runs low on memory. The value must be one of the following:

  • “normal” - Default. Objects may be removed from the cache if needed by the ScaleOut service when running under low-memory conditions.

  • “notremovable” - Objects must remain in the ScaleOut service until its expiration is reached or the object is explicitly removed.

geos.push.policy - Specifies whether the cache participates in GeoServer Push replication. (GeoServer DR must be licensed and the ScaleOut service must be configured for GeoServer Push replication, otherwise this parameter is ignored). The value must be one of the following:

  • “allow” - Default. The cache will participate in GeoServer replication (if enabled), replicating objects to a remote ScaleOut cluster.

  • “disabled” - GeoServer replication will not be performed for this cache.

geos.pull.policy - Specifies whether the cache participates in GeoServer Pull replication. (GeoServer Pro must be licensed and the ScaleOut service must be configured for GeoServer Pull replication, otherwise this parameter is ignored). The value must be one of the following:

  • “disabled” - Default. Remote stores will not be allowed to access objects in this cache via GeoServer Pull replication.

  • “allow” - Remote access will be allowed.

geos.coherency.policy - Sets the policy for how GeoServer remote stores should refresh their proxies to objects in the cache when GeoServer Pull replication is being used. (GeoServer Pro must be licensed and the ScaleOut service must be configured for GeoServer Pull replication, otherwise this parameter is ignored). The value must be one of the following:

  • “no” - Default. Proxy objects in other stores should not be refreshed automatically.

  • “poll” - Proxy objects will be periodically refreshed in remote stores. Use the “geos.coherency.policy.interval” value to specify the frequency.

  • “notify” - Remote stores will be notified of changes to the object so they can refresh their proxy object.

geos.coherency.policy.interval - Specifies how often GeoServer remote stores will refresh their proxies to objects in the cache if the Poll policy is used with GeoServer pull replication. The default value is four minutes. The value will be read in as Duration.ofMinutes(value);