JSR-043: JTAPI-1.4

Package javax.telephony.media.async

Defines asynchronous methods, events and Listeners for the media package.

See:
          Description

Interface Summary
Async Asynchronous Event and Listener interfaces.
Async_ASR Asynchronous version of ASR Resource methods.
Async_ASREvent Defines an ASREvent with Async.ResourceEvent methods.
Async_ASRListener Defines the callback methods for Async_ASR transactional Events.
Async_Delegation Asynchronous versions of the Delegation transaction methods.
Async_Player Non-blocking methods for the Player resource.
Async_PlayerEvent Defines a PlayerEvent with Async.ResourceEvent methods.
Async_PlayerListener Defines the callback methods for Async_Player transactional Events.
Async_Recorder Non-blocking methods for Recorder resource.
Async_RecorderEvent Defines a RecorderEvent with Async.ResourceEvent methods.
Async_RecorderListener Defines the callback methods for Async_Recorder transactional Events.
Async_SignalDetector Non-blocking methods for SignalDetector.
Async_SignalDetectorEvent Defines a SignalDetectorEvent with Async.ResourceEvent methods.
Async_SignalDetectorListener Defines the callback methods for Async_SignalDetector completion Events.
Async_SignalGenerator Non-blocking methods for SignalGenerator.
Async_SignalGeneratorEvent Defines a SignalGeneratorEvent with Async.ResourceEvent methods.
Async_SignalGeneratorListener Defines the callback methods for Async_SignalGenerator completion Events.
Async_TTSPlayer Non-blocking methods for the TTS Player resource.
Async_TTSPlayerListener Defines the callback methods for Async_Player transactional Events.
Async.BindAndReleaseEvent Marks the events from the GroupProvider.
Async.BindAndReleaseListener Listener for Async.BindAndReleaseEvents.
Async.BindEvent Return event when binding.
Async.BindToCallEvent Return event when binding to a Call.
Async.DelegationEvent Return type from async_delegateToService().
Async.DelegationListener Listener for Async.DelegationEvents.
Async.Event Asynchronous version of the MediaEvent.
Async.MediaGroupEvent Marks those Async events that come from the MediaGroup methods.
Async.MediaGroupListener Listener for MediaGroup method transaction completion events.
Async.MediaService Asynchronous methods for a MediaService.
Async.MediaServiceEvent An Async.Event from a MediaService; includes getMediaService().
Async.ReleaseEvent return type from async_release().
Async.ResourceEvent Extends ResourceEvent to include asynchronous event methods.
 

Class Summary
Async_ASRListenerAdapter Implements all Async_ASRListener and ASRListener methods.
Async_PlayerListenerAdapter Implements all Async_PlayerListener and PlayerListener methods.
Async_RecorderListenerAdapter Implements all Async_RecorderListener and RecorderListener methods.
 

Package javax.telephony.media.async Description

Defines asynchronous methods, events and Listeners for the media package.

Package Overview

The async package defines interfaces for asynchronous MediaService methods, asynchronous Events, Listener callback interfaces, and asynchronous Resource interfaces.

The asynchronous MediaService method definitions are derived from the synchronous method definitions. Async.MediaService defines a method corresponding to each synchronous MediaService method. For each synchronous methodName(arglist), the corresponding asynchronous methods is named: async_methodName. The async method has exactly the same arglist as the synchronous methodName. The return values are always some Async.Event, specialized as necessary to contain any return values. In all cases, the asynchronous methods have exactly the same argument signature as the synchronous counterpart, and always return an Async.Event.

The same rules apply to Resource methods. Most synchronous Resource methods return some MediaEvent. For example play returns a PlayerEvent. The corresponding asynchronous method returns an Async.Event named by prepending "Async_". For example, async_play returns Async_PlayerEvent.

Theory of Operation:

All MediaService and Resource methods are internally invoked using the async interfaces. The return value from all async methods is some specialization of Async.Event. The synchronous transaction methods block waiting until the Async.Event is done. An event is done when the transaction is complete and the return values from the operation have been stored in the event. When the event is done, the synchronous MediaService methods return the value of interest as extracted from the event (or return void, if there is no interesting value). The synchronous Resource method return the event itself; the event acts like a multiple-value return structure.

In contrast, the asychronous methods immediately and directly return the Async.Event object. The application has limited access to the fields of the event until the event is done. Two event accessors are always (or immediately) accessible: the EventID and the Event source (a MediaService). The methods getEventID() and getSource() (or the equivalent getMediaService()) return these values. The other fields of an event are not accessible until the event is done.

If a transactional method completes with an error status, then the event contains an Exception. The synchronous API methods extract and throw that error (using throwIfXXXException(). The asychronous API methods never throw the Exceptions created from transactional errors. However, that asynchronous methods may throw Exceptions based on analysis at invocation time. The application should check for errors using getException() or for Resource events one can also use getError().

An application can synchronize with an event (wait for it to be done) in several ways:

  1. Invoke the waitForEventDone() method directly. The waitForEventDone() method blocks until the event is done, and then returns. [the invoking Thread is blocks using Thread.wait() and is released by notifyAll() when the event is done.]
  2. Invoke an event accessor (other than getEventID or getMediaService). All event accessors internally call waitForEventDone() before extracting values from the event.
  3. Invoke the event method isDone() to effect a "polling" test. isDone() returns false if waitForEventDone() would block. [internally waitForEventDone() blocks until isDone() returns true.]
  4. Establish a Listener for the event of interest. The listener callback is invoked when the event is done.
  5. Invoke the waitForListenersDone() method. The waitForListenersDone() method blocks until the event is done and all Listeners have run, and then returns. This method is used the synchronouse API methods.
Note that synchronous tranasction methods do generate asynchronous events internally, and those events are delivered to listeners. Note also that the event objects returned from synchronous Resource methods are guarenteed to be done when the method returns. Furthermore, the synchronous API guarantees that all listeners have been notified before the method returns.

As always, the order in which listeners are invoked is indeterminate.

Since:
Jtapi-1.4

JSR-043: JTAPI-1.4

Send comments to: JSR-43@ectf.org