Transports provide the mechanism by which external events are accepted and mapped to
NetKernel service invocations and the resultant responses are returned.
NetKernel does not make any assumption about the nature of transports.
NetKernel ships with standard internet protocol transports such as HTTP
and new transports can be added easily.
An example of an interesting custom transport is the GUI message transport
used in the PingPong application.
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.
An external event is received by the transport. The transport decides (in some implementation dependent manner)
the internal URI of the service to invoke to process the event.
The transport makes an internal URI request to the kernel through the Transport Manager.
If the external
event has additional parameters, the transport is responsible for providing these with the internal
request.
The internal request URI commences the service process in the module hosting the transport.
See
Module Guide for details about resource mapping and the application module hierarchy.
The response from the request is returned to the transport which will return it to the event generator.
If the service request produces an exception the transport may optionally choose to invoke an exception
handler by issuing further requests for services.
The remainder of this guide describes how to create a new transport.
Coding a Transport
To create a new transport, create a class which extends
NKFTransportImpl.
package com.myCom.myApp;
import org.ten60.netkernel.layer1.nkf.*;
import org.ten60.netkernel.layer1.nkf.impl.*;
/**
* MyTransport
*/
public class MyTransport extends NKFTransportImpl
{
/** Creates a new instance of MyTransport */
public MyTransport()
{
}
/*Start transport*/
public void startTransport() throws Exception
{ // technology specific startup code
}
/*Stop transport*/
public void stopTransport() throws Exception
{ // technology specific stop code
}
}
The startTransport and stopTransport methods are called by the TransportManager to
start and stop the transport.
The implementation of these methods depends on your underlying application protocol technology.
Making NetKernel Requests
Implement an event handler method specific to your technology - this should be called for
any external event that needs servicing by a NetKernel service:
private void myTransportEventHandler(MyEventData aData)
{
// get the Transport INKFConvenienceHelper context object
INKFConvenienceHelper context=this.getContext();
// Create a sub-request
INKFRequest req=context.createSubRequest();
// Set the URI of the service to be requested - the URI of the service
// to be determined by you in some transport specific manner.
req.setURI(processURI);
// add any specific arguments if necessary
req.addArgument("myArg", myData);
// issue the request
try
{ INKFResponse resp=context.issueSubRequest(req);
//Retrieve appropriate aspect
IAspectBinaryStream bs=(IAspectBinaryStream)resp.getAspect(IAspectBinaryStream.class);
//Send response to initiating event
}
catch(NKFException e)
{ // perform transport specific exception handling / notification
}
}
The INKFConvenienceHelper is used to create and issue a request for a NetKernel hosted service - the comments in the example above
show the typical steps in creating, adding arguments and issuing a request.
Asynchronous Requests
The example above shows a synchronous (blocking) request for a NetKernel service. It is equally
possible to issue a non-blocking asynchronous request - the result can either be obtained by joining with
the request using the INKFRequestHandle or by registering the transports callback interface.
To create a callback transport the transport should implement
INKFAsyncRequestListener.
It should then issue it's Kernel sub-request as follows...
// issue an async request
INKFRequestHandle handle=context.issueAsyncSubRequest(req);
handle.setListener(this);
//Continue monitoring for events
Sourcing Resources
It is often useful to source resources from the host Fulcrum's address space,
for example to read configuration when starting the transport.
The INKFConvenienceHelper context can be used to issue kernel
requests to source resources.
The context can be obtained at any time using the
getContext() method.
The context may be used in exactly the same way as if the transport were an Accessor in the address space of the fulcrum module.
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 a fulcrum 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.