org.jvoicexml.interpreter.datamodel

Interface DataModel

public interface DataModel

The datamodel is a repository for both user- and system-defined data and properties. To simplify variable lookup,we define the datamodel with a synchronous function-call API, rather than an asynchronous one based on events. The data model API does not assume any particular underlying representation of the data or any specific access language, thus allowing implementations to plug in different concrete data model languages.

There is a single global data model that is created when the system is first initialized. Access to data is controlled by means of scopes, which are stored in a stack. Data is always accessed within a particular scope, which may be specified by name but defaults to being the top scope in the stack. At initialization time, a single scope named "Global" is created. Thereafter scopes are explicitly created and destroyed by the data model's clients.

Some first steps to follow the ideas mentioned in the VoiceXML 3.0 draft http://www.w3.org/ TR/voicexml30/#Resources:Datamodel

Since:

0.7.7

Field Summary

Fields

Modifier and Type	Field and Description
static int	ERROR_SCOPE_NOT_FOUND A specified scope could not be found.
static int	ERROR_VARIABLE_ALREADY_DEFINED A specified variable was previously defined.
static int	ERROR_VARIABLE_NOT_FOUND A specified variable was not found.

Method Summary

Modifier and Type	Method and Description
int	createArray(java.lang.String arrayName, int dimension) Creates an array with the given dimension on top most scope on the scope stack.
int	createArray(java.lang.String arrayName, int dimension, Scope scope) Creates an array with the given dimension at the specified scope.
java.lang.Object	createNewObject() Retrieves a new empty object for this data model.
int	createScope() Creates a new scope object and pushes it on top of the scope stack.
int	createScope(Scope scope) Creates a new scope object and pushes it on top of the scope stack.
int	createVariable(java.lang.String variableName) Creates a variable with the default value specified by the underlying datamodel retrieved via getUndefinedValue() at the topmost scope on the scope stack.
int	createVariable(java.lang.String variableName, java.lang.Object value) Creates a variable with the given initial value on top most scope on the scope stack.
int	createVariable(java.lang.String variableName, java.lang.Object value, Scope scope) Creates a variable.
int	createVariableFor(java.lang.Object variable, java.lang.String variableName) Creates a variable as a nested property in the specified variable container with the default value specified by the underlying datamodel retrieved via getUndefinedValue() at the topmost scope on the scope stack.
int	createVariableFor(java.lang.Object variable, java.lang.String variableName, java.lang.Object value) Creates a variable as a nested property in the given container with the given initial value on top most scope on the scope stack.
int	deleteScope() Removes a topmost scope from the scope stack.
int	deleteScope(Scope scope) Removes a scope with the provided name from the scope stack.
int	deleteVariable(java.lang.String variableName) Deletes the variable with the specified name from the topmost scope on the stack.
int	deleteVariable(java.lang.String variableName, Scope scope) Deletes the variable with the specified name from the specified scope..
<T> T	evaluateExpression(java.lang.String expr, java.lang.Class<T> type) Evaluates the specified expression in the topmost scope on the stack and returns it value.
<T> T	evaluateExpression(java.lang.String expr, Scope scope, java.lang.Class<T> type) Evaluates the specified expression in the specified scope and returns it value.
boolean	existsVariable(java.lang.String variableName) Checks if the given variable exists.
boolean	existsVariable(java.lang.String variableName, Scope scope) Checks if the given variable exists at the given scope.
DataModelObjectSerializer	getSerializer() Retrieves the Serializer for objects when submitting.
java.lang.Object	getUndefinedValue() Retrieves the value for undefined.
DataModel	newInstance() Creates a new data model.
<T> T	readArray(java.lang.String arrayName, int position, java.lang.Class<T> type) Returns the value of the array at the given position with the specified name from the topmost scope on the stack.
<T> T	readArray(java.lang.String arrayName, int position, Scope scope, java.lang.Class<T> type) Returns the value of the array at the given position with the specified name from the specified scope on the stack.
<T> T	readVariable(java.lang.String variableName, java.lang.Class<T> type) Returns the value of the variable with the specified name from the topmost scope on the stack.
<T> T	readVariable(java.lang.String variableName, Scope scope, java.lang.Class<T> type) Returns the value of the variable with the specified name from the specified scope on the stack.
int	resizeArray(java.lang.String arrayName, int dimension) Resizes an array with the given dimension on top most scope on the scope stack.
int	resizeArray(java.lang.String arrayName, int dimension, Scope scope) Resizes an array with the given dimension at the specified scope.
java.lang.String	toString(java.lang.Object object) Retrieves a human readable representation of the given object retrieved from this data model.
int	updateArray(java.lang.String variableName, int position, java.lang.Object newValue) Assigns a new value to the array at the given position on the topmost scope on the stack.
int	updateArray(java.lang.String variableName, int position, java.lang.Object newValue, Scope scope) Assigns a new value to the array at the given position in the specified scope.
int	updateVariable(java.lang.String variableName, java.lang.Object newValue) Assigns a new value to the variable specified on the topmost scope on the stack.
int	updateVariable(java.lang.String variableName, java.lang.Object newValue, Scope scope) Assigns a new value to the variable specified from the specified scope.
int	updateVariableFor(java.lang.Object variable, java.lang.String variableName, java.lang.Object newValue) Assigns a new value to the variable specified on the topmost scope on the stack.

Field Detail

ERROR_SCOPE_NOT_FOUND

static final int ERROR_SCOPE_NOT_FOUND

A specified scope could not be found.

See Also:

Constant Field Values

ERROR_VARIABLE_NOT_FOUND

static final int ERROR_VARIABLE_NOT_FOUND

A specified variable was not found.

See Also:

Constant Field Values

ERROR_VARIABLE_ALREADY_DEFINED

static final int ERROR_VARIABLE_ALREADY_DEFINED

A specified variable was previously defined.

See Also:

Constant Field Values

Method Detail

newInstance

DataModel newInstance()

Creates a new data model.

Returns:

new data model

getUndefinedValue

java.lang.Object getUndefinedValue()

Retrieves the value for undefined. Either this value or null may be returned to indicate a defined variable with no value.

Returns:

undefined value

createNewObject

java.lang.Object createNewObject()

Retrieves a new empty object for this data model.

Returns:

new object

toString

java.lang.String toString(java.lang.Object object)

Retrieves a human readable representation of the given object retrieved from this data model.

Parameters:

object - the value to convert

Returns:

string representation of object

createScope

int createScope(Scope scope)

Creates a new scope object and pushes it on top of the scope stack.

Parameters:

scope - the scope to create

Returns:

0 upon success, failure status if a scope already exists with the specified name.

createScope

int createScope()

Creates a new scope object and pushes it on top of the scope stack. The scope is anonymous and may be accessed only when it on the top of the scope stack.

Returns:

0 upon success

deleteScope

int deleteScope()

Removes a topmost scope from the scope stack.

Returns:

0 upon success

deleteScope

int deleteScope(Scope scope)

Removes a scope with the provided name from the scope stack.

Parameters:

scope - the scope to remove

Returns:

0 upon success, failure status if the stack is empty or no scope with the specified name exists

createVariable

int createVariable(java.lang.String variableName)

Creates a variable with the default value specified by the underlying datamodel retrieved via getUndefinedValue() at the topmost scope on the scope stack.

Parameters:

variableName - name of the variable to create

Returns:

0 upon success, failure status if a variable of the same name already exists

createVariableFor

int createVariableFor(java.lang.Object variable,
                      java.lang.String variableName)

Creates a variable as a nested property in the specified variable container with the default value specified by the underlying datamodel retrieved via getUndefinedValue() at the topmost scope on the scope stack.

Parameters:

variable - the container (previously obtained from the datamodel) where to create the variable

variableName - name of the variable to create

Returns:

0 upon success, failure status if a variable of the same name already exists

createVariable

int createVariable(java.lang.String variableName,
                   java.lang.Object value)

Creates a variable with the given initial value on top most scope on the scope stack.

Parameters:

variableName - name of the variable to create

value - initial value of the variable

Returns:

0 upon success, failure status if a variable of the same name already exists

createVariableFor

int createVariableFor(java.lang.Object variable,
                      java.lang.String variableName,
                      java.lang.Object value)

Creates a variable as a nested property in the given container with the given initial value on top most scope on the scope stack.

Parameters:

variable - the container (previously obtained from the datamodel) where to create the variable

variableName - name of the variable to create

value - initial value of the variable

Returns:

0 upon success, failure status if a variable of the same name already exists

createVariable

int createVariable(java.lang.String variableName,
                   java.lang.Object value,
                   Scope scope)

Creates a variable. If no value is provided, the variable is created with the default value specified by the underlying datamodel retrieved via getUndefinedValue().

Parameters:

variableName - name of the variable to create

value - initial value of the variable, maybe null

scope - scope, where to create the variable

Returns:

0 upon success, failure status if a variable of the same name already exists in the specified scope

createArray

int createArray(java.lang.String arrayName,
                int dimension)

Creates an array with the given dimension on top most scope on the scope stack. All values are initialized with getUndefinedValue().

Parameters:

arrayName - name of the array to create

dimension - initial dimension of the array

Returns:

0 upon success, failure status if a variable of the same name already exists

createArray

int createArray(java.lang.String arrayName,
                int dimension,
                Scope scope)

Creates an array with the given dimension at the specified scope. All values are initialized with getUndefinedValue().

Parameters:

arrayName - name of the array to create

dimension - initial dimension of the array

scope - scope, where to create the array

Returns:

0 upon success, failure status if a variable of the same name already exists in the specified scope

resizeArray

int resizeArray(java.lang.String arrayName,
                int dimension)

Resizes an array with the given dimension on top most scope on the scope stack. All values are initialized with getUndefinedValue().

Parameters:

arrayName - name of the array to create

dimension - new dimension of the array after resizing

Returns:

0 upon success, failure status if the array could not be found

resizeArray

int resizeArray(java.lang.String arrayName,
                int dimension,
                Scope scope)

Resizes an array with the given dimension at the specified scope. All values are initialized with getUndefinedValue().

Parameters:

arrayName - name of the array to create

dimension - new dimension of the array after resizing

scope - scope, where to create the variable

Returns:

0 upon success, failure status if the array could not be found

existsVariable

boolean existsVariable(java.lang.String variableName)

Checks if the given variable exists.

Parameters:

variableName - name of the variable to check

Returns:

true if the variable exists

existsVariable

boolean existsVariable(java.lang.String variableName,
                       Scope scope)

Checks if the given variable exists at the given scope.

Parameters:

variableName - name of the variable to check

scope - the scope where to check for the variable

Returns:

true if the variable exists

deleteVariable

int deleteVariable(java.lang.String variableName)

Deletes the variable with the specified name from the topmost scope on the stack.

Parameters:

variableName - the variable to delete

Returns:

0 upon success, failure status if no variable with the specified name exists

deleteVariable

int deleteVariable(java.lang.String variableName,
                   Scope scope)

Deletes the variable with the specified name from the specified scope..

Parameters:

variableName - the variable to delete

scope - scope, where to delete the variable

Returns:

0 upon success, failure status if no variable with the specified name exists

updateVariable

int updateVariable(java.lang.String variableName,
                   java.lang.Object newValue)

Assigns a new value to the variable specified on the topmost scope on the stack.

Parameters:

variableName - the variable to update

newValue - new value of the variable

Returns:

0 upon success, failure status if the specified variable or scope cannot be found.

updateVariableFor

int updateVariableFor(java.lang.Object variable,
                      java.lang.String variableName,
                      java.lang.Object newValue)

Assigns a new value to the variable specified on the topmost scope on the stack.

Parameters:

variable - the variable that has variableName as a property

variableName - the variable to update

newValue - new value of the variable

Returns:

0 upon success, failure status if the specified variable or scope cannot be found.

updateVariable

int updateVariable(java.lang.String variableName,
                   java.lang.Object newValue,
                   Scope scope)

Assigns a new value to the variable specified from the specified scope.

Parameters:

variableName - the variable to update

newValue - new value of the variable

scope - scope, where to update the variable

Returns:

0 upon success, failure status if no variable with the specified name exists

updateArray

int updateArray(java.lang.String variableName,
                int position,
                java.lang.Object newValue)

Assigns a new value to the array at the given position on the topmost scope on the stack.

Parameters:

variableName - the variable to update

position - the position in the array to update

newValue - new value of the variable

Returns:

0 upon success, failure status if the specified variable, field, or scope cannot be found.

updateArray

int updateArray(java.lang.String variableName,
                int position,
                java.lang.Object newValue,
                Scope scope)

Assigns a new value to the array at the given position in the specified scope.

Parameters:

variableName - the variable to update

position - the position in the array to update

newValue - new value of the variable

scope - scope, where to update the variable

Returns:

0 upon success, failure status if no variable with the specified name exists

readVariable

<T> T readVariable(java.lang.String variableName,
                   java.lang.Class<T> type)
            throws SemanticError

Returns the value of the variable with the specified name from the topmost scope on the stack.

Type Parameters:

T - type of the variable to read

Parameters:

variableName - the variable to delete

type - type of the variable

Returns:

value of the variable

Throws:

SemanticError - if the specified variable or scope can not be found

readVariable

<T> T readVariable(java.lang.String variableName,
                   Scope scope,
                   java.lang.Class<T> type)
            throws SemanticError

Returns the value of the variable with the specified name from the specified scope on the stack.

Type Parameters:

T - type of the variable to read

Parameters:

variableName - the variable to delete

scope - scope, where to update the variable

type - type of the variable

Returns:

value of the variable

Throws:

SemanticError - if the specified variable or scope can not be found

readArray

<T> T readArray(java.lang.String arrayName,
                int position,
                java.lang.Class<T> type)
         throws SemanticError

Returns the value of the array at the given position with the specified name from the topmost scope on the stack.

Type Parameters:

T - type of the variable to read

Parameters:

arrayName - the variable to delete

position - the position to read from

type - type of the variable

Returns:

value of the variable

Throws:

SemanticError - if the specified variable or scope can not be found

readArray

<T> T readArray(java.lang.String arrayName,
                int position,
                Scope scope,
                java.lang.Class<T> type)
         throws SemanticError

Returns the value of the array at the given position with the specified name from the specified scope on the stack.

Type Parameters:

T - type of the variable to read

Parameters:

arrayName - the variable to delete

position - the position to read from

scope - scope, where to update the variable

type - type of the variable

Returns:

value of the variable

Throws:

SemanticError - if the specified variable or scope can not be found

evaluateExpression

<T> T evaluateExpression(java.lang.String expr,
                         java.lang.Class<T> type)
                  throws SemanticError

Evaluates the specified expression in the topmost scope on the stack and returns it value.

Type Parameters:

T - type of the variable to read

Parameters:

expr - the expression to evaluate

type - type of the variable

Returns:

evaluated value

Throws:

SemanticError - if the specified scope can not be found or the expression could not be evaluated

evaluateExpression

<T> T evaluateExpression(java.lang.String expr,
                         Scope scope,
                         java.lang.Class<T> type)
                  throws SemanticError

Evaluates the specified expression in the specified scope and returns it value.

Type Parameters:

T - type of the variable to read

Parameters:

expr - the expression to evaluate

scope - scope, where to evaluate the expression

type - type of the variable

Returns:

evaluated value

Throws:

SemanticError - if the specified scope can not be found or the expression could not be evaluated

getSerializer

DataModelObjectSerializer getSerializer()

Retrieves the Serializer for objects when submitting.

Returns:

serializer to use