|
Request Guide |
Introduction
A request can be made from either an accessor or a transport and if the NetKernel can resolve it it will be mapped into a request on another accessor in possibly another module. The technical design of the Universal Resource Request Infrastructure can be found here.
Constructing a Request
//Create Request
URRequest request = new URRequest
( aURI,
aRequestor,
aSession,
aContext,
aType,
aCurrentWorkingURI,
aParentRequest,
aAspect
);
| Field | Description |
| aURI | an absolute URI which is the subject of the request. This must be supplied for all
request types except RQT_NEW |
| aRequestor | the IURRequestor that is making the request and expecting the
result. This must be supplied for all requests, including synchronous |
| aSession | the IRequestorSession that this request belongs within. A new
session object is created by a transport when the request enters the system. All
sub-requests must then use this same session that can be gained from the parent
request. |
| aContext | the IRequestorContext that the request is resolved against.
All Modules implement IRequestorContext and the context of any given request
should always be the module that owns the requestor. |
| aType | an integer constant for one of the registered request types. |
| aCurrentWorkingURI | like current working directory, current working URI defines the URI that relative URIs in subrequests will be resolved against. |
| aParent | for all requests other than transport initiated requests this should be a reference to the request which initiated the accessor which is making this sub-request. |
| aAspect | the class of an IURAspect that the result must contain. As
com.ten60.netkernel.urii.IURAspect is the base interface of
all aspects, passing this class in is like a wildcard. |
Passing arguments by Value
It is possible to pass arguments to a request by value, this is typically
used when dealing with requests to Active Accessors using
Compound URIs but is also used to pass the value to
sink in a RQT_SINK request.
//Add an argument to request
IURRepresentation myValue = .......;
URIdentifier uri = new URIdentifier("var:myValue");
request.addArg( uri, myValue );
Request Types
| Type | Description |
| RQT_SOURCE | Source an in-memory representation for a resource specified by a URI resolved in the given context. The represesentation must contain an aspect which implements the given aspect interface. |
| RQT_SINK | Sink new state to a resource specified by a URI resolved in the given context.
The state to sink the resource with is taken from a pass-by-value
argument in the request with the URI URRequest.URI_SYSTEM. It
is the responsibility of the accessor handling the request to ensure the
argument contains an appropriate aspect and to transrepresent it if not. A
sink request returns a IVoidAspect if sucessful. |
| RQT_TRANSREPRESENT | Transrepresent a representation from one aspect to another. The given
URI is transrepresented by an appropriate transreptor located in
the given context. The value to transrepresent is taken from a pass-by-value
argument in the request with the URI URRequest.URI_SYSTEM. |
| RQT_DELETE | Delete a resource specified by a URI resolved in the given context. The
symantics of delete are resource dependent but a sucessful delete should
always effect the outcome of an RQT_EXISTS request. A delete
request returns a IAspectBoolean result to indicate whether the
resource was deleted or not. |
| RQT_EXISTS | Checks for the existence of a resource specified by a URI resolved in
the given context. A exists request returns a IAspectBoolean
result to indicate whether the resource exists or not. |
| RQT_NEW | Creates a new resource with a dynamically assigned URI from
a pass-by-value argument in the request with the URI
URRequest.URI_SYSTEM. |
All requests may return IAspectNetKernelException results as exceptions if they fail
for any of these reasons:
- No accessor or transreptor can be found to handle the request.
- An accessor or transreptor cannot find the specified resource.
- An internal error in an accessor or transreptor.
Synchronous or Asynchronous?
Both synchronous and asynchronous requests can be made by an accessor to the scheduler. Asynchronous requests have a lower system overhead but have the disadvantange that code must be written in a more event handler style way to deal with callbacks. Using synchronous requests the calling thread must be blocked until a result is available but it has the advantage that you can write traditional funcional style java code in accessors.
Take a look at some of the shipped accessors to see the difference in styles. The
layer1 accessor org.ten60.netkernel.layer1.accessor.ExistsAccessor is a
good example of using a fully asynchronous model. All of the accessors in the
xml module make use of synchronous requests hidden behind the XAccessor
API.
Special Accessors
The RQT_EXISTS request can be invoked from DPML using the exists accessor.
The RQT_DELETE request can be invoked from DPML using the delete accessor.
|
1060® NetKernelTM Documentation (C) 2003-2004 1060 Research Limited Send Feedback |