NetKernel Foundation API

Programs written with a scripting language (or Java) use the NetKernel Foundation API (NKF) to access a programable layer residing above the microkernel.

The NKF is available as a set of Java interfaces exported by the Layer1 module (urn:org:ten60:netkernel:ext:layer1) and is documented with Javadoc. The Scripting Language Framework integrates the NKF with each scripting language and provides a local variable context which is an instance of INKFConvenienceHelper. Script code will use the methods provided by context to obtain arguments, issue sub-requests and return a resource representation.

General Processing Model

The processing sequence followed by all script code is:

1. Retrieve and process arguments from the initiating request
2. Perform necessary processing (including issuing sub-requests)
3. Create a response, configure it and allow it to be returned to the initiating request.

Accessors

Accessors are the most common NetKernel software component. They act as software endpoints or servers which handle requests. They can also act as a client and issue new requests (sub-request) to access resources needed to complete their work.

The org.ten60.netkernel.layer1.nkf.impl.NKFAccessorImpl class is the base class for developing accessors which use the NetKernel Foundation API. The NKFAccessorImpl must implement:

void processRequest(INKFConvenienceHelper context);

When a request's URI address is mapped to an accessor (to act as the endpoint), the microkernel calls the accessor's processRequest() method. The underlying NKFAccessorImpl manages the initiating kernel request and provides a number of services for interacting with the kernel, these are made available through the INKFConvenienceHelper.

The INKFConvenienceHelper or context object is the primary means to access initiating requests, to issue sub-requests to the kernel and to issue a response to the invoking request.

Scripting Note: In the NetKernel Scripting Framework a script execution commences as the result of a call to processRequest() in the underlying ScriptEngine accessor. Each script receives the INKFConvenienceHelper object which in all scripts is called the context object and which, in the script, has global scope. Conceptually you can think of a script execution as a dynamically coded accessor and the context object provides access to the initiating request in just the same way.

Request

NetKernel requests includes a URI address and optional arguments. The arguments are distinguished by name (not position) and comprise a URI address. The request being processed by an accessor can be retrieved with:

INKFRequestReadOnly reqro=context.getThisRequest();

The INKFRequestReadOnly interface provides read-only access to various facets of the request.

Arguments can be accessed uniformly, regardless of whether they are pass-by-value or pass-by-reference, using the this:param: URI scheme (The code supporting this scheme transparently handles any differences between pass-by-value and pass-by reference arguments). For example, suppose we had a request URI

active:myAccessor+arg1@ffcpl:/myResource.xml

The resource ffcpl:/myResource.xml can be sourced with

context.source("this:param:arg1");

Sub-Requests

If an accessor requires other resources to complete its processing it can obtain them by issuing a sub-request back to NetKernel. (The full set of sub-requests issued to process a root request can be see in the Request Visualizer tool.)

To issue a sub-request, a request object is created with the createSubRequest() method:

INKFRequest req=context.createSubRequest();

and is then configured before being issued. The base URI is set using

req.setURI("..");

(For example, to request an XSLT transform you would set the base URI to active:xslt)

Arguments can be added with the addArgument() method:

req.addArgument("myArg", ...);

The addArgument() method is overloaded and supports either pass-by-value or pass-by-reference. A pass-by-reference argument is one in which the address of the value is provided as a URI address. A pass-by-value argument is one in which the aspect is provided directly from the code. When pass-by-value is used NetKernel transparently creates a hidden URI address that points to the aspect. This hidden URI is handled transparently when the accessor retrieves its argument values using the this:param: scheme. While pass-by-value may be easier to use in some situations it prevents the caching of the resulting response.

The desired representation type (aspect type) can also be specified with:

req.setAspectClass(...);

For example to return a binary stream use IAspectBinaryStream.class, or to get an XML aspect, use IXAspect.class.

Once a request has been configured it can be issued to the microkernel:

IURRepresentation result=context.issueSubRequest(req)

The result of the request will be an IURRepresentation - from which you can obtain the aspect you requested with its getAspect(...) method.

The thread issuing a sub-requests will block until the sub-request is fully processed and returns a response. NetKernel is architected to guarantee that synchronous requests do not lead to the creation of unnecessary threads and that thread starvation will not occur. However, NetKernel is fully asynchronous, see the next section for asynchronous requests.

Asynchronous Sub-Requests

A sub-request may be issued asynchronously to allow the sub-request to be processed by a separate thread. The response from the asynchronous sub-request can be obtained later by issuing a call to join its thread with the accessor's processing thread. This coordination is achieved by using a handle. For example, using the context's issueAsyncSubRequest() method the sub-request is issued and an instance of INKFAsyncRequestHandle. is immediately returned.

INKFAsyncRequestHandle handle=context.issueAsyncSubRequest(req)

This method is non-blocking which means the accessor may continue with its independent processing. When the accessor can proceed no further without the response from the sub-request it calls the context's join() method. When join is called the accessor code blocks until the sub-request completes.

IURRepresentation rep=handle.join()

You can also receive responses asynchronously from the sub-request by attaching a listener to the handle. This allows you to wait for a response without tying up a thread. Typically the listener will be the accessor object itself. It must implement the INKFAsyncRequestListener interface. A typical pattern is to only issue a response from your accessor once you have received your response from a sub-request. The following example illustrates how to do this:

import org.ten60.netkernel.layer1.nkf.*;
import org.ten60.netkernel.layer1.nkf.impl.NKFAccessorImpl;
import com.ten60.netkernel.urii.*;

/** Accessor to source the operand URI asynchronously and attach a listener to
 receive result return it. **/
public class TestAsyncAccessor1 extends NKFAccessorImpl 
  implements INKFAsyncRequestListener
{
    public  TestAsyncAccessor1()
    {   super(5, true, INKFRequestReadOnly.RQT_SOURCE);
    }

    public void processRequest(INKFConvenienceHelper context) throws Exception
    {   context.setResponse(null);
        INKFRequest req = context.createSubRequest();
        String operand = context.getThisRequest().getArgument("operand");
        req.setURI(operand);
        context.issueAsyncSubRequest(req).setListener(this);
    }

    public void receiveException(NKFException aException,
         INKFRequest aRequest, INKFConvenienceHelper context) throws Exception
    {   throw aException;
    }

    public void receiveRepresentation(IURRepresentation aRepresentation,
         INKFRequest aRequest, INKFConvenienceHelper context) throws Exception
    {   INKFResponse resp = context.createResponseFrom(aRepresentation);
        context.setResponse(resp);
    }
}

Note that the processRequest() method calls context.setResponse(null). This ensures that a void response is not returned prematurely when the processRequest() method completes. Instead a response is returned when either the receiveRepresentation() or receiveException() method completes. Again if either of these methods called context.setResponse(null) they would not return a response either. This is useful for chaining a sequence of asynchronous requests. If a coding error causes an accessor to never return a response then it will be left dangling and eventually caught by the deadlock detector.

If the asynchronously issued sub-request is never joined or a listener attached its result will be discarded. In this case the initiating process will complete but the asynchronously issued sub-request will independently continue execution until it completes.

Response

An accessor returns a response object to the microkernel which is then returned to the initiating request. A response object must be an instance of a class implementing INKFResponse. The instance of INKFConvenienceHelper (provided as the variable context) provides the method createResponseFrom which accepts either a representation or an aspect. If a response is created from an aspect a representation with the correct references to the aspect will be created. If you need fine control, create a representation holding your aspect and the representation to construct your INKFResponse.

INKFResponse resp=context.createResponseFrom(..)

The response may be configured by calling a number of methods such as setCacheable() and setExpiryPeriod().

Transports and Transreptors

This document has introduced NKF from the perspective of Accessors which is the most common component. The request context and INKFCovenienceHelper is a common API used throughout all NKF-based components. See the Transport and Transreptor guides for example of the NKF API in use by other components.