Package org.apache.geode.cache

Interface Cache

All Superinterfaces:
AutoCloseable, 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/cache8_0.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:
GemFire 2.0

  • Method Details

    • 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, org.apache.geode.cache.RegionAttributes<K, V>) instead.
      Creates a VM region using the specified RegionAttributes.
      Type Parameters:
      K - the type of keys in the region
      V - the type of values in the region
      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.
      Type Parameters:
      K - the type of keys in the region
      V - the type of values in the region
      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:
      GemFire 5.0

    • createRegionFactory

      <K, V> RegionFactory<K,V> createRegionFactory()
      Creates a RegionFactory which can be used to specify additional attributes for Region creation.
      Type Parameters:
      K - the type of keys in the region
      V - the type of values in the region
      Returns:
      a RegionFactory which can be used to specify additional attributes for Region creation
      Since:
      GemFire 6.5
      See Also:

    • createRegionFactory

      <K, V> RegionFactory<K,V> createRegionFactory(RegionShortcut shortcut)
      Creates a RegionFactory for the most commonly used Region types defined by RegionShortcut
      Type Parameters:
      K - the type of keys in the region
      V - the type of values in the region
      Parameters:
      shortcut - the region type as defined by RegionShortcut
      Returns:
      a RegionFactory
      Since:
      GemFire 6.5

    • createRegionFactory

      <K, V> RegionFactory<K,V> createRegionFactory(String regionAttributesId)
      Creates a RegionFactory for creating a Region from RegionAttributes mapped to this regionAttributesId
      Type Parameters:
      K - the type of keys in the region
      V - the type of values in the region
      Parameters:
      regionAttributesId - the Id of RegionAttributes to be used
      Returns:
      a RegionFactory
      Since:
      GemFire 6.5
      See Also:

    • createRegionFactory

      <K, V> RegionFactory<K,V> createRegionFactory(RegionAttributes<K,V> regionAttributes)
      Creates a RegionFactory for creating a Region from the given regionAttributes
      Type Parameters:
      K - the type of keys in the region
      V - the type of values in the region
      Parameters:
      regionAttributes - regionAttributes for the new region
      Returns:
      a RegionFactory
      Since:
      GemFire 6.5
      See Also:

    • 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.
      Returns:
      the number of seconds a cache operation will wait to obtain a distributed lock lease

    • setLockTimeout

      void setLockTimeout(int seconds)
      Sets the number of seconds a cache operation may wait to obtain a distributed lock lease before timing out.
      Parameters:
      seconds - 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.
      Returns:
      the length, in seconds, of distributed lock leases obtained by this cache

    • setLockLease

      void setLockLease(int seconds)
      Sets the length, in seconds, of distributed lock leases obtained by this cache.
      Parameters:
      seconds - 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.
      Returns:
      the number of seconds a cache get operation can spend searching for a value before it times out

    • setSearchTimeout

      void setSearchTimeout(int seconds)
      Sets the number of seconds a cache get operation can spend searching for a value.
      Parameters:
      seconds - the number of seconds a cache get operation can spend searching for a value
      Throws:
      IllegalArgumentException - if seconds is less than zero

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

      Returns:
      the newly created CacheServer
      Since:
      GemFire 5.7
      See Also:

    • getCacheServers

      List<CacheServer> getCacheServers()
      Returns a collection of all of the CacheServers that can serve the contents of this Cache to clients.
      Returns:
      a collection of all of the CacheServers
      Since:
      GemFire 5.7
      See Also:

    • setGatewayConflictResolver

      void setGatewayConflictResolver(GatewayConflictResolver resolver)
      Adds a gateway event conflict resolution resolver. This is invoked if an event is processed that comes from a different distributed system than the last event to modify the affected entry. It may alter the event or disallow the event. If it does neither the event is applied to the cache if its timestamp is newer than what is in the cache or if it is the same and the event's distributed system ID is larger than that of the last event to modify the affected entry.
      Parameters:
      resolver - gateway event conflict resolution resolver
      Since:
      GemFire 7.0

    • getGatewayConflictResolver

      GatewayConflictResolver getGatewayConflictResolver()
      Returns the current gateway event conflict resolver
      Returns:
      the current gateway event conflict resolver
      Since:
      GemFire 7.0

    • 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.
      Parameters:
      isServer - whether this Cache resides in a long-running "cache server" VM
      Since:
      GemFire 4.0

    • isServer

      boolean isServer()
      Returns whether or not this cache resides in a "cache server" VM.
      Returns:
      whether this cache resides in a "cache server" VM
      Since:
      GemFire 4.0
      See Also:

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

      Throws:
      IllegalStateException - if called by a non-durable client
      Since:
      GemFire 5.5

    • createGatewaySenderFactory

      GatewaySenderFactory createGatewaySenderFactory()
      Creates GatewaySenderFactory for creating a SerialGatewaySender
      Specified by:
      createGatewaySenderFactory in interface GemFireCache
      Returns:
      a GatewaySenderFactory
      Since:
      GemFire 7.0

    • createAsyncEventQueueFactory

      AsyncEventQueueFactory createAsyncEventQueueFactory()
      Creates AsyncEventQueueFactory for creating a AsyncEventQueue
      Returns:
      a AsyncEventQueueFactory
      Since:
      GemFire 7.0

    • createGatewayReceiverFactory

      GatewayReceiverFactory createGatewayReceiverFactory()
      Creates GatewayReceiverFactory for creating a GatewayReceiver
      Returns:
      a GatewayReceiverFactory
      Since:
      GemFire 7.0

    • getGatewaySenders

      Set<GatewaySender> getGatewaySenders()
      Returns all GatewaySenders for this Cache.
      Returns:
      Set of GatewaySenders
      Since:
      GemFire 7.0

    • getGatewaySender

      GatewaySender getGatewaySender(String id)
      Returns the GatewaySender with the given id added to this Cache.
      Parameters:
      id - the id of the GatewaySender
      Returns:
      GatewaySender with id
      Since:
      GemFire 7.0

    • getGatewayReceivers

      Set<GatewayReceiver> getGatewayReceivers()
      Returns all GatewayReceivers for this Cache
      Returns:
      Set of GatewaySenders
      Since:
      GemFire 7.0

    • getAsyncEventQueues

      Set<AsyncEventQueue> getAsyncEventQueues()
      Returns all AsyncEventQueues for this Cache
      Returns:
      Set of AsyncEventQueue
      Since:
      GemFire 7.0

    • getAsyncEventQueue

      AsyncEventQueue getAsyncEventQueue(String id)
      Returns the AsyncEventQueue with the given id added to this Cache.
      Parameters:
      id - the id of the AsyncEventQueue
      Returns:
      AsyncEventQueue with id
      Since:
      GemFire 7.0

    • getMembers

      Set<DistributedMember> getMembers()
      Returns a set of the other non-administrative members in the distributed system.
      Returns:
      a set of the other non-administrative members in the distributed system
      Since:
      GemFire 6.6

    • getAdminMembers

      Set<DistributedMember> getAdminMembers()
      Returns a set of the administrative members in the distributed system.
      Returns:
      a set of the administrative members in the distributed system
      Since:
      GemFire 6.6

    • getMembers

      Set<DistributedMember> getMembers(Region region)
      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:
      region - a Region in the cache
      Returns:
      a set of the members in the distributed system that have the given region
      Since:
      GemFire 6.6

    • getSnapshotService

      CacheSnapshotService getSnapshotService()
      Obtains the snapshot service to allow the cache data to be imported or exported.
      Returns:
      the snapshot service

    • isReconnecting

      boolean isReconnecting()
      Test to see whether the Cache is in the process of reconnecting and recreating a new cache after it has been removed from the system by other members or has shut down due to missing Roles and is reconnecting.

      This will also return true if the Cache has finished reconnecting. When reconnect has completed you can use getReconnectedCache() to retrieve the new cache instance.

      Returns:
      true if the Cache is attempting to reconnect or has finished reconnecting

    • waitUntilReconnected

      boolean waitUntilReconnected(long time, TimeUnit units) throws InterruptedException
      Wait for the Cache to finish reconnecting to the distributed system and recreate a new Cache. This may throw a CacheClosedException if reconnect attempts fail due to an exception. The exception will detail what went wrong.
      Parameters:
      time - amount of time to wait, or -1 to wait forever
      units - time unit
      Returns:
      true if the cache was reconnected
      Throws:
      InterruptedException - if the thread is interrupted while waiting
      See Also:

    • stopReconnecting

      void stopReconnecting()
      Force the Cache to stop reconnecting. If the Cache is currently connected this will disconnect and close it.

    • getReconnectedCache

      Cache getReconnectedCache()
      Returns the new Cache if there was an auto-reconnect and the cache was recreated.
      Returns:
      the new Cache if there was an auto-reconnect and the cache was recreated