Transport Developers Guide

Introduction

Transports provide the mechanism by which external requests are mapped into NetKernel application invocations and processed responses are delivered back to the requester.

The 1060 NetKernel does not make any assumption about the nature of the transport. By default it provides the standard internet protocol transports such as HTTP and SMTP but new transports can be readily created and added to the system.

An extensible transport architecture allows interesting custom transports to be developed such as, for example, a GUI message transport. Indeed nothing prevents asymmetric transports with a request-acknowledge inbound protocol on one channel and a response-acknowledge on a different channel.

Transport-Kernel Interaction

The diagram on the left shows the general pattern of interaction between a transport and the Kernel.

1. An external request is received by the transport. The transport decides the URI of the application to invoke for the request.
2. The transport makes an internal request to the kernel through the Transport Manager. If the external request has additional parameters, the transport is responsible for providing these with the internal request - as appropriate.
3. The internal request URI commences the resource request process in the home module of the transport. See Module Guide for details about resource mapping and the application module hieararchy.
4. The response document from the application is returned to the transport. It will generally be served back to the requester but if necessary the transport may perform post-processing operations, such as rendering for example, before serving the response.
5. If the application generates an exception the transport may optionally choose to invoke an exception application. Since exceptions are XML documents it is convenient to process exceptions using an XML Application

The remainder of this guide describes how to create a new transport.

Coding a Transport

Create a new class which implements the com.ten60.netkernel.transport.ITransport interface.

package com.myCom.myApp;

import com.ten60.netkernel.transport.*;
import com.ten60.netkernel.container.*;
import com.ten60.netkernel.urrequest.*;
import com.ten60.netkernel.urii.*;
import com.ten60.netkernel.urii.representation.*;
import com.ten60.netkernel.util.NetKernelException;

/**
 *  MyTransport 
 */
public class MyTransport implements ITransport
{   private Container mContainer;   

    /** Creates a new instance of MyTransport */
    public TelnetTransport()
    {   
    }
    
    /*Start transport*/
    public void start(Container aContainer, IRequestorContext aContext) throws NetKernelException
    {   mContainer=aContainer;
    }
    
    /*Stop transport*/
    public void stop() throws NetKernelException
    {
    }
}

The ITransport interface is called by the TransportManager to start and stop the transport. The implementation of these methods pretty much depends on what you are doing. Obviously you will want to initiate your Transport Specific classes when the Transport is started. It is important to keep a reference to the Kernel's Container since the TransportManager is discovered from the Container and without the TransportManager the transport cannot issue internal requests.

Making Internal Requests

Get Transport Manager

TransportManager tm = (TransportManager)aContainer.getComponent(TransportManager.URI);

Create a request. It is important to specify the class of the IURAspect you want returned. The lowest common denominator is to request IAspectBinaryStream.class. See the Request Guide for more details.

Issue request

IURRepresentation rep=mManager.handleRequest(request);

Obtain the interface to the aspect you requested - this example gets an IAspectBinaryStream interface.

IAspectBinaryStream bs=(IAspectBinaryStream)rep.getAspect(IAspectBinaryStream.class);

The external response is issued to the external requestor in whatever transport specific manner you chose.

Registering a Transport

Since a transport is generally imported into another module. It is important for the transport module itself to export the Transport Class. The public interface of a module is explored in depth in the module guide.

Transports are imported into another module. Within the module.xml definition of the module that wants to use the transport specify a first child element <transports> and add a <transport> element like this:

The text value should be a fully qualified java classname of the class implementing the transport interface. When the module is discovered the TransportManager will automatically start the transport.