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’s common folder, and the other classes available in the application server’s CLASSPATH. 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 in common.

  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.

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.

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 the application folder of that application. If the class is to be shared across all applications, it must be placed in the common folder of VXML Server.

• The classes in the util folder will not be reloaded when the application is updated using the updateApp administration script. If this behavior is not desired or the utility libraries are frequently updated, place these files in the application 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.

While the Java API has Javadocs explaining what can be done with the classes and methods in the API, the DTDs for every XML document sent either as a request or a response is described within this document. A quick introduction to DTD diagrams is warranted at this point in order to fully understand the XML API.

The preceding figure shows a sample DTD diagram that contains most of what can be found in an XML DTD. A DTD diagram is a graphical representation of a DTD, which explains how an XML document is formatted. Due to the nature of XML, syntax is very important and DTD diagrams describe the syntax of an XML document. The diagram shows the hierarchical structure of XML by using a sideways tree display, listing tags and their child tags from left to right. The diagram shows the attributes of tags as well as how those tags can be added to their parent tags.

The characteristics of the sample DTD diagram are:

• The root tag is named parent. A Tag is denoted by a blue diamond in its box.

• The parent tag has two attributes: attribute1 and attribute2, displayed in a red box emerging from the tag. An attribute is denoted by a blue circle in its box.

  • The type of each attribute is shown in the gray section of the box (enumeration and string in this example).

    An enumerated type is an attribute whose value can be one of a select group of options (for example, "apple", "orange" or "grape").

  • In this example, attribute2 is an optional attribute, denoted by a question mark to its left.

  • In this example, attribute1 is a required attribute, denoted by having no symbol to its left.

• The parent tag has four child tags that can appear within the encapsulating parent tag. This is denoted by a red bracket encapsulating all the tags.

  • A bracket indicates that the child tags must appear within the parent tag in the order set in the diagram.

  • A "*" at the left edge of the tag indicates it can appear from 0 to many times.

  • A "+" indicates it can appear from 1 to many times (that is, it must appear at least once in the document).

  • A "?" indicates it can appear from 0 to 1 time (if it appears, it can only be once).

• The child2 tag contains its own tags, another_child1 and another_child2.

  This time, however, an angled red line is used to encapsulate the tags. This indicates that either one or the other can appear, but not both.

• The child4 tag has a similar situation, but a + sign appears before its child tags, indicating that the child tags can appear any number of times, in any order, as long as there is at least one appearance.

The following code is an example XML document that conforms to the above DTD:

<parent attribute1=”something”> 
	  <child1 attribute=”a value”/>
	  <child1/>
	  <child2>
		    <another_child1 attribute=”this is required”>
		      	Some value for the another_child1 tag.
	    	</another_child1>
		    <another_child2>
		      	The content for another_child2.
	    	</another_child2>
	  </child2>
	  <child4>
	    	<child1_of_child4/>
	    	<child2_of_child4/>
	    	<child2_of_child4/>
	    	<child1_of_child4/>
  	</child4>
</parent>

Note	The child1 tag is allowed to appear multiple times because it has a * next to it. One child1 tag does not have an attribute because it is optional. Additionally, since these tags do not encompass any additional content, the tag is closed with a "/>" so there is no need for a closing tag.

Note	The child2 tag contains its two child tags. The another_child1 and another_child2 tags encapsulate text so they have an open and close tag. The another_child1 tag must specify its required attribute.

Note	The child3 tag can be omitted because it is optional.

Note	The child4 tag contains any number of its child tags in any order. It would be a syntax error to not include any child tag at all since at least one is required.

Note	The order in which the child tags of parent must conform to the diagram. If child4, for example, appeared before the child1 tag, that would be a syntax error.

It is up to the developer to set up the environment necessary to support the requests made by VXML Server. Since the API is accessed over HTTP, the XML content must be served by a web or application server. This content could potentially be served on the same machine as VXML Server though the act of parsing XML and the details of using HTTP will add additional overhead to the performance of VXML Server. To get the best performance, the setup should consist of a separate system handing the requests on the same subnet as the machine on which VXML Server is installed. Maintaining the two systems on the same subnet will reduce any network overhead as well as allow the administrator to restrict communication to occur only within the same subnet.

Keep in mind that, unlike Java, changes made to components using the XML API are not graceful. Components using the Java API are deployed on top of VXML Server and therefore take advantage of the graceful nature of VXML Server administration activity, while components using the XML API are hosted on separate systems. Any changes made to system that would affect the XML sent as response to VXML Server requests would be available immediately. The administrator must ensure that maintenance activity be performed on both systems to ensure callers do not experience changes within a single phone call. For handling updates to applications using components using the XML API, suspend the application before changes are made to the server hosting the XML.