public class ClientCacheFactory extends Object
client cache
and connect to one or more GemFire Cache Servers. If the application wants to connect to GemFire as a peer it should use CacheFactory
instead.
Once the factory has been configured using its set* methods you produce a ClientCache
by calling the create()
method.
The
"cache-xml-file"
property can be used to specify a cache.xml file to initialize the cache with.
The contents of this file must comply with the
"doc-files/cache8_0.dtd"
file and the top level element must be a client-cache
element.
Client connections are managed through connection pools
. ClientCacheFactory creates a single pool to use by default on the cache it creates. ClientCacheFactory can also be used to configure the default connection pool using its setPool*
and addPool*
methods. In most cases, the defaults used by this implementation will suffice. For the default pool attributes see PoolFactory
.
If no pool is configured and a pool was not declared in cache.xml or created using PoolManager
then a default one will be created that connects to a server on the default cache server port and local host. If multiple pools are declared in cache.xml or created by the PoolFactory then no default pool will exist and ClientRegionFactory.setPoolName
will need to be called on each region created.
To get the existing unclosed singleton client cache instance call getAnyInstance()
.
The following examples illustrate bootstrapping the client cache using region shortcuts:
Example 1: Connect to a CacheServer on the default host and port and access a region "customers"
ClientCache c = new ClientCacheFactory().create(); Region r = c.createClientRegionFactory(PROXY).create("customers"); // The PROXY shortcut tells GemFire to route all requests to the servers //. i.e. there is no local cachingExample 2: Connect using the GemFire locator and create a local LRU cache
ClientCache c = new ClientCacheFactory() .addPoolLocator(host, port) .create(); Region r = c.createClientRegionFactory(CACHING_PROXY_HEAP_LRU) .create("customers"); // The local LRU "customers" data region will automatically start evicting, by default, at 80% heap utilization thresholdExample 3: Access the query service
QueryService qs = new ClientCacheFactory().create().getQueryService();Example 4: Construct the client cache region declaratively in cache.xml
<!DOCTYPE client-cache PUBLIC "-//GemStone Systems, Inc.//GemFire Declarative Caching 6.5//EN" "http://www.gemstone.com/dtd/cache8_0.dtd"> <client-cache> <pool name="myPool"> <locator host="hostName" port="10334"/> </pool> <region name="myRegion" refid="PROXY"/> <!-- you can override or add to the PROXY attributes by adding a region-attributes sub element here --> </client-cache>Now, create the cache telling it to read your cache.xml file:
ClientCache c = new ClientCacheFactory() .set("cache-xml-file", "myCache.xml") .create(); Region r = c.getRegion("myRegion");
For a complete list of all client region shortcuts see ClientRegionShortcut
.
Applications that need to explicitly control the individual region attributes can do this declaratively in XML or using API.
Example 5: Define custom region attributes for persistence in XML and create region using API. Define new region attributes with ID "MYAPP_CACHING_PROXY_MEM_LRU" that overrides the "CACHING_PROXY" shortcut
<!DOCTYPE client-cache PUBLIC "-//GemStone Systems, Inc.//GemFire Declarative Caching 8.0//EN" "http://www.gemstone.com/dtd/cache8_0.dtd"> <client-cache> <!-- now create a named region attributes that uses the CACHING_PROXY shortcut and adds a memory LRU limited to 900 megabytes --> <region-attributes id="MYAPP_CACHING_PROXY_MEM_LRU" refid="CACHING_PROXY" > <lru-memory-size maximum="900"/> </region-attributes> </client-cache>Now, create the data region in the client cache using this new attributes ID.
ClientCache c = new ClientCacheFactory() .set("cache-xml-file", "myCache.xml") .addPoolLocator(host, port) .create(); Region r = c.createClientRegionFactory("MYAPP_CACHING_PROXY_MEM_LRU").create("customers");
Constructor and Description |
---|
ClientCacheFactory()
Creates a new client cache factory.
|
ClientCacheFactory(Properties props)
Create a new client cache factory given the initial gemfire properties.
|
Modifier and Type | Method and Description |
---|---|
ClientCacheFactory |
addPoolLocator(String host,
int port)
Add a locator, given its host and port, to this factory.
|
ClientCacheFactory |
addPoolServer(String host,
int port)
Add a server, given its host and port, to this factory.
|
ClientCache |
create()
Create a singleton client cache.
|
static ClientCache |
getAnyInstance()
Gets an arbitrary open instance of
ClientCache produced by an
earlier call to create() . |
static String |
getVersion()
Returns the version of the cache implementation.
|
ClientCacheFactory |
set(String name,
String value)
Sets a gemfire property that will be used when creating the ClientCache.
|
ClientCacheFactory |
setPdxDiskStore(String diskStoreName)
Set the disk store that is used for PDX meta data.
|
ClientCacheFactory |
setPdxIgnoreUnreadFields(boolean ignore)
Control whether pdx ignores fields that were unread during deserialization.
|
ClientCacheFactory |
setPdxPersistent(boolean isPersistent)
Control whether the type metadata for PDX objects is persisted to disk.
|
ClientCacheFactory |
setPdxReadSerialized(boolean pdxReadSerialized)
Sets the object preference to PdxInstance type.
|
ClientCacheFactory |
setPdxSerializer(PdxSerializer serializer)
Set the PDX serializer for the cache.
|
ClientCacheFactory |
setPoolFreeConnectionTimeout(int connectionTimeout)
Sets the free connection timeout for this pool.
|
ClientCacheFactory |
setPoolIdleTimeout(long idleTimeout)
Set the amount of time a connection can be idle before expiring the connection.
|
ClientCacheFactory |
setPoolLoadConditioningInterval(int loadConditioningInterval)
Sets the load conditioning interval for this pool.
|
ClientCacheFactory |
setPoolMaxConnections(int maxConnections)
Set the max number of client to server connections that the pool will create.
|
ClientCacheFactory |
setPoolMinConnections(int minConnections)
Set the minimum number of connections to keep available at all times.
|
ClientCacheFactory |
setPoolMultiuserAuthentication(boolean enabled)
If set to
true then the created pool can be used by multiple
users. |
ClientCacheFactory |
setPoolPingInterval(long pingInterval)
How often to ping servers to verify that they are still alive.
|
ClientCacheFactory |
setPoolPRSingleHopEnabled(boolean enabled)
By default setPRSingleHopEnabled is
true
in which case the client is aware of the location of partitions on servers hosting
regions with
DataPolicy.PARTITION . |
ClientCacheFactory |
setPoolReadTimeout(int timeout)
Sets the number of milliseconds to wait for a response from a server before
timing out the operation and trying another server (if any are available).
|
ClientCacheFactory |
setPoolRetryAttempts(int retryAttempts)
Set the number of times to retry a request after timeout/exception.
|
ClientCacheFactory |
setPoolServerGroup(String group)
Configures the group that all servers this pool connects to must belong to.
|
ClientCacheFactory |
setPoolSocketBufferSize(int bufferSize)
Sets the socket buffer size for each connection made in this pool.
|
ClientCacheFactory |
setPoolStatisticInterval(int statisticInterval)
How often to send client statistics to the server.
|
ClientCacheFactory |
setPoolSubscriptionAckInterval(int ackInterval)
Sets the interval in milliseconds
to wait before sending acknowledgements to the cache server for
events received from the server subscriptions.
|
ClientCacheFactory |
setPoolSubscriptionEnabled(boolean enabled)
If set to
true then the created pool will have server-to-client
subscriptions enabled. |
ClientCacheFactory |
setPoolSubscriptionMessageTrackingTimeout(int messageTrackingTimeout)
Sets the messageTrackingTimeout attribute which is the time-to-live period, in
milliseconds, for subscription events the client has received from the server.
|
ClientCacheFactory |
setPoolSubscriptionRedundancy(int redundancy)
Sets the redundancy level for this pools server-to-client subscriptions.
|
ClientCacheFactory |
setPoolThreadLocalConnections(boolean threadLocalConnections)
Sets the thread local connections policy for this pool.
|
public ClientCacheFactory()
public ClientCacheFactory(Properties props)
props
- The initial gemfire properties to be used.
These properties can be overridden using the set(java.lang.String, java.lang.String)
method
For a full list of valid gemfire properties see DistributedSystem
.public ClientCacheFactory set(String name, String value)
DistributedSystem
.name
- the name of the gemfire propertyvalue
- the value of the gemfire propertypublic ClientCache create()
While creating the cache instance any declarative cache configuration (cache.xml) is processed and used to initialize the created cache.
Note that the cache that is produced is a singleton. Before a different instance
can be produced the old one must be closed
.
IllegalStateException
- if a client cache already exists and it
is not compatible with this factory's configuration.public ClientCacheFactory setPoolFreeConnectionTimeout(int connectionTimeout)
AllConnectionsInUseException
. If max connections
is not set this setting has no effect.connectionTimeout
- the connection timeout in millisecondsthis
IllegalArgumentException
- if connectionTimeout
is less than or equal to 0
.setPoolMaxConnections(int)
public ClientCacheFactory setPoolLoadConditioningInterval(int loadConditioningInterval)
A value of -1
disables load conditioning
loadConditioningInterval
- the connection lifetime in millisecondsthis
IllegalArgumentException
- if connectionLifetime
is less than -1
.public ClientCacheFactory setPoolSocketBufferSize(int bufferSize)
bufferSize
- the size of the socket buffers used for reading and
writing on each connection in this pool.this
IllegalArgumentException
- if bufferSize
is less than or equal to 0
.public ClientCacheFactory setPoolThreadLocalConnections(boolean threadLocalConnections)
true
then any time a thread goes to use a connection
from this pool it will check a thread local cache and see if it already
has a connection in it. If so it will use it. If not it will get one from
this pool and cache it in the thread local. This gets rid of thread contention
for the connections but increases the number of connections the servers see.
If false
then connections are returned to the pool as soon
as the operation being done with the connection completes. This allows
connections to be shared amonst multiple threads keeping the number of
connections down.
threadLocalConnections
- if true
then enable thread local
connections.this
public ClientCacheFactory setPoolReadTimeout(int timeout)
timeout
- number of milliseconds to wait for a response from a serverthis
IllegalArgumentException
- if timeout
is less than 0
.public ClientCacheFactory setPoolMinConnections(int minConnections)
0
then connections will not be made until an actual operation
is done that requires client-to-server communication.minConnections
- the initial number of connections
this pool will create.this
IllegalArgumentException
- if minConnections
is less than 0
.public ClientCacheFactory setPoolMaxConnections(int maxConnections)
maxConnections
- the maximum number of connections in the pool.
this pool will create. -1 indicates that there is no maximum number of connectionsthis
IllegalArgumentException
- if maxConnections
is less than minConnections
.setPoolFreeConnectionTimeout(int)
public ClientCacheFactory setPoolIdleTimeout(long idleTimeout)
setPoolMinConnections(int)
, connections which have been idle
for longer than the idleTimeout will be closed.idleTimeout
- The amount of time in milliseconds that an idle connection
should live before expiring. -1 indicates that connections should never expire.this
IllegalArgumentException
- if idleTimout
is less than -1
.public ClientCacheFactory setPoolRetryAttempts(int retryAttempts)
retryAttempts
- The number of times to retry a request
after timeout/exception. -1 indicates that a request should be
tried against every available server before failingthis
IllegalArgumentException
- if idleTimout
is less than -1
.public ClientCacheFactory setPoolPingInterval(long pingInterval)
pingInterval
- The amount of time in milliseconds between
pings.this
IllegalArgumentException
- if pingInterval
is less than or equal to 0
.CacheServer.setMaximumTimeBetweenPings(int)
public ClientCacheFactory setPoolStatisticInterval(int statisticInterval)
gfmon
to monitor clients.
A value of -1
disables the sending of client statistics
to the server.
statisticInterval
- The amount of time in milliseconds between
sends of client statistics to the server.this
IllegalArgumentException
- if statisticInterval
is less than -1
.public ClientCacheFactory setPoolServerGroup(String group)
group
- the server group that this pool will connect to.
If null
or ""
then all servers will be connected to.this
public ClientCacheFactory addPoolLocator(String host, int port)
host
- the host name or ip address that the locator is listening on.port
- the port that the locator is listening onthis
IllegalArgumentException
- if host
is an unknown host
according to InetAddress.getByName(String)
or if port is outside
the valid range of [1..65535] inclusive.IllegalStateException
- if a server has already been added
to this factory.public ClientCacheFactory addPoolServer(String host, int port)
host
- the host name or ip address that the server is listening on.port
- the port that the server is listening onthis
IllegalArgumentException
- if host
is an unknown host
according to InetAddress.getByName(String)
or if port is outside
the valid range of [1..65535] inclusive.IllegalStateException
- if a locator has already been added
to this factory.public ClientCacheFactory setPoolSubscriptionEnabled(boolean enabled)
true
then the created pool will have server-to-client
subscriptions enabled.
If set to false
then all Subscription*
attributes
are ignored at create time.this
public ClientCacheFactory setPoolSubscriptionRedundancy(int redundancy)
0
then no redundant copies will be kept on the servers.
Otherwise an effort will be made to maintain the requested number of
copies of the server-to-client subscriptions. At most one copy per server will
be made up to the requested level.redundancy
- the number of redundant servers for this client's subscriptions.this
IllegalArgumentException
- if redundancyLevel
is less than -1
.public ClientCacheFactory setPoolSubscriptionMessageTrackingTimeout(int messageTrackingTimeout)
messageTrackingTimeout
- number of milliseconds to set the timeout to.this
IllegalArgumentException
- if messageTrackingTimeout
is less than or equal to 0
.public ClientCacheFactory setPoolSubscriptionAckInterval(int ackInterval)
ackInterval
- number of milliseconds to wait before sending event
acknowledgements.this
IllegalArgumentException
- if ackInterval
is less than or equal to 0
.public ClientCacheFactory setPoolPRSingleHopEnabled(boolean enabled)
true
in which case the client is aware of the location of partitions on servers hosting
regions
with
DataPolicy.PARTITION
.
Using this information, the client routes the client cache operations
directly to the server which is hosting the required partition for the
cache operation using a single network hop.
This mode works best
when setPoolMaxConnections(int)
is set
to -1
which is the default.
This mode causes the client to have more connections to the servers.
If setPRSingleHopEnabled is false
the client may need to do an extra network hop on servers
to go to the required partition for that cache operation.
The client will use fewer network connections to the servers.
Caution: for partition
regions
with
local-max-memory
equal to zero, no cache operations mentioned above will be routed to those
servers as they do not host any partitions.
public ClientCacheFactory setPoolMultiuserAuthentication(boolean enabled)
true
then the created pool can be used by multiple
users. proxies
. No client side storage is allowed.this
public static String getVersion()
String
public static ClientCache getAnyInstance()
ClientCache
produced by an
earlier call to create()
.CacheClosedException
- if a cache has not been created
or the only created one is closed
IllegalStateException
- if the cache was created by CacheFactory instead
of ClientCacheFactorypublic ClientCacheFactory setPdxReadSerialized(boolean pdxReadSerialized)
PdxInstance
will be returned instead of the actual domain class.
The PdxInstance is an interface that provides run time access to
the fields of a PDX without deserializing the entire PDX.
The PdxInstance implementation is a light weight wrapper
that simply refers to the raw bytes of the PDX that are kept
in the cache. Using this method applications can choose to
access PdxInstance instead of Java object.
Note that a PdxInstance is only returned if a serialized PDX is found in the cache. If the cache contains a deserialized PDX, then a domain class instance is returned instead of a PdxInstance.
pdxReadSerialized
- true to prefer PdxInstancePdxInstance
public ClientCacheFactory setPdxSerializer(PdxSerializer serializer)
serializer
- the serializer to usePdxSerializer
public ClientCacheFactory setPdxDiskStore(String diskStoreName)
diskStoreName
- the name of the disk store to use
for the PDX metadata.public ClientCacheFactory setPdxPersistent(boolean isPersistent)
isPersistent
- true if the metadata should be persistentpublic ClientCacheFactory setPdxIgnoreUnreadFields(boolean ignore)
You should only set this attribute to true
if you know this member
will only be reading cache data. In this use case you do not need to pay the cost
of preserving the unread fields since you will never be reserializing pdx data.
ignore
- true
if fields not read during pdx deserialization should be ignored;
false
, the default, if they should be preserved.Copyright © 1997-2017 Pivotal Software, Inc. All rights reserved.