org.speakright.core
Class TrailWrapper

java.lang.Object
  org.speakright.core.TrailWrapper

All Implemented Interfaces:

java.io.Serializable, IFlow

public class TrailWrapper
extends java.lang.Object
implements IFlow

A wrapper flow object that does nothing except remember which of its methods were called. Uses a Trail object to build a string. Used for unit tests only.

Author:

IanRaeLaptop

See Also:

Serialized Form

Field Summary

Trail

m_trail

Constructor Summary

TrailWrapper(IFlow flow)

Method Summary

IFlowRenderer	createRenderer()
void	execute(IExecutionContext context) Generates a VoiceXML page, which is sent to the speech platform for execution.
int	executionCount() The number of times this flow has been executed (in the current activation).
Grammar	fixupGrammar(Grammar gram) Callback that lets a flow object do any adjustments on grammars.
java.lang.String	fixupPrompt(java.lang.String item) Callback that lets a flow object do any adjustments on prompt text.
IFlow	getFirst(IFlowContext context) Gets the first sub-flow to be executed.
IFlow	getNext(IFlow current, SRResults results) Gets the next flow object to be executed.
IFlow	getSubFlowAfter(IFlow subFlow) Return the next sub-flow after subFlow.
IFlow	InnerFlow()
java.lang.String	name() Name of the flow object, used for logging and (optionally) as a means of finding flow objects.
void	onBegin(IFlowContext context) The first method called when a flow is executed.
IFlow	onCatch(IFlow current, SRResults results, java.lang.String eventName, ThrowEvent event) Event handler for custom events.
boolean	onComplete() Do any side-effects that should be done when the flow finishes, such as updating a database.
IFlow	onDisconnect(IFlow current, SRResults results) Event handler for a disconnect event.
void	onEnd(IFlowContext context) The last method called when a flow is executed.
IFlow	onNoInput(IFlow current, SRResults results) Event handler for the no-input event.
IFlow	onPlatformError(IFlow current, SRResults results) Event handler for a error returned by the speech platform.
IFlow	onTransferFailed(IFlow current, SRResults results) Event handler for a failed transfer.
IFlow	onValidateFailed(IFlow current, SRResults results) Event handler for validation failed.
java.lang.String	promptGroup() The prompt group prefix applies to prompt ids.
void	setExecutionCount(int count) Used internally by SRInstance.
void	setPromptGroup(java.lang.String groupPrefix) Set the prompt group prefix.
boolean	shouldExecute() Used for optional sub-flows.
boolean	validateInput(java.lang.String input, SRResults results) Validates user input.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

m_trail

public Trail m_trail

Constructor Detail

TrailWrapper

public TrailWrapper(IFlow flow)

Method Detail

InnerFlow

public IFlow InnerFlow()

name

public java.lang.String name()

Description copied from interface: IFlow

Name of the flow object, used for logging and (optionally) as a means of finding flow objects.

Name should be a descriptive single word, such as "AskFlightNumber". Question flows should begin with a verb such as "Ask", and output flows should begin with a verb such as "Say".

If the name is not specified by the developer, a flow's default name is the class name, for example, org.foobar.flightapp.AskFlightNumber. Names do not need to be unique.

Specified by:

name in interface IFlow

Returns:

name of the flow object (names are case-sensitive).

execute

public void execute(IExecutionContext context)

Description copied from interface: IFlow

Generates a VoiceXML page, which is sent to the speech platform for execution. SpeakRight will execute a single flow object at a time, waiting for the results from the speech platform before executing the next flow object.

Execute may choose to generate no content; this is called an "empty" flow object. Execute may also choose to generate a flow event. This is used for error conditions where the application can't proceed and needs to jump to a different flow. For example, Execute may want to access a web service to play weather information. If the web service is down, a flow event can be thrown.

Specified by:

execute in interface IFlow

Parameters:

context - Contains the page renderer.

getFirst

public IFlow getFirst(IFlowContext context)

Description copied from interface: IFlow

Gets the first sub-flow to be executed. getFirst is called when a flow begins execution. It can return itself, or a sub-flow.

Returning null is not allowed. Some exceptions to this exist; BasicFlow supports "optional" sub-flows where a sub-flow returns null from getFirst to indicate that it doesn't wish to run. However the outer flow object (BasicFlow) ensures that its getFirst never returns null.

getFirst may be called more than once per activation (see BasicFlow).

Specified by:

getFirst in interface IFlow

Returns:

an IFlow object to be executed.

getNext

public IFlow getNext(IFlow current,
                     SRResults results)

Description copied from interface: IFlow

Gets the next flow object to be executed. SpeakRight will call getFirst, and then getNext repeatedly until it returns null. Each call to getNext is returning the results of the previous VoiceXML page. The flow object uses the results to determine which sub-flow to execute next. It can return itself. If the flow object is finished, it returns null.

Specified by:

getNext in interface IFlow

Parameters:

current - the currently executing flow object. More precisely, current is the flow object that this object most recently returned from getFirst or getNext.

results - the results of current's execution by the speech platform. Results contains user input and/or events such as disconnect or platform-error.

Returns:

the next flow to run, or null which means this flow object is finished.

onBegin

public void onBegin(IFlowContext context)

Description copied from interface: IFlow

The first method called when a flow is executed. Any initialization code should be placed here. Called once before getFirst.

Specified by:

onBegin in interface IFlow

onEnd

public void onEnd(IFlowContext context)

Description copied from interface: IFlow

The last method called when a flow is executed. Any cleanup code should be placed here. Called once after getNext returns null.

Specified by:

onEnd in interface IFlow

onDisconnect

public IFlow onDisconnect(IFlow current,
                          SRResults results)

Description copied from interface: IFlow

Event handler for a disconnect event. Disconnect occurs when the user terminates the application by hanging up (or when the application disconnects using a HangUp block). This handler must return an ExitEvent since it makes no sense to keep executing after the call has ended.

The SRApp class provides a default implementation that returns an ExitEvent.

Specified by:

onDisconnect in interface IFlow

Parameters:

current - the currently executing flow object.

results - the results of current's execution. In this case results will contain a Disconnect result code. User input may be present, if the caller spoke before hanging up. Some applications may want to process this final utterance before terminating.

Returns:

the next flow to run, or null which means this flow object does not handle this event.

onNoInput

public IFlow onNoInput(IFlow current,
                       SRResults results)

Description copied from interface: IFlow

Event handler for the no-input event. No-input occurs when the VoiceXML was listening for the caller to speak, but no (valid) utterance was heard. This can occur is the caller is silent or her speech is unrecognizable. Speech recognition engines assign a confidence level to each utterance that they match. If the confidence is less than the configured recognition-threshold, the utterance is rejected as a "NoReco" error. VoiceXML pages will typically retry several times. Only if the maximum number of retries is exceeded, is a No-input event generated.

No-Input only applies if the VoiceXML has active grammars. An output only page does not generate this event.

SRApp provides a default implementation that transfers the call to the operator. In some cases, No-Input is a valid event. For example, a flow object that reads a long weather bulletin may be listening for "stop" or "cancel". If the caller listens to the whole bulletin without speaking, a No-Input will be returned. The application ignores the No-Input by overriding onNoInput in the flow object, and having it return its normal getNext value.

Specified by:

onNoInput in interface IFlow

Parameters:

current - the currently executing flow object.

results - the results of current's execution. In this case results will contain a Disconnect result code. User input may be present, if the caller spoke before hanging up. Some applications may want to process this final utterance before terminating.

Returns:

the next flow to run, or null which means this flow object does not handle this event.

onCatch

public IFlow onCatch(IFlow current,
                     SRResults results,
                     java.lang.String eventName,
                     ThrowEvent event)

Description copied from interface: IFlow

Event handler for custom events. Custom events are generated by the application returning a ThrowEvent object in getFirst, getNext, or in execute. Custom events are a form of "goto" in that they cause a jump to another flow. However, their behaviour is closer to exceptions in that the flow that "cathes" the event must be a currently executing flow (that is, is on the flow stack). Each custom event must have a unique name.

Event handling in SpeakRight involves a search up the flow stack. First the currently executing flow (current) is checked. If its event handler returns non-null then the event has been handled. Otherwise the next flow object on the flow stack is checked, up to the outermost flow object (the application flow object). It is an error for an event not to be caught. SRApp provides default handlers for all events.

Specified by:

onCatch in interface IFlow

Parameters:

current - the currently executing flow object.

results - the results of current's execution.

eventName - name of the event. most event handling can be done using just the name.

event - event object. advanced event handling may require the actual event object

Returns:

the next flow to run, or null which means this flow object does not handle this event.

onPlatformError

public IFlow onPlatformError(IFlow current,
                             SRResults results)

Description copied from interface: IFlow

Event handler for a error returned by the speech platform. This can be due to many things such as bad grammar URLs, network problems, or a platform crash.

The SRApp class provides a default implementation that transfers the call to an operator.

Specified by:

onPlatformError in interface IFlow

Parameters:

current - the currently executing flow object.

results - the results of current's execution. In this case results will contain a PlatformFailed result code.

Returns:

the next flow to run, or null which means this flow object does not handle this event.

onTransferFailed

public IFlow onTransferFailed(IFlow current,
                              SRResults results)

Description copied from interface: IFlow

Event handler for a failed transfer. If a transfer fails due to busy or ring-no-answer then this event is thrown.

The SRApp class provides a default implementation that transfers the call to an operator.

Specified by:

onTransferFailed in interface IFlow

Parameters:

current - the currently executing flow object.

results - the results of current's execution. In this case results will contain a TransferFailed result code.

Returns:

the next flow to run, or null which means this flow object does not handle this event.

onValidateFailed

public IFlow onValidateFailed(IFlow current,
                              SRResults results)

Description copied from interface: IFlow

Event handler for validation failed. Validation occurs whenever the results of a VoiceXML page execution contain user input. The current flow's ValidateInput is called. If it returns false then a validate-failed event is generated. Speech recognition grammars can limit somewhat the user's input. However, the application may want to validate the input, such as looking up the flight number in a database.

The default implementation of onValidateFailed is to return this, which causes the flow object to be executed again. The ExecutionCount field can be used to detect re-execution, and generate a retry prompt. FlowBase provides the default implemenation.

Specified by:

onValidateFailed in interface IFlow

Parameters:

current - the currently executing flow object.

results - the results of current's execution. In this case results will contain the user input that failed validation.

Returns:

the next flow to run, or null which means this flow object does not handle this event.

validateInput

public boolean validateInput(java.lang.String input,
                             SRResults results)

Description copied from interface: IFlow

Validates user input. Validation occurs whenever the results of a VoiceXML page execution contain user input. The current flow's ValidateInput is called. If it returns false then a validate-failed event is generated. Speech recognition grammars can limit somewhat the user's input. However, the application may want to validate the input, such as looking up the flight number in a database.

FlowBase provides the default implementation, which simply returns true.

Specified by:

validateInput in interface IFlow

Parameters:

input - String value of the user input. For simple, single-value inputs, input is sufficient. For more complicated user inputs, use the SML in results.

results - Results containing the user input, including the SML, confidence vales, and NBest information.

Returns:

boolean indicating if the input is valid or not.

onComplete

public boolean onComplete()

Description copied from interface: IFlow

Do any side-effects that should be done when the flow finishes, such as updating a database. onComplete is where the business logic of an application goes.

Specified by:

onComplete in interface IFlow

Returns:

boolean indicating whether the business logic has finished. false means an asynchronous operation has been started. The flow is now paused. Later when the operation finishes, call SRInstance.Resume to continue.

createRenderer

public IFlowRenderer createRenderer()

Specified by:

createRenderer in interface IFlow

fixupPrompt

public java.lang.String fixupPrompt(java.lang.String item)

Description copied from interface: IFlow

Callback that lets a flow object do any adjustments on prompt text. For example, change "IBM" to "I.B.M" so it will be spoken correctly by the TTS engine. When SpeakRight renders a prompt it walks the flow stack upward (from the current flow toward the app flow) calling fixupPrompt until a non-null value is returned.

Specified by:

fixupPrompt in interface IFlow

Parameters:

item - the tts prompt item to be adjusted

Returns:

null means don't change. else return a new value for item

fixupGrammar

public Grammar fixupGrammar(Grammar gram)

Description copied from interface: IFlow

Callback that lets a flow object do any adjustments on grammars. An app may want to adjust the caching of its grammars. This can be done in a single place by having the main application flow object override this method. When SpeakRight renders a grammar it walks the flow stack upward (from the current flow toward the app flow) calling fixupGrammar until a non-null value is returned.

Specified by:

fixupGrammar in interface IFlow

Parameters:

gram - a grammar object

Returns:

null means don't change. else return a new value for item

executionCount

public int executionCount()

Description copied from interface: IFlow

The number of times this flow has been executed (in the current activation). Starts at 1. executionCount is not the same as the # of times a flow object has been executed during this phone call. We don't track that (but it would be called activationCount if we did).

Specified by:

executionCount in interface IFlow

Returns:

setExecutionCount

public void setExecutionCount(int count)

Description copied from interface: IFlow

Used internally by SRInstance.

Specified by:

setExecutionCount in interface IFlow

promptGroup

public java.lang.String promptGroup()

Description copied from interface: IFlow

The prompt group prefix applies to prompt ids. Prompt ids are used load prompt text from external XML files. Each prompt has a unique id. IFlow-derived classes often define prompt ids. But we want instaces of these classes to be able to override prompts in an application-defined prompt XML file. Prompt groups allow this. The group prefix allows a two-step lookup; first the prefix is added to the prompt id and the prompt is looked up. If not found then the original id is looked up.

For example, consider a SROLogin class that defines a common login behaviour. It has a prompt id "id:loginFailed" with a default prompt in its prompt XML file. If we use SROLogin several times in our app, we may want to customize the loginFailed prompt each time. Prompt groups allow this. If our first login flow object uses a prompt group of "logon", then the two-stage lookup is: first lookup "id:logon.loginFailed", then "id:loginFailed". Then in our application prompt XML file we'ld add a prompt for "login.loginFailed". Prompt groups are flexible because we can add to the application XML file at any time, without any code changes needed.

Specified by:

promptGroup in interface IFlow

Returns:

the prompt group prefix.

setPromptGroup

public void setPromptGroup(java.lang.String groupPrefix)

Description copied from interface: IFlow

Set the prompt group prefix. The default prompt group prefix is the IFlow's name.

Specified by:

setPromptGroup in interface IFlow

Parameters:

groupPrefix - the prompt group prefix, or "*" which means uses the IFlow's name().

getSubFlowAfter

public IFlow getSubFlowAfter(IFlow subFlow)

Description copied from interface: IFlow

Return the next sub-flow after subFlow. Return null if subFlow is not one of our sub-flows, or there is no next one after it. This method is used to implement optional sub-flows (see BasicFlow)

Specified by:

getSubFlowAfter in interface IFlow

Returns:

null or next sub-flow after subFlow

shouldExecute

public boolean shouldExecute()

Description copied from interface: IFlow

Used for optional sub-flows. A flow object can return false from this method if it wants to be skipped (that is, not execute). All the restrictions of optional-sub-flows apply, such as can't-be-last.

Specified by:

shouldExecute in interface IFlow

Returns:

true (default) to execute, false to not execute this flow object