The Unified API allows you to attach listeners to the repositories and certain services. The base interface of all listeners is CapListener. The base class of all events is CapEvent.

In Figure 4.5, “Class Diagram: Listeners” you see the type hierarchy of the class CapListener. Normally, you will want to implement one of the repository listeners, but there are occasions when you need the events of a service listener or a connection listener.

Figure 4.5. Class Diagram: Listeners

Most listener classes come with an abstract handler class whose name can be derived by adding Base to the interface's name. You can inherit from these classes when you want to handle only a small subset of the events provided. For example, a ContentRepositoryListener might be based on the class ContentRepositoryListenerBase.

Listeners are informed about changes asynchronously. No guarantees are made about the possible delays. However, it is assured that a listener will receive exactly those events that arise out of operations that are executed after the listener is added and before the listener is removed. Furthermore, all changes of an operation are visible through the Unified API before a listener is notified about the changes. In particular, the internal cache is invalidated as needed. It may be, however, that subsequent operations have already overwritten the state that was generated by the operation that caused the event. For example, a renamed document may have already been re-renamed before the event of the first rename operation is processed.

Listeners are called in a single thread. Events are processed in order and each event is delivered to all interested listeners before the next event is handled. This means that a slow listener can create a backlog of unprocessed events, even for other listeners. It also implies that listeners must not wait for events to arrive at other listeners.

You can set a listener priority to define the order of notification when adding a listener. A listener with a higher priority will be notified about a single event before all listeners with a lower priority. The default priority is CapListener.DEFAULT_PRIORITY.

Listeners may access the Unified API for processing events. They may even make write calls that cause additional events. However, a listener must not add or remove listeners. It may not even remove itself from the set of listeners. Spawn a separate thread if you have to do this.

When a CapConnection is closed, all listeners that are attached to the connection or its repositories are automatically removed. No more events are delivered, even when the connection is reopened. If desired, new listeners have to be attached.