Cache (Apache Geode 1.7.0)
Date: 2018-09-27

org.apache.geode.cache

## Interface Cache

- All Superinterfaces:
    java.lang.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 Summary

    All Methods Instance Methods Abstract Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `CacheServer` | `addCacheServer()` Creates a new cache server, with the default configuration, that will allow clients to access this cache.
    `void` | `close(boolean keepAlive)` Deprecated. as of 6.5 use `ClientCache.close(boolean)` instead.
    `AsyncEventQueueFactory` | `createAsyncEventQueueFactory()` Creates `AsyncEventQueueFactory` for creating a AsyncEventQueue
    `GatewayReceiverFactory` | `createGatewayReceiverFactory()` Creates `GatewayReceiverFactory` for creating a GatewayReceiver
    `GatewaySenderFactory` | `createGatewaySenderFactory()` Creates `GatewaySenderFactory` for creating a SerialGatewaySender
    `<K,V> Region<K,V>` | `createRegion(java.lang.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 shortcut)` Creates a `RegionFactory` for the most commonly used `Region` types defined by `RegionShortcut`
    `<K,V> RegionFactory<K,V>` | `createRegionFactory(java.lang.String regionAttributesId)` Creates a `RegionFactory` for creating a `Region` from `RegionAttributes` mapped to this regionAttributesId
    `<K,V> Region<K,V>` | `createVMRegion(java.lang.String name, RegionAttributes<K,V> aRegionAttributes)` Deprecated. as of GemFire 5.0, use `createRegion(java.lang.String, org.apache.geode.cache.RegionAttributes<K, V>)` instead.
    `java.util.Set<DistributedMember>` | `getAdminMembers()` Returns a set of the administrative members in the distributed system.
    `AsyncEventQueue` | `getAsyncEventQueue(java.lang.String id)` Returns the `AsyncEventQueue` with the given id added to this Cache.
    `java.util.Set<AsyncEventQueue>` | `getAsyncEventQueues()` Returns all `AsyncEventQueue`s for this Cache
    `java.util.List<CacheServer>` | `getCacheServers()` Returns a collection of all of the `CacheServer`s that can serve the contents of this `Cache` to clients.
    `GatewayConflictResolver` | `getGatewayConflictResolver()` Returns the current gateway event conflict resolver
    `java.util.Set<GatewayReceiver>` | `getGatewayReceivers()` Returns all `GatewayReceiver`s for this Cache
    `GatewaySender` | `getGatewaySender(java.lang.String id)` Returns the `GatewaySender` with the given id added to this Cache.
    `java.util.Set<GatewaySender>` | `getGatewaySenders()` Returns all `GatewaySender`s for this 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.
    `LogWriterI18n` | `getLoggerI18n()` Deprecated. as of 6.5 use getLogger().convertToLogWriterI18n() instead
    `java.util.Set<DistributedMember>` | `getMembers()` Returns a set of the other non-administrative members in the distributed system.
    `java.util.Set<DistributedMember>` | `getMembers(Region region)` 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.
    `Cache` | `getReconnectedCache()` Returns the new Cache if there was an auto-reconnect and the cache was recreated.
    `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
    `CacheSnapshotService` | `getSnapshotService()` Obtains the snapshot service to allow the cache data to be imported or exported.
    `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.
    `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.
    `void` | `setGatewayConflictResolver(GatewayConflictResolver resolver)` Adds a gateway event conflict resolution resolver.
    `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.
    `void` | `stopReconnecting()` Force the Cache to stop reconnecting.
    `boolean` | `waitUntilReconnected(long time, java.util.concurrent.TimeUnit units)` Wait for the Cache to finish reconnecting to the distributed system and recreate a new Cache.

    - ### Methods inherited from interface org.apache.geode.cache.GemFireCache

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

    - ### Methods inherited from interface org.apache.geode.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(java.lang.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.
      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
        `java.lang.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(java.lang.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
        `java.lang.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.
      Since:
        GemFire 6.5
      See Also:
        `createRegionFactory(RegionShortcut)`

    - #### createRegionFactory

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

      Creates a `RegionFactory` for the most commonly used `Region` types defined by `RegionShortcut`
      Since:
        GemFire 6.5

    - #### createRegionFactory

          <K,V> RegionFactory<K,V> createRegionFactory(java.lang.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:
        GemFire 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:
        GemFire 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:
        `java.lang.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:
        `java.lang.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:
        `java.lang.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:
        `java.lang.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`.

      Since:
        GemFire 5.7
      See Also:
        `CacheServer`

    - #### getCacheServers

          java.util.List<CacheServer> getCacheServers()

      Returns a collection of all of the `CacheServer`s that can serve the contents of this `Cache` to clients.
      Since:
        GemFire 5.7
      See Also:
        `addCacheServer()`

    - #### 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
      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.
      Since:
        GemFire 4.0

    - #### isServer

          boolean isServer()

      Returns whether or not this cache resides in a "cache server" VM.
      Since:
        GemFire 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.

      Throws:
        `java.lang.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`
      Since:
        GemFire 7.0

    - #### createAsyncEventQueueFactory

          AsyncEventQueueFactory createAsyncEventQueueFactory()

      Creates `AsyncEventQueueFactory` for creating a AsyncEventQueue
      Since:
        GemFire 7.0

    - #### createGatewayReceiverFactory

          GatewayReceiverFactory createGatewayReceiverFactory()

      Creates `GatewayReceiverFactory` for creating a GatewayReceiver
      Since:
        GemFire 7.0

    - #### getGatewaySenders

          java.util.Set<GatewaySender> getGatewaySenders()

      Returns all `GatewaySender`s for this Cache.
      Returns:
        Set of GatewaySenders
      Since:
        GemFire 7.0

    - #### getGatewaySender

          GatewaySender getGatewaySender(java.lang.String id)

      Returns the `GatewaySender` with the given id added to this Cache.
      Returns:
        GatewaySender with id
      Since:
        GemFire 7.0

    - #### getGatewayReceivers

          java.util.Set<GatewayReceiver> getGatewayReceivers()

      Returns all `GatewayReceiver`s for this Cache
      Returns:
        Set of GatewaySenders
      Since:
        GemFire 7.0

    - #### getAsyncEventQueues

          java.util.Set<AsyncEventQueue> getAsyncEventQueues()

      Returns all `AsyncEventQueue`s for this Cache
      Returns:
        Set of AsyncEventQueue
      Since:
        GemFire 7.0

    - #### getAsyncEventQueue

          AsyncEventQueue getAsyncEventQueue(java.lang.String id)

      Returns the `AsyncEventQueue` with the given id added to this Cache.
      Returns:
        AsyncEventQueue with id
      Since:
        GemFire 7.0

    - #### getMembers

          java.util.Set<DistributedMember> getMembers()

      Returns a set of the other non-administrative members in the distributed system.
      Since:
        GemFire 6.6

    - #### getAdminMembers

          java.util.Set<DistributedMember> getAdminMembers()

      Returns a set of the administrative members in the distributed system.
      Since:
        GemFire 6.6

    - #### getMembers

          java.util.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
      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,
                                       java.util.concurrent.TimeUnit units)
                                throws java.lang.InterruptedException

      Wait for the Cache to finish reconnecting to the distributed system and recreate a new Cache.
      Parameters:
        `time` - amount of time to wait, or -1 to wait forever
        `units` - time unit
      Returns:
        true if the cache was reconnected
      Throws:
        `java.lang.InterruptedException` - if the thread is interrupted while waiting
      See Also:
        `getReconnectedCache()`

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