org.speakright.core
Interface IFlow

All Superinterfaces:

java.io.Serializable

All Known Subinterfaces:

IConfirmationFlow

All Known Implementing Classes:

App, App.AskCharacter, App.CharacterDescription, App.MainMenu, App.RelatedCharacterYesNo, App.VoteYesNo, App.VotingResultsList, App1, AppEvent, AppWithLoop, AsyncFlow, BaseSROQuestion, BaseSROQuestion.MyConfirmationWrapper, BaseSROSayDate, BasicFlow, BranchFlow, BranchFlow.GotoBranchEvent, ChoiceFlow, ConfirmationWrapper, ControlFlow, DisconnectFlow, ExitEvent, Flow2Wrapper, FlowBase, FlowList, genSROChoice, genSROConfirmYesNo, genSRODigitString, genSROListNavigator, genSRONumber, genSROTransferCall, genSROYesNo, GotoUrlFlow, InteractiveTester.App2, LoopFlow, MyFlow, MyMenu, PromptFlow, QuestionFlow, RawContentFlow, RecordAudioFlow, SRApp, SROCancelCommand, SROChoice, SROConfirmYesNo, SRODigitString, SROListNavigator, SRONumber, SROSayDate, SROTransferCall, SROYesNo, TestConfirmation.AskCityFlow, TestConfirmation.ConfYNFlow, TestModel.EarlyBindingFlow, TestNesting.OptionalFlow, TestNesting.RepeatFlow, TestNumber.genSROQuantity, TestNumber.SROQuantity, TestRender.PlayOnceFlow, TestRender.QFlow, TestRender.YouSaidFlow, TestRender.ZFlow, TestSerialization.PFlow, TestSerialization.QFlow, TestSRApp.TestApp1, TestSRApp.TestApp2, TestSRApp.TestApp3, TestWebServlet2.MyApp, TestWebServlet2.PFlow, TestWebServlet2.QFlow, TestYesNo.YesNoApp, ThrowEvent, TrailWrapper, TransferFlow, ValFlow

public interface IFlow
extends java.io.Serializable

IFlow is the basic building block of SpeakRight. A flow object generates VoiceXML pages, and also manages control flow in the application. In MVC terms, a flow object is both a view and a controller. Flow objects are similar to controls in a GUI application; they encapsulate some user interface behaviour.

IFlow objects can contain child IFlow objects (called sub-flows). Everything from the lowest-level prompt-block to a complete SpeakRight application is an IFlow. IFlow classes are Serializable so that SpeakRight can save & restore state between HTTP requests. Mark any fields transient that you don't want to be persisted.

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.
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.

Method Detail

name

java.lang.String name()

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.

Returns:

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

execute

void execute(IExecutionContext context)

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.

Parameters:

context - Contains the page renderer.

getFirst

IFlow getFirst(IFlowContext context)

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).

Returns:

an IFlow object to be executed.

getNext

IFlow getNext(IFlow current,
              SRResults results)

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.

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

void onBegin(IFlowContext context)

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

onEnd

void onEnd(IFlowContext context)

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

onDisconnect

IFlow onDisconnect(IFlow current,
                   SRResults results)

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.

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

IFlow onNoInput(IFlow current,
                SRResults results)

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.

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.

onValidateFailed

IFlow onValidateFailed(IFlow current,
                       SRResults results)

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.

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.

onCatch

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

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.

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.

onTransferFailed

IFlow onTransferFailed(IFlow current,
                       SRResults results)

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.

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.

onPlatformError

IFlow onPlatformError(IFlow current,
                      SRResults results)

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.

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.

validateInput

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

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.

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

boolean onComplete()

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.

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

IFlowRenderer createRenderer()

fixupPrompt

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

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.

Parameters:

item - the tts prompt item to be adjusted

Returns:

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

fixupGrammar

Grammar fixupGrammar(Grammar gram)

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.

Parameters:

gram - a grammar object

Returns:

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

executionCount

int executionCount()

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).

Returns:

setExecutionCount

void setExecutionCount(int count)

Used internally by SRInstance.

promptGroup

java.lang.String promptGroup()

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.

Returns:

the prompt group prefix.

setPromptGroup

void setPromptGroup(java.lang.String groupPrefix)

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

Parameters:

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

getSubFlowAfter

IFlow getSubFlowAfter(IFlow subFlow)

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)

Parameters:

subFlow -

Returns:

null or next sub-flow after subFlow

shouldExecute

boolean shouldExecute()

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.

Returns:

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