NuGram Server provides three servlets: one that emulates a JSP-like interface to dynamic grammars, while the other two provide a more REST-like interface.
For all the examples below, assume that the web application name
is nugram-server and the application runs on the
localhost on port 8080.
/grammars
This servlet only supports the dynamic grammar instantiation
service and the generation service. It handles all requests
whose path is of the
form /grammars/resource. It behaves
differently depending on the type of requested resource:
grammars directory of the web application,
but not an ABNF grammar, it is served as is;grammars directory of the web application, it
is instantiated using the request parameters passed to
the context
initializer and the resulting grammar is generated in the
ABNF format;grxml
or gsl but with the same name as an ABNF grammar
in the grammars directory of the web application,
the ABNF grammar is instantiated using the request parameters
passed to the context
initializer and the resulting grammar is generated in the
XML form or the GSL form, depending on the resource's
extension.The servlet can also be used to serve all other resources other than the speech recognition grammars (like phonetic dictionaries, etc.).
To illustrate, assume the grammars directory
contains the following files:
static-grammar.abnf contacts.abnf contacts.pls
The request
http://localhost:8080/nugram-server/grammars/contacts.pls
returns the content of the file. To
convert static-grammar.abnf to the XML form, the
following request is issued:
http://localhost:8080/nugram-server/grammars/static-grammar.grxml
Finally, to instantiate contacts.abnf and
get the result in GSL form, the following request is issued:
http://localhost:8080/nugram-server/grammars/contacts.gsl?name=john&id=1234
In contrast to the JSP-like servlet, the REST-like servlets operate in two steps for the generation of dynamic grammars. They support all of NuGram Server's services.
/grammar
This servlet is used for instantiating dynamic grammars and generating the corresponding grammar source.
To instantiate a dynamic grammar or load a static grammar for
doing semantinc interpretation, an HTTP POST
request is sent to the servlet. The request URL is of the form:
http://hostname:port/webapp-name/grammar/grammarPathwhere
grammarPath is the relative path of
the ABNF grammar in the grammars directory. For
dynamic grammars, the instantiation context is sent in the
request's body, encoded using
the application/x-www-form-urlencoded MIME
type. How the data is interpreted to build the instantiation
context depends on
the context
initializer associated with the ABNF grammar.
Upon successful loading or instantiation of the grammar, the servlet returns an XML document of the form:
<?xml version="1.0" encoding="encoding"?>
<grammar grammarUrl="grammarUrl"
interpreterUrl="interpretaterUrl" />
The grammarUrl gives the URL for requesting the
textual representation of the loaded grammar, while
the interpreterUrl gives the URL for invoking
the semantic interpretation service for the loaded grammar.
To get the source of the generated grammar in a format other
than ABNF, simply add the format parameter
to grammarUrl. The supported values for this
parameter are abnf, grxml,
or gsl.
POST'ing the parameters name=john&id=1234 to the URL
http://localhost:8080/nugram-server/grammar/contacts.abnf
returns a response like
<?xml version="1.0" encoding="encoding"?> <grammar grammarUrl="http://localhost:8765/nugram-server/grammar/6d26c5a7faa9196bfb9d73609f997cd141d50b3a;jsessionid=j72xfs1s3i9h" interpreterUrl="http://localhost:8765/nugram-server/interpretation/6d26c5a7faa9196bfb9d73609f997cd141d50b3a;jsessionid=j72xfs1s3i9h" />
To get the generated grammar in XML form, a GET request is send to the following URL:
http://localhost:8765/nugram-server/grammar/6d26c5a7faa9196bfb9d73609f997cd141d50b3a;jsessionid=j72xfs1s3i9h?format=grxml
/interpretation
This servlet is used to perform the semantic interpretation of a
textual sentence using a grammar previously loaded by a request
to the /grammar servlet.
To perform the interpretation, an HTTP POST request
is sent the interpretation URL with the sentence
parameter set to the sentence to interpret, properly encoded using the
application/x-www-form-urlencoded MIME
type.
Upon successful interpretation of the sentence, the servlet responds with an XML document of the form:
<?xml version="1.0" encoding="encoding"?> <interpretation> <![CDATA[ JSON-encoded representation of the semantic interpretation ]]> </interpretation>
Using the interpretation URL from the previous
example, POST'ing the
parameters sentence=call%20john (which corresponds
to the sentence "call john", to the URL
http://localhost:8765/nugram-server/interpretation/6d26c5a7faa9196bfb9d73609f997cd141d50b3a;jsessionid=j72xfs1s3i9h
returns a reponse like
<?xml version="1.0" encoding="encoding"?>
<interpretation>
<![CDATA[ [{"contactId": "1234"}] ]]>
</interpretation>
When more control is required regarding the creation and initialization
of context initializers, it is advised to extend one of the provided
servlet classes and override its doInit()
method. In this method, the getGrammarServerConfig() method is
called to access the servlet's configuration and add associations between grammar names
and context initializers.
In this example, the GrammarsServlet class is extended and
context initializers are added programmatically:
public class MyGrammarServlet extends GrammarServlet {
protected void doInit(ServletConfig servletConfig) {
GrammarServerConfiguration config = getGrammarServerConfiguration();
config.addContextInitializer("en/autoattendant.abnf", new AutoAttendantContextInitializer("en"););
config.addContextInitializer("fr/autoattendant.abnf", new AutoAttendantContextInitializer("fr"););
}
}