org.infinispan.client.hotrod

Class RemoteCacheManager

java.lang.Object

org.infinispan.client.hotrod.RemoteCacheManager

All Implemented Interfaces:

BasicCacheContainer, Lifecycle

public class RemoteCacheManager
extends Object
implements BasicCacheContainer

Factory for RemoteCaches.

Lifecycle:

In order to be able to use an RemoteCache, the RemoteCacheManager must be started first: beside other things, this instantiates connections to Hot Rod server(s). Starting the RemoteCacheManager can be done either at creation by passing start==true to constructor or by using a constructor that does that for you (see C-tor documentation); or after construction by calling RemoteCacheManager.start().

This is an "expensive" object, as it manages a set of persistent TCP connections to the Hot Rod servers. It is recommended to only have one instance of this per JVM, and to cache it between calls to the server (i.e. remoteCache operations).

RemoteCacheManager.stop() needs to be called explicitly in order to release all the resources (e.g. threads, TCP connections).

Configuration:

The cache manager is configured through a Configuration object passed to the constructor (there are also "simplified" constructors that rely on default values). If migrating from a previous version of Infinispan, where Properties were used to configure the RemoteCacheManager, please use the ConfigurationBuilder.withProperties(Properties) method.

Below is the list of supported configuration elements:

• infinispan.client.hotrod.request_balancing_strategy, default = org.infinispan.client.hotrod.impl.transport.tcp.RoundRobinBalancingStrategy. For replicated (vs distributed) Hot Rod server clusters, the client balances requests to the servers according to this strategy.
• infinispan.client.hotrod.server_list, default = 127.0.0.1:11222. This is the initial list of Hot Rod servers to connect to, specified in the following format: host1:port1;host2:port2... At least one host:port must be specified.
• infinispan.client.hotrod.force_return_values, default = false. Whether or not to implicitly Flag.FORCE_RETURN_VALUE for all calls.
• infinispan.client.hotrod.tcp_no_delay, default = true. Affects TCP NODELAY on the TCP stack.
• infinispan.client.hotrod.tcp_keep_alive, default = false. Affects TCP KEEPALIVE on the TCP stack.
• infinispan.client.hotrod.ping_on_startup, default = true. If true, a ping request is sent to a back end server in order to fetch cluster's topology.
• infinispan.client.hotrod.transport_factory, default = org.infinispan.client.hotrod.impl.transport.tcp.TcpTransportFactory - controls which transport to use. Currently only the TcpTransport is supported.
• infinispan.client.hotrod.marshaller, default = org.infinispan.marshall.jboss.GenericJBossMarshaller. Allows you to specify a custom org.infinispan.marshall.Marshaller implementation to serialize and deserialize user objects. For portable serialization payloads, you should configure the marshaller to be ProtoStreamMarshaller
• infinispan.client.hotrod.async_executor_factory, default = org.infinispan.client.hotrod.impl.async.DefaultAsyncExecutorFactory. Allows you to specify a custom asynchroous executor for async calls.
• infinispan.client.hotrod.default_executor_factory.pool_size, default = 99. If the default executor is used, this configures the number of threads to initialize the executor with.
• infinispan.client.hotrod.default_executor_factory.queue_size, default = 100000. If the default executor is used, this configures the queue size to initialize the executor with.
• infinispan.client.hotrod.hash_function_impl.1, default = It uses the hash function specified by the server in the responses as indicated in ConsistentHashFactory. This specifies the version of the hash function and consistent hash algorithm in use, and is closely tied with the HotRod server version used.
• infinispan.client.hotrod.key_size_estimate, default = 64. This hint allows sizing of byte buffers when serializing and deserializing keys, to minimize array resizing.
• infinispan.client.hotrod.value_size_estimate, default = 512. This hint allows sizing of byte buffers when serializing and deserializing values, to minimize array resizing.
• infinispan.client.hotrod.socket_timeout, default = 60000 (60 seconds). This property defines the maximum socket read timeout before giving up waiting for bytes from the server.
• infinispan.client.hotrod.protocol_version, default = 2.0 .This property defines the protocol version that this client should use. Other valid values include 1.0.
• infinispan.client.hotrod.connect_timeout, default = 60000 (60 seconds). This property defines the maximum socket connect timeout before giving up connecting to the server.
• infinispan.client.hotrod.max_retries, default = 10. This property defines the maximum number of retries in case of a recoverable error. A valid value should be greater or equals to 0 (zero). Zero mean no retry.

The following properties are related to connection pooling:

• maxActive - controls the maximum number of connections per server that are allocated (checked out to client threads, or idle in the pool) at one time. When non-positive, there is no limit to the number of connections per server. When maxActive is reached, the connection pool for that server is said to be exhausted. The default setting for this parameter is -1, i.e. there is no limit.
• maxTotal - sets a global limit on the number persistent connections that can be in circulation within the combined set of servers. When non-positive, there is no limit to the total number of persistent connections in circulation. When maxTotal is exceeded, all connections pools are exhausted. The default setting for this parameter is -1 (no limit).
• maxIdle - controls the maximum number of idle persistent connections, per server, at any time. When negative, there is no limit to the number of connections that may be idle per server. The default setting for this parameter is -1.
• whenExhaustedAction - specifies what happens when asking for a connection from a server's pool, and that pool is exhausted. Possible values:
  • 0 - an exception will be thrown to the calling user
  • 1 - the caller will block (invoke waits until a new or idle connections is available.
  • 2 - a new persistent connection will be created and returned (essentially making maxActive meaningless.)
  The default whenExhaustedAction setting is 1.
• Optionally, one may configure the pool to examine and possibly evict connections as they sit idle in the pool and to ensure that a minimum number of idle connections is maintained for each server. This is performed by an "idle connection eviction" thread, which runs asynchronously. The idle object evictor does not lock the pool throughout its execution. The idle connection eviction thread may be configured using the following attributes:
  • timeBetweenEvictionRunsMillis - indicates how long the eviction thread should sleep before "runs" of examining idle connections. When non-positive, no eviction thread will be launched. The default setting for this parameter is 2 minutes
  • minEvictableIdleTimeMillis - specifies the minimum amount of time that an connection may sit idle in the pool before it is eligible for eviction due to idle time. When non-positive, no connection will be dropped from the pool due to idle time alone. This setting has no effect unless timeBetweenEvictionRunsMillis > 0. The default setting for this parameter is 1800000(30 minutes).
  • testWhileIdle - indicates whether or not idle connections should be validated by sending an TCP packet to the server, during idle connection eviction runs. Connections that fail to validate will be dropped from the pool. This setting has no effect unless timeBetweenEvictionRunsMillis > 0. The default setting for this parameter is true.
  • minIdle - sets a target value for the minimum number of idle connections (per server) that should always be available. If this parameter is set to a positive number and timeBetweenEvictionRunsMillis > 0, each time the idle connection eviction thread runs, it will try to create enough idle instances so that there will be minIdle idle instances available for each server. The default setting for this parameter is 1.

Since:

4.1

Author:

Mircea.Markus@jboss.com

Field Summary

Fields

Modifier and Type	Field and Description
static String	DEFAULT_CACHE_NAME
static String	HOTROD_CLIENT_PROPERTIES
protected ClientListenerNotifier	listenerNotifier
protected TransportFactory	transportFactory

Constructor Summary

Constructors

Constructor and Description
RemoteCacheManager() Same as RemoteCacheManager.RemoteCacheManager(boolean) and it also starts the cache.
RemoteCacheManager(boolean start) Same as RemoteCacheManager.RemoteCacheManager(java.util.Properties), but it will try to lookup the config properties in the classpath, in a file named hotrod-client.properties.
RemoteCacheManager(Configuration configuration) Create a new RemoteCacheManager using the supplied Configuration.
RemoteCacheManager(Configuration configuration, boolean start) Create a new RemoteCacheManager using the supplied Configuration.
RemoteCacheManager(Marshaller marshaller, Properties props) Deprecated.
RemoteCacheManager(Marshaller marshaller, Properties props, boolean start) Deprecated.
RemoteCacheManager(Marshaller marshaller, Properties props, boolean start, ClassLoader classLoader, ExecutorFactory asyncExecutorFactory) Deprecated.
RemoteCacheManager(Marshaller marshaller, Properties props, ClassLoader classLoader) Deprecated.
RemoteCacheManager(Marshaller marshaller, Properties props, ExecutorFactory asyncExecutorFactory) Deprecated.
RemoteCacheManager(Properties props) Deprecated.
RemoteCacheManager(Properties props, boolean start) Deprecated.
RemoteCacheManager(Properties props, boolean start, ClassLoader classLoader, ExecutorFactory asyncExecutorFactory) Deprecated.
RemoteCacheManager(Properties props, ClassLoader classLoader) Deprecated.
RemoteCacheManager(String servers) Deprecated.
RemoteCacheManager(String servers, boolean start) Deprecated.
RemoteCacheManager(String servers, boolean start, ClassLoader classLoader) Deprecated.
RemoteCacheManager(String servers, ClassLoader classLoader) Deprecated.
RemoteCacheManager(String host, int port) Deprecated.
RemoteCacheManager(String host, int port, boolean start) Deprecated.
RemoteCacheManager(String host, int port, boolean start, ClassLoader classLoader) Deprecated.
RemoteCacheManager(String host, int port, ClassLoader classLoader) Deprecated.
RemoteCacheManager(URL config) Deprecated.
RemoteCacheManager(URL config, boolean start) Deprecated.
RemoteCacheManager(URL config, boolean start, ClassLoader classLoader) Deprecated.
RemoteCacheManager(URL config, ClassLoader classLoader) Deprecated.

Method Summary

Methods

Modifier and Type	Method and Description
static byte[]	cacheNameBytes()
static byte[]	cacheNameBytes(String cacheName)
protected <K,V> NearCacheService<K,V>	createNearCacheService(NearCacheConfiguration cfg)
<K,V> RemoteCache<K,V>	getCache() Retrieves the default cache from the remote server.
<K,V> RemoteCache<K,V>	getCache(boolean forceReturnValue)
<K,V> RemoteCache<K,V>	getCache(String cacheName) Retrieves a named cache from the remote server if the cache has been defined, otherwise if the cache name is underfined, it will return null.
<K,V> RemoteCache<K,V>	getCache(String cacheName, boolean forceReturnValue)
Configuration	getConfiguration() Retrieves the configuration currently in use.
Marshaller	getMarshaller()
Properties	getProperties() Deprecated.
boolean	isStarted()
void	start() Invoked on component start
void	stop() Stop the remote cache manager, disconnecting all existing connections.

Field Detail

DEFAULT_CACHE_NAME

public static final String DEFAULT_CACHE_NAME

See Also:

Constant Field Values

HOTROD_CLIENT_PROPERTIES

public static final String HOTROD_CLIENT_PROPERTIES

See Also:

Constant Field Values

transportFactory

protected TransportFactory transportFactory

listenerNotifier

protected ClientListenerNotifier listenerNotifier

Constructor Detail

RemoteCacheManager

public RemoteCacheManager(Configuration configuration)

Create a new RemoteCacheManager using the supplied Configuration. The RemoteCacheManager will be started automatically

Parameters:

configuration - the configuration to use for this RemoteCacheManager

Since:

5.3

RemoteCacheManager

public RemoteCacheManager(Configuration configuration,
                  boolean start)

Create a new RemoteCacheManager using the supplied Configuration. The RemoteCacheManager will be started automatically only if the start parameter is true

Parameters:

configuration - the configuration to use for this RemoteCacheManager

start - whether or not to start the manager on return from the constructor.

Since:

5.3

RemoteCacheManager

@Deprecated
public RemoteCacheManager(Marshaller marshaller,
                             Properties props,
                             boolean start)

Deprecated.

Builds a remote cache manager that relies on the provided Marshaller for marshalling keys and values to be send over to the remote Infinispan cluster.

Parameters:

marshaller - marshaller implementation to be used

props - other properties

start - whether or not to start the manager on return from the constructor.

RemoteCacheManager

@Deprecated
public RemoteCacheManager(Marshaller marshaller,
                             Properties props,
                             boolean start,
                             ClassLoader classLoader,
                             ExecutorFactory asyncExecutorFactory)

Deprecated.

Builds a remote cache manager that relies on the provided Marshaller for marshalling keys and values to be send over to the remote Infinispan cluster.

Parameters:

marshaller - marshaller implementation to be used

props - other properties

start - whether or not to start the manager on return from the constructor.

RemoteCacheManager

@Deprecated
public RemoteCacheManager(Marshaller marshaller,
                             Properties props)

Deprecated.

Same as RemoteCacheManager.RemoteCacheManager(Marshaller, java.util.Properties, boolean) with start = true.

RemoteCacheManager

@Deprecated
public RemoteCacheManager(Marshaller marshaller,
                             Properties props,
                             ExecutorFactory asyncExecutorFactory)

Deprecated.

Same as RemoteCacheManager.RemoteCacheManager(Marshaller, java.util.Properties, boolean) with start = true.

RemoteCacheManager

@Deprecated
public RemoteCacheManager(Marshaller marshaller,
                             Properties props,
                             ClassLoader classLoader)

Deprecated.

Same as RemoteCacheManager.RemoteCacheManager(Marshaller, java.util.Properties, boolean) with start = true.

RemoteCacheManager

@Deprecated
public RemoteCacheManager(Properties props,
                             boolean start)

Deprecated.

Build a cache manager based on supplied properties.

RemoteCacheManager

@Deprecated
public RemoteCacheManager(Properties props,
                             boolean start,
                             ClassLoader classLoader,
                             ExecutorFactory asyncExecutorFactory)

Deprecated.

Build a cache manager based on supplied properties.

RemoteCacheManager

@Deprecated
public RemoteCacheManager(Properties props)

Deprecated.

Same as RemoteCacheManager.RemoteCacheManager(java.util.Properties, boolean), and it also starts the cache (start==true).

RemoteCacheManager

@Deprecated
public RemoteCacheManager(Properties props,
                             ClassLoader classLoader)

Deprecated.

Same as RemoteCacheManager.RemoteCacheManager(java.util.Properties, boolean), and it also starts the cache (start==true).

RemoteCacheManager

public RemoteCacheManager(boolean start)

Same as RemoteCacheManager.RemoteCacheManager(java.util.Properties), but it will try to lookup the config properties in the classpath, in a file named hotrod-client.properties. If no properties can be found in the classpath, the server tries to connect to "127.0.0.1:11222" in start.

Parameters:

start - whether or not to start the RemoteCacheManager

Throws:

HotRodClientException - if such a file cannot be found in the classpath

RemoteCacheManager

public RemoteCacheManager()

Same as RemoteCacheManager.RemoteCacheManager(boolean) and it also starts the cache.

RemoteCacheManager

@Deprecated
public RemoteCacheManager(String host,
                             int port,
                             boolean start)

Deprecated.

Creates a remote cache manager aware of the Hot Rod server listening at host:port.

Parameters:

start - whether or not to start the RemoteCacheManager.

RemoteCacheManager

@Deprecated
public RemoteCacheManager(String host,
                             int port,
                             boolean start,
                             ClassLoader classLoader)

Deprecated.

Creates a remote cache manager aware of the Hot Rod server listening at host:port.

Parameters:

start - whether or not to start the RemoteCacheManager.

RemoteCacheManager

@Deprecated
public RemoteCacheManager(String host,
                             int port)

Deprecated.

Same as RemoteCacheManager.RemoteCacheManager(String, int, boolean) with start=true.

RemoteCacheManager

@Deprecated
public RemoteCacheManager(String host,
                             int port,
                             ClassLoader classLoader)

Deprecated.

Same as RemoteCacheManager.RemoteCacheManager(String, int, boolean) with start=true.

RemoteCacheManager

@Deprecated
public RemoteCacheManager(String servers,
                             boolean start)

Deprecated.

The given string should have the following structure: "host1:port2;host:port2...". Every host:port defines a server.

RemoteCacheManager

@Deprecated
public RemoteCacheManager(String servers,
                             boolean start,
                             ClassLoader classLoader)

Deprecated.

The given string should have the following structure: "host1:port2;host:port2...". Every host:port defines a server.

RemoteCacheManager

@Deprecated
public RemoteCacheManager(String servers)

Deprecated.

Same as RemoteCacheManager.RemoteCacheManager(String, boolean), with start=true.

RemoteCacheManager

@Deprecated
public RemoteCacheManager(String servers,
                             ClassLoader classLoader)

Deprecated.

Same as RemoteCacheManager.RemoteCacheManager(String, boolean), with start=true.

RemoteCacheManager

@Deprecated
public RemoteCacheManager(URL config,
                             boolean start)

Deprecated.

Same as RemoteCacheManager.RemoteCacheManager(java.util.Properties), but it will try to lookup the config properties in supplied URL.

Parameters:

start - whether or not to start the RemoteCacheManager

Throws:

HotRodClientException - if properties could not be loaded

RemoteCacheManager

@Deprecated
public RemoteCacheManager(URL config,
                             boolean start,
                             ClassLoader classLoader)

Deprecated.

Same as RemoteCacheManager.RemoteCacheManager(java.util.Properties), but it will try to lookup the config properties in supplied URL.

Parameters:

start - whether or not to start the RemoteCacheManager

Throws:

HotRodClientException - if properties could not be loaded

RemoteCacheManager

@Deprecated
public RemoteCacheManager(URL config)

Deprecated.

Same as RemoteCacheManager.RemoteCacheManager(java.net.URL) and it also starts the cache (start==true).

Parameters:

config -

RemoteCacheManager

@Deprecated
public RemoteCacheManager(URL config,
                             ClassLoader classLoader)

Deprecated.

Same as RemoteCacheManager.RemoteCacheManager(java.net.URL) and it also starts the cache (start==true).

Parameters:

config -

Method Detail

getConfiguration

public Configuration getConfiguration()

Retrieves the configuration currently in use. The configuration object is immutable. If you wish to change configuration, you should use the following pattern:

 ConfigurationBuilder builder = new ConfigurationBuilder();
 builder.read(remoteCacheManager.getConfiguration());
 // modify builder
 remoteCacheManager.stop();
 remoteCacheManager = new RemoteCacheManager(builder.build());
 

Returns:

The configuration of this RemoteCacheManager

Since:

5.3

getProperties

@Deprecated
public Properties getProperties()

Deprecated.

Retrieves a clone of the properties currently in use. Note that making any changes to the properties instance retrieved will not affect an already-running RemoteCacheManager. If you wish to make changes to an already-running RemoteCacheManager, you should use the following pattern:

 Properties p = remoteCacheManager.getProperties();
 // update properties
 remoteCacheManager.stop();
 remoteCacheManager = new RemoteCacheManager(p);
 

Returns:

a clone of the properties used to configure this RemoteCacheManager

Since:

4.2

getCache

public <K,V> RemoteCache<K,V> getCache(String cacheName)

Retrieves a named cache from the remote server if the cache has been defined, otherwise if the cache name is underfined, it will return null.

Specified by:

getCache in interface BasicCacheContainer

Parameters:

cacheName - name of cache to retrieve

Returns:

a cache instance identified by cacheName or null if the cache name has not been defined

getCache

public <K,V> RemoteCache<K,V> getCache(String cacheName,
                              boolean forceReturnValue)

getCache

public <K,V> RemoteCache<K,V> getCache()

Retrieves the default cache from the remote server.

Specified by:

getCache in interface BasicCacheContainer

Returns:

a remote cache instance that can be used to send requests to the default cache in the server

getCache

public <K,V> RemoteCache<K,V> getCache(boolean forceReturnValue)

start

public void start()

Description copied from interface: Lifecycle

Invoked on component start

Specified by:

start in interface Lifecycle

stop

public void stop()

Stop the remote cache manager, disconnecting all existing connections. As part of the disconnection, all registered client cache listeners will be removed since client no longer can receive callbacks.

Specified by:

stop in interface Lifecycle

isStarted

public boolean isStarted()

createNearCacheService

protected <K,V> NearCacheService<K,V> createNearCacheService(NearCacheConfiguration cfg)

getMarshaller

public Marshaller getMarshaller()

cacheNameBytes

public static byte[] cacheNameBytes(String cacheName)

cacheNameBytes

public static byte[] cacheNameBytes()