WARNING: This server provides a static reference view of the NetKernel documentation. Links to dynamic content do not work. For the best experience we recommend you install NetKernel and view the documentation in the live system .

Deprecated!

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:

  • Immutable - A tenet of resource oriented computing is that representations are immutable. HDS is completely safe as it does not provide any means to mutate a structure once constructed.
  • Small - HDS is designed to use a minimal amount of memory.
  • Fast - HDS has been optimized for high-performance.
  • Ideal dimensionality - HDS is essentially a 2 1/2 dimensional structure and can function as a list, tree, forest or map. Based on experience this is "just right" for the majority of resources.
  • Future proof - because HDS structures can add branches or dimensions in ways that do not invalidate earlier structures, systems that use HDS find that new versions of tools and services work with earlier versions of resources smoothly.
  • Rich support - Support for HDS includes binary stream parsers and serializers as well as transreptors to and from Strings, XML, etc.

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:

<root>
  <tree-root />
  <tree-root />
</root>

An HDS is a tree structure based on IHDSNode objects which references a String object with the node's name and a Object object representing the node's value. 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 HDSBuilder. 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 org.netkernel.layer0.representation and org.netkernel.layer0.representation.impl

List

An HDS can be used as a list structure by populating only the first level of the forest with nodes.

For example:

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("/*")[3]

Tree

An HDS can be used as a classic tree structure by adding, pushing and popping nodes.

For example:

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

<root>
  <customer>
    <name>General Technology, Inc.</name>
    <address>
      <street>123 Main</street>
      <city>Forestville</city>
      <state>FL</state>
    </address>
  </customer>
</root>

which can be queried using HDS XPath

stateNode = hds.getFirstNode("//state")

Forest

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:

<root>
  <resultset>
    <row>
      <name>Fred</name>
    </row>
    <row>
      <name>Susan</name>
    </row>
  </resultset>
  <resultset>
    <row>
      <state>FL</state>
    </row>
    <row>
      <state>NY</state>
    </row>
  </resultset>
  <resultset>
    <row>
      <course>Math 101</course>
      <grade>A+</grade>
    </row>
    <row>
      <course>Biology 203</course>
      <grade>B-</grade>
    </row>
  </resultset>
</root>

Such a forest can be queried using HDS XPath:

// Get the rows from the second result set
nodelist = hds.getNodes("/resultset[2]/row");

Map

An HDS can be used to model a map, an association of a key with a value.

Comparison with XML

There are several important differences between an HDS and XML:

  • HDS is an in-memory structure based on HDS nodes arranged in a tree structure.
  • HDS always has a structure root node (with name and value set to 'null').
  • Values of an HDS node are Java objects (POJOs) while in XML values are textual.
  • HDS can have tree root nodes (a forest) while XML can have only a single tree root node.
  • Each HDS node has a single value so it cannot support "mixed content"

Special support for XML transreption

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:

  • nodes with names containing colons ":" will be considered as XML elements with name space prefixes
  • nodes with names starting with an at "@" will be considered as XML attributes.
  • nodes with string values starting with "<!--" and ending with "-->" will be considered as XML comments.
  • nodes with string values starting with "<![CDATA[" and ending with "]]>" will be considered as XML comments.