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