Genesys Labs
DMS

 

 

 

 

 

 


Class SampleDriver

This is the central class of the Sample Driver; it implements interface ChannelDriver and demonstrates using of services provided by interface ChannelDriverPU. This class is instantiated by SM Server during the server’s startup stage if corresponding media channel is specified in the server’s configuration; namely, if there exists media channel in the configuration, which refers to this specific class name.

The next configuration will result in the Sample Driver loading:

[channel-sample]

driver-classname=com.genesyslab.mcr.smserver.channel.sample.SampleDriver

DMS loads respective class from specified classpath, creates instance of the class, and inquires method initialize, which must be implemented in class.

There is no need to define a special constructor for a channel driver’s class because DMS uses default constructor for the class.

The Sample Driver class is declared as belonging to the package com.genesyslab.mcr.smserver.channel.sample. A custom driver’s implementation may select its own package name as it is suitable for a particular case.

The class should be declared as follows, i.e. it must implement DMS interface ChannelDriver:

 

public class SampleDriver

     implements ChannelDriver

 

The class’ declaration section provides access to required resources of DMS and Genesys Platform SDK:

 

import com.genesyslab.mcr.smserver.channel.ChannelDriver;

import com.genesyslab.mcr.smserver.channel.ChannelDriverConstants;

import com.genesyslab.mcr.smserver.channel.ChannelDriverPU;

import com.genesyslab.mcr.smserver.channel.ChannelPU;

import com.genesyslab.mcr.smserver.common.Utils;

import com.genesyslab.mcr.smserver.gframework.GfrPU;

import com.genesyslab.mcr.smserver.gframework.LmsMessages;

 

import com.genesyslab.platform.commons.collections.KeyValueCollection;

import com.genesyslab.platform.commons.protocol.Message;

Channel Driver Initialization and Shutdown

The class’ method initialize (ChannelDriverPU channelDriverPU) is the first method, which is called by DMS after the driver has been instantiated.
In this method the Sample Driver performs its initialization – saves object ChannelDriverPU for later use, fetches configuration parameters by calling method getConfiguration of its helper class SampleDriverParams (which wraps CfgOptions class) and creates and launches SampleMonitor’s execution thread, which will imitate inbound data flow processing.

Note, that though the Sample Driver’s data fetching monitor is started here, it will not begin to create and submit messages to DMS, because the monitor’s activity is controlled by the driver’s connection state, namely it is controlled by the driver’s variable mediaConnected, which is set in connect / disconnect methods described below.

The method uses log services trace and logPfx, which are reviewed in the next section, and helper method getGfrPU, declared in the SampleDriver class.

    /**

     * Object ChannelDriverPU passed to the driver in initialize method

     */

    protected ChannelDriverPU channelPU = null;

 

    /**

     * Driver parameters populated by SampleDriverParams.getConfiguration

     */

    protected SampleDriverParams driverParams = null;

 

    /**

     * Connection state with media source

     */

    protected boolean mediaConnected = false;

 

    . . .

 

    /**

     * Object SampleMonitor(), which imitates inbound data flow and submits interactions to Interaction Server.

     */

    private SampleMonitor sampleMonitor = null;

 

 

    /**

     *

     */

    public void initialize(ChannelDriverPU channelDriverPU)

         throws Exception

    {

     this.channelPU = (ChannelPU) channelDriverPU;

     final String logRpfx = logPfx("initialize");

 

     driverParams = new SampleDriverParams(this);

     try {

         driverParams.getConfiguration();

     }

     catch (Exception ex) {

         getGfrPU().trace(LmsMessages.error2, logRpfx, "Failed to get configuration parameters, " +

                          ex.getMessage());

         throw new Exception("Channel driver initiaization failed");

     }

 

     // create monitor, which imitates input data source and submit inbound interactions

     sampleMonitor = new SampleMonitor(this);

     // start monitor

     sampleMonitor.start();

    }

 

    /**

     * Helper method, which returns GfrPU object

     */

    protected GfrPU getGfrPU()

    {

     return (null == channelPU) ? null : channelPU.getGfrPU();

    }

 

When DMS is shutdown it calls the driver’s method shutdown, which instructs a driver to perform its shutdown procedure, e.g. close connection with media source, store its data, if needed, write log messages, et al.

    public void shutdown()

         throws Exception

Logging

The code fragment shown above demonstrates how to write messages from a channel driver to the Genesys’ logging system. The method uses logging service provided by DMS – method trace, specified in DMS’s package com.genesyslab.mcr.smserver.gframework.GfrPU. The method’s definition is:

    /**

     * Writes message to a log file.

     *

     * @param msg_id

     *            message template's identification stored in LMS file

     * @param args

     *            message's parameters

     */

    public void trace(int msg_id, Object... args)

The method is available via DMS’s object of class GfrPU, which may be obtained from object, implementing ChannelDriverPU interface as it is shown in the previous section.

The Sample Driver also implements and uses in its classes the helper method logPfx, shown below, which constructs a unified signature for logging messages. Own channel name is available for a driver from method getChannelName.

 

    protected String logPfx(String secondName)

    {

     return "(" + channelPU.getChannelName() + ").(driver).(" + secondName + "):";

    }

Establishing Connection with Media Source

DMS controls establishing connection with media source and breaking it by invoking interface methods connect and disconnect. The server invokes these methods while it is initially started a driver and when it processes LCA commands like set primary/backup and stop.

A driver must report about its connection state to the server. It is made by calling method connectionState defined in ChannelDriverPU interface. A driver may invoke this method whenever it is necessary, e.g. when a connection with a media source has been broken and it is impossible to restore it.

The Sample Driver’s connection/disconnection procedures imitate establishing connection – set connection state internal variable mediaConnected, which is used in SampleMonitor’s method run.

   public void connect()

         throws Exception

    {

     if (mediaConnected) {

         channelPU.connectionState(true, "connected already");

         return;

     }

 

     try {

         mediaConnected = true;

         channelPU.connectionState(true, "connected");

     }

     catch (Exception ex) {

         channelPU.connectionState(false, "connecting attempt failed");

         throw new Exception("connecting attempt failed", ex);

     }

    }

The Driver’s disconnection procedure imitates disconnection with a media data source.

    public void disconnect()

         throws Exception

    {

     if (mediaConnected) {

         mediaConnected = false;

         channelPU.connectionState(false, "disconnected");

     }

     else {

         channelPU.connectionState(false, "was not connected");

     }

    }

Name and Version Reporting

There are two reporting methods, which are called by the server to get descriptive information about a channel driver – getName and getVersion. These methods return signatures of a driver, which are used by the server for logging purposes.

    static final private String NAME = "Genesys Driver Sample";

    static final private String VERSION = "8.0.210.01";

    static final private String COPYRIGHT_NOTE = "Copyright 2011 Genesys Telecommunications Laboratories Inc.";

 

 

    public String getName()

    {

     return NAME + ". " + COPYRIGHT_NOTE;

    }

 

    public String getVersion()

    {

     return VERSION;

    }

ESP Requests’ Processing

ESP requests assigned to a channel driver are delivered to the driver via method umsRequest of ChannelDriver interface. A driver receives an ESP request’s content in the method’s parameters.

Parameter serviceName contains a name of a service (or a name of one of a few services) supported by a channel driver. The Sample Driver supports one service Sample.

Parameter methodName contains a name of a method (or a name of one of a few methods) supported a channel driver. The Sample Driver supports one method SendMessage.

DMS merges an ESP request’s parameters and attributes of an associated interaction into one data structure, which is passed in the method’s parameter requestData. This parameter has type KeyValueCollection, defined in the Genesys Platform SDK. Content of the parameter, i.e., its keys and values, is not a part of ChannelDriver interface. Thus, every driver implementation may use its own keys. There is a recommendation to use a driver / media channel-specific prefix for keys. It’s also recommended to use, in combinations with driver-specific prefix, pre-defined keys from class ChannelDriverConstants whenever it is applicable. An example of using KeyValueCollection object is shown below.

The Sample Driver constructs key names from prefix KEY_PFX, defined in its class SampleDriver and predefined key names, defined in ChannelDriverConstants class, as it is demonstrated below.

     String msgType = requestData.getString(KEY_PFX + ChannelDriverConstants.UMSKEY_MSGTYPE);

     String msgPlainText = requestData.getString(KEY_PFX + ChannelDriverConstants.UMSKEY_MSGPLAINTEXT);

     String toAddr = requestData.getString(KEY_PFX + ChannelDriverConstants.UMSKEY_TOADDR);

A driver must send to DMS a result of ESP request’s processing by calling one of the reporting methods - umsResponse or umsFaultResponse, specified in ChannelDriverPU interface. Both processing responses may return to a caller any complementary data, provided by a driver, which will be transferred to a business process as ESP response parameters. Fault response additionally sends to a caller an error code and message, which describe a problem occurred in an ESP request’s processing.

Results reports are associated with original requests by specifying unique request identification serverRequestId. Below is an example of ESP request processing.

For more details refer to umsResponse and umsFaultResponse.

    public String umsRequest(String serverRequestId, String serviceName, String methodName,

         KeyValueCollection requestData)

         throws Exception

    {

     . . .

 

     // CHECKING CORRECTNES OF PARAMETERS SERVICE AND METHOD

 

     . . .

 

     // REQUEST PROCESSING

 

     if (<the request processing is successful>)

         channelPU.umsResponse(serverRequestId, resultData);

     else

         channelPU.umsFaultResponse(serverRequestId, 1102, errMsg, null);

 

         return serverRequestId;

    }

Note that ESP response may be sent to DMS even when umsRequest procedure has finished its execution and returned control to DMS. Thus a channel driver may implement asynchronous processing of ESP requests, where umsRequest procedure just receives requests and places them in a processing queue, and a dedicated ESP requests processor executes them and reports to DMS about processing results by invoking umsResponse or umsFaultResponse methods.

These are the basics of how to implement ChannelDriver interface and use ChannelDriverPU object in a channel driver.

Additional Information

For more information about the Genesys SDKs, including the latest versions of all SDK documents, check out the Genesys Developer Zone, which also contains forums and other important sources of developer-related information. DevZone is available at http://www.genesyslab.com/developer.

Additional information on Genesys Telecommunications Laboratories, Inc. is available on our Technical Support website.

Top of Page


 

 

 

 

 

 

 

 

Genesys Labs
DMS

 

 


Send comments on this topic.
Copyright © 2010–2018 Genesys Telecommunications Laboratories, Inc. All Rights Reserved.