VoiceObjects Back-End Integration - Part II: Java Connector
This is a shortened excerpt of the Blog Article VoiceObjects Back-End Integration - Part II: Java Connector from Jens Bäcker in the VoiceObjects Developer Blog on http://developers.voiceobjects.com. Please read the whole article there!
In the first part of this series about back-end integration with VoiceObjects we have seen an overview of the different approaches that are available with VoiceObjects 9.1. Now, in this second part, we will take a closer look at the Java Connector.
Basics
The basic idea of the Java Connector is that you implement a Java class for back-end integration. This Java class is instantiated directly by the VoiceObjects Server instance (i.e. it is running in the same Java Virtual Machine as the VoiceObjects Server instance), and the VoiceObjects Connector object of your VoiceObjects dialog implementation directly uses instances of your custom Java class.
Your Java class has to follow some conventions to allow the VoiceObjects Server to use it (your class does not have to implement any specific interface or extend any specific super-class).
- It has to be a Java Bean that provides public set methods for your input parameters and public get methods for your return parameters.
- All parameters (input and return parameters) have to be of type String (java.lang.String).
- Your Java Bean also needs to have one public business method - a method that performs the actual back-end access.
- The business method must not have any parameters (it solely operates on the parameters that are set using the set methods).
For error handling, you can implement two additional get methods (in addition to the methods for your return parameters) - getErrorCode and getErrorMessage. Both methods have to return a String - the return value of getErrorCode is actually a number in wrapped in a String.
The basic idea is, that first the VoiceObjects Server (based on the definition of the Connector object in your VoiceObjects application) will call the set methods of your class to set the input parameters for your back-end access. Then the VoiceObjects Server will call your business method. And lastly it will call the get methods to retrieve the return values (as well as error code and error message).
How it works
Now, let's take a look at how you can pass parameters from your VoiceObjects application to your Java class, call your business method, and retrieve the return values for further processing in your VoiceObjects application.
First, you need to compile your Java class and create a jar file containing your class (and all your other custom classes that might be needed by your business method).
Now, you create a Connector object in your VoiceObjects application that will use your Java class.
Here are the key things you need in your Connector object (also see the documentation of the Connector object the VoiceObjects Object Reference Guide):
- Location: a Resource Locator pointing at the location of your jar file (HTTP or file URL)
- File: the filename of your jar (if you need more than just one jar, you can provide a comma-separated list of filenames - only use comma as a separator - no spaces)
- Class/Port: the fully qualified class name of your Java Bean
- Method: the name of the business method in your Java Bean
- Parameter Set: the list of parameters you want to exchange with your Java Bean. In the Alias/Property field you have to specify the name of the Java Bean property (following the Java Bean conventions).
When the VoiceObjects Connector object is executed, the VoiceObjects Server performs the following steps:
- Iterate over all parameters in the parameter set and check for each parameter if the Java Bean provides a set method.
- Call the business method of the Java Bean.
- Iterate over all parameters in the parameter set and check for each parameter if the Java Bean provides a get method.
A Simple Sample Implementation
Now, let's take a look at a first sample application. Our sample application is going to ask for a company name and will present us the latest stock quote for this company.
Please open the original Blog Article VoiceObjects Back-End Integration - Part II: Java Connector to get the whole example.
A Sample Implementation using Collections
To illustrate the usage of Collections in a Java connector, we will extend our sample application a bit. It will now fetch multiple stock quotes at once which will then be presented using a List object.
Please open the original Blog Article VoiceObjects Back-End Integration - Part II: Java Connector to get the whole example.
To implement the processing of the Collection on the Java side (parsing the XML, manipulating cell contents, generating XML), you can use a utility class that is part of your VoiceObjects installation. The jar file is called ConnectorUtil.jar and resides in the directory Platform/Resources/CGIConnector/WEB-INF/lib/ of your VoiceObjects installation. The class that is relevant here is com.voiceobjects.connector.util.VOCollection. A JavaDoc documentation can be found at Platform /Resources/CGIConnector/doc/.
Class Loading and Versioning
As your custom Java classes are executed inside the same Java Virtual Machine as the VoiceObjects Server instance, changing your jar files requires a restart of your VoiceObjects Server instances. There is a way to monitor the jar files and to dynamically reload them when they were changed (see VoiceObjects Object Reference Guide). However, this is not recommended in production environments, as it will impact performance.
To avoid the need for restarting, you can use names for jar files and for java packages that reflect the versioning of your Java Connectors. Example:
The jar file could be called sample_java_connector.v1.jar and the package contained in this file could be called com.voxeo.connector.sample.v1. So if you make changes to your Java implementation, you increment the version numbers in your jar file as well as in your package name. You adapt the definition of the VoiceObjects Connector object accordingly and you can deploy a new version of your application without restarting the server instances. The old classes will still be loaded, but they won't be used anymore.
Pros and Cons of the Java Connector
Here is a quick overview of the Pros and Cons of the Java Connector to help you assess if the Java Connector is the adequate connector type for your use-case (for a direct comparison with the other connector types, please see VoiceObjects Back-End Integration - Part I: Overview).
Pros
- No communication overhead: As the Java Bean is executed in the same JVM as the VoiceObjects Server instance, the communication between these components are plain Java method invocations. There is no additional communication overhead like HTTP requests, assembling and parsing XML, etc. This allows high performance and low latency implementations.
- Simple architecture: The Java Connector does not require any additional components (e.g. application servers, middleware, etc) for back-end integration. This results in a simple 2-tier architecture.
Cons
- Impact on VoiceObjects Server instance: As the Java Bean is executed in the same JVM as the VoiceObjects Server instance, the performance of the custom Java code can have a negative impact on the VoiceObjects Server. This holds for memory consumption (if your Java code requires a significant amount of main memory, you have to take this into account in the memory configuration of your VO Server), impact on garbage collection (if your Java code creates a lot of objects, this might lead to increased garbage collection, which might have a negative impact on the response times of the VO Server), CPU load, and code stability (unstable code might negatively impact the stability of the VoiceObjects Server).
- Class loading for new versions: If your Java code changes frequently, you will either have to restart your VoiceObjects Server instances from time to time to load the new classes or you have to follow the naming convention that includes version numbers in jar and package names to avoid restarting.
Is the Java Connector the right Thing for me?
It is, if
- you want to avoid any communication overhead
- HTTP(S) communication for back-end integration is not allowed
- you want to implement your back-end integration in Java
- you don't want to have a 3-tier architecture with a dedicated data-access layer
It is not, if
- Java programming is not an option
- your integration code requires a significant amount of main memory, creates a large number of objects, or uses a large number of threads
- your integration code depends on a large number of external jar files
- you are concerned about the quality of your integration code (as bad integration code in a Java Connector can have negative effects on the stability of your VO Server)
- your integration code is not under your control (e.g. if you are building a hosting platform and your clients will write their own back-end integration code)
- your integration code changes frequently
Resources
RSS