This documentation relates to an old version of HDS that is now deprecated in favour of [[doc:mod:hds:title|HDS2]]. By the virtue of [[doc:glossary:transreptor|transreptors]] existing functionality using HDS will continue to operate and inter-operate with newer functionality.
The Hierarchical Data Structure (HDS) is a high-performance, in-memory, immutable data structure that unifies list, tree, forest and map models into one physical structure.
The need for, and the design of, HDS was heavily influenced by experience with resource models in earlier versions of NetKernel. HDS is ideal as the physical level representation for many resources because it has the following characteristics:
HDS is the de-facto physical model used internally for resource representation in NetKernel 4 and should be considered for any new resource representation needs
Because an HDS is based on an expanded tree structure closely related to XML, XML can be used to visually illustrate the contents of an HDS. For example, a simple HDS with two trees, each with only tree root elements would be:
An HDS is a tree structure based on
objects which references a
String object with the node's
name and a
Object object representing the
A node may also reference one or more child nodes and a single parent node.
Because an HDS is immutable it must be created by an instance of
To create an HDS, first create a builder, then use its methods
to direct the construction of an HDS and
finally, when construction is complete, ask the builder to return
the completed immutable HDS.
HDS is provided by layer0 of NetKernel and is available
by importing the packages
An HDS can be used as a list structure by populating only the first level of the forest with nodes.
builder = new HDSBuilder() builder.addNode(null,"List Item 1") builder.addNode(null,"List Item 2") builder.addNode(null,"List Item 3") builder.addNode(null,"List Item 4") builder.addNode(null,"List Item 5") builder.addNode(null,"List Item 6") hds = builder.getRoot() // Retrieve the value of the 4th item from the list String value = hds.getValues("/*")
An HDS can be used as a classic tree structure by adding, pushing and popping nodes.
builder = new HDSBuilder() builder.pushNode("customer") builder.pushNode("name", "General Technology, Inc.") builder.pushNode("address") builder.addNode("street", "123 Main") builder.addNode("city", "Forestville") builder.addNode("state","FL") hds = builder.getRoot()
creates the following structure
which can be queried using HDS XPath
stateNode = hds.getFirstNode("//state")
An HDS can be used to model a forest, a collection of trees, by adding, pushing and popping nodes.
For example, the RDBMS access module returns an HDS that could contain a forest of result sets. The structure returned by a stored procedure call could be:
Such a forest can be queried using HDS XPath:
// Get the rows from the second result set nodelist = hds.getNodes("/resultset/row");
An HDS can be used to model a map, an association of a key with a value.
There are several important differences between an HDS and XML:
Bi-direction transreption support with XML is provided in Layer1. Several conventions on the naming of nodes in HDS enable support for XML namespaces and XML attributes: