VMware Tanzu GemFire Native C++ Reference 10.3.0
apache::geode::client::CacheWriter Class Reference

An application plug-in that can be installed on the region. More...

#include <CacheWriter.hpp>

Public Member Functions

virtual bool beforeCreate (const EntryEvent &event)
 Called before an entry is created. More...
 
virtual bool beforeDestroy (const EntryEvent &event)
 Called before an entry is destroyed. More...
 
virtual bool beforeRegionClear (const RegionEvent &event)
 called before this region is cleared More...
 
virtual bool beforeRegionDestroy (const RegionEvent &event)
 called before this region is destroyed More...
 
virtual bool beforeUpdate (const EntryEvent &event)
 Called before an entry is updated. More...
 
virtual void close (Region &rp)
 Called when the region containing this callback is destroyed, when the cache is closed. More...
 

Detailed Description

An application plug-in that can be installed on the region.

Defines methods that are called BEFORE entry modification. A distributed region will typically have a single cache writer. If the application is designed such that all or most updates to a region occurs on a node, it is desirable to have the cache writer for the region to be installed at that node.

Cache writer invocations are initiated by the node where the entry or region modification occurs. If there is a local cache writer on the node where the change occurs, that is invoked. If there is no local cache writer , the system knows which of the nodes that have the region defined have a cache writer defined.

Note that cache writer callbacks are synchronous callbacks and have the ability to veto the cache update. Since cache writer invocations require communications over the network, (especially if they are not colocated on the nodes where the change occurs) the use of cache writers presents a performance penalty.

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, Geode 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 CacheWriters available in the distributed system, the Geode 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 process as the CacheWriter.

See also
RegionAttributesFactory::setCacheWriter
RegionAttributes::getCacheWriter
AttributesMutator::setCacheWriter

Member Function Documentation

◆ beforeCreate()

virtual bool apache::geode::client::CacheWriter::beforeCreate ( const EntryEvent event)
virtual

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 from EntryEvent::isLoad. 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
eventEntryEvent denotes the event object associated with creating the entry
See also
Region::create
Region::put
Region::get

◆ beforeDestroy()

virtual bool apache::geode::client::CacheWriter::beforeDestroy ( const EntryEvent event)
virtual

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::localDestroyRegion.

Parameters
eventEntryEvent denotes the event object associated with destroying the entry
See also
Region::destroy

◆ beforeRegionClear()

virtual bool apache::geode::client::CacheWriter::beforeRegionClear ( const RegionEvent event)
virtual

called before this region is cleared

Parameters
eventEntryEvent denotes the event object associated with clearing the region
See also
Region::clear

◆ beforeRegionDestroy()

virtual bool apache::geode::client::CacheWriter::beforeRegionDestroy ( const RegionEvent event)
virtual

called before this region is destroyed

Parameters
eventEntryEvent denotes the event object associated with destroying the region
See also
Region::destroyRegion

◆ beforeUpdate()

virtual bool apache::geode::client::CacheWriter::beforeUpdate ( const EntryEvent event)
virtual

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 nullptr. The entry being updated may or may not exist in the local cache where the CacheWriter is installed.

Parameters
eventEntryEvent denotes the event object associated with updating the entry
See also
Region::put
Region::get

◆ close()

virtual void apache::geode::client::CacheWriter::close ( Region rp)
virtual

Called when the region containing this callback is destroyed, when the cache is closed.

Implementations should clean up any external resources, such as database connections. Any runtime exceptions this method throws will be logged.

It is possible for this method to be called multiple times on a single callback instance, so implementations must be tolerant of this.

See also
Cache::close
Region::destroyRegion

Apache Geode C++ Cache API Documentation