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 run-time behavior of listeners and their associated notifications.

The figures that illustrate listener run-time interactions with synchronous and asynchronous notifications in this section show the run-time 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), the server retrieves a connection from the associated connection node before it calls the listener's listenerStartup method. This method can access the connection using the retrieveConnection method from the base class. The listenerStartup implementation should validate the values of any metadata parameter settings, and perform any initialization required prior to the first waitForData call. An exception thrown by the listenerStartup method, or a failure to retrieve a connection by the server, disables the listener.

After initialization of the listener is complete, the 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 event-processing loop begins with a call to the listener's waitForData method. This method should interrogate the adapter resource to determine whether an event has occurred that the listener should report. If not, the listener should return a null object to allow the server to check for the shutdown conditions mentioned above. The model assumes that the listener will implement some form of blocking read operation with a time component that will allow it to return periodically, even if no notification event has occurred. It is your responsibility to 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).

When the listener's waitForData method returns a non-null object, the server iterates through the listener notifications that are currently registered with the listener (which must be enabled and registered). For each notification, the supports method is passed the data object received from waitForData (step 3.2). (The notification list order can be manipulated in the adapter's administrative interface by editing the listener's settings.) For the first notification to return true from its supports method, the server calls the runNotification method, passing the data object wrapped as a NotificationEvent (step 3.3). The NotificationResults object returned from runNotification is then passed to the listener's processNotificationResults method (step 3.4). If no notification returned true from the supports call, 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 interpreting the NotificationEvent object, and for 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 doNotify (step 3.3.1 in the figure that shows listener run-time interactions with asynchronous notification), which publishes the document in the same way it does for polling notifications. After publishing the notification, an asynchronous listener notification should 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).

The implementation of runNotification in a synchronous notification passes its output WmRecord object to invokeService instead of doNotify (step 3.3.1 in the figure that shows listener run-time interactions with synchronous notification). The service called by this method is specified in the configuration of the synchronous listener notification node. (As noted in the diagram, the service is invoked on a separate thread and transaction context.) The results of this service invocation are returned by invokeService 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.