11.3. Remote Event Notification Framework
Prev | Chapter 11. Remote and Offline Operation | Next

## 11.3. Remote Event Notification Framework

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.

| Important
This feature requires Kodo Enterprise Edition or Kodo Standard Edition with the Performance Pack.

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.

### 11.3.1. Remote Commit Provider Configuration

Kodo includes built in remote commit providers for JMS and TCP communication.

#### 11.3.1.1. JMS

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.8. 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 `EntityManagerFactory.close` or `PersistenceManagerFactory.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.

#### 11.3.1.2. TCP

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:

Example 11.9. TCP Remote Commit Provider Configuration

JPA XML format:

    <property name="kodo.RemoteCommitProvider"
        value="tcp(Addresses=10.0.1.10;10.0.1.11;10.0.1.12;10.0.1.13)"/>

JDO properties format:

    kodo.RemoteCommitProvider: tcp(Addresses=10.0.1.10;10.0.1.11;10.0.1.12;10.0.1.13)

#### 11.3.1.3. Common Properties

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.10. 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)

### 11.3.2. Customization

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. For details on particular customization needs, contact us at support@solarmetric.com.

Prev | Up | Next
11.2. Remote Managers | Home | Chapter 12. Management and Monitoring