This section describes how to extend UNICOM® Digital Transformation Toolkit (UDTT™) by implementing a new channel. It can also be helpful in understanding the implementation and behavior of the multichannel architecture channels.
The steps for implementing a new channel device are described in detail in the following sections:
1 Creating the channel driver
2 Creating the request handler
3 Creating the presentation handler
4 Adding channel session management
5 Managing channel sessions for any communication protocol
The class for a new channel driver must implement the com.ibm.btt.clientserver.ChannelDriver interface. It must also provide behavior to perform the following tasks:
▪ Create an instance of the channel context. The channel context should contain a reference to the request object, response object, and the channel driver object. For example, a channel context for a channel supporting the HTTP protocol would contain a reference to the HttpServletRequest, HttpServletResponse, and channel driver.
▪ Determine the device type. The channel driver must be able to determine the device type where the request originated and to update the channel context. For example, a channel supporting the HTTP protocol could use the User-Agent parameter in the request header to determine the type of browser from which the request originated.
▪ Create an instance of a channel handler. The channel handler should only be created the first time that the channel is accessed for a specific device. The channel handler will contain the reference to the instances of the handlers (request handler and presentation handler) required by the multichannel support components for the specific channel, and is externalized by adding a definition in the toolkit server configuration file (btt.xml). The channel handler may also contain a hash table of optional channel-specific information. Once the instance of the channel handler has been created, the reference is maintained by the handler registry singleton object.
The following is an example of the definition for the channel handlers in the server configuration file:
<!-- Each channelHandlers tag must have an entry in the requestHandlers tag --> <!-- and the presentationHandlers tag. All other tags are optional tags that --> <!-- are required by the driver --> <kColl id="channelHandlers"> <kColl id="java"> <field id="requestHandler" value="com.ibm.btt.cs.java.JavaRequestHandler"/> <field id="presentationHandler" value="com.ibm.btt.cs.java.JavaPresentationHandler"/> <field id="cookies" value="true"/> <field id="runInSession" value="true"/> </kColl> <kColl id="html"> <field id="requestHandler" value="com.ibm.btt.cs.html.HtmlRequestHandler"/> <field id="presentationHandler" value="com.ibm.btt.cs.html.HtmlPresentationHandler"/> <field id="cookies" value="false"/> <field id="runInSession" value="true"/> </kColl> </kColl>
▪ Create the channel session. Each channel driver must be able to create and manage a channel session, which is used to manage the communication between the client and the server. The channel session must only be created when the client requests to establish a session. Subsequent requests from the client should use the session that has already been created. The channel context must be updated with the channel session instance.
▪ Parse the request data. The request data must be parsed into a keyed collection that is maintained by the channel context. How the message is parsed will depend on the message, the communication protocol, and the device. The request data has been divided into two keyed collections, the header data and the message data. Additional requirements are specific to the message for the channel. For example, the channel driver will need to implement the XML for Java parsers if the device uses XML.
▪ Determine the request handler and presentation handler. The channel driver must be able to determine the channel handler for the specific device from the handler registry. The request handler is required when integration with the toolkit is required, and the presentation handler is required when a response is to be returned to the device.
▪ Process the request. The channel driver must be able to determine if the device request is to establish a session or execute a business request and invoke the corresponding protocol for the request handler. For example, a channel that supports the HTTP protocol may provide servlets to differentiate between the requests.
▪ Handle exceptions. The channel driver must be able to handle all exceptions. The channel driver should first attempt to determine the channel presentation handler to render the exception back to the device. This is not always possible as the channel handler cannot be determined until the application server has been established. In the event that the presentation handler cannot be determined, the channel driver may be required to notify the device directly that an error has occurred on the server. The exceptions should be logged to the server Trace Facility.
The following table briefly describes the methods of the ChannelDriver interface:
Creates the channel context, which is passed among the components that provide multichannel support. The ChannelContext data is used to manage the state for a single request.
Accepts and reads the channel driver request data, then builds a keyed collection of data in such a way that other multichannel support components can use it.
Accepts and reads the request header if the channel driver requires one, then builds a keyed collection of data in such a way that other multichannel support components can use it.
Performs the required session management. If the device provides session management, you can invoke it here. If not, you can invoke the session management available in the application.
The request handler is the main integration point between the channel driver and the toolkit, and must therefore be specific to the communication protocol, device, and business distribution channel. A request handler should inherit from the abstract class DSERequestHandler, which is an implementation of the RequestHandler interface. The abstract implementation class is provided as a starting point for developing new request handlers.
After a request handler class has been defined, it must be registered in the toolkit configuration file (server btt.xml), using the requestHandler field ID.
The request handler must perform the following tasks:
▪ Process the request. The request handler must be able to determine the contents of the ChannelContext request data in order to build and execute the application operation when a request is made from the device. For example, the request handler must be able to determine the operation name to be executed and the parent context to chain to the operation context, to update the timestamp of the session in the application session table, to handle a request to execute operations without a session, etc.
▪ Process the request to establish the session. By getting the ChannelContext request data, the request handler must be able to perform any integration that may be required when the request is made from a device to establish the session. For example, the request handler may be required to determine if the request is for an existing session and be able to obtain that session from the application session table.
▪ Determine the presentation handler. The channel driver must be able to determine this handler for the specific device from the channel handler, which is maintained by the handler registry. The presentation handler is required when a response must be returned to the device.
▪ Handle exceptions. The request handler must be able to handle all exceptions. The request handler should first attempt to determine the channel presentation handler to render the exception back to the device. This is not always possible as an invalid presentation handler may have been specified in the server configuration or the application server connection may not have been established. In the event that the presentation handler cannot be determined, exceptions should be logged to the server Trace Facility.
Informs the device that the session has been successfully established and performs any additional processing not available from the processReply() method. This method is used when a session has already been established, and should be customized for each presentation handler.
This method provides a generic mechanism to render an error to the client device. The method is used when an exception occurs, and should be customized for each presentation handler.
The presentation handler is responsible for rendering a result or exception to the device. To create the presentation handler for your new device channel, inherit from the abstract class DSEPresentationHandler class, which implements the PresentationHandler interface.
After your presentation handler has been designed, it must be registered in the toolkit configuration file (server btt.xml), using the presentationHandler field ID.
The presentation handler must perform the following tasks:
▪ Process the session reply. The presentation handler must be able to render a response to the device for the request to establish a session. For example, this may include information about the status, session ID, and timeout values to be used by future communications.
▪ Process the reply. The presentation handler must be able to render a response to the device in order for the request to perform an operation. For example, this may include information about the status, session ID, response data, and reply format.
▪ Process exceptions. The presentation handler must be able to render a response to the client that a request has resulted in an exception on the server. For example, an HTML client may be redirected to an error page.
▪ Handle an exception. The presentation handler should log exceptions to the server Trace Facility if unable to render the response to the device.
Handles a request to execute an operation. The method should remain unchanged to define the process flow of the request handler; use the protected methods to specialize the implementation.
Handles a request to create and establish a channel session. The method should remain unchanged to define the overall flow; use the protected methods to specialize the implementation.