org.speakright.core
Class FlowBase

java.lang.Object
  org.speakright.core.FlowBase

All Implemented Interfaces:

java.io.Serializable, IFlow

Direct Known Subclasses:

BasicFlow, BranchFlow, ConfirmationWrapper, ControlFlow, DisconnectFlow, GotoUrlFlow, PromptFlow, QuestionFlow, RawContentFlow, RecordAudioFlow, SROCancelCommand, TransferFlow

public class FlowBase
extends java.lang.Object
implements IFlow

FlowBase is an adapter for IFlow; it implements all the IFlow interface methods. Most flow objects derive from FlowBase so that they need only to override a few of the IFlow methods.

The default behaviour that FlowBase implements is a do-nothing flow object with no sub-flows. It returns itself in getFirst, and null in getNext, and execute does nothing.

Author:

Ian Rae

See Also:

Serialized Form

Constructor Summary

FlowBase()

FlowBase(java.lang.String name)
Create a flow with the given name.

Method Summary

IFlowRenderer	createRenderer()
void	execute(IExecutionContext context) The default implementation of execute is to render this object.
int	executionCount() The number of times this flow has been executed (in the current activation).
Grammar	fixupGrammar(Grammar gram) The default implementation is to do nothing.
java.lang.String	fixupPrompt(java.lang.String item) The default implementation is to do nothing.
IFlow	getFirst(IFlowContext context) The default implementation of getFirst is to return this.
IFlow	getNext(IFlow current, SRResults results) The default implementation of getNext is to return null.
IFlow	getSubFlowAfter(IFlow subFlow) Return the next sub-flow after subFlow.
void	log(java.lang.String message) Log to the SpeakRight logger (log4j)
void	logError(java.lang.String message) Log an error to the SpeakRight logger (log4j).
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 default implementation of onBegin is to do nothing.
IFlow	onCatch(IFlow current, SRResults results, java.lang.String eventName, ThrowEvent event) The default implementation of onCatch is to return null, indicating that this object does not handle custom events.
boolean	onComplete() The default implementation is to return true;
IFlow	onDisconnect(IFlow current, SRResults results) The default implementation of onDisconnect is to return null, indicating that this object does not handle disconnect events.
void	onEnd(IFlowContext context) The default implementation of onEnd is to do nothing.
IFlow	onNoInput(IFlow current, SRResults results) The default implementation of onNoInput is to return null, indicating that this object does not handle no-input events.
IFlow	onPlatformError(IFlow current, SRResults results) The default implementation of onCatch is to return null, indicating that this object does not handle platform errors.
IFlow	onTransferFailed(IFlow current, SRResults results) The default implementation of onCatch is to return null, indicating that this object does not handle transfer failures.
IFlow	onValidateFailed(IFlow current, SRResults results) The default implementation of onValidateFailed is to return null, indicating that this object does not handle validate-failed events.
java.lang.String	promptGroup() The prompt group prefix applies to prompt ids.
void	setExecutionCount(int count) Used internally by SRInstance.
void	setName(java.lang.String name) Sets the name of the flow object.
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) The default implementation is to return true.

Methods inherited from class java.lang.Object

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

Constructor Detail

FlowBase

public FlowBase()

FlowBase

public FlowBase(java.lang.String name)

Create a flow with the given name. Names are used for logging only, but it helps if they're unique.

Parameters:

name -

Method Detail

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

log

public void log(java.lang.String message)

Log to the SpeakRight logger (log4j)

Parameters:

message -

logError

public void logError(java.lang.String message)

Log an error to the SpeakRight logger (log4j). Will be logged at 'error' level.

Parameters:

message -

setName

public void setName(java.lang.String name)

Sets the name of the flow object.

Parameters:

name -

See Also:

IFlow.name()

execute

public void execute(IExecutionContext context)

The default implementation of execute is to render this object. However the default rendering is a 'silent' voicexml page.

Specified by:

execute in interface IFlow

Parameters:

context - Contains the page renderer.

getFirst

public IFlow getFirst(IFlowContext context)

The default implementation of getFirst is to return this.

Specified by:

getFirst in interface IFlow

Returns:

an IFlow object to be executed.

getNext

public IFlow getNext(IFlow current,
                     SRResults results)

The default implementation of getNext is to return 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)

The default implementation of onBegin is to do nothing.

Specified by:

onBegin in interface IFlow

onEnd

public void onEnd(IFlowContext context)

The default implementation of onEnd is to do nothing.

Specified by:

onEnd in interface IFlow

onDisconnect

public IFlow onDisconnect(IFlow current,
                          SRResults results)

The default implementation of onDisconnect is to return null, indicating that this object does not handle disconnect events.

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)

The default implementation of onNoInput is to return null, indicating that this object does not handle no-input events.

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)

The default implementation of onCatch is to return null, indicating that this object does not handle custom 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)

The default implementation of onCatch is to return null, indicating that this object does not handle platform errors.

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)

The default implementation of onCatch is to return null, indicating that this object does not handle transfer failures.

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)

The default implementation of onValidateFailed is to return null, indicating that this object does not handle validate-failed events.

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)

The default implementation is to return 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()

The default implementation is to return true;

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)

The default implementation is to do nothing.

Specified by:

fixupPrompt in interface IFlow

Parameters:

item - the tts prompt item to be adjusted

Returns:

null

fixupGrammar

public Grammar fixupGrammar(Grammar gram)

The default implementation is to do nothing.

Specified by:

fixupGrammar in interface IFlow

Parameters:

gram - a grammar object

Returns:

null

executionCount

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

Specified by:

executionCount in interface IFlow

Returns:

setExecutionCount

public void setExecutionCount(int count)

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