Sub-Requests

When an accessor processes a resource request it is acting as a server. In resource oriented computing an accessor is symmetrical; it can act as a client and issue its own requests. The new requests are called sub-requests to distinguish them from the original request.

There are many design patterns that call for accessors to issue sub-requests. For example, the accessor may be composing information from different sources (such as legacy systems) or it may apply a policy to the original request and, after checking the policy configuration, issue the original request as a sub-request into a (possibly different) address space.

Create a sub-request

To create a sub-request use the following code:

subRequest = context.createSubRequest();

Then add the resource URI address, verb, and any parameter arguments. In the following example the sub-request will call the active:xslt service and use pass-by-reference arguments.

subRequest.setURI("active:xslt");

// sets verb to SOURCE (redundant as SOURCE is default)
subRequest.setRequestType(INKFRequestReadOnly.RQT_SOURCE);

// sets operator argument
subRequest.addArgument("operator", "ffcpl:/style.xsl");

// sets operand  argument
subRequest.addArgument("operand",  "ffcpl:/data.xml");

// sets the desired class (optional)
subRequest.setAspectClass(StringAspect.class);

Note: the specification of a desired return aspect class is optional. SOURCE is the default request type and and so in 90% of cases setting the type is not needed, in which case the code could be as simple as:

subRequest = context.createSubRequest("active:xslt");
subRequest.addArgument("operator", "ffcpl:/style.xsl");
subRequest.addArgument("operand",  "ffcpl:/data.xml");

Issue sub-request

Once the sub-request is configured it is issued using this code:

representation = context.issueSubRequest(subRequest);

or

//Convenience method unpacks desired Aspect from Representation
aspect = context.issueSubRequestForAspect(subRequest);

These are pseudo-synchronous requests and the calling process will appear to block while waiting on a response. They are pseudo-synchronous because in fact the thread that calls this method re-enters the kernel and will be assigned work while the request is processed.

Asynchronous Requests

It is possible to issue explicitly asynchronous requests...

subRequestHandle = context.issueAsyncSubRequest(subRequest);
...
... //Continue doing useful work
...
representation = subRequestHandle.join();

In this case the requesting thread returns immediately with a handle to the asynchronous request. It can then continue performing local work. At any point you can call the join method to retrieve the response of the asynchronous request. If the asynchronous response is not yet ready the local process will block.

Pass-by-Value

In some situations you may wish to pass arguments by value instead of by reference. For example, if your accessor code has an aspect in a local variable it can use pass-by-value in a sub-request. Using pass-by-value arguments is analogous to an HTTP POST. Just like POST, responses to pass-by-value requests are not cacheable.

To use pass-by-value simply use the addArgument method and provide either a representation or aspect:

...
subRequest.addArgument("operand", representation);
subRequest.addArgument("operator", aspect);

SINK and TRANSREPT

Unless you need the fine control of creating a subrequest we recommend using the context object's convenience methods for SINK and TRANSREPT requests...

//Sinks aspect to target URI.
context.sinkAspect("TargetURI", aspect);

//Issues a transrept request to find a service to go from aspect to desired
desired=context.transrept(aspect, Desired.class);

If you need fine control you can create a subrequest and set its type, as above, but you must use the addSystemArgument() to set the value on the request:

...
subRequest.setRequestType(INKFRequestReadOnly.RQT_SINK);

// use a representation or
subRequest.addSystemArgument(representation);

// an aspect
subRequest.addSystemArgument(aspect);