org.jvoicexml.interpreter

Interface EventHandler

All Superinterfaces:

EventSubscriber

All Known Implementing Classes:

JVoiceXmlEventHandler

public interface EventHandler
extends EventSubscriber

Event handler to catch events generated from the ImplementationPlatform and propagated via the EventBus.

When an event is thrown, the scope in which the event is handled and its enclosing scopes are examined to find the best qualified catch element, according to the following algorithm:

1. Form an ordered list of catches consisting of all catches in the current scope and all enclosing scopes (form item, form, document, application root document, interpreter context), ordered first by scope (starting with the current scope), and then within each scope by document order.
2. Remove from this list all catches whose event name does not match the event being thrown or whose cond evaluates to false after conversion to boolean.
3. Find the correct count: the highest count among the catch elements still on the list less than or equal to the current count value.
4. Select the first element in the list with the correct count.

The name of a thrown event matches the catch element event name if it is an exact match, a prefix match or if the catch event attribute is not specified (note that the event attribute cannot be specified as an empty string - event="" is syntactically invalid). A prefix match occurs when the catch element event attribute is a token prefix of the name of the event being thrown, where the dot is the token separator, all trailing dots are removed, and a remaining empty string matches everything.

See Also:

ImplementationPlatform

Method Summary

Modifier and Type	Method and Description
boolean	addStrategy(EventStrategy strategy) Adds a strategy for the given event type.
void	clean(FormItem item) Removes all event handlers that were collected for the given form item.
void	clearEvent() Removes all cached events that have been received.
void	collect(VoiceXmlInterpreterContext context, VoiceXmlInterpreter interpreter, Dialog dialog) Adds all event handlers defined in the given dialog.
java.util.Collection<EventStrategy>	collect(VoiceXmlInterpreterContext context, VoiceXmlInterpreter interpreter, FormInterpretationAlgorithm fia, CatchContainer item) Adds all event handlers defined in the given input item.
void	collect(VoiceXmlInterpreterContext context, VoiceXmlInterpreter interpreter, org.jvoicexml.xml.vxml.VoiceXmlDocument document) Adds all event handlers defined in the given document.
JVoiceXMLEvent	getEvent() Retrieves the event.
void	processEvent(CatchContainer item) Processes the last received event.
boolean	removeStrategies(java.util.Collection<EventStrategy> strategies) Removes the given strategies.
JVoiceXMLEvent	waitEvent() Waits until an event was generated in the implementation platform.

Methods inherited from interface org.jvoicexml.event.EventSubscriber

onEvent

Method Detail

collect

void collect(VoiceXmlInterpreterContext context,
             VoiceXmlInterpreter interpreter,
             org.jvoicexml.xml.vxml.VoiceXmlDocument document)

Adds all event handlers defined in the given document.

Parameters:

context - the current VoiceXmlInterpreterContext

interpreter - the current VoiceXmlInterpreter

document - the document to inspect.

collect

void collect(VoiceXmlInterpreterContext context,
             VoiceXmlInterpreter interpreter,
             Dialog dialog)

Adds all event handlers defined in the given dialog.

Parameters:

context - the current VoiceXmlInterpreterContext

interpreter - the current VoiceXmlInterpreter

dialog - the dialog to inspect.

collect

java.util.Collection<EventStrategy> collect(VoiceXmlInterpreterContext context,
                                            VoiceXmlInterpreter interpreter,
                                            FormInterpretationAlgorithm fia,
                                            CatchContainer item)

Adds all event handlers defined in the given input item.

Parameters:

context - the current VoiceXmlInterpreterContext

interpreter - the current VoiceXmlInterpreter

fia - the current FIA.

item - the form item to inspect.

Returns:

added event handlers

clean

void clean(FormItem item)

Removes all event handlers that were collected for the given form item.

Parameters:

item - the form item

Since:

0.7.4

waitEvent

JVoiceXMLEvent waitEvent()

Waits until an event was generated in the implementation platform.

Returns:

the caught event.

processEvent

void processEvent(CatchContainer item)
           throws JVoiceXMLEvent

Processes the last received event.

Parameters:

item - The current form item.

Throws:

JVoiceXMLEvent - Error or event processing the event or there was no handler to process the current event

clearEvent

void clearEvent()

Removes all cached events that have been received.

Since:

0.7.7

addStrategy

boolean addStrategy(EventStrategy strategy)

Adds a strategy for the given event type.

Parameters:

strategy - the strategy to add.

Returns:

true if the strategy was added.

removeStrategies

boolean removeStrategies(java.util.Collection<EventStrategy> strategies)

Removes the given strategies.

Parameters:

strategies - strategies to remove

Returns:

true if at least one strategy was removed

Since:

0.7.2

getEvent

JVoiceXMLEvent getEvent()

Retrieves the event.

Returns:

the caught event.