The remote event notification framework allows a subset of the information available through Kodo's transaction events (see Section 9.8, “Transaction Events”) to be broadcast to remote listeners. Kodo's data cache, for example, uses remote events to remain synchronized when deployed in multiple JVMs.
To enable remote events, you must configure the
EntityManagerFactory
or PersistenceManagerFactory
to use a RemoteCommitProvider
(see below).
When a RemoteCommitProvider
is properly configured, you
can register
RemoteCommitListener
s that will be alerted
with a list of modified object ids whenever a transaction on a remote
machine successfully commits.
Kodo includes built in remote commit providers for JMS and TCP communication.
Kodo includes built in remote commit providers for JMS and TCP
communication. The JMS remote commit provider can be configured by
setting the
kodo.RemoteCommitProvider
property
to contain the appropriate configuration properties. The JMS
provider understands the following properties:
Topic
: The topic that the remote commit
provider should publish notifications to and subscribe
to for notifications sent from other JVMs. Defaults to
topic/KodoCommitProviderTopic
TopicConnectionFactory
: The JNDI name of
a javax.jms.TopicConnectionFactory
factory to use for finding topics. Defaults to
java:/ConnectionFactory
. This setting may
vary depending on the application server in use; consult
the application server's documentation for details
of the default JNDI name for the
javax.jms.TopicConnectionFactory
instance. For example, under Weblogic, the JNDI name
for the TopicConnectionFactory is
javax.jms.TopicConnectionFactory
.
ExceptionReconnectAttempts
: The number of
times to attempt to reconnect if the JMS system notifies
Kodo of a serious connection error. Defaults to 0, meaning
Kodo will log the error but otherwise ignore it, hoping the
connection is still valid.
*
: All other configuration properties
will be interpreted as settings to pass to the JNDI
InitialContext
on construction. For
example, you might set the java.naming.provider.url
property to the URL of the context provider.
To configure a factory to use the JMS provider, your properties might look like the following:
Example 11.9. JMS Remote Commit Provider Configuration
JPA XML format:
<property name="kodo.RemoteCommitProvider" value="jms(Topic=topic/KodoCommitProviderTopic)"/>
JDO properties format:
kodo.RemoteCommitProvider: jms(Topic=topic/KodoCommitProviderTopic)
Note | |
---|---|
Because of the nature of JMS, it is important that you invoke
|
The TCP remote commit provider has several options that are
defined as host specifications containing a host name or IP
address and an optional port separated by a colon. For example,
the host specification saturn.bea.com:1234
represents an InetAddress
retrieved by
invoking InetAddress.getByName ("saturn.bea.com")
and a port of 1234.
The TCP provider can be configured by setting the
kodo.RemoteCommitProvider
plugin property to contain the
appropriate configuration settings. The TCP provider understands the
following properties:
Port
: The TCP port that the provider
should listen on for commit notifications. Defaults to
5636.
Addresses
: A semicolon-separated list of
IP addresses to which notifications should be sent. No
default value.
NumBroadcastThreads
: The number of
threads to create for the purpose of transmitting events to
peers. You sould increase this value as the number of
concurrent transactions increases. The maximum number of
concurrent transactions is a function of the size of the
connection pool. See the the MaxActive
property of
kodo.ConnectionFactoryProperties
in
Section 4.1, “Using the Kodo DataSource”.
Setting a value of 0 will result in behavior where the
thread invoking commit
will
perform the broadcast directly. Defaults to 2.
RecoveryTimeMillis
: Amount of time to
wait in milliseconds before attempting to reconnect to a
peer of the cluster when connectivity to the peer is lost.
Defaults to 15000.
MaxIdle
: The number of TCP sockets
(channels) to keep open to each peer in the cluster for
the transmission of events. Defaults to 2.
MaxActive
: The maximum allowed number
of TCP sockets (channels) to open simultaneously
between each peer in the cluster.
Defaults to 2.
To configure a factory to use the TCP provider, your properties might look like the following:
In addition to the provider-specific configuration options above, all providers accept the following plugin properties:
TransmitPersistedObjectIds
: Whether
remote commit events will include the object ids of
instances persisted in the transaction. By default only
the class names of types persisted in the transaction are
sent. This results in smaller events and more efficient
network utilization. If you have registered your own
remote commit listeners, however, you may require the
persisted object ids as well.
To transmit persisted object ids in our remote commit events using the JMS provider, we modify the previous example as follows:
Example 11.11. Transmitting Persisted Object Ids
JPA XML format:
<property name="kodo.RemoteCommitProvider" value="jms(Topic=topic/KodoCommitProviderTopic, TransmitPersistedObjectIds=true)"/>
JDO properties format:
kodo.RemoteCommitProvider: jms(Topic=topic/KodoCommitProviderTopic, TransmitPersistedObjectIds=true)