The remote event notification framework allows a subset of the information available through OpenJPA's transaction events (see Section 7, “ Transaction Events ”) to be broadcast to remote listeners. OpenJPA'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
to use a RemoteCommitProvider (see below).
When a RemoteCommitProvider is properly configured, you can
register
RemoteCommitListeners that will be alerted with
a list of modified object ids whenever a transaction on a remote machine
successfully commits.
OpenJPA includes built in remote commit providers for JMS and TCP communication.
The JMS remote commit provider can be configured by setting the
openjpa.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/OpenJPACommitProviderTopic
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 OpenJPA of a serious connection error.
Defaults to 0, meaning OpenJPA 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 12.2. JMS Remote Commit Provider Configuration
<property name="openjpa.RemoteCommitProvider"
value="jms(ExceptionReconnectAttempts=5)"/>
Because of the nature of JMS, it is important that you invoke
EntityManagerFactory.close when finished with a factory. If you do
not do so, a daemon thread will stay up in the JVM, preventing the JVM from
exiting.
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
openjpa.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 should 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
MaxTotal property of
openjpa.ConnectionFactoryProperties in
Section 1, “
Using the OpenJPA 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.
MaxTotal: Total 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:
Example 12.3. TCP Remote Commit Provider Configuration
<property name="openjpa.RemoteCommitProvider"
value="tcp(Addresses=10.0.1.10;10.0.1.11;10.0.1.12;10.0.1.13)"/>
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 12.4. JMS Remote Commit Provider transmitting Persisted Object Ids
<property name="openjpa.RemoteCommitProvider"
value="jms(ExceptionReconnectAttempts=5, TransmitPersistedObjectIds=true)"/>
You can develop additional mechanisms for remote event notification be by
creating an implementation of the
RemoteCommitProvider interface, possibly by
extending the
AbstractRemoteCommitProvider abstract class..