The Declarative Request Syntax is used by many NetKernel technologies. They can also be incorporated for use programmatically in your custom endpoints and overlays. The usual pattern is that a configuration document contains one or more request declarations that your endpoint will want to call under certain circumstances.
The first step is to construct an instance of a builder, this will parse the request definition and validate it's syntax. It is best to do this only once and keep a reference to the builder:
org.w3c.dom.Element requestDefn; org.netkernel.container.ILogger logger=aContext.getKernelContext().getKernel().getLogger() RequestBuilder builder = new RequestBuilder( requestDefn, logger );
When you want to issue a sub-request based on the declarative request:
INKFRequest subRequest=builder.buildRequest(context, null, null); context.issueRequest(subRequest);
It is common for an endpoint to want to make special values available to be passed as arguments to sub-requests. You can do this with declarative requests using the RequestBuilder.Arguments class passed as the second argument to the buildRequest method. An example of this is the Pluggable Overlay making arg:request and arg:response available.
RequestBuilder.Arguments arguments = new RequestBuilder.Arguments(); arguments.addArgument("arg:arg1", "http://1060research.com" ); arguments.addArgumentByValue( "arg:arg2", new Integer(1060) ); INKFRequest subRequest=builder.buildRequest(context, arguments, null);
If the declarative request syntax specifies a representation class it may to supply a classloader instance to the buildRequest method so that classes can be located and loaded. The third argument to buildRequest is an optional classloader instance. If null the kernel classloader will be used to locate classes, this will limit classes to those defined in the core NetKernel libraries (layer0, standard module, kernel) and those defined in the JRE.
Usually you will want to use the classloader from your application module, this can be obtained like this:
ClassLoader classloader=this.getSpace().getClassLoader(); INKFRequest subRequest=builder.buildRequest(context, arguments, classloader);