Setting Up Servers for an Inline Cache
See The Inline Cache for an introductory description of an inline cache. The implementation of an inline cache requires custom code deployed on the GemFire servers to interact with the backend data store for read misses and for writes.
The custom code always implements a cache loader for read misses. The custom code and configuration setup differs for writes. A write-behind implementation uses an asynchronous event queue (AEQ) and an AEQ listener. A write-through implementation uses a cache writer.
Implement a Cache Loader for Read Misses
An app’s get operation is a cache read.
If the desired entry is in the region, it is a cache hit,
and the value is quickly returned to the app.
If the desired entry is not in the region, it is a cache miss.
For an inline cache, that value is acquired from the backend data store.
You implement the CacheLoader
interface to handle cache misses.
Each cache miss invokes the CacheLoader.load
method.
The CacheLoader.load
method must acquire and return the value
for the specified key.
See the Pivotal GemFire API Documentation for the interface’s details.
The value returned from the CacheLoader.load
method
will be put into the region and then returned to the waiting app,
completing the app’s get operation.
Since the app blocks while waiting for the result of the get operation,
design the CacheLoader.load
method to acquire the value
as quickly as possible.
The CacheLoader
implementation must be thread-safe.
You will deploy the implementation to the servers during
configuration.
The CacheLoader.load
method
queries the backend data store for the desired entry.
That communication between the server process and the backend
data store requires a connection,
and establishing a connection is likely to use a set of
credentials.
You provide a custom implementation of
the CacheLoader.initialize
method to establish the connection.
You specify the credentials during configuration with the gfsh
create region
command
by adding the JSON description to the --cache-loader
option.
The credentials will be passed as parameters to the
invoked CacheLoader.initialize
method as part of the CacheLoader
instance
construction.
Implement an Asynchronous Event Queue and Cache Listener for Write Behind
An app’s put operation is a cache write. For a write-behind implementation, the value is placed into the region, and it will also be asynchronously written to the backend data store, allowing the app’s write operation to complete without waiting for the backend-data-store write to complete.
An asynchronous event queue (AEQ) to queue the write events together with
an implementation of the AsyncEventListener
interface
provides the desired behavior.
See the Pivotal GemFire API Documentation for the interface’s details.
With a configured AEQ, all put operations first create or update the entry in the hosted region on the server and then add the event to the AEQ.
You provide a custom implementation of the AsyncEventListener
interface.
Your AsyncEventListener.processEvents
method’s task is to
iterate through the events in the AEQ,
writing each newly created or updated entry in the AEQ
to the backend data store.
The AsyncEventListener.processEvents
method is invoked
when either the AEQ holds a configured quantity of events,
or a configured quantity of time has elapsed
since the earliest entry entered the AEQ.
The communication between the server process and the backend
data store to do the writes requires a connection,
and establishing a connection is likely to use a set of
credentials.
You provide a custom implementation of
the AsyncEventListener.initialize
method to establish the connection.
You specify the credentials during configuration in
the gfsh create async-event-queue
command
with the --listener-param
option as described in
Configure Using gfsh for Write Behind.
The credentials will be passed as parameters to the
invoked AsyncEventListener.initialize
method as part of AsyncEventListener
instance construction.
Your configuration will specify the AEQ as persistent, such that it does not lose queued backend-data-store writes across unexpected server restarts.
Implement a Cache Writer for Write Through
An app’s put operation is a cache write. For a write-through implementation, the value will be written to the backend data store prior to being placed into the region. After both writes, the app’s put operation completes.
An implementation of the CacheWriter
interface implementation provides
the correct behavior for write through.
See the Pivotal GemFire API Documentation for the interface’s details.
You provide a custom implementation of the CacheWriter.beforeCreate
method to handle backend-data-store writes for put operations that add
a new entry to the region.
You provide a custom implementation of the CacheWriter.beforeUpdate
method to handle backend-data-store writes for put operations that modify
an existing entry in the region.
You provide a custom implementation of CacheWriter.beforeDestroy
,
as appropriate,
to handle an update of the backend data store for a region
operation that removes an entry.
The CacheWriter
implementation must be thread-safe.
You will deploy the implementation to the servers during configuration.
Communication between the server process and the backend
data store to do the writes requires a connection,
and establishing a connection is likely to use a set of
credentials.
You provide a custom implementation of
the CacheWriter.initialize
method to establish the connection.
Specify the credentials in the gfsh create region
command
during configuration as described in
Configure Using gfsh for Write Through.
Add the JSON description to the --cache-writer
option.
The credentials will be passed as parameters to the
invoked CacheWriter.initialize
method as part of
the CacheWriter
instance construction.
Configure Using gfsh for Write Behind
Follow this procedure to deploy your custom implementations of the interfaces to the servers, create the AEQ, and configure the region to use the AEQ and the deployed interface implementations.
Follow the directions in Connect with gfsh over HTTPS to connect to the cluster with a role that is able to manage both the cluster and the data.
Deploy the cache loader and the AEQ listener code to the servers within the PCC service instance:
gfsh>deploy --jars=/path/to/MyLoader.jar,/path/to/MyListener.jar
Create the AEQ, assigning a name for the AEQ (called
WB-AEQ
in this example), specifying the AEQ listener, and specifying the AEQ listener’s parameters:gfsh>create async-event-queue --id=WB-AEQ \ --parallel=true --persistent \ --listener=com.myCompany.MyListener \ --listener-param=url#jdbc:db2:SAMPLE,username#admin,password#gobbledeegook
The persistence of the AEQ uses the default disk store, since no disk store is specified in this command.
Create the region, specifying the cache loader and the assigned AEQ name.
gfsh>create region --name=myRegion --type=PARTITION_REDUNDANT \ --cache-loader=com.myCompany.MyLoader{'url':'jdbc:db2:SAMPLE','username':'admin',password:'gobbledeegook'} --async-event-queue-id=WB-AEQ
Configure Using gfsh for Write Through
Follow this procedure to deploy your custom implementations of the interfaces to the servers, and configure the region to use the deployed interface implementations.
Follow the directions in Connect with gfsh over HTTPS to connect to the cluster with a role that is able to manage both the cluster and the data.
Deploy the cache loader and the cache writer code to the servers within the PCC service instance:
gfsh>deploy --jars=/path/to/MyLoader.jar,/path/to/MyWriter.jar
Create the region, specifying the cache loader and the cache writer:
gfsh>create region --name=myRegion --type=PARTITION_REDUNDANT \ --cache-loader=com.myCompany.MyLoader{'url':'jdbc:db2:SAMPLE','username':'admin',password:'gobbledeegook'} --cache-writer=com.myCompany.MyWriter{'url':'jdbc:db2:SAMPLE','username':'admin',password:'gobbledeegook'}