javax.telephony.media.provider
Class Base.Event

java.lang.Object
  |
  +--java.util.EventObject
        |
        +--javax.telephony.media.provider.EventObject
              |
              +--javax.telephony.media.provider.Base.Event

All Implemented Interfaces:

Async.Event, Dispatcher.DispatchableEvent, MediaConstants, MediaEvent, MediaServiceConstants, java.io.Serializable

Direct Known Subclasses:

Base.MediaServiceEvent

Enclosing class:

Base

public static class Base.Event

extends javax.telephony.media.provider.EventObject

implements Async.Event, Dispatcher.DispatchableEvent

Implement a base class for Async.Event and MediaEvent. Includes in-package methods for provider use.

This class can be instantiated, but the resulting event has a no-op dispatch method; which means it goes through the EventQueue, but is not dispatched to any Listener. For most uses, a specialized class with a dispatch to Listener should be used.

This models the basic S.200 Event structure. The standard message/event fields are represented in this object, eventID, qualifier, error, suberr, payload, S.200 "status" is represented by the exception field in combination with the error:

statusOK:	error == Error_OK;	exception == null
statusWarn:	error != Error_OK;	exception == null
statusFail:	error != Error_OK;	exception != null

See Also:

Serialized Form

Inner Class Summary

static class

Base.Event.SyncInterruptedException Thown when waitForEventDone() is interrupted by another Thread.

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

Constructor Summary

Base.Event(java.lang.Object source, Symbol eventID)
Construct specific completion or non-tranaction event.

Base.Event(java.lang.Object source, Symbol eventID, java.lang.Exception exception)
Constructor for an event that is done.

Method Summary

void	dispatch(java.util.EventListener listener) Invoke the appropriate callback method on the appropriate Listener.
void	done(java.lang.Exception exception) Set the exception and mark as done.
Symbol	getError() Identify the reason or cause of an error or failure.
Symbol	getEventID() Get the Symbol that identifies this event.
java.lang.Exception	getException() Simple waitForEventDone() and then return any Exception.
MediaService	getMediaService() Deprecated. "use MediaServiceEvent.getMediaService()"
java.util.Dictionary	getPayload() Get the Payload of this event.
Symbol	getQualifier() Get the Qualifier of this event.
int	getSubError() Get the suberror for this event.
Symbol	getWarning() Return the error code, in the case where it was not a failure that generates an Exception.
boolean	isDone() Indicates whether this Event has completed.
void	setError(Symbol error)
void	setFields(java.util.Dictionary message) extract common fields from an S.200 message Dictionary
void	setFields(Symbol qual, Symbol error, int suberror, java.util.Dictionary payload) Set extra info fields before done(Exception).
void	setPayload(java.util.Dictionary payload)
void	setQualifier(Symbol qual)
void	setSubError(int suberror)
void	throwIfRuntimeException() waitForEventDone() and then throw if event holds a RuntimeException.
java.lang.String	toString()
void	waitForEventDone() Waits for this event to complete.
void	waitForEventDone(long msecs) Waits at most msecs for this event to complete.
void	waitForListenersDone() waitForEventDone() and wait for Listener callbacks to return.

Methods inherited from class java.util.EventObject

getSource

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Base.Event

public Base.Event(java.lang.Object source,
                  Symbol eventID)

Construct specific completion or non-tranaction event.

Parameters:

source - the MPI$Owner which dispatches this Dispather.DispatchableEvent.

eventID - a Symbol that identifies this event.

Base.Event

public Base.Event(java.lang.Object source,
                  Symbol eventID,
                  java.lang.Exception exception)

Constructor for an event that is done.

Parameters:

source - the MediaService object that created this EventObject.

eventID - a Symbol that identifies the event.

exception - an Exception to be thrown in invoking thread.

Method Detail

toString

public java.lang.String toString()

Overrides:

toString in class java.util.EventObject

getMediaService

public MediaService getMediaService()

Deprecated. "use MediaServiceEvent.getMediaService()"

Get the MediaService associated with the current event.

Defined in MediaEvent

Returns:

the MediaService associated with this event.

getEventID

public Symbol getEventID()

Get the Symbol that identifies this event.

Implements MediaEvent

Specified by:

getEventID in interface MediaEvent

Returns:

the Symbol that identifies this event

getQualifier

public Symbol getQualifier()

Get the Qualifier of this event.

Specified by:

getQualifier in interface MediaEvent

Returns:

one of the qualifier Symbols (q_Something)

getError

public Symbol getError()

Identify the reason or cause of an error or failure.
If this ResourceEvent is associated with an Exception, then getError() will identify the problem.

If this Event is not associated with an Exception, then getError() returns ESymbol.Error_OK. In such a case, use getWarning()

Specified by:

getError in interface MediaEvent

Returns:

one of the Error Symbols

getWarning

public Symbol getWarning()

Return the error code, in the case where it was not a failure that generates an Exception.

Specified by:

getWarning in interface MediaEvent

Returns:

one of the Error Symbols

getSubError

public int getSubError()

Get the suberror for this event.

Specified by:

getSubError in interface MediaEvent

Returns:

an int

getPayload

public java.util.Dictionary getPayload()

Get the Payload of this event.

Specified by:

getPayload in interface MediaEvent

Returns:

a Dictionary of [additional] event information.

getException

public java.lang.Exception getException()

Simple waitForEventDone() and then return any Exception.

Implements Async.Event.

Specified by:

getException in interface MediaEvent

Following copied from interface: javax.telephony.media.MediaEvent

Returns:

any Exception generated by the transaction.

throwIfRuntimeException

public void throwIfRuntimeException()

waitForEventDone() and then throw if event holds a RuntimeException.

Implements Async.Event

All synchronous API methds come here to synchronize, and this method does special synchronization to wait until all the Listeners for an event have run an returned.

Note: We believe the synch APIs are the only users of this method. If this method comes to be used in a context where this 'Listener' synchronization is not desired, then we could use the regular waitForEventDone() here and change Base_MediaService.java to invoke waitForListenersDone() directly before calling throwIf...Exception().

Note: This method catches any InterruptedException and throws it as a RuntimeException. If an application needs to catch the InterruptedException directly, it should use waitForEventDone(long).

Specified by:

throwIfRuntimeException in interface Async.Event

Following copied from interface: javax.telephony.media.async.Async.Event

Throws:

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

waitForListenersDone

public void waitForListenersDone()

waitForEventDone() and wait for Listener callbacks to return.

Used by the synchronous API.

Note: This method catches any InterruptedException and throws it as a RuntimeException. If an application needs to catch the InterruptedException directly, it should use waitForEventDone(long).

Specified by:

waitForListenersDone in interface Async.Event

Following copied from interface: javax.telephony.media.async.Async.Event

Throws:

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

waitForEventDone

public void waitForEventDone()

Waits for this event to complete.

Implements Async.Event

Note: This method catches any InterruptedException and throws it as a RuntimeException. If an application needs to catch the InterruptedException directly, it should use waitForEventDone(long).

Note: Applications should be aware that Listener callbacks may run before, during, or after the thread that calls this method is continued. In contrast, the synchonous API methods use waitForListenersDone() which blocks until all Listeners have been notified.

Specified by:

waitForEventDone in interface Async.Event

Throws:

SyncInterruptedException, - a RuntimeException if another thread has interrupted the current thread.

waitForEventDone

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

Waits at most msecs for this event to complete.

Implements Async.Event

Specified by:

waitForEventDone in interface Async.Event

Parameters:

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

Throws:

Base.Event.SyncInterruptedException - if another thread has interrupted the current thread. The interrupted status of the current thread is cleared when this exception is thrown.

isDone

public final boolean isDone()

Indicates whether this Event has completed.

Implements Async.Event

Specified by:

isDone in interface Async.Event

Returns:

true iff this event has completed.

setFields

public void setFields(java.util.Dictionary message)

extract common fields from an S.200 message Dictionary

setFields

public void setFields(Symbol qual,
                      Symbol error,
                      int suberror,
                      java.util.Dictionary payload)

Set extra info fields before done(Exception).

Note: this is not synchronized, it should be called from the same thread that [later] calls done(Exception).

Parameters:

qual - a Symbol that identifies the cause of completion

error - a Symbol that identifies the cause of failure

suberror - an int with more info about the error

payload - a Dictionary of additional information (non null).

setQualifier

public void setQualifier(Symbol qual)

setError

public void setError(Symbol error)

setSubError

public void setSubError(int suberror)

setPayload

public void setPayload(java.util.Dictionary payload)

done

public void done(java.lang.Exception exception)

Set the exception and mark as done. Invokes .notifyAll() to release any .wait() invocations, making event fields available to users.

Used by implementations of MPI.MediaGroup and MPI.GroupProvider.

Implements MPI.Event

dispatch

public void dispatch(java.util.EventListener listener)

Invoke the appropriate callback method on the appropriate Listener. Each sub-class must define an EventListener and callback method by supplying this method.

Implements Dispatcher.DispatchableEvent

Typically, Async.SomeEvent dispatches to like this:

public void dispatch(EventListener listener) {
if (listener instanceof Async.SomeListener)
((Async.SomeListener)listener).onSomeDone(this);
}

Invoked by Base_MediaService

Specified by:

dispatch in interface Dispatcher.DispatchableEvent

Parameters:

listener - an EventListener, some kind of MediaListener.