Listener and Listener Notification Interactions
The design time interactions for listeners and listener notifications are essentially the same as the interactions for connections and polling notifications, as described in
Connection Class Interactions and
Polling Notification Interactions, respectively. This section describes the runtime behavior of listeners and their associated notifications.
Important:
A listener and the associated listener notifications must reside in the same package in the Integration Server_directory /instances/<instance_name>/packages/<your_package> folder. Otherwise, data is lost when a package is reloaded.
The figures that illustrate listener runtime interactions with synchronous and asynchronous notifications in this section show the runtime lifecycle of a listener from the time it is started until the time it is shut down. The difference between the two diagrams begins at step 3.3, when the server calls the runNotification method of the notification. Do not interpret the separation of these diagrams to imply that a given listener can use only synchronous or asynchronous notifications. On the contrary, step 3 represents a loop that repeats continuously while the listener is running, and any iteration of the loop may follow either course depending on the class type of the notification that indicates support for the notification event.
When a listener starts (or restarts), Integration Server performs the following:
Retrieves a connection from the associated connection node.
Calls the listener's
listenerStartup method. This
listenerStartup method performs the following:
Access the connection using the
retrieveConnection method from the base class.
Initialization required prior to the first
waitForData call.
Disables the listener if an exception is thrown by the
listenerStartup method, or if retrieving connection by
Integration Server fails.
Note:
A listener instance holds the connection it retrieves during listener initialization for the lifetime of the listener instance. Disabling the connection node has no impact on this connection already held by the listener, but prevents the listener from starting or restarting in the event of an AdapterConnectionException.
After initialization of the listener is complete, Integration Server initiates the notification event-processing loop represented by step 3 of the interaction diagrams. This loop continues until one of the following events occurs:
The user of the adapter disables the listener in the adapter's administrative interface.
Package containing the listener is disabled (or reloaded).
Note:
Disable the listener package before you disable the adapter package.
Integration Server is shut down.
Listener or a listener notification throws an
AdapterConnectionException. This causes the listener to shut down and to attempt to restart with a new connection.
Listener throws an
AdapterException or a
RunTimeException.
The following figure shows the listener runtime interactions with synchronous notification
The event-processing loop begins with a call to the listener's waitForData method. This method performs the following:
Interrogates the adapter resource to determine whether an event has occurred that the listener should report.
If the event has not occurred, the listener should return a
null object.
The model assumes that the listener implements some form of blocking read operation with a time component that allows it to return periodically, even if no notification event has occurred. The adapter developer must provide appropriate means of configuring the timing characteristics of this blocked read, such as through a metadata parameter on either the listener or the connection.
If the event has occurred, the listener's
waitForData method returns a non-null object,
Integration Server iterates through the listener notifications that are currently registered with the listener, which must be enabled and registered.
The data object received from
waitForData method is passed to the
supports method (step 3.2) for each notification.
For the first notification that returns
true from its
supports method:
Integration Server calls the
runNotification method passing the data object wrapped as a
NotificationEvent (step 3.3).
Integration Server calls the listener's
processNotificationResults method with a
NotificationResults as input object returned from
runNotification (step 3.4).
If no notification returned
true from the
supports method, or if
runNotification threw an exception other than an
AdapterConnectionException, then
processNotificationResults is called with a
null argument.
The listener notification's runNotification method (step 3.3) is responsible for the following:
Interpreting the
NotificationEvent object.
Building a
WmRecord object consistent with its output signature.
This may or may not require additional interaction with the resource. If it does, a connection is made available for that purpose through the retrieveConnection method, which is the same connection used by the listener.
An asynchronous notification passes this
WmRecord object to the
doNotify method (step 3.3.1).
The
doNotify method publishes the document in the same way it does for polling notifications.
An asynchronous notification must instantiate a new
AsynchNotificationResults object (step 3.3.3), including the notification name, which can be retrieved from the base class
nodeName method (step 3.3.2).
A synchronous notification's implementation of
runNotification method passes its output,
WmRecord object to
invokeService method instead of
doNotify method (step 3.3.1).
The service called by
invokeService method is specified in the configuration of the synchronous listener notification node. The service is invoked on a separate thread and transaction context.
The results of the service invocation are returned to
invokeService method as a
SynchronousNotificationResults object.
The results are then available to be interrogated by the notification and/or the listener, using the methods provided by that class.