org.jvoicexml

Interface Session

All Known Implementing Classes:

JVoiceXmlSession

public interface Session

A session begins when the user starts to interact with a VoiceXML interpreter context, continues as documents are loaded and processed, and ends when requested by the user, a document, or the interpreter context. Note, that a session is only valid for a single call and cannot be reused for subsequent calls.

A Session can be obtained via the JVoiceXml.createSession(ConnectionInformation) method.

A client usually performs the following method calls to interact with the interpreter:

1. call
2. hangup

Note, that a call to call(URI) must be followed by a call to hangup() in order to free resources such as ASR and TTS.

The call method returns immediately. In case of an error the client does not get notified. In order to monitor the call and retrieve error messages, clients should use the waitSessionEnd method. This may be done synchronously right after the call method call or asynchronously in a thread.

See Also:

JVoiceXml.createSession(ConnectionInformation)

Method Summary

Modifier and Type	Method and Description
void	addSessionListener(SessionListener listener) Adds the session listener.
Application	call(java.net.URI uri) Handles a call request.
Application	getApplication() Retrieves the application that is currently being processed.
DtmfInput	getDtmfInput() Retrieves the DTMF input device.
ErrorEvent	getLastError() Retrieves an error, if any, that happened during call processing.
java.lang.String	getSessionId() Retrieves the universal unique identifier for this session.
void	hangup() Closes this session.
boolean	hasEnded() Checks if this session has ended.
void	removeSessionListener(SessionListener listener) Removes the session listener.
void	waitSessionEnd() Delays until the session ends.

Method Detail

addSessionListener

void addSessionListener(SessionListener listener)

Adds the session listener.

Parameters:

listener - the session listener to add.

Since:

0.7.3

removeSessionListener

void removeSessionListener(SessionListener listener)

Removes the session listener.

Parameters:

listener - the session listener to remove.

Since:

0.7.3

getSessionId

java.lang.String getSessionId()

Retrieves the universal unique identifier for this session.

Returns:

Universal unique identifier for this session.

Since:

0.4

call

Application call(java.net.URI uri)
          throws ErrorEvent

Handles a call request.

Starts processing of the given application and returns immediately.

Since this method returns immediately, it offers no means to monitor the call processing and catch exceptions. Therefore clients are requested to use the waitSessionEnd() method to monitor the session. Another way can be via the Telephony interface and calling getLastError(). However, the latter option relies on the concrete implementation.

Ensure that you call hangup() after this call to ensure that resources like ASR and TTS are released.

Parameters:

uri - URI of the first document to load.

Returns:

called application

Throws:

ErrorEvent - Error initiating the call.

hangup

void hangup()

Closes this session. After a session is closed, it can not be reopened e.g., to call another application.

Since:

0.4

getApplication

Application getApplication()

Retrieves the application that is currently being processed.

Returns:

the current application

Since:

0.7.7

getDtmfInput

DtmfInput getDtmfInput()
                throws NoresourceError,
                       ConnectionDisconnectHangupEvent

Retrieves the DTMF input device.

Returns:

DTMF input device.

Throws:

NoresourceError - Input device is not available.

ConnectionDisconnectHangupEvent - the user hung up

Since:

0.5

hasEnded

boolean hasEnded()

Checks if this session has ended.

Returns:

true if the session has ended.

Since:

0.7.5

waitSessionEnd

void waitSessionEnd()
             throws ErrorEvent

Delays until the session ends.

Throws:

ErrorEvent - Error waiting for the end of the call.

Since:

0.4

getLastError

ErrorEvent getLastError()
                 throws ErrorEvent

Retrieves an error, if any, that happened during call processing.

Returns:

an error that happened during call processing, null if there was no error.

Throws:

ErrorEvent - Error reading the last error.

Since:

0.7