Creating a distributed MemoryStore driver
The Apama installation includes a driver for integrating the distributed MemoryStore with TCStore or the BigMemory Max distributed caching software. If you use other third-party distributed caching software, you need to write a driver that provides the bridge between Apama's MemoryStore and the third-party software in use. Apama provides a Service Provider Interface (SPI) for you to use when writing drivers.
This topic presents an introduction to the SPI and a description of its essential elements. Complete Javadoc information for the SPI is available in the
API Reference for Java (Javadoc); see the
com.apama.correlator.memstore package.
Overview
A driver for a distributed cache needs to extend the following abstract classes:
AbstractStoreFactoryAbstractStore AbstractTable Implementation details:
AbstractStoreFactory – This is the abstract class that holds the configuration used to instantiate a distributed
Store. The starting point for creating an Apama distributed cache driver is to create a concrete subclass of
AbstractStoreFactory. The subclass should have the following:
A public no-args constructor.
JavaBeans-style setter and getter methods for all provider-specific configuration properties.
An implementation of
createStore() that makes use of these product-specific properties, in addition to the generic properties defined on this factory, which are
getClusterName(),
getLogLevel(), and
getBackupCopies().
afterPropertiesSet() (optional, but useful).
Implementers are encouraged to do as much validation as possible of the configuration in the afterPropertiesSet() method. This method is called by Spring during correlator startup, after setters have been invoked for all properties in the configuration file. The createStore() action will never be called before this has happened.
The StoreFactory class that is implemented must then be named in the storeName-spring.xml configuration file for the distributed store.
AbstractStore – This is the abstract class that provides access to tables whose data is held in a distributed store. Implementers should create a subclass of
AbstractStore.
A driver's implementation of the AbstractStore needs to implement or override the following methods:
createTable() init() close() getTotalClusterMembers() AbstractTable – This is the abstract class that holds
Row objects whose data is held in a distributed store.
If the distributed store provides a java.util.concurrent.ConcurrentMap, Apama recommends that implementers of Apama distributed stores create a subclass of the ConcurrentMapAdapter abstract class for ease of development and maintenance. If the distributed store does not provide a ConcurrentMap, implementers should create a subclass of Apama's AbstractTable class.
If you are implementing from AbstractTable, you need to implement or override the following methods:
get() clear() remove() replace() putIfAbsent() containsKey() size() Drivers may also optionally provide support for EPL subscribing to row changed data notifications. To allow EPL application to subscribe to these notifications, subclasses of AbstractTable (or ConcurrentMapAdapter) must provide an instance of RowChangedSubscriptionManager that provides implementations of addRowChangedListener and removeRowChangedListener, and calls fireRowChanged when changes are detected. Also, if a subclass implements notifications, it should override the getRowChangedSubscriptionManager method and have it return the instance of RowChangedSubscriptionManager for this table. Calls to subscribeRowChanged and unsubscribe are passed to this instance. The default implementation of getRowChangedSubscriptionManager returns null, indicating that row changed notifications are not supported; in this case, calls to subscribeRowChanged and unsubscribe will throw OperationNotSupportedException.
Drivers may also optionally provide support for accessing extra fields that are present in an individual row but not in the table's schema. To do this, the table should implement the marker interface TableSupportsExtraFields and use the RowValue.getExtraFields() method to get and set a row's extra fields when converting between RowValue objects and the data type used by the distributed store to represent row values.
RowValue – The
RowValue class is not inherited from or implemented, but a driver must be able to store and retrieve objects of the Apama
RowValue class. Typically, a cache can store any suitable Java class, but some mapping may be required as well. For more information about this class, see the
API Reference for Java (Javadoc) for
com.apama.correlator.memstore.RowValue.
Sample driver
To help get started writing a driver, the BigMemory Max driver is provided in source form as a sample. It implements the SPI described above and invokes the Ehcache API in order to use BigMemory Max. The sample is provided in the samples/distmemstore_driver/bigmemory directory of the Apama installation. To avoid confusion with the pre-compiled driver supplied in the product, the sample BigMemory Max driver uses the package name com.apamax.memstore.provider.bigmemory. A README.txt file describes how to build the sample.