com.cisco.jtapi.extensions
Interface CiscoSynchronousObserver


public interface CiscoSynchronousObserver

Introduction

The Cisco JTAPI implementation is designed to allow applications to invoke blocking JTAPI methods such as Call.connect() and TerminalConnection.answer() from within their observer callbacks. This means that applications are not subject to the restrictions imposed by the JTAPI specification, which cautions applications against using JTAPI methods from within observer callbacks.

Normally, when an application adds a new observer to a JTAPI object, the Cisco JTAPI implementation creates an event queue and an accompanying worker thread to service the new observer. If the same observer is added to another object, its queue and thread are reused; in effect, every unique observer object has a single queue and worker thread. As noted, the advantage of this arrangement is that an application may invoke blocking JTAPI methods from within its observer callback. A subtle disadvantage, however, is that accessor methods such as Call.getConnections() and Connection.getState() may not return results that are consistent with events when invoked from within the observer callback.

For example, suppose that an application creates and connects a call from address "A" to address "B." If the application is observing address "A", it might reasonably expect that when it receives the CallActiveEv, the state of the call will be Call.ACTIVE. This is not necessarily true, because the worker thread that delivers events to the application is decoupled from the internal JTAPI thread that updates object states. In fact, if "B" rejects the call from "A," the call object might be in either the Call.ACTIVE state or the Call.INVALID state, depending on the exact moment at which the worker thread delivers the CallActiveEv.

Many applications will not be adversely affected by this asychronous behavior. Applications that would benefit from a coherent call model during observer callbacks, however, can selectively disable the queueing logic of the Cisco JTAPI implementation. Applications that implement the CiscoSynchronousObserver interface on their observer objects declare that they want events to be delivered synchronously to its observers. Events delivered to synchronous observers will match the states of the call model objects queried from within the observer callback.

Objects that implement the CiscoSynchronousObserver interface may not invoke blocking JTAPI methods from within their event callbacks. The consequences of doing so are unpredictable, and may include deadlocking the JTAPI implementation. On the other hand, you may safely use the accessor methods of any JTAPI object, such as Call.getConnections() or Connection.getState().