Java API
There are two parts of the Unified CVP Java API: a set of Java interfaces and classes that are implemented or extended to build a custom component and a set of classes used by those components to obtain information on the environment in which the call is occurring. Each component implements or extends a different class, though many of them share a common base. Similarly, the class used to obtain environment information differs for each component, though each of those classes shares a common base class.
The classes used to obtain and change environment information are referred to as the Session API. All components receive an instance of one of the classes to act as the conduit between the component and VXML Server. The classes in the Session API are organized into a hierarchy where the classes for each component add unique capabilities to the common base with regards to what data is available to it and what it is allowed to modify.
When building a component, the design requires the component to implement a single execution method VXML Server uses to access the component. This method can be seen as the "main" method for that component; it is where VXML Server leaves its context and enters the component’s. It is this execution method that receives as a parameter a class belonging to the Session API to provide the component access to environment information.
The execution method is used exclusively by VXML Server. Two components, custom configurable elements and Say It Smart plugins, require integration with Builder for Call Studio. For those components, the API additionally requires methods that define how to render it.
For those components that need to produce VoiceXML (primarily configurable voice elements and hotevents), Unified CVP provides another set of Java API classes called the Voice Foundation Classes (VFCs). These classes act as an abstraction layer to VoiceXML and allow Unified CVP components to work seamlessly on any supported voice browser. Building VoiceXML using the VFCs is very much like building VoiceXML statically, except in a Java environment.
The API Javadocs contain detailed descriptions for each of the classes in the Java API, including the Session API and the VFCs.
Design Considerations
A few notes on VXML Server and how it interacts with custom components written in Java is warranted. This information is important to keep in mind since how a developer approaches the design of the components they wish to build is impacted by them:
-
Each application is run by VXML Server in its own separate classloader. The classloader’s focus includes all Java classes found in the local application’s
java
folder, all classes found in VXML Server’scommon
folder, and the other classes available in the application server’sCLASSPATH
. The advantage of this approach is that developers need only worry about class name conflicts within an individual application. One consequence, however, is that static class variables are static only within each application, even if they appear in classes stored incommon
.Additionally, when an application is updated, a new classloader is created for the application, replacing the previous one. This is not a problem unless dealing with static variables, which would be reset once the application is updated. While knowledge of classloaders is not required in order to know how to build custom components, it can be useful to understand how classloaders work in Java to understand how custom component code integrates with VXML Server.
-
An application is loaded into memory when VXML Server first starts up or the application is updated. During this process, a single instance of each element (both standard and configurable) is created and cached for the application to use. Whenever a call to that application encounters an element, VXML Server will call the execution method of that single instance. This means that a single element instance will handle requests made across all calls to the application. This applies to multiple uses of an element type in the call flow (for example, if the call flow contains two Digits elements, VXML Server will actually use the same instance for both across all calls). This is very important because in this design, the element class acts as if it is static.
The consequence of this is that all member variables defined in the element class act as static variables, meaning that once changed, every caller experiencing that element type is exposed to the same value. Use only static final member variables, store any persistent data in the session (which the API provides access to), and keep all other variables local to the execution method. Everything an element needs is provided by the API so while this is important to be aware of, this design restriction should not prevent the developer from implementing any desired functionality within the element.
-
VXML Server runs in a multi-threaded environment. If the guidelines above are followed, such as avoiding member variables and non-final static variables this does not pose a problem. The developer does not need to worry about architecting their code with synchronization in mind when dealing with local or session variables. They would, however, when performing tasks such as accessing external resources such as files.
Compiling Custom Java Components
Once a component is constructed in Java, the process for compiling
and deploying these classes is very simple. The VXML Server
lib
directory includes JAR files containing
everything a developer requires to compile custom components. The main JAR file
of interest is framework.jar
, which defines the
entire Unified CVP Java API (including the VFCs).
To create custom
components, all that is needed is to ensure that this JAR file appears in the
compiler’s CLASSPATH
or referred to in a Java IDE
project file. Some Java IDEs may require additional JAR files,
servlet.jar
and
xalan.jar
, to appear in the
CLASSPATH
since the classes within
framework.jar
refer to classes defined in those JAR
files and these IDEs cannot compile without definitions for these additional
classes. The command-line Java compiler does not require
servlet.jar
or xalan.jar
to appear in the CLASSPATH
. The developer is then
responsible for adding to the CLASSPATH
any
additional JAR files their custom code requires.
Deployment
Once compiled, component class files are deployed separately for Call Studio and VXML Server. Within these deployments, a developer can choose to associate component classes with a specific application or with the system as a whole so that the components can be shared across all applications. The deployment process for Call Studio and VXML Server are described in the following sections. A third section provides details on the specific deployment directories developers should use.
Call Studio Deployment
Call Studio provides a location to place components that are to be shared across all applications: Call Studio\eclipse\plugins\com.audiumcorp.studio.library.common
. Individual classes are placed in the classes
subdirectory and JAR file archives are placed in the lib
subdirectory.
Note |
The only classes that need to be placed here are custom configurable elements and Say It Smart plugins since all other components have no Call Studio interface and hence require deployment only on VXML Server. |
Once deployed in this folder, custom configurable elements will appear in the element pane directly under the Elements folder alongside with Unified CVP-provided elements.
For component classes that apply to a specific application only, a developer uses the deploy\java
directory found in that application’s project folder. Within Call Studio, compiled classes and/or JAR files can be dragged
from outside Call Studio to the appropriate subdirectory in the deploy\java
folder.
An alternative method that does not require Call Studio to be running would be to copy the files into the appropriate subdirectory
of the deploy\java
folder using the file system.
The application project folder can be found in Call Studio\eclipse\workspace
(unless the developer sets the workspace to a custom directory) and the deploy\java
folder within the application will appear here exactly as it appears in the Call Studio application project window. This
can also be done while Call Studio is running, though to view the copied files in Call Studio, the deploy
folder should be selected and the Refresh option chosen from the contextual menu.
Custom configurable elements placed in the deploy\java
directory will appear in Call Studio’s element pane under the folder named Local Elements. The call flow editor for that application must be closed and reopened in order for newly copied local elements to appear
in the element pane.
When the application is deployed from within Call Studio, the VXML Server folder created for that application will contain
a folder named java
whose contents is identical to the deploy\java
folder in the Call Studio project.
It is important to mention that you can have a Java library with *.zip filenames in your development environment (Call Studio), because classpaths are explicitly specified. However, the VXML Server runtime environment has to preload all library classes implicitly. The naming convention the VXML Server enforces the *.jar filename extension and will not load classes with *.zip filenames. Therefore you must use *.jar filenames for classes that are developed on Call Studio and will run on VXML Server.
VXML Server Deployment
When an application is deployed through Call Studio, a folder is created that encapsulates all the information for that application, including all Java code the developer placed in the Call Studio project as per the instructions given in the previous section. If the application is to change in any way, from changes to the call flow, to the addition or subtraction of required Java files, those changes must be done through Call Studio and then redeployed to VXML Server.
One deployment requirement that must be performed by the developer is to ensure that the Java components and utility libraries
stored in the Call Studio\eclipse\plugins\com.audiumcorp.studio.library.common
folder are also placed in the VXML Server common
folder. When an application is deployed from Call Studio, only that application’s files are created, any common code is not
included. As a result, it is the developer’s responsibility that the contents of the common
folder in Call Studio also appear in the VXML Server common folder.
Note |
When VXML Server initializes, it first loads the classes in common
and then loads each application’s classes. Due to the way Java classloaders
work, if a Java class appears in both the
common
folder and an application’s
java
folder, the one in
common
will take precedence and the one in the application’s
java
folder
will not be
loaded.
|
Note |
Due to the order in which these classes are loaded, the developer cannot place a class in common
that refers to a class that only appears in an application’s
java
folder since the classes in
common
are loaded first. Keep in mind that some application servers have advanced
options to change this precedence to
parent-last,
meaning that the application-level classloaders take precedence. By default,
all application servers should be configured to be
parent-first.
|
Subdirectories of the Java Folder
The
java
folder of a Call Studio project and a VXML Server application folder contain
two subdirectories named
application
and
util
.
Each folder encapsulates Java classes used for different purposes, their
distinctions applying primarily to how the application works within VXML
Server.
The
application
folder should contain all Java code for
components that are used by the application.
Note |
In Call Studio, any custom configurable elements that are utilized only by the application would be placed in this folder and will appear in Call Studio’s element pane under the folder named Local Elements. The call flow editor for that application must be closed and reopened in order for newly copied local elements to appear in the element pane. |
The second
subdirectory of the
java
folder is the
util
folder. This is used for Java libraries that provide the application with
utilities unaffiliated with Unified CVP (such as math libraries, XML parsing
libraries, etc.).
Notes concerning which folder to use:
-
Any class that refers to Unified CVP-specific API classes cannot be deployed in the
util
folder. If the class is application-specific, it must be placed in theapplication
folder of that application. If the class is to be shared across all applications, it must be placed in thecommon
folder of VXML Server. -
The classes in the
util
folder will not be reloaded when the application is updated using theupdateApp
administration script. If this behavior is not desired or the utility libraries are frequently updated, place these files in theapplication
folder. See User Guide for Cisco Unified CVP VXML Server and Unified Call Studio for more information. -
Utility classes that do not refer to Unified CVP classes at all (such as third-party libraries) can be placed anywhere within the CLASSPATH of the application server. For example, on the Tomcat application server, a library for connecting to a mainframe system can be placed in
TOMCAT_HOME\lib
rather than any Unified CVP directory.
Object getLocalVariableData
This method returns the current value of the local variable passed as a parameter in an application. The return type of the variable is a Java object class. If you send a variable name which does not exist on the application or null parameter, this method will return an empty string. This API works with respect to the current subflow or main flow execution.
setLocalVariableData
This method allows you to set values for local variables in an application. This API works with respect to the current subflow or main flow execution.