javax.telephony.media.async
Interface Async.Event

All Superinterfaces:

MediaConstants, MediaEvent, MediaServiceConstants

All Known Subinterfaces:

Async_ASREvent, Async_ContainerEvent, Async_DataObjectEvent, Async_MediaConnectionEvent, Async_PlayerEvent, Async_RecorderEvent, Async_ServiceEvent, Async_SignalDetectorEvent, Async_SignalGeneratorEvent, Async.BindAndReleaseEvent, Async.BindEvent, Async.BindToCallEvent, Async.DelegationEvent, Async.MediaGroupEvent, Async.MediaServiceEvent, Async.ReleaseEvent, Async.ResourceEvent

All Known Implementing Classes:

Base.Event

Enclosing class:

Async

public static interface Async.Event

extends MediaEvent

Asynchronous version of the MediaEvent. Methods aupported by asynchronous events. Other Async Event interfaces extend from this.

An Async.Event [that is, a transaction] has methods:

  isDone();               // test for done-ness
  waitForEventDone();     // wait until isDone()
  waitForListenersDone(); // wait until isDone() and Listeners have returned
  getException();         // test failure/success

The MediaEvent methods getEventID and getSource() (and various flavors of it) immediately return the requested value.

Note: getException() and any accessor for the results of an operation (for example, getError(), ResourceEvent.getQualifier() or BindToCallEvent.getCall()) first waits for the event to complete (using waitForEventDone()), and then return the requested value. If you do not want to wait, then test first using isDone() to see if the event is complete.

Implementation Note: The Event's source is an MPI.Owner: a MediaService, ContainerService, etc. When an Async.Event completes, a notification is sent to the Event's source using (MPI.Owner).onEventDone(). The owner dispatches the event to any Listeners. See the MPI for more details.

See Also:

Fields inherited from interface javax.telephony.media.MediaServiceConstants

ev_BindAndConnect, ev_BindToCall, ev_BindToServiceName, ev_BindToTerminal, ev_BindToTerminalName, ev_Configure, ev_Connected, ev_DelegateToService, ev_Disconnected, ev_GetConfigSpec, ev_GetConfiguration, ev_GetParameters, ev_GetTerminal, ev_GetTerminalName, ev_GetUserValues, ev_GroupStop, ev_Release, ev_ReleaseDelegated, ev_ReleaseToDestroy, ev_ReleaseToService, ev_ReleaseToTag, ev_Retrieve, ev_Retrieved, ev_SetParameters, ev_SetUserDictionary, ev_SetUserValues, ev_TerminalIdle, ev_TriggerRTC

Fields inherited from interface javax.telephony.media.MediaConstants

e_OK, q_Duration, q_Standard, q_Stop

Method Summary

boolean	isDone() Indicates whether this Event has completed.
void	throwIfRuntimeException() waitForListenersDone() and then throw a RuntimeException, if any.
void	waitForEventDone() Wait for this asynchronous event to complete.
void	waitForEventDone(long msecs) Waits at most msecs for this event to complete.
void	waitForListenersDone() Wait for this event to complete and Listeners to complete.

Methods inherited from interface javax.telephony.media.MediaEvent

getError, getEventID, getException, getPayload, getQualifier, getSubError, getWarning

Method Detail

isDone

public boolean isDone()

Indicates whether this Event has completed.

Returns:

true iff this event has completed.

waitForEventDone

public void waitForEventDone()

Wait for this asynchronous event to complete.

Note: to get direct access to any InterruptedException use waitForEventDone(long) instead.

Throws:

a - RuntimeException if another thread interrupts the current thread. That is, any InterruptedException is wrapped in a RuntimeException.

waitForEventDone

public void waitForEventDone(long msecs)
                      throws java.lang.InterruptedException

Waits at most msecs for this event to complete.

Implements Async.Event

Parameters:

msecs - the time to wait in milliseconds, msecs = 0 means wait forever.

Throws:

java.lang.InterruptedException - if another thread has interrupted the current thread. The interrupted status of the current thread is cleared when this Exception is thrown.

waitForListenersDone

public void waitForListenersDone()

Wait for this event to complete and Listeners to complete.

This method is used by the synchronous API to wait for Listeners to complete before continuing the "main" thread.

Throws:

a - RuntimeException if another thread interrupts the current thread. That is, any InterruptedException is wrapped in a RuntimeException.

throwIfRuntimeException

public void throwIfRuntimeException()
                             throws java.lang.RuntimeException

waitForListenersDone() and then throw a RuntimeException, if any. Throw if requested operation resulted in a RuntimeException.

Note: other events define methods to throw other classes of Exceptions, and those methods invoke this one internally. Therefore all the throwIf() methods waitForListenersDone, and also throw any RuntimeException in the event.

Throws:

java.lang.RuntimeException - if the event holds a RuntimeException.