com.gemstone.gemfire.cache
Interface Cache

All Superinterfaces:

GemFireCache, RegionService

public interface Cache
extends GemFireCache

Caches are obtained from the CacheFactory.create() method. See CacheFactory for common usage patterns for creating the cache instance.

When a cache is created a DistributedSystem is also created. 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/cache6_5.dtd" file and the top level element must be a cache element.

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

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(boolean keepalive) Deprecated. as of 6.5 use ClientCache.close(boolean) instead.
<K,V> Region<K,V>	createRegion(String name, RegionAttributes<K,V> aRegionAttributes) Deprecated. as of 6.5 use createRegionFactory(RegionAttributes) instead
<K,V> RegionFactory<K,V>	createRegionFactory() Creates a RegionFactory which can be used to specify additional attributes for Region creation.
<K,V> RegionFactory<K,V>	createRegionFactory(RegionAttributes<K,V> regionAttributes) Creates a RegionFactory for creating a Region from the given regionAttributes
<K,V> RegionFactory<K,V>	createRegionFactory(RegionShortcut atts) Creates a RegionFactory for the most commonly used Region types defined by RegionShortcut
<K,V> RegionFactory<K,V>	createRegionFactory(String regionAttributesId) Creates a RegionFactory for creating a Region from RegionAttributes mapped to this regionAttributesId
<K,V> Region<K,V>	createVMRegion(String name, RegionAttributes<K,V> aRegionAttributes) Deprecated. as of GemFire 5.0, use createRegion(java.lang.String, com.gemstone.gemfire.cache.RegionAttributes) instead.
Set<DistributedMember>	getAdminMembers() Returns a set of the administrative members in the distributed system.
List<CacheServer>	getBridgeServers() Deprecated. as of 5.7 use getCacheServers() instead.
List<CacheServer>	getCacheServers() Returns a collection of all of the CacheServers that can serve the contents of this Cache to clients.
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<GatewayHub>	getGatewayHubs() Returns a list of all of the GatewayHubs.
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.
LogWriterI18n	getLoggerI18n() Deprecated. as of 6.5 use getLogger().convertToLogWriterI18n() instead
Set<DistributedMember>	getMembers() Returns a set of the other non-administrative members in the distributed system.
Set<DistributedMember>	getMembers(Region r) Returns a set of the members in the distributed system that have the given region.
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.
int	getSearchTimeout() Gets the number of seconds a cache get operation can spend searching for a value before it times out.
LogWriterI18n	getSecurityLoggerI18n() Deprecated. as of 6.5 use getSecurityLogger().convertToLogWriterI18n() instead
boolean	isServer() Returns whether or not this cache resides in a "cache server" VM.
void	readyForEvents() Deprecated. as of 6.5 use ClientCache.readyForEvents() instead.
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	setSearchTimeout(int seconds) Sets the number of seconds a cache get operation can spend searching for a value.

Methods inherited from interface com.gemstone.gemfire.cache.GemFireCache

createDiskStoreFactory, findDiskStore, getCacheTransactionManager, getCopyOnRead, getDistributedSystem, getInitializer, getInitializerProps, getJNDIContext, getLogger, getName, getPdxDiskStore, getPdxIgnoreUnreadFields, getPdxPersistent, getPdxReadSerialized, getPdxSerializer, getRegionAttributes, getResourceManager, getSecurityLogger, listRegionAttributes, loadCacheXml, setCopyOnRead, setRegionAttributes

Methods inherited from interface com.gemstone.gemfire.cache.RegionService

close, createPdxEnum, createPdxInstanceFactory, getCancelCriterion, getQueryService, getRegion, isClosed, rootRegions

Method Detail

close

@Deprecated
void close(boolean keepalive)

Deprecated. as of 6.5 use ClientCache.close(boolean) instead.

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

@Deprecated
<K,V> Region<K,V> createVMRegion(String name,
                                            RegionAttributes<K,V> 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

@Deprecated
<K,V> Region<K,V> createRegion(String name,
                                          RegionAttributes<K,V> aRegionAttributes)
                         throws RegionExistsException,
                                TimeoutException

Deprecated. as of 6.5 use createRegionFactory(RegionAttributes) instead

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

createRegionFactory

<K,V> RegionFactory<K,V> createRegionFactory()

Creates a RegionFactory which can be used to specify additional attributes for Region creation.

Since:

6.5

See Also:

createRegionFactory(RegionShortcut)

createRegionFactory

<K,V> RegionFactory<K,V> createRegionFactory(RegionShortcut atts)

Creates a RegionFactory for the most commonly used Region types defined by RegionShortcut

Since:

6.5

createRegionFactory

<K,V> RegionFactory<K,V> createRegionFactory(String regionAttributesId)

Creates a RegionFactory for creating a Region from RegionAttributes mapped to this regionAttributesId

Parameters:

regionAttributesId - the Id of RegionAttributes to be used

Since:

6.5

See Also:

GemFireCache.setRegionAttributes(String, RegionAttributes)

createRegionFactory

<K,V> RegionFactory<K,V> createRegionFactory(RegionAttributes<K,V> regionAttributes)

Creates a RegionFactory for creating a Region from the given regionAttributes

Parameters:

regionAttributes - regionAttributes for the new region

Since:

6.5

See Also:

createRegionFactory(RegionShortcut)

getLoggerI18n

@Deprecated
LogWriterI18n getLoggerI18n()

Deprecated. as of 6.5 use getLogger().convertToLogWriterI18n() instead

Internal GemStone method for accessing the internationalized logging object for GemFire, use GemFireCache.getLogger() instead. This method does not throw CacheClosedException if the cache is closed.

Returns:

the logging object

getSecurityLoggerI18n

@Deprecated
LogWriterI18n getSecurityLoggerI18n()

Deprecated. as of 6.5 use getSecurityLogger().convertToLogWriterI18n() instead

Internal GemStone method for accessing the internationalized logging object for GemFire, use GemFireCache.getSecurityLogger() instead. 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

@Deprecated
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

@Deprecated
List<CacheServer> 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<CacheServer> 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

@Deprecated
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

getGatewayHub

@Deprecated
GatewayHub getGatewayHub()

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

Gets the existing GatewayHub.

See Also:

Gateway

getGatewayHubs

List<GatewayHub> getGatewayHubs()

Returns a list of all of the GatewayHubs.

Since:

5.1

See Also:

addGatewayHub(java.lang.String, int)

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)

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 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)

readyForEvents

@Deprecated
void readyForEvents()

Deprecated. as of 6.5 use ClientCache.readyForEvents() instead.

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).

Durable clients must call this method after they are done creating regions. If it is called before the client creates the regions then updates will be lost. Any time a new Pool is created and regions have been added to it then this method needs to be called again.

For pools declared in cache.xml this method is implicitly called at the end of cache creation so the regions on that pool need to also be declared in cache.xml.

Throws:

IllegalStateException - if called by a non-durable client

Since:

5.5

getMembers

Set<DistributedMember> getMembers()

Returns a set of the other non-administrative members in the distributed system.

Since:

6.6

getAdminMembers

Set<DistributedMember> getAdminMembers()

Returns a set of the administrative members in the distributed system.

Since:

6.6

getMembers

Set<DistributedMember> getMembers(Region r)

Returns a set of the members in the distributed system that have the given region. For regions with local scope an empty set is returned.

Parameters:

r - a Region in the cache

Since:

6.6