org.speakright.core
Class SRInstance

java.lang.Object
  org.speakright.core.SRInstance

All Implemented Interfaces:

java.io.Serializable, IGrammarAdjuster, IPromptAdjuster

public class SRInstance
extends java.lang.Object
implements java.io.Serializable, IPromptAdjuster, IGrammarAdjuster

SRInstance is the SpeakRight runtime for a single call. It manages execution of the flow objects. It is Serializable so SpeakRight can save & restore state between HTTP requests.

Author:

Ian Rae

See Also:

Serialized Form

Field Summary

boolean	m_dtmfOnlyModeIsActive
Trail	m_trail

Constructor Summary

SRInstance()

Method Summary

IFlow	ApplicationFlow() Get the outermost flow object, that was passed to start.
boolean	failed(SRError parent) extracts any errors that this SRInstance object logged.
void	finishActivation() MUST be called after activating (restoring this object using serialization).
Grammar	fixupGrammar(Grammar gram) Walk the flow stack until a flow object returns non-null from it's fixupGrammar method.
java.lang.String	fixupPrompt(java.lang.String item) Walk the flow stack until a flow object returns non-null from it's fixupPrompt method.
static void	forceUCIReset() used for unit testing only
void	generateFinPage() Generate the final page for the application.
java.lang.String	getContent() Get the content (the VoiceXML page).
boolean	isFailed() Has an error ocurred yet.
boolean	isFinished() Has the application finished.
boolean	isPaused() Is the application paused.
boolean	isStarted() Has start been called.
java.lang.String	language() Get the current language
SRLocations	locations() Get the locations object.
void	log(java.lang.String message) Log to the SpeakRight logger (log4j)
IFlow	peekCurrent() Get the currently executing flow object.
void	prepareToPassivate() When saving state in a servlet, we're going to just save the whoe SRInstance object in the HttpSession.
void	proceed(SRResults results) Continue execution, using the given results that we returned by the voicexml platform to determine what flow is executed next.
void	registerPromptFile(java.lang.String path) Register a prompt file, for the duration of the call.
void	restoreModelBinder(IModelBinder binder) Restore the model binder.
void	resume() Resume (after pausing).
boolean	runAll(IFlow flow) used for unit tests only.
void	setContentLogging(java.lang.String dir)
void	setExtensionFactory(ISRExtensionFactory factory) Set the extension point factory.
void	setGrammarBaseUrl(java.lang.String url) Set the URL of grammar files.
void	setInstrumentation(ISRInstrumentation instrumentation) Set the instrumentation object (can be at most one)
void	setLanguage(java.lang.String s) Set the current language.
void	setModelBinder(IModel model, IModelBinder binder) Set the model and model binder.
void	setPromptBaseUrl(java.lang.String url) Set the URL of audio files.
void	setPromptLogging(boolean b) Enable/disable logging of prompts during rendering.
void	setReturnUrl(java.lang.String url) Set the return url, which is used in the submit VoiceXML tag to POST the results of a page back.
void	setSROBaseUrl(java.lang.String url) Set the base URL of sro files.
boolean	start(IFlow flow) Start the application.
int	UCI() Unique Call Identifier (UCI) is a value generated by SpeakRight to distinguish one session (phone call) from another.

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

m_dtmfOnlyModeIsActive

public boolean m_dtmfOnlyModeIsActive

Constructor Detail

SRInstance

public SRInstance()

Method Detail

prepareToPassivate

public void prepareToPassivate()

When saving state in a servlet, we're going to just save the whoe SRInstance object in the HttpSession. But we need to clear the transient fields since they are not needed and are not serializable.

finishActivation

public void finishActivation()

MUST be called after activating (restoring this object using serialization). It re-initializes the SRInstance transient fields.

registerPromptFile

public void registerPromptFile(java.lang.String path)

Register a prompt file, for the duration of the call.

Parameters:

path -

setPromptLogging

public void setPromptLogging(boolean b)

Enable/disable logging of prompts during rendering.

Parameters:

b -

setReturnUrl

public void setReturnUrl(java.lang.String url)

Set the return url, which is used in the submit VoiceXML tag to POST the results of a page back. For a java servlet, the return url is simply the servlet's URL.

Parameters:

url -

setGrammarBaseUrl

public void setGrammarBaseUrl(java.lang.String url)

Set the URL of grammar files. Any grammar urls in the app that are relative urls will have this url pre-pended.

Parameters:

url - usually a url within the java web application, such as "http://somecompany.com/speechapp1/grammar"

setSROBaseUrl

public void setSROBaseUrl(java.lang.String url)

Set the base URL of sro files. Under this there should be audio/ and grammar/ sub-dirs.

Parameters:

url - usually a url within the java web application, such as "http://somecompany.com/speechapp1/sro"

setPromptBaseUrl

public void setPromptBaseUrl(java.lang.String url)

Set the URL of audio files. Any audio urls in the app that are relative urls will have this url pre-pended.

Parameters:

url - usually a url within the java web application, such as "http://somecompany.com/speechapp1/audio"

setInstrumentation

public void setInstrumentation(ISRInstrumentation instrumentation)

Set the instrumentation object (can be at most one)

Parameters:

instrumentation - object that gets notified of important things during the session (phone call).

setContentLogging

public void setContentLogging(java.lang.String dir)

forceUCIReset

public static void forceUCIReset()

used for unit testing only

UCI

public int UCI()

Unique Call Identifier (UCI) is a value generated by SpeakRight to distinguish one session (phone call) from another. Each session has its own SRInstance object, so the UCI is stored here.

Returns:

the UCI

log

public void log(java.lang.String message)

Log to the SpeakRight logger (log4j)

Parameters:

message -

failed

public boolean failed(SRError parent)

extracts any errors that this SRInstance object logged.

Parameters:

parent - error object to copy error info into.

Returns:

true if any errors have occured.

ApplicationFlow

public IFlow ApplicationFlow()

Get the outermost flow object, that was passed to start.

Returns:

setModelBinder

public void setModelBinder(IModel model,
                           IModelBinder binder)

Set the model and model binder. Use of a model is optional in a SpeakRight application, but if you're app has a model, then you MUST call this before calling start

Parameters:

model - the IModel object used by this session (phone call)

binder - a model binder (usually ModelBinder)

restoreModelBinder

public void restoreModelBinder(IModelBinder binder)

Restore the model binder. Used after de-serialization (aka. activation). For performance reasons, we don't serialize the model binder, so you must invoke this method after activation in order to restore this SRInstance object properly. Only necessary to call this if your app has a model.

Parameters:

binder - a new ModelBinder object.

setExtensionFactory

public void setExtensionFactory(ISRExtensionFactory factory)

Set the extension point factory. This method is optional because SRInstance initializes itself to use a default factory. Use this method when you have created your own factory.

Parameters:

factory -

language

public java.lang.String language()

Get the current language

Returns:

language, such as "en-us"

setLanguage

public void setLanguage(java.lang.String s)

Set the current language.

Parameters:

s - language, such as "en-us"

locations

public SRLocations locations()

Get the locations object.

Returns:

isFailed

public boolean isFailed()

Has an error ocurred yet.

Returns:

true if error has ocurred.

start

public boolean start(IFlow flow)

Start the application.

Parameters:

flow - the application flow object.

Returns:

whether app was started successfully.

generateFinPage

public void generateFinPage()

Generate the final page for the application. This page terminates the call and the VoiceXML session.

fixupPrompt

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

Walk the flow stack until a flow object returns non-null from it's fixupPrompt method.

Specified by:

fixupPrompt in interface IPromptAdjuster

fixupGrammar

public Grammar fixupGrammar(Grammar gram)

Walk the flow stack until a flow object returns non-null from it's fixupGrammar method.

Specified by:

fixupGrammar in interface IGrammarAdjuster

Parameters:

gram - A grammar object that is being rendered

Returns:

null if no adjustments have been made, else grammar

getContent

public java.lang.String getContent()

Get the content (the VoiceXML page). MUST be called immediately after start or proceed

Returns:

the generated voicexml page.

resume

public void resume()

Resume (after pausing). Only used by async transactions (IFlow.onComplete).

isPaused

public boolean isPaused()

Is the application paused. Only used by async transactions (IFlow.onComplete)

Returns:

proceed

public void proceed(SRResults results)

Continue execution, using the given results that we returned by the voicexml platform to determine what flow is executed next.

Parameters:

results - results from the voicexml platform. These are the results of executing the previous page.

isFinished

public boolean isFinished()

Has the application finished.

Returns:

true if fin

isStarted

public boolean isStarted()

Has start been called.

Returns:

true if started.

peekCurrent

public IFlow peekCurrent()

Get the currently executing flow object.

Returns:

flow object that's on the top of the flow stack.

runAll

public boolean runAll(IFlow flow)

used for unit tests only.

Parameters:

flow -

Returns: