Installs an AsyncEventListener implementation to GemFire XD peers in
a specified server group.
Syntax
CREATE ASYNCEVENTLISTENER listener-name
(
LISTENERCLASS 'class-name'
INITPARAMS 'init-params'
[ MANUALSTART boolean-constant ]
[ ENABLEBATCHCONFLATION boolean-constant ]
[ BATCHSIZE integer-constant ]
[ BATCHTIMEINTERVAL integer-constant ]
[ ENABLEPERSISTENCE boolean-constant ]
[ DISKSTORENAME store-name]
[ MAXQUEUEMEMORY integer-constant ]
[ ALERTTHRESHOLD integer-constant ]
)
SERVER GROUPS ( server_group_name [, server_group_name ]*)
- LISTENERCLASS
- The fully-qualified name of the class that implements the
AsyncEventListener interface. For example,
"user.application.TestAsyncEventListener". If you are configuring the built-in
DBSynchronizer implementation, specify
com.pivotal.gemfirexd.callbacks.DBSynchronizer.
- INITPARAMS
- Specify initialization parameters to pass to the init() method of the AsyncEventListener
implementation.
- GemFire XD passes a single string of initialization parameters when you
execute the CREATE ASYNCEVENTLISTENER statement. You must include the
INITPARAMS argument, even if it defines no parameters (INITPARAMS '').
- As a best practice, Pivotal recommends that you supply only a single parameter in the
string using the format
file=path-to-file, where
path-to-file references a file that defines each
listener parameter on a dedicated line, similar
to:
user=user-name
password=plain-text-password
- Using a separate parameter file enables you to change initialization parameters
after you have configured the listener in GemFire XD. Only the
file path is hard-coded in the listener configuration. If you define
parameters in the string passed to INITPARAMS, then you
must drop and re-create the listener in order to change any of those
parameter values.
- If you send user credentials in the initialization parameters, consider
encrypting the password using encrypt-password with the external
option. Your listener will need to use the
AsyncEventHelper.decryptPassword method to decrypt the
password before sending credentials to the outside data source.
- The built-in DBSynchronizer implementation requires specific parameters in order to initiate
a connection to a JDBC data source and apply DML to a database. See DBSynchronizer Initialization Parameters for a complete
reference to the DBSynchronizer parameters.
- MANUALSTART
- A boolean value that specifies whether you need to manually start
the listener with
SYS.START_ASYNC_EVENT_LISTENER.
If you do not supply a value, the default is "true" and you must start the
listener manually using
SYS.START_ASYNC_EVENT_LISTENER.
- ENABLEBATCHCONFLATION
- A Boolean value that determines whether GemFire XD should conflate
messages. The default is false.
- BATCHSIZE
- GemFire XD creates an internal queue where it stores the events that are eventually
dispatched to a configured listener. Multiple events are dispatched to the
listener in batches, and the BATCHSIZE parameter defines
the maximum number of messages that a batch can contain. The default is 100
messages. This parameter, along with BATCHTIMEINTERVAL,
determine the frequency with which GemFire XD dispatches queued events.
- BATCHTIMEINTERVAL
- The maximum number of milliseconds that can elapse between
sending batches. The default is 1000 milliseconds.
- ENABLEPERSISTENCE
- A Boolean value that determines whether GemFire XD persists the event queue to disk for high
availability. The default is "False."
Note: GemFire XD uses disk storage for
queue overflow when needed, even if you do not enable persistence for
the queue.
- DISKSTORENAME
- The named disk store to use for storing the queue overflow (default), or for
persisting the queue. If you specify a value, the named disk store must
exist. If do not specify a value, GemFire XD uses the default disk store for
queue overflow and persistence.
- MAXQUEUEMEMORY
- The maximum amount of memory in megabytes that the queue can
consume before overflowing to disk. The default is 100 megabytes.
- ALERTTHRESHOLD
- The maximum number of milliseconds that an event can remain in
this queue before GemFire XD logs an alert. The default is value is "0."
- SERVER GROUPS
- A comma-separated list of server group names. GemFire XD deploys the event listener
implementation on all peers in the specified server group(s).
Note: The specified server groups must contain at least one data
store member at the time you execute the CREATE ASYNCEVENTLISTENER
statement.
Note: When you deploy an event listener (or DBSynchronizer) to
listen for asynchronous events, specify a server group that contains no
more than 3 data stores. GemFire XD automatically designates the first
listener to startup as the "primary," and the remaining listeners become
"secondaries." Every additional "secondary" can slow down the publisher.
By default all GemFire XD members that store data are members of a
single "default" server group.
When multiple data stores host an
event listener, there is no direct way to ensure that a specific
GemFire XD data store hosts the active instance. If you require a
specific member to host the active instance, ensure that only that
member is running in the target server groups when you deploy the
listener and attach the table. You can then start the remaining data
stores in the server group, and they will host redundant, standby
instances.
Examples
Install a basic AsyncEventListener implementation to all data stores in the SG1
server group:
CREATE ASYNCEVENTLISTENER MyListener
(
LISTENERCLASS 'user.application.TestAsyncEventListener'
INITPARAMS ''
) SERVER GROUPS ( SG1 );
Install a DBSynchronizer configuration with a persistent event queue:
CREATE ASYNCEVENTLISTENER mydbsynch
(
LISTENERCLASS 'com.pivotal.gemfirexd.callbacks.DBSynchronizer'
INITPARAMS 'org.apache.derby.jdbc.EmbeddedDriver,jdbc:derby:newDB;create=true;'
ENABLEPERSISTENCE true
DISKSTORENAME mystore
)
SERVER GROUPS ( SG1 );
Create a new table and attach the installed DBSynchronizer:
CREATE TABLE TESTTABLE (ID INT NOT NULL,
NAME VARCHAR(10))
ASYNCEVENTLISTENER(mydbsynch);
Note: You can optionally install the AsyncEventListener configuration
after you
associate a table with the listener name. Make sure that you use the same listener
name with both the CREATE ASYNCEVENTLISTNER command and the
CREATE TABLE command.