Request Processing

In this section we explore the resource request in detail and show how to code accessors to retrieve request information. The definitive guide to accessor development is found in the NetKernel Extension Guide. In this section we use Beanshell (a scripting language based closely on Java) because we can illustrate the use of the NetKernel API without focusing on class types.

Once an endpoint has been located the microkernel assigns a thread from its worker pool to the request code and schedules it to start. The endpoint accessor may elect one of several approaches to handle the request:

• Return an existing static representation such as information in a file.
• Synthesize the representation with a computation.
• Transform another resource representation.
• Compose a representation by issuing sub-requests for other resource representations and combine their responses.
• Apply a policy (such as security) and re-issue the request.
• Map the request to another address by modifying the URI and re-issue the request.

Resource Request

A resource request contains the following information:

• The resource address (URI address) encoded as a text string
• A verb (SOURCE, SINK, NEW, EXISTS, DELETE or META)
• Optionally, one or more named parameters or an anonymous system parameter

Resource Address

To retrieve the address URI of the requested resource as a String:

request = context.getThisRequest();
uri     = request.getURI(); // query for resource address

For example, if you are writing a random number generator service and the URI mapped to your accessor is active:random then the value stored in the variable uri (above) is "active:random".

Verb

To retrieve the verb associated with a request as a Java integer (int):

request = context.getThisRequest();
verb    = request.getRequestType(); // query for request verb 

The constants for the verbs are:

INKFRequestReadOnly.RQT_DELETE
INKFRequestReadOnly.RQT_EXISTS
INKFRequestReadOnly.RQT_FRAGMENT
INKFRequestReadOnly.RQT_NEW
INKFRequestReadOnly.RQT_SINK
INKFRequestReadOnly.RQT_SOURCE
INKFRequestReadOnly.RQT_TRANSREPT

If you write an accessor using Java you can specify in its constructor the set of verbs the accessor's code supports. When using a scripting language you can only test for the verb associated with the request and respond appropriately. For example:

request = context.getThisRequest();
if (INKFRequestReadOnly.RQT_SOURCE != request.getRequestType())
{ throw new NetKernelException("Unsupported Request Verb");
}

Parameters and Arguments

Argument values are accessed through the parameter address space this:param: For example, if the request has a parameter named operand the argument value for that parameter has the address this:param:operand. The accessor for this address space manages the differences between pass-by-value and pass-by-reference arguments to present uniform access to argument values.

An accessor usually supports a fixed set of parameters. The argument values for each parameter can be retrieved by issuing a sub-request into the this:param: address space. For example, to get the StringAspect passed as the argument for the operand parameter:

subRequest     = context.createSubRequest("this:param:operand");
representation = context.issueSubRequest(subRequest);
aspect         = representation.getAspect(StringAspect.class);
stringValue    = aspect.getString();

This code shows that in NetKernel 3 the returned representation references one or more immutable Aspects. In this case we expect a StringAspect which contains a Java String object.

Convenience methods are provided for retrieving argument values. To directly retrieve the representation use:

representation = context.source("this:param:operand");
aspect         = representation.getAspect(StringAspect.class);
stringValue    = aspect.getString();

To directly retrieve a specific aspect use:

aspect      = context.sourceAspect("this:param:operand", StringAspect.class);
stringValue = aspect.getString();

Sometimes an accessor must be coded to accept arbitrary parameter names and their arguments. In this case, ask for a Java Iterator of parameter names (as Strings) and sequence through them:

request = context.getThisRequest();
iter request.arguments(); // query for parameter name Iterator
while (iter.hasNext())
{
  parameterName = iter.next();
  subRequest    = context.createSubRequest("this:param:" + parameterName );
  ...
}

In the case of the RQT_SINK verb the argument to be sunk is passed as an anonymous argument. This is retrieved by using a special address value encoded in the constant INKRequestReadOnly.URI_SYSTEM. For example, the following code tests for the verb and retrieves the argument's representation:

request = context.getThisRequest();
if (INKFRequestReadOnly.RQT_SINK == request.getRequestType())
{ representation = context.source(INKFRequestReadOnly.URI_SYSTEM);
...
}

The anonymous argument is otherwise invisible and does not appear in the list of argument names if a Java Iterator is requested with the arguments() method.

Treating the URI Address as a value

Sometimes it is important to treat the argument address as a value. For example, RESTful applications often encode information within the address such as in this URI:

ffcpl:/customer/id/334543

If the following is the effective request URI address:

active:customerReport+operand@ffcpl:/customer/id/334543

It can be processed within the customerReport implementation with the following code code:

request     = context.getThisRequest();
argumentURI = request.getArgument("operand");
... // parse argumentURI to extract the customer id value.

Which in this case the value "ffcpl:/customer/id/334543" is stored in the variable argumentURI and can be parsed using common Java parsing code.

Another example where this approach is useful is the random number generator service. If this service is to support a maximum value it might be convenient to encode the request as

active:random+max@20

In this case the code:

maxValue = context.getThisRequest().getArgument("max");

results in the text value "20" being stored in the variable maxValue.

Response

An accessor must return a response that includes a resource representation. A number of convenience methods are available to create a response. The most commonly used one creates a response from an aspect:

aspect   = new StringAspect("Hello World!");
response = context.createResponse(aspect);
...
context.setResponse(response);

Once a response is created its methods may be used to set attributes such as the MIME type of the returned value, whether the system should cache the value and more.

aspect   = new StringAspect("Hello World!");
response = context.createResponse(aspect);
response.setMimeType("text/plain");
response.setCacheable();
context.setResponse(response);