CacheWriter (Apache Geode 2.0.2)
Description: declaration: package: org.apache.geode.cache, interface: CacheWriter

Package org.apache.geode.cache

# Interface CacheWriter<K,V>

All Superinterfaces:
  `CacheCallback`, `Declarable`

All Known Implementing Classes:
  `CacheWriterAdapter`, `JdbcWriter`, `LocalSessionCacheWriter`

public interface CacheWriter<K,V> extends CacheCallback
A user-defined object defined in the `RegionAttributes` that is called synchronously before a region or entry in the cache is modified. The typical use for a `CacheWriter` is to update a database. Application writers should implement these methods to execute application-specific behavior before the cache is modified.

Before the region is updated via a put, create, or destroy operation, GemFire will call a `CacheWriter` that is installed anywhere in any participating cache for that region, preferring a local `CacheWriter` if there is one. Usually there will be only one `CacheWriter` in the distributed system. If there are multiple `CacheWriter`s available in the distributed system, the GemFire implementation always prefers one that is stored locally, or else picks one arbitrarily; in any case only one `CacheWriter` will be invoked.

The `CacheWriter` is capable of aborting the update to the cache by throwing a `CacheWriterException`. This exception or any runtime exception thrown by the `CacheWriter` will abort the operation and the exception will be propagated to the initiator of the operation, regardless of whether the initiator is in the same VM as the `CacheWriter`.

WARNING: To avoid risk of deadlock, do not invoke CacheFactory.getAnyInstance() from within any callback methods. Instead use EntryEvent.getRegion().getCache() or RegionEvent.getRegion().getCache().

Since:
  GemFire 3.0
See Also:
  - `AttributesFactory.setCacheWriter(org.apache.geode.cache.CacheWriter<K, V>)`
  - `RegionAttributes.getCacheWriter()`
  - `AttributesMutator.setCacheWriter(org.apache.geode.cache.CacheWriter<K, V>)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `beforeCreate(EntryEvent<K,V> event)`
  Called before an entry is created.
  `void`
  `beforeDestroy(EntryEvent<K,V> event)`
  Called before an entry is destroyed.
  `void`
  `beforeRegionClear(RegionEvent<K,V> event)`
  Called before a region is cleared.
  `void`
  `beforeRegionDestroy(RegionEvent<K,V> event)`
  Called before a region is destroyed.
  `void`
  `beforeUpdate(EntryEvent<K,V> event)`
  Called before an entry is updated.

  ### Methods inherited from interface org.apache.geode.cache.CacheCallback

  `close`

  ### Methods inherited from interface org.apache.geode.cache.Declarable

  `init, initialize`

- ## Method Details

  - ### beforeUpdate

    void beforeUpdate(EntryEvent<K,V> event) throws CacheWriterException
    Called before an entry is updated. The entry update is initiated by a `put` or a `get` that causes the loader to update an existing entry. The entry previously existed in the cache where the operation was initiated, although the old value may have been null. The entry being updated may or may not exist in the local cache where the CacheWriter is installed.
    Parameters:
      `event` - an EntryEvent that provides information about the operation in progress
    Throws:
      `CacheWriterException` - if thrown will abort the operation in progress, and the exception will be propagated back to caller that initiated the operation
    See Also:
      - `Region.put(Object, Object)`
      - `Region.get(Object)`

  - ### beforeCreate

    void beforeCreate(EntryEvent<K,V> event) throws CacheWriterException
    Called before an entry is created. Entry creation is initiated by a `create`, a `put`, or a `get`. The `CacheWriter` can determine whether this value comes from a `get` or not by evaluating the `Operation`'s `Operation.isLoad()` method. The entry being created may already exist in the local cache where this `CacheWriter` is installed, but it does not yet exist in the cache where the operation was initiated.
    Parameters:
      `event` - an EntryEvent that provides information about the operation in progress
    Throws:
      `CacheWriterException` - if thrown will abort the operation in progress, and the exception will be propagated back to caller that initiated the operation
    See Also:
      - `Region.create(Object, Object)`
      - `Region.put(Object, Object)`
      - `Region.get(Object)`

  - ### beforeDestroy

    void beforeDestroy(EntryEvent<K,V> event) throws CacheWriterException
    Called before an entry is destroyed. The entry being destroyed may or may not exist in the local cache where the CacheWriter is installed. This method is not called as a result of expiration or `Region.localDestroy(Object)`.
    Parameters:
      `event` - an EntryEvent that provides information about the operation in progress
    Throws:
      `CacheWriterException` - if thrown will abort the operation in progress, and the exception will be propagated back to caller that initiated the operation
    See Also:
      - `Region.destroy(Object)`

  - ### beforeRegionDestroy

    void beforeRegionDestroy(RegionEvent<K,V> event) throws CacheWriterException
    Called before a region is destroyed. The `CacheWriter` will not additionally be called for each entry that is destroyed in the region as a result of a region destroy. If the region's subregions have `CacheWriter`s installed, then they will be called for the cascading subregion destroys. This method is not called as a result of `Region.close()`, `Cache.close(boolean)`, or `Region.localDestroyRegion()`. However, the `Region.close()` method is invoked regardless of whether a region is destroyed locally. A non-local region destroy results in an invocation of this method is followed by an invocation of `Region.close()`.

    WARNING: This method should not destroy or create any regions itself or a deadlock will occur.

    Parameters:
      `event` - a RegionEvent that provides information about the operation
    Throws:
      `CacheWriterException` - if thrown, will abort the operation in progress, and the exception will be propagated back to the caller that initiated the operation
    See Also:
      - `Region.destroyRegion()`

  - ### beforeRegionClear

    void beforeRegionClear(RegionEvent<K,V> event) throws CacheWriterException
    Called before a region is cleared. The `CacheWriter` will not additionally be called for each entry that is cleared in the region as a result of a region clear.

    WARNING: This method should not clear/destroy any regions

    Parameters:
      `event` - a RegionEvent that provides information about the operation
    Throws:
      `CacheWriterException` - if thrown, will abort the operation in progress, and the exception will be propagated back to the caller that initiated the operation
    See Also:
      - `Region.clear()`