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.