NetKernel News Volume 5 Issue 3

We’ve known that the usability of HDS has needed to be improved for a while now. Working on Comb9 with HDS as the primary representation within the app has made me see how much brittle code I needed painstakingly write to manipulate HDS. So there are a few motivations behind this new HDS.

Firstly, and primarily, the aim was to gain support for full XPath. Additionally I wanted to get a mutation interface (not sure - is there an OO pattern name for this?) similar to XDA that we have for XML.

Also it’s been a bugbear for a long time that HDS has a parent reference in the data-structure. This was necessary for navigation but causes big inefficiencies because it is always necessary to clone the whole tree when making modifications.

I have used Apache JXPath to provide XPath support. With a bit of customisation it has provided a seamless implementation of XPath. It is a 300k jar and licensed, obviously, with an Apache2 license. Because of the capabilities of JXPath it has been possible to eliminate the need for the parent reference whilst still being able to perform full XPath including support for .. and ancestor etc axes.

To provide full backward compatibility with existing HDS I have created an IHDSContext and IHDSMutableContext interfaces which can be created by a factory and wrap or import and existing IHDSNode or a new lighter weight IHDS2Node. Also you can create an empty IHDSMutableContext to create a document from scratch.

The IHDSContext interface provides methods to perform queries to gain a single or multiple values and single or multiple nodes in response.

The IHDSMutableContext provides similar methods to XDA such as insertBefore, rename, delete etc but supports the concept of a cursor. This allows a developer to seamlessly use the builder pattern functionality such as pushNode, popNode with macro manipulation operations. When all manipulation is complete you can extract an IHDSNode or IHDS2Node from the context using toHDS() or toHDS2() methods.

Here is some sample code:

IHDSMutableContext b=HDSContextFactory.getNewHDSContext();
b.pushNode("a");
b.pushNode("b").addNode("id", 1).addNode("v", "first").popNode();
b.pushNode("b").addNode("id", 2).addNode("v", "second").popNode();
String v=(String)b.getFirstValue("/a/b[id='2']/v”
b.setCursor(“/a/b[1]”);
b.rename(“c”);
IHDSNode hds=b.toHDS();

Details to download the module and a set of unit tests are provided below. Have a play and let’s discuss.

I don’t plan to release this right away as I need to use it anger to check it really works as well as I hope it will!

<produces>

Purpose

The RESTOverlay can perform dynamic content negotiation in order to locate a target endpoint that satisfies the expressed content requirements of the HTTP client (via the incoming HTTP Accept header).

If the Accept header preference is not matched by any <produces> tags and the RESTOverlay is not in strict mode then the request will be resolved to the first endpoint matching the REST path's simple grammar.

The value of the produces tag must be the mimetype which this endpoint produces.

An endpoint should only produce one mimetype.

Tag Value

A single valued mimetype.

Multiple <produces> tags and @withTransform

If multiple produces tags are specified then the Accept header preferences will be resolved against each of the <produces> mimetypes. The required mimetype resolved during this process is subsequently checked against the mimetype returned in the endpoint's response.

In the event that the endpoint returns a mimetype that differs from the required mimetype then the response will be passed as the operand argument to the service specified by the withTransform attribute on the resolved <produces>.

Example

Say an HTTP request has an Accept header requiring text/html...

HTTP Request:
Accept text/html

and your RESTOverlay metadata for the target endpoint has multiple <produces> tags...

Then the request will be issued to the endpoint but by default it will return a text/xml representation.

The RESTOverlay will detect that the required mimetype is text/html. It will also determine that the <produces> tag that specified text/html has an @withTransform attribute.

To convert the received response to the required mimetype the RESTOverlay will make a request to the service specified by the withTransform attribute and provide the endpoint's response as the operand argument.

In this example it will issue a request for

active:styleMyXMLResponse+operand@response from the endpoint

The withTransform service must be able to transform the mimetype of the endpoint response to the mimetype declared by the matched <produces> tag.

Any number of <produces withTransform=""> tags may be added. The single requirement is that the withTransform service is implemented and has an active grammar that accepts the operand argument with the original response.