GemFire 5.7.1

com.gemstone.gemfire.cache
Interface Cache


public interface Cache

Caches are obtained from static methods on the CacheFactory class.

When a cache is created a DistributedSystem must be specified. This system tells the cache where to find other caches on the network and how to communicate with them. The system can also specify a "cache-xml-file" property which will cause this cache to be initialized with the contents of that file. The contents must comply with the "doc-files/cache5_0.dtd" file.

When a cache will no longer be used it should be closed. Once it is closed any attempt to use it or any Region obtained from it will cause a CacheClosedException to be thrown.

A cache can have multiple root regions, each with a different name.

Since:
2.0
See Also:
AttributesMutator

Method Summary
 BridgeServer addBridgeServer()
          Deprecated. as of 5.7 use addCacheServer() instead.
 CacheServer addCacheServer()
          Creates a new cache server, with the default configuration, that will allow clients to access this cache.
 GatewayHub addGatewayHub(String id, int port)
          Creates a new GatewayHub with the default configuration and adds it to the collection of GatewayHubs.
 void close()
          Terminates this object cache and releases all the resources.
 void close(boolean keepalive)
          Terminates this object cache and releases all the resources.
 Region createRegion(String name, RegionAttributes aRegionAttributes)
          Creates a region using the specified RegionAttributes.
 Region createVMRegion(String name, RegionAttributes aRegionAttributes)
          Deprecated. as of GemFire 5.0, use createRegion(java.lang.String, com.gemstone.gemfire.cache.RegionAttributes) instead.
 List getBridgeServers()
          Deprecated. as of 5.7 use getCacheServers() instead.
 List getCacheServers()
          Returns a collection of all of the CacheServers that can serve the contents of this Cache to clients.
 CacheTransactionManager getCacheTransactionManager()
          Get the CacheTransactionManager instance for this Cache.
 boolean getCopyOnRead()
          Indicates whether the "copy on read" is enabled for this Cache.
 DistributedSystem getDistributedSystem()
          Returns the distributed system that this cache was created with.
 GatewayHub getGatewayHub()
          Deprecated. as of GemFire 5.1, use getGatewayHubs().get(0) instead.
 GatewayHub getGatewayHub(String id)
          Returns a GatewayHub with the given id.
 List getGatewayHubs()
          Returns a list of all of the GatewayHubs.
 Context getJNDIContext()
          Returns the JNDI context associated with the Cache.
 int getLockLease()
          Gets the length, in seconds, of distributed lock leases obtained by this cache.
 int getLockTimeout()
          Gets the number of seconds a cache operation will wait to obtain a distributed lock lease.
 LogWriter getLogger()
          Gets the logging object for GemFire.
 int getMessageSyncInterval()
          Gets the frequency (in seconds) at which a message will be sent by the primary cache-server to all the secondary cache-server nodes to remove the events which have already been dispatched from the queue.
 String getName()
          Returns the name of this cache.
 QueryService getQueryService()
          Return the QueryService for this cache.
 Region getRegion(String path)
          Return the existing region (or subregion) with the specified path that already exists or is already mapped into the cache.
 RegionAttributes getRegionAttributes(String id)
          Returns the RegionAttributes with the given id or null if no RegionAttributes with that id exists.
 int getSearchTimeout()
          Gets the number of seconds a cache get operation can spend searching for a value before it times out.
 LogWriter getSecurityLogger()
          Gets the security logging object for GemFire.
 boolean isClosed()
          Indicates if this cache has been closed.
 boolean isServer()
          Returns whether or not this cache resides in a "cache server" VM.
 Map listRegionAttributes()
          Returns an unmodifiable mapping of ids to region attributes.
 void loadCacheXml(InputStream is)
          Loads the cache configuration described in a declarative caching XML file into this cache.
 void readyForEvents()
          Notifies the server that this client is ready to receive updates.
 Set rootRegions()
          Returns unmodifiable set of root regions in the cache.
 void setCopyOnRead(boolean copyOnRead)
          Sets the "copy on read" feature for Cache read operations.
 GatewayHub setGatewayHub(String id, int port)
          Deprecated. as of GemFire 5.1, use addGatewayHub(java.lang.String, int) instead.
 void setIsServer(boolean isServer)
          Sets whether or not this Cache resides in a long-running "cache server" VM.
 void setLockLease(int seconds)
          Sets the length, in seconds, of distributed lock leases obtained by this cache.
 void setLockTimeout(int seconds)
          Sets the number of seconds a cache operation may wait to obtain a distributed lock lease before timing out.
 void setMessageSyncInterval(int seconds)
          Sets the frequency (in seconds) at which a message will be sent by the primary cache-server node to all the secondary cache-server nodes to remove the events which have already been dispatched from the queue.
 void setRegionAttributes(String id, RegionAttributes attrs)
          Sets the id of the given RegionAttributes.
 void setSearchTimeout(int seconds)
          Sets the number of seconds a cache get operation can spend searching for a value.
 

Method Detail

getName

String getName()
Returns the name of this cache. This method does not throw CacheClosedException if the cache is closed.

Returns:
the String name of this cache

isClosed

boolean isClosed()
Indicates if this cache has been closed. After a new cache object is created, this method returns false; After the close is called on this cache object, this method returns true. This method does not throw CacheClosedException if the cache is closed.

Returns:
true, if this cache is closed; false, otherwise

getDistributedSystem

DistributedSystem getDistributedSystem()
Returns the distributed system that this cache was created with. This method does not throw CacheClosedException if the cache is closed.


getQueryService

QueryService getQueryService()
Return the QueryService for this cache.

Since:
4.0 The Query operations performed using this QueryService instance will be executed on the local cache. Applications using client server topology and wanting to execute queries on the server from the client should obtain the QueryService instance from the Pool.
See Also:
Pool.getQueryService()

close

void close()
Terminates this object cache and releases all the resources. Calls Region.close() on each region in the cache. After this cache is closed, any further method call on this cache or any region object will throw CacheClosedException, unless otherwise noted.

Throws:
CacheClosedException - if the cache is already closed.

close

void close(boolean keepalive)
Terminates this object cache and releases all the resources. Calls Region.close() on each region in the cache. After this cache is closed, any further method call on this cache or any region object will throw CacheClosedException, unless otherwise noted.

Parameters:
keepalive - whether the server should keep the durable client's queues alive for the timeout period
Throws:
CacheClosedException - if the cache is already closed.

createVMRegion

Region createVMRegion(String name,
                      RegionAttributes aRegionAttributes)
                      throws RegionExistsException,
                             TimeoutException
Deprecated. as of GemFire 5.0, use createRegion(java.lang.String, com.gemstone.gemfire.cache.RegionAttributes) instead.

Creates a VM region using the specified RegionAttributes.

Parameters:
name - the name of the region to create
aRegionAttributes - the attributes of the root region
Returns:
the region object
Throws:
RegionExistsException - if a region is already in this cache
LeaseExpiredException - if lease expired on distributed lock for Scope.GLOBAL
TimeoutException - if timed out getting distributed lock for Scope.GLOBAL
CacheClosedException - if the cache is closed
IllegalStateException - If the supplied RegionAttributes violate the region creation constraints with a region of the same name in another cache in the distributed system

createRegion

Region createRegion(String name,
                    RegionAttributes aRegionAttributes)
                    throws RegionExistsException,
                           TimeoutException
Creates a region using the specified RegionAttributes.

Parameters:
name - the name of the region to create
aRegionAttributes - the attributes of the root region
Returns:
the region object
Throws:
RegionExistsException - if a region is already in this cache
LeaseExpiredException - if lease expired on distributed lock for Scope.GLOBAL
TimeoutException - if timed out getting distributed lock for Scope.GLOBAL
CacheClosedException - if the cache is closed
IllegalStateException - If the supplied RegionAttributes violate the region creation constraints with a region of the same name in another cache in the distributed system
Since:
5.0

getRegion

Region getRegion(String path)
Return the existing region (or subregion) with the specified path that already exists or is already mapped into the cache. Whether or not the path starts with a forward slash it is interpreted as a full path starting at a root.

Parameters:
path - the path to the region
Returns:
the Region or null if not found
Throws:
IllegalArgumentException - if path is null, the empty string, or "/"

rootRegions

Set rootRegions()
Returns unmodifiable set of root regions in the cache. This set is a snapshot; it is not backed by the Cache.

Returns:
a Set of regions

getLogger

LogWriter getLogger()
Gets the logging object for GemFire. This method does not throw CacheClosedException if the cache is closed.

Returns:
the logging object

getSecurityLogger

LogWriter getSecurityLogger()
Gets the security logging object for GemFire. This method does not throw CacheClosedException if the cache is closed.

Returns:
the security logging object

getLockTimeout

int getLockTimeout()
Gets the number of seconds a cache operation will wait to obtain a distributed lock lease. This method does not throw CacheClosedException if the cache is closed.


setLockTimeout

void setLockTimeout(int seconds)
Sets the number of seconds a cache operation may wait to obtain a distributed lock lease before timing out.

Throws:
IllegalArgumentException - if seconds is less than zero

getMessageSyncInterval

int getMessageSyncInterval()
Gets the frequency (in seconds) at which a message will be sent by the primary cache-server to all the secondary cache-server nodes to remove the events which have already been dispatched from the queue.

Returns:
The time interval in seconds

setMessageSyncInterval

void setMessageSyncInterval(int seconds)
Sets the frequency (in seconds) at which a message will be sent by the primary cache-server node to all the secondary cache-server nodes to remove the events which have already been dispatched from the queue.

Parameters:
seconds - - the time interval in seconds
Throws:
IllegalArgumentException - if seconds is less than zero

getLockLease

int getLockLease()
Gets the length, in seconds, of distributed lock leases obtained by this cache. This method does not throw CacheClosedException if the cache is closed.


setLockLease

void setLockLease(int seconds)
Sets the length, in seconds, of distributed lock leases obtained by this cache.

Throws:
IllegalArgumentException - if seconds is less than zero.

getSearchTimeout

int getSearchTimeout()
Gets the number of seconds a cache get operation can spend searching for a value before it times out. The search includes any time spent loading the object. When the search times out it causes the get to fail by throwing an exception. This method does not throw CacheClosedException if the cache is closed.


setSearchTimeout

void setSearchTimeout(int seconds)
Sets the number of seconds a cache get operation can spend searching for a value.

Throws:
IllegalArgumentException - if seconds is less than zero

addBridgeServer

BridgeServer addBridgeServer()
Deprecated. as of 5.7 use addCacheServer() instead.

Creates a new bridge server with the default configuration.

Since:
4.0
See Also:
BridgeLoader, BridgeWriter

addCacheServer

CacheServer addCacheServer()
Creates a new cache server, with the default configuration, that will allow clients to access this cache.

For the default configuration see the constants in CacheServer.

Since:
5.7
See Also:
com.gemstone.gemfire.cache.server

getBridgeServers

List getBridgeServers()
Deprecated. as of 5.7 use getCacheServers() instead.

Returns a collection of all of the BridgeServers that can serve the contents of this Cache.

Since 5.7 this method returns a ListCollection.

Since:
4.0
See Also:
addBridgeServer()

getCacheServers

List getCacheServers()
Returns a collection of all of the CacheServers that can serve the contents of this Cache to clients.

Since:
5.7
See Also:
addCacheServer()

setGatewayHub

GatewayHub setGatewayHub(String id,
                         int port)
Deprecated. as of GemFire 5.1, use addGatewayHub(java.lang.String, int) instead.

Creates a new GatewayHub with the default configuration.

Parameters:
id - The id of the GatewayHub
port - The port of the GatewayHub
Since:
4.2
See Also:
Gateway

addGatewayHub

GatewayHub addGatewayHub(String id,
                         int port)
Creates a new GatewayHub with the default configuration and adds it to the collection of GatewayHubs.

Parameters:
id - The id of the GatewayHub
port - The port of the GatewayHub
Since:
5.1
See Also:
Gateway
Note: Early Access. Please consult GemStone technical support for assistance with this functionality.

getGatewayHub

GatewayHub getGatewayHub()
Deprecated. as of GemFire 5.1, use getGatewayHubs().get(0) instead.

Gets the existing GatewayHub.

See Also:
Gateway

getGatewayHubs

List getGatewayHubs()
Returns a list of all of the GatewayHubs.

Since:
5.1
See Also:
addGatewayHub(java.lang.String, int)
Note: Early Access. Please consult GemStone technical support for assistance with this functionality.

getGatewayHub

GatewayHub getGatewayHub(String id)
Returns a GatewayHub with the given id.

Parameters:
id - The id of the GatewayHub
Since:
5.7
See Also:
addGatewayHub(java.lang.String, int)
Note: Early Access. Please consult GemStone technical support for assistance with this functionality.

setIsServer

void setIsServer(boolean isServer)
Sets whether or not this Cache resides in a long-running "cache server" VM. A cache server may be an application VM or may be a stand-along VM launched using the GemFire Console, administration API, or the cacheserver command line utility.

Since:
4.0

isServer

boolean isServer()
Returns whether or not this cache resides in a "cache server" VM.

Since:
4.0
See Also:
setIsServer(boolean)

getCacheTransactionManager

CacheTransactionManager getCacheTransactionManager()
Get the CacheTransactionManager instance for this Cache.

Returns:
The CacheTransactionManager instance.
Throws:
CacheClosedException - if the cache is closed.
Since:
4.0

setCopyOnRead

void setCopyOnRead(boolean copyOnRead)
Sets the "copy on read" feature for Cache read operations.

Since:
4.0

getCopyOnRead

boolean getCopyOnRead()
Indicates whether the "copy on read" is enabled for this Cache.

Returns:
true if "copy on read" is enabled, false otherwise.
Since:
4.0

getJNDIContext

Context getJNDIContext()
Returns the JNDI context associated with the Cache.

Returns:
javax.naming.Context Added as part of providing JTA implementation in Gemfire.
Since:
4.0

getRegionAttributes

RegionAttributes getRegionAttributes(String id)
Returns the RegionAttributes with the given id or null if no RegionAttributes with that id exists.

Since:
4.1
See Also:
setRegionAttributes(java.lang.String, com.gemstone.gemfire.cache.RegionAttributes)

setRegionAttributes

void setRegionAttributes(String id,
                         RegionAttributes attrs)
Sets the id of the given RegionAttributes. If a region attributes named name already exists, the mapping will be overwritten with attrs. However, changing the mapping will not effect existing regions.

Parameters:
id - The id of the region attributes
attrs - The attributes to associate with id. If attrs is null, any existing RegionAttributes associated with id will be removed.
Since:
4.1
See Also:
getRegionAttributes(java.lang.String)

listRegionAttributes

Map listRegionAttributes()
Returns an unmodifiable mapping of ids to region attributes. The keys of the map are Strings and the values of the map are RegionAttributes.

Since:
4.1

loadCacheXml

void loadCacheXml(InputStream is)
                  throws TimeoutException,
                         CacheWriterException,
                         GatewayException,
                         RegionExistsException
Loads the cache configuration described in a declarative caching XML file into this cache. If the XML describes a region that already exists, any mutable region attributes, indexes, and region entries that are defined in the XML are updated/added.

Because this method may perform a put on a Region, it declares that it throws a TimeoutException, CacheWriterException, GatewayException, or RegionExistsException.

Throws:
CacheXmlException - If the XML read from is does not conform to the dtd or if an IOException occurs while reading the XML.
TimeoutException
CacheWriterException
GatewayException
RegionExistsException
Since:
4.1

readyForEvents

void readyForEvents()
Notifies the server that this client is ready to receive updates. This method is used by durable clients to notify servers that they are ready to receive updates. As soon as the server receives this message, it will forward updates to this client (if necessary).

Since:
5.5

GemFire 5.7.1

Copyright © 2002-2008 GemStone Systems, Inc. All Rights Reserved.