Event notifications are used to notify listening applications that an event they are interested in has occurred. The POA keeps a notification list in memory, which contains a list of registered applications. (Applications add themselves to the notification list by calling the getEventsRequest method with the notify element set to True.) Each application in the notification list can be listening for events for many users.
Be aware of the following when using event notifications:
Because there could be network problems or applications might not be listening when a notification is sent, we cannot guarantee that you’ll receive every notification. However, an event record is created in the user's store that describes the event. Your application can periodically read the events and determine if the local store is current.
By default, the getEventsResponse method returns 256 event items. This default number can be changed by setting the count element to the desired count. However, we recommend using the default setting.
For example, if you were processing 500 event items in a user's event queue, your application is notified that events are available. It would then call getEventsRequest and receive 256 items. However, the POA does not notify the application that there are more events in the queue. The first notification was for all 500 event items. You would need to call getEventsRequest one more time to retrieve the remaining 244 events.
Notifications resume if a new event is added to the event queue (in addition to the original 500), and if the application is in the notification list
The POA maintains a notification list in memory. If the notification list has five users associated with one application, the notification process on the POA opens and closes one connection for all the users in the list.
Each event has a UID element. The UID is a unique identifier for the corresponding event record in the database. The UIDs are sequentially numbered in the database. For example, a database can have events 1086, 1087, 1088, 1089, and 1090 in ascending order. However, calling getEventsResponse might not return the event items in ascending order.
UIDs that are created in a one-second duration are returned in descending order. For example, UID 1086 is created between seconds one and two. UIDs 1087, 1088, 1089 are created between seconds two and three. UID 1090 is created between seconds three and four. The getEventResponse method returns the event UIDs in the following order: 1086, 1089, 1088, 1087, and 1090, with the items created between seconds two and three in descending order.
There might be a small time period where all events are not returned by calling getEventsRequest. The is a timing issue based on retrieving events using the from and until dateTime elements.
For example, there are five separate events written to a user's store in one second and only three of the five events are in the database when the application retrieves the events. The other two events are written to the database after the retrieval. The application might assume that it retrieved all the event s in the database for that one second, but that might not be the case.
We recommend using the following algorithm when retrieving events to ensure that events are not missed. (There might be other methods to achieve the same results.)
An application calls getEventsRequest and finds the newest event record returned by selecting the newest timeStamp in the returned list.
When the application calls getEventsRequest again, it uses the newest timeStamp and subtracts one second from it. Any duplicates can be removed by the application by tracking the UIDs of items that it has already processed.
If a POA goes down, the notification list that is stored in memory is lost. Before GroupWise 8.0 SP2, the application needed to call getEventsRequest with the notify element set to True to add itself to the notification list again. Now, when the POA comes back up, it will automatically put the event configuration in the notification list and send a notification on the first event that triggers from the event configuration.
GroupWise Event notifications do not work correctly when more than one POA runs against a Post Office because the notification list stored in a POA’s memory is created and updated when an application calls the getEventsRequest with the notify element set to true.
For example, we have POA1 and POA2 running against PO1, but our application knows only about POA1. The application calls getEventsRequest with the notify element set to True for POA1. POA1 is now building a notification list to tell the application when a specific event occurs. If a GroupWise client now connects to POA2, POA2 processes the action and creates the event in the user's database. However, POA2 does not have the notification list in memory to notify the application of events. Thus, notifications do not work as expected.
If your application is interested only in retrieving event records outside of notifications, having two POAs running against one post office is acceptable.