com.apama.correlator.memstore
Class AbstractStoreFactory

java.lang.Object
  com.apama.correlator.memstore.AbstractStoreFactory

All Implemented Interfaces:

org.springframework.beans.factory.BeanNameAware, org.springframework.beans.factory.DisposableBean, org.springframework.beans.factory.InitializingBean

public abstract class AbstractStoreFactory
extends java.lang.Object
implements org.springframework.beans.factory.InitializingBean, org.springframework.beans.factory.DisposableBean, org.springframework.beans.factory.BeanNameAware

Factory object for creating store objects, and holding the configuration properties requried to do so. Implementing classes have a public no-args constructor. Typically configuration properties will be specified using bean-style setPropName(value) methods which can be set easily from the Spring configuration file. Implementors should create a subclass of AbstractStoreFactory, ensure it has a public no-args constructor, create Java bean-style setter and getter methods for all required configuration properties, and provide an implementation of createStore() that makes use of these properties, in addition to the standard properties defined on this factory: getClusterName(), getLogLevel() and getBackupCopies(). Implementors are encouraged to do as much validation as possible of the configuration in the afterPropertiesSet() method. This method will be called by Spring during Correlator startup, after setters have been invoked, for all properties in the configuration file. CreateStore will never be called before this has happened. Thread-safety: after initialization of properties this object will be accessed by only one thread at a time so there is no need for implementors to add additional synchronization.

Constructor Summary

AbstractStoreFactory()

Method Summary

void	afterPropertiesSet() Validates the configuration properties at the end of the initialization process.
abstract AbstractStore	createStore() Prepares and returns a new store object using this factory's configuration and storeName.
void	destroy() Performs final cleanup of the Called once during clean Correlator shutdown.
int	getBackupCopies() Retrieve the number of additional redundant nodes that will hold a backup copy of data.
java.lang.String	getClusterName() The provider specific clusterName which groups same named distributed stores together for communication and data sharing.
int	getInitialMinClusterSize() Retrieve the number of nodes required to join the cluster before the Distributed MemoryStore will send the Finished event.
java.lang.String	getLogLevel() Get the log level that should be used (if possible) for the 3rd party provider's logging.
boolean	getRowChangedOldValueRequired() Retrieve whether subscribers should receive old values in RowChanged events.
java.lang.String	getStoreName() The unique storeName for this factory, specified by the id attribute in the configuration.
void	initializeProviderSystemProperty(java.lang.String propertyName, java.lang.String value) Helper method for setting the value of a JVM-wide system property which is required by this store.
void	setBackupCopies(int backupCopies) The number of additional redundant nodes that should hold a backup copy of each key/value data element.
void	setBeanName(java.lang.String storeName) Called by Spring to initialize the storeName using the id attribute in its configuration.
void	setClusterName(java.lang.String clusterName) A provider-specific string used to group together distributed store nodes that communicate with each other and share data.
void	setInitialMinClusterSize(int initialMinClusterSize) The minimum number of nodes that are required to join the cluster before the Distributed MemoryStore will send the Finished event.
void	setLogLevel(java.lang.String providerLogLevel) The Apama log level at which this provider should log its own messages (not all providers will support this).
void	setRowChangedOldValueRequired(boolean oldValueRequired) Set whether subscribers should receive old values in RowChanged events.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AbstractStoreFactory

public AbstractStoreFactory()

Method Detail

createStore

public abstract AbstractStore createStore()
                                   throws DistMemStoreProviderException

Prepares and returns a new store object using this factory's configuration and storeName. This method will be called the first time the Storage.prepareDistributed EPL action is called for this store name (note that if the MemoryStore is deleted from the Correlator and re-injected this method will be executed again the next time prepareDistributed is called). Implementations should create a new store using any provider-specific configuration properties, and should also apply the value of the standard properties: getClusterName(), getLogLevel() and getBackupCopies(). Implementors may choose to put most of the initialization logic into the createStore method, or alternatively to simply pass this store factory to a constructor of the provider AbstractStore class which can extract the required information. Logging should usually be written to the main Correlator log (using log4j or Logger) or else to a separate file, rather than to standard out/err.

Returns:

Returns a store. Implementations must not return null; instead throw a DistMemStoreProvider exception if configuration could not be completed.

Throws:

DistMemStoreProviderException - Exception type to be thrown for bad configuration or connection problems (i.e. anything that does not indicate an internal error).

See Also:

initializeProviderSystemProperty(String, String): For providers that need system properties to be set on the JVM (e.g. for logging configuration), this method should be used, afterPropertiesSet(): Validation of the configuration should be performed mostly in afterPropertiesSet rather than createStore.

afterPropertiesSet

public void afterPropertiesSet()
                        throws java.lang.Exception

Validates the configuration properties at the end of the initialization process. Called during Correlator startup, after the setter methods on this bean have been called for all properties that are set in the Spring configuration. This method is the recommended place to validate configuration properties, since any exception thrown from this method will prevent the Correlator from starting, indicating the problem straight away without waiting until some EPL tries and fails to prepare the store. Subclass implementations are strongly recommended to start by calling the AbstractStoreFactory superclass implementation of this method, which validates standard properties such as clusterName and backupCopies.

Specified by:

afterPropertiesSet in interface org.springframework.beans.factory.InitializingBean

Throws:

java.lang.Exception

See Also:

org.springframework.beans.factory.InitializingBean#afterPropertiesSet()

destroy

public void destroy()
             throws java.lang.Exception

Performs final cleanup of the Called once during clean Correlator shutdown. This method can be overridden if required to free any resources (e.g. background threads) associated with this store factory - however best practice is to defer allocating any such resources until createStore is called, so this method should usually not be required.

Specified by:

destroy in interface org.springframework.beans.factory.DisposableBean

Throws:

java.lang.Exception

See Also:

org.springframework.beans.factory.DisposableBean#destroy()

getStoreName

public final java.lang.String getStoreName()

The unique storeName for this factory, specified by the id attribute in the configuration.

Returns:

the unique storeName for this factory

setBeanName

public final void setBeanName(java.lang.String storeName)

Called by Spring to initialize the storeName using the id attribute in its configuration. Internal only - do not call this method.

Specified by:

setBeanName in interface org.springframework.beans.factory.BeanNameAware

Parameters:

storeName - Set the bean name to that of the storeName

See Also:

org.springframework.beans.factory.BeanNameAware#setBeanName(java.lang.String)

getClusterName

public java.lang.String getClusterName()

The provider specific clusterName which groups same named distributed stores together for communication and data sharing. It is recommended to confirm this property is set in afterPropertiesSet() AbstractStoreFactory implementations are responsible for calling this method in their createStore implementation and applying the specified value to the distributed cache.

Returns:

this stores clusterName

setClusterName

public void setClusterName(java.lang.String clusterName)

A provider-specific string used to group together distributed store nodes that communicate with each other and share data. Stores with different clusterName values should operate independently. Typically clusterName represents a multicast group name, but for some providers it might be a list of host:port servers used to locate the nodes forming a cluster, or other provider-specific string.

Parameters:

clusterName - Set the clusterName to this

getLogLevel

public java.lang.String getLogLevel()

Get the log level that should be used (if possible) for the 3rd party provider's logging. AbstractStoreFactory implementations are responsible for calling this method and applying the value to the stores that they create.

Returns:

null if the default log level should be used (which is provider-specific), or else a string compatible with the Apama logger (conversion of empty strings to null and upper-casing of other strings is automatic, to simplify implementation).

See Also:

Logger

setLogLevel

public void setLogLevel(java.lang.String providerLogLevel)

The Apama log level at which this provider should log its own messages (not all providers will support this).

Parameters:

providerLogLevel - Set the log level to this

See Also:

Logger.setThreshold(String)

getBackupCopies

public int getBackupCopies()

Retrieve the number of additional redundant nodes that will hold a backup copy of data. It is recommended to confirm this property is set in afterPropertiesSet() AbstractStoreFactory implementations are responsible for calling this method in their createStore implementation and applying the specified value to the distributed cache.

Returns:

the number of additional nodes with copies of data

setBackupCopies

public void setBackupCopies(int backupCopies)

The number of additional redundant nodes that should hold a backup copy of each key/value data element. The minimum value for this property is 0 (indicating no redundancy). The default value is 1, indicating that all data should have one backup copy, i.e. all data will reside on 2 nodes. This value should override any backupCopies set in provider-specific configuration. Some providers may allow customizing the backup count on a per-table basis, in which case this property specifies an overridable default value for tables that do not specify it explicitly.

Parameters:

backupCopies - Set the number of backup copies required to this

getInitialMinClusterSize

public int getInitialMinClusterSize()

Retrieve the number of nodes required to join the cluster before the Distributed MemoryStore will send the Finished event. AbstractStoreFactory implementations are not responsible for implementing and using this property, the Correlator takes care of applying the initialMinClusterSize.

Returns:

the number of nodes required to join before starting the Distributed Memory store

setInitialMinClusterSize

public void setInitialMinClusterSize(int initialMinClusterSize)

The minimum number of nodes that are required to join the cluster before the Distributed MemoryStore will send the Finished event. The minimum value for this property is 1. The default value is 1.

Parameters:

initialMinClusterSize - Set the initial minimum cluster size to this

setRowChangedOldValueRequired

public void setRowChangedOldValueRequired(boolean oldValueRequired)

Set whether subscribers should receive old values in RowChanged events. If true (the default), then subscribers will include old values in RowChanged events. Not all providers support both settings; they may throw an exception if attempted to be configured with a setting that it cannot support.

getRowChangedOldValueRequired

public boolean getRowChangedOldValueRequired()

Retrieve whether subscribers should receive old values in RowChanged events. If true (the default), then subscribers will include old values in RowChanged events. Not all providers support both settings; they may throw an exception if attempted to be configured with a setting that it cannot support.

initializeProviderSystemProperty

public void initializeProviderSystemProperty(java.lang.String propertyName,
                                             java.lang.String value)

Helper method for setting the value of a JVM-wide system property which is required by this store. This method should be used in the createStore method implementation. This is the only recommended way to set standard system properties for a provider. It includes logging to make clear what is going on, and if the property was already set to a different value (explicitly by the user, or by another store) a warning is written to the log but the property is not changed.

Parameters:

propertyName - the property to set

value - the value to set the property to