org.jvoicexml.xml.srgs
Class Grammar

java.lang.Object
  org.jvoicexml.xml.AbstractXmlNode
      org.jvoicexml.xml.srgs.Grammar

All Implemented Interfaces:

SrgsNode, VoiceXmlNode, XmlNode, Node

public final class Grammar
extends AbstractXmlNode
implements VoiceXmlNode

The <grammar> element is used to provide a speech grammar that

• specifies a set of utterances that a user may speak to perform an action or supply information, and
• for a matching utterance, returns a corresponding semantic interpretation. This may be a simple value (such as a string), a flat set of attribute-value pairs (such as day, month, and year), or a nested object (for a complex request).

Version:

$Revision: 2914 $

Author:

Steve Doyle, Dirk Schnelle-Walka

Field Summary

static String	ATTRIBUTE_FETCHHINT This defaults to the grammarfetchhint property.
static String	ATTRIBUTE_FETCHTIMEOUT This defaults to the fetchtimeout property.
static String	ATTRIBUTE_MAXAGE This defaults to the grammarmaxage property.
static String	ATTRIBUTE_MAXSTALE This defaults to the grammarmaxstale property.
static String	ATTRIBUTE_MODE Defines the mode of the grammar following the modes of the W3C Speech Recognition Grammar Specification.
protected static ArrayList<String>	ATTRIBUTE_NAMES Supported attribute names for this node.
static String	ATTRIBUTE_ROOT Defines the rule which acts as the root rule of the grammar.
static String	ATTRIBUTE_SCOPE Either "document", which makes the grammar active in all dialogs of the current document (and relevant application leaf documents), or "dialog", to make the grammar active throughout the current form.
static String	ATTRIBUTE_SRC The URI specifying the location of the grammar and optionally a rulename within that grammar, if it is external.
static String	ATTRIBUTE_SRCEXPR Equivalent to src, except that the URI is dynamically determined by evaluating the given ECMAScript expression in the current scope (e.g. the current form item).
static String	ATTRIBUTE_TAG_FORMAT Defines the tag content format for all tags within the grammar.
static String	ATTRIBUTE_TYPE The preferred media type of the grammar.
static String	ATTRIBUTE_VERSION Defines the version of the grammar.
static String	ATTRIBUTE_WEIGHT Specifies the weight of the grammar.
static String	ATTRIBUTE_XML_BASE Declares the base URI from which relative URIs in the grammar are resolved.
static String	ATTRIBUTE_XML_LANG The language identifier for the grammar.
static String	ATTRIBUTE_XMLNS The designated namespace for VoiceXXML (required).
static String	DEFAULT_VERSION Constant for version 1.0.
static String	DEFAULT_XMLNS Default namespace.
static String	SCOPE_DIALOG Scope dialog, which makes the grammar active throughout the current form..
static String	SCOPE_DOCUMENT Scope document, which makes the grammar active in all dialogs of the current document (and relevant application leaf documents).
static String	TAG_NAME Name of the grammar tag.

Fields inherited from interface org.w3c.dom.Node

ATTRIBUTE_NODE, CDATA_SECTION_NODE, COMMENT_NODE, DOCUMENT_FRAGMENT_NODE, DOCUMENT_NODE, DOCUMENT_POSITION_CONTAINED_BY, DOCUMENT_POSITION_CONTAINS, DOCUMENT_POSITION_DISCONNECTED, DOCUMENT_POSITION_FOLLOWING, DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC, DOCUMENT_POSITION_PRECEDING, DOCUMENT_TYPE_NODE, ELEMENT_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE, NOTATION_NODE, PROCESSING_INSTRUCTION_NODE, TEXT_NODE

Constructor Summary

Grammar()
Construct a new grammar object without a node.

Method Summary

CDATASection	addCData(String data) Creates a new CDATA section within this grammar.
Text	addText(String text) Create a new text within this grammar.
protected boolean	canContainChild(String tagName) Can the specified sub-tag be contained within this node?
Collection<String>	getAttributeNames() Returns a collection of permitted attribute names for the node.
String	getFetchhint() Retrieve the fetchhint attribute.
String	getFetchtimeout() Retrieve the fetchtimeout attribute.
long	getFetchTimeoutAsMsec() Retrieves the fetchtimeout attribute as msec.
long	getMastaleAsMsec() Retrieves the maxstale attribute as msec.
String	getMaxage() Retrieve the maxage attribute.
long	getMaxageAsMsec() Retrieves the maxage attribute as msec.
String	getMaxstale() Retrieve the maxstale attribute.
ModeType	getMode() Retrieves the mode attribute.
String	getModename() Retrieves the mode attribute.
Collection<Rule>	getPublicRules() Retrieves all public rule nodes.
String	getRoot() Retrieve sthe root attribute.
Rule	getRootRule() Retrieves the root rule node.
Rule	getRule(String name) Retrieves the rule node with the given name.
Collection<Rule>	getRules() Retrieves all rule nodes.
String	getScope() Retrieve the scope attribute.
String	getSrc() Retrieve the src attribute.
String	getSrcexpr() Retrieve the srcexpr attribute.
URI	getSrcUri() Retrieve the src attribute as a URI.
URL	getSrcUrl() Retrieve the src attribute as a URL.
String	getTagFormat() Retrieve the tag-format attribute.
String	getTagName() Get the name of the tag for the derived node.
GrammarType	getType() Retrieves the type attribute.
String	getTypename() Retrieves the type attribute.
String	getVersion() Retrieve the version attribute.
String	getWeight() Retrieve the weight attribute.
String	getXmlBase() Retrieve the xml:base attribute.
String	getXmlLang() Retrieve the xml:lang attribute.
Locale	getXmlLangObject() Retrieve the xml:lang attribute.
boolean	isExternalGrammar() This method checks, if this grammar is an external grammar or an inline grammar.
XmlNode	newInstance(Node n, XmlNodeFactory<? extends XmlNode> factory) Create a new instance for the given node.
void	setFetchhint(String fetchhint) Set the fetchhint attribute.
void	setFetchtimeout(String fetchtimeout) Set the fetchtimeout attribute.
void	setMaxage(String maxage) Set the maxage attribute.
void	setMaxstale(String maxstale) Set the maxstale attribute.
void	setMode(ModeType mode) Sets the mode attribute.
void	setMode(String mode) Set the mode attribute.
void	setRoot(Rule rule) Sets the root attribute to the id of the given rule.
void	setRoot(String root) Sets the root attribute.
void	setScope(String scope) Set the scope attribute.
void	setSrc(String src) Set the src attribute.
void	setSrc(URI uri) Set the src attribute to the given URL.
void	setSrc(URL url) Set the src attribute to the given URL.
void	setSrcexpr(String srcexpr) Set the srcexpr attribute.
void	setTagFormat(String tagFormat) Set the tag-format attribute.
void	setType(GrammarType type) Sets the type attribute.
void	setType(String type) Sets the type attribute.
void	setVersion(String version) Set the version attribute.
void	setWeight(String weight) Set the weight attribute.
void	setXmlBase(String xmlBase) Set the xml:base attribute.
void	setXmlLang(Locale locale) Set the xml:lang attribute.
void	setXmlLang(String xmlLang) Set the xml:lang attribute.

Methods inherited from class org.jvoicexml.xml.AbstractXmlNode

addChild, addChild, appendChild, appendChild, appendDeepClone, cloneNode, compareDocumentPosition, equals, getAttribute, getAttributes, getBaseURI, getChildNodes, getChildNodes, getChildren, getDefinedAttributeNames, getFeature, getFirstChild, getFirstLevelTextContent, getLastChild, getLocalName, getNamespaceURI, getNextSibling, getNode, getNodeFactory, getNodeName, getNodeType, getNodeValue, getOwnerDocument, getOwnerXmlDocument, getParentNode, getPrefix, getPreviousSibling, getTextContent, getUserData, hasAttributes, hasChildNodes, hashCode, insertBefore, isDefaultNamespace, isEqualNode, isSameNode, isSupported, lookupNamespaceURI, lookupPrefix, normalize, removeChild, replaceChild, setAttribute, setNodeValue, setPrefix, setTextContent, setUserData, toString

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.jvoicexml.xml.XmlNode

addChild, getAttribute, getChildNodes, getChildren, getNode, setAttribute

Methods inherited from interface org.w3c.dom.Node

appendChild, cloneNode, compareDocumentPosition, getAttributes, getBaseURI, getChildNodes, getFeature, getFirstChild, getLastChild, getLocalName, getNamespaceURI, getNextSibling, getNodeName, getNodeType, getNodeValue, getOwnerDocument, getParentNode, getPrefix, getPreviousSibling, getTextContent, getUserData, hasAttributes, hasChildNodes, insertBefore, isDefaultNamespace, isEqualNode, isSameNode, isSupported, lookupNamespaceURI, lookupPrefix, normalize, removeChild, replaceChild, setNodeValue, setPrefix, setTextContent, setUserData

Field Detail

TAG_NAME

public static final String TAG_NAME

Name of the grammar tag.

See Also:

Constant Field Values

DEFAULT_XMLNS

public static final String DEFAULT_XMLNS

Default namespace.

See Also:

ATTRIBUTE_XMLNS, Constant Field Values

ATTRIBUTE_XMLNS

public static final String ATTRIBUTE_XMLNS

The designated namespace for VoiceXXML (required). The namespace for SRGS is defined to be DEFAULT_XMLNS

See Also:

Constant Field Values

ATTRIBUTE_VERSION

public static final String ATTRIBUTE_VERSION

Defines the version of the grammar.

See Also:

Constant Field Values

DEFAULT_VERSION

public static final String DEFAULT_VERSION

Constant for version 1.0.

See Also:

Constant Field Values

ATTRIBUTE_XML_LANG

public static final String ATTRIBUTE_XML_LANG

The language identifier for the grammar. If omitted, the value is inherited down from the document hierarchy.

See Also:

Constant Field Values

ATTRIBUTE_MODE

public static final String ATTRIBUTE_MODE

Defines the mode of the grammar following the modes of the W3C Speech Recognition Grammar Specification.

See Also:

Constant Field Values

ATTRIBUTE_ROOT

public static final String ATTRIBUTE_ROOT

Defines the rule which acts as the root rule of the grammar.

See Also:

Constant Field Values

ATTRIBUTE_TAG_FORMAT

public static final String ATTRIBUTE_TAG_FORMAT

Defines the tag content format for all tags within the grammar.

See Also:

Constant Field Values

ATTRIBUTE_XML_BASE

public static final String ATTRIBUTE_XML_BASE

Declares the base URI from which relative URIs in the grammar are resolved. This base declaration has precedence over the <vxml> base URI declaration. If a local declaration is omitted, the value is inherited down the document hierarchy.

See Also:

Constant Field Values

ATTRIBUTE_SRC

public static final String ATTRIBUTE_SRC

The URI specifying the location of the grammar and optionally a rulename within that grammar, if it is external. The URI is interpreted as a rule reference as defined in Section 2.2 of the Speech Recognition Grammar Specification [SRGS] but not all forms of rule reference are permitted from within VoiceXML. The rule reference capabilities are described in detail below this table.

See Also:

Constant Field Values

ATTRIBUTE_SCOPE

public static final String ATTRIBUTE_SCOPE

Either "document", which makes the grammar active in all dialogs of the current document (and relevant application leaf documents), or "dialog", to make the grammar active throughout the current form. If omitted, the grammar scoping is resolved by looking at the parent element.

See Also:

SCOPE_DOCUMENT, SCOPE_DIALOG, Constant Field Values

SCOPE_DOCUMENT

public static final String SCOPE_DOCUMENT

Scope document, which makes the grammar active in all dialogs of the current document (and relevant application leaf documents).

See Also:

ATTRIBUTE_SCOPE, SCOPE_DIALOG, Constant Field Values

SCOPE_DIALOG

public static final String SCOPE_DIALOG

Scope dialog, which makes the grammar active throughout the current form..

See Also:

ATTRIBUTE_SCOPE, SCOPE_DOCUMENT, Constant Field Values

ATTRIBUTE_TYPE

public static final String ATTRIBUTE_TYPE

The preferred media type of the grammar. A resource indicated by the URI reference in the src attribute may be available in one or more media types. The author may specify the preferred media-type via the type attribute. When the content represented by a URI is available in many data formats, a VoiceXML platform may use the preferred media-type to influence which of the multiple formats is used. For instance, on a server implementing HTTP content negotiation, the processor may use the preferred media-type to order the preferences in the negotiation.

See Also:

Constant Field Values

ATTRIBUTE_WEIGHT

public static final String ATTRIBUTE_WEIGHT

Specifies the weight of the grammar.

See Also:

Constant Field Values

ATTRIBUTE_FETCHHINT

public static final String ATTRIBUTE_FETCHHINT

This defaults to the grammarfetchhint property.

See Also:

Constant Field Values

ATTRIBUTE_FETCHTIMEOUT

public static final String ATTRIBUTE_FETCHTIMEOUT

This defaults to the fetchtimeout property.

See Also:

Constant Field Values

ATTRIBUTE_MAXAGE

public static final String ATTRIBUTE_MAXAGE

This defaults to the grammarmaxage property.

See Also:

Constant Field Values

ATTRIBUTE_MAXSTALE

public static final String ATTRIBUTE_MAXSTALE

This defaults to the grammarmaxstale property.

See Also:

Constant Field Values

ATTRIBUTE_SRCEXPR

public static final String ATTRIBUTE_SRCEXPR

Equivalent to src, except that the URI is dynamically determined by evaluating the given ECMAScript expression in the current scope (e.g. the current form item). The expression must be evaluated each time the grammar needs to be activated. If srcexpr cannot be evaluated, an error.semantic event is thrown.

See Also:

Constant Field Values

ATTRIBUTE_NAMES

protected static final ArrayList<String> ATTRIBUTE_NAMES

Supported attribute names for this node.

Constructor Detail

Grammar

public Grammar()

Construct a new grammar object without a node.

This is necessary for the node factory.

See Also:

VoiceXmlNodeFactory

Method Detail

getTagName

public String getTagName()

Get the name of the tag for the derived node.

Specified by:

getTagName in interface XmlNode

Returns:

name of the tag.

newInstance

public XmlNode newInstance(Node n,
                           XmlNodeFactory<? extends XmlNode> factory)

Create a new instance for the given node.

Each XmlNode can serve as a prototype in a XmlNodeFactory to produce a collection of child nodes. Factories can then use the prototype pattern to produce new nodes.

Specified by:

newInstance in interface XmlNode

Parameters:

n - The node to encapsulate.

factory - the factroy that calls this method.

Returns:

The new instance.

See Also:

XmlNodeFactory

getVersion

public String getVersion()

Retrieve the version attribute.

Returns:

Value of the version attribute.

See Also:

ATTRIBUTE_VERSION

setVersion

public void setVersion(String version)

Set the version attribute.

Parameters:

version - Value of the version attribute.

See Also:

ATTRIBUTE_VERSION

getModename

public String getModename()

Retrieves the mode attribute.

Returns:

Value of the mode attribute.

See Also:

ATTRIBUTE_MODE

getMode

public ModeType getMode()

Retrieves the mode attribute.

Returns:

Value of the mode attribute.

See Also:

ATTRIBUTE_MODE

setMode

public void setMode(String mode)

Set the mode attribute.

Parameters:

mode - Value of the mode attribute.

See Also:

ATTRIBUTE_MODE

setMode

public void setMode(ModeType mode)

Sets the mode attribute.

Parameters:

mode - Value of the mode attribute.

See Also:

ATTRIBUTE_MODE

getRoot

public String getRoot()

Retrieve sthe root attribute.

Returns:

Value of the root attribute.

See Also:

ATTRIBUTE_ROOT

setRoot

public void setRoot(String root)

Sets the root attribute.

Parameters:

root - Value of the root attribute.

See Also:

ATTRIBUTE_ROOT

setRoot

public void setRoot(Rule rule)

Sets the root attribute to the id of the given rule.

Parameters:

rule - the root rule

Since:

0.7.4

getRootRule

public Rule getRootRule()

Retrieves the root rule node.

Returns:

root rule node, null if the node could not be found.

Since:

0.7

getRules

public Collection<Rule> getRules()

Retrieves all rule nodes.

Returns:

all rule nodes.

Since:

0.7.5

getPublicRules

public Collection<Rule> getPublicRules()

Retrieves all public rule nodes.

Returns:

all public rule nodes.

Since:

0.7.5

getRule

public Rule getRule(String name)

Retrieves the rule node with the given name.

Parameters:

name - name of the rule to retrieve.

Returns:

rule node with the given name, null if there is no rule with that name.

Since:

0.7

getTagFormat

public String getTagFormat()

Retrieve the tag-format attribute.

Returns:

Value of the tag-format attribute.

See Also:

ATTRIBUTE_TAG_FORMAT

setTagFormat

public void setTagFormat(String tagFormat)

Set the tag-format attribute.

Parameters:

tagFormat - Value of the tag-format attribute.

See Also:

ATTRIBUTE_TAG_FORMAT

getXmlLang

public String getXmlLang()

Retrieve the xml:lang attribute.

Returns:

Value of the xml:lang attribute.

See Also:

ATTRIBUTE_XML_LANG

getXmlLangObject

public Locale getXmlLangObject()

Retrieve the xml:lang attribute.

Returns:

Value of the xml:lang attribute.

Since:

0.7.1

See Also:

ATTRIBUTE_XML_LANG

setXmlLang

public void setXmlLang(String xmlLang)

Set the xml:lang attribute.

Parameters:

xmlLang - Value of the xml:lang attribute.

See Also:

ATTRIBUTE_XML_LANG

setXmlLang

public void setXmlLang(Locale locale)

Set the xml:lang attribute.

Parameters:

locale - Value of the xml:lang attribute.

Since:

0.7.1

See Also:

ATTRIBUTE_XML_LANG

getXmlBase

public String getXmlBase()

Retrieve the xml:base attribute.

Returns:

Value of the xml:base attribute.

See Also:

ATTRIBUTE_XML_BASE

setXmlBase

public void setXmlBase(String xmlBase)

Set the xml:base attribute.

Parameters:

xmlBase - Value of the xml:base attribute.

See Also:

ATTRIBUTE_XML_BASE

getSrc

public String getSrc()

Retrieve the src attribute.

Returns:

Value of the src attribute.

See Also:

ATTRIBUTE_SRC

getSrcUrl

public URL getSrcUrl()
              throws MalformedURLException

Retrieve the src attribute as a URL.

Returns:

Value of the src attribute.

Throws:

MalformedURLException - src value can not be evaluated to a URL.

Since:

0.7.1

See Also:

ATTRIBUTE_SRC

getSrcUri

public URI getSrcUri()
              throws URISyntaxException

Retrieve the src attribute as a URI.

Returns:

Value of the src attribute.

Throws:

URISyntaxException - src value can not be evaluated to a URL.

Since:

0.7.1

See Also:

ATTRIBUTE_SRC

setSrc

public void setSrc(String src)

Set the src attribute.

Parameters:

src - Value of the src attribute.

See Also:

ATTRIBUTE_SRC

setSrc

public void setSrc(URL url)

Set the src attribute to the given URL.

Parameters:

url - URL of the src attribute.

See Also:

ATTRIBUTE_SRC

setSrc

public void setSrc(URI uri)

Set the src attribute to the given URL.

Parameters:

uri - URI of the src attribute.

Since:

0.7.1

See Also:

ATTRIBUTE_SRC

getScope

public String getScope()

Retrieve the scope attribute.

Returns:

Value of the scope attribute.

See Also:

ATTRIBUTE_SCOPE

setScope

public void setScope(String scope)

Set the scope attribute.

Parameters:

scope - Value of the scope attribute.

See Also:

ATTRIBUTE_SCOPE

getTypename

public String getTypename()

Retrieves the type attribute.

Returns:

Value of the type attribute.

See Also:

ATTRIBUTE_TYPE

getType

public GrammarType getType()

Retrieves the type attribute.

Returns:

Value of the type attribute.

See Also:

ATTRIBUTE_TYPE

setType

public void setType(String type)

Sets the type attribute.

Parameters:

type - Value of the type attribute.

See Also:

ATTRIBUTE_TYPE

setType

public void setType(GrammarType type)

Sets the type attribute.

Parameters:

type - Value of the type attribute.

See Also:

ATTRIBUTE_TYPE

getWeight

public String getWeight()

Retrieve the weight attribute.

Returns:

Value of the weight attribute.

See Also:

ATTRIBUTE_WEIGHT

setWeight

public void setWeight(String weight)

Set the weight attribute.

Parameters:

weight - Value of the weight attribute.

See Also:

ATTRIBUTE_WEIGHT

getFetchhint

public String getFetchhint()

Retrieve the fetchhint attribute.

Returns:

Value of the fetchhint attribute.

See Also:

ATTRIBUTE_FETCHHINT

setFetchhint

public void setFetchhint(String fetchhint)

Set the fetchhint attribute.

Parameters:

fetchhint - Value of the fetchhint attribute.

See Also:

ATTRIBUTE_FETCHHINT

getFetchtimeout

public String getFetchtimeout()

Retrieve the fetchtimeout attribute.

Returns:

Value of the fetchtimeout attribute.

See Also:

ATTRIBUTE_FETCHTIMEOUT

getFetchTimeoutAsMsec

public long getFetchTimeoutAsMsec()

Retrieves the fetchtimeout attribute as msec.

Returns:

number of milliseconds, -1 if the value can not be converted to a number.

Since:

0.6

setFetchtimeout

public void setFetchtimeout(String fetchtimeout)

Set the fetchtimeout attribute.

Parameters:

fetchtimeout - Value of the fetchtimeout attribute.

See Also:

ATTRIBUTE_FETCHTIMEOUT

getMaxage

public String getMaxage()

Retrieve the maxage attribute.

Returns:

Value of the maxage attribute.

See Also:

ATTRIBUTE_MAXAGE

getMaxageAsMsec

public long getMaxageAsMsec()

Retrieves the maxage attribute as msec.

Returns:

number of milliseconds, -1 if the value can not be converted to a number.

Since:

0.6

setMaxage

public void setMaxage(String maxage)

Set the maxage attribute.

Parameters:

maxage - Value of the maxage attribute.

See Also:

ATTRIBUTE_MAXAGE

getMaxstale

public String getMaxstale()

Retrieve the maxstale attribute.

Returns:

Value of the maxstale attribute.

See Also:

ATTRIBUTE_MAXSTALE

getMastaleAsMsec

public long getMastaleAsMsec()

Retrieves the maxstale attribute as msec.

Returns:

number of milliseconds, -1 if the value can not be converted to a number.

Since:

0.6

setMaxstale

public void setMaxstale(String maxstale)

Set the maxstale attribute.

Parameters:

maxstale - Value of the maxstale attribute.

See Also:

ATTRIBUTE_MAXSTALE

getSrcexpr

public String getSrcexpr()

Retrieve the srcexpr attribute.

Returns:

Value of the maxssrcexprtale attribute.

See Also:

ATTRIBUTE_SRCEXPR

setSrcexpr

public void setSrcexpr(String srcexpr)

Set the srcexpr attribute.

Parameters:

srcexpr - Value of the srcexpr attribute.

See Also:

ATTRIBUTE_SRCEXPR

addText

public Text addText(String text)

Create a new text within this grammar.

Parameters:

text - The text to be added.

Returns:

The new created text.

addCData

public CDATASection addCData(String data)

Creates a new CDATA section within this grammar.

Parameters:

data - the CDATA to be added

Returns:

the new created CDATA section

Since:

0.7.5

canContainChild

protected boolean canContainChild(String tagName)

Can the specified sub-tag be contained within this node?

Specified by:

canContainChild in class AbstractXmlNode

Parameters:

tagName - Name of child.

Returns:

True if the sub-tag is allowed on this node.

getAttributeNames

public Collection<String> getAttributeNames()

Returns a collection of permitted attribute names for the node.

Specified by:

getAttributeNames in interface XmlNode

Overrides:

getAttributeNames in class AbstractXmlNode

Returns:

A collection of attribute names that are allowed for the node

isExternalGrammar

public boolean isExternalGrammar()
                          throws IllegalAttributeException

This method checks, if this grammar is an external grammar or an inline grammar.

Returns:

true, if the grammar is external, else false

Throws:

IllegalAttributeException - Exactly one of "src", "srcexpr", or an inline grammar must be specified; otherwise, an error.badfetch event is thrown.