index.html

<html>
<head>
<title>Haystack Java Toolkit</title>
<style type="text/css">
<!--
body {
  background: #ffffff;
}

h1 {
  color: #000;
  background: #eee;
  border-bottom: 1px solid black;
  padding-left: 5px;
  font-size: 18pt;
}

h1.title {
  color: #144b7a;
  background: none;
  font-size: 24pt;
  border: none;
}

h2 {
  font-size: 16pt;
  padding-left: 0.5em;
  width: 40%;
}

h3, h4, h5, h6
{
  font-size: 14pt;
  padding-left: 0.5em;
}

p {
  padding-left: 10px;
  padding-right: 10px;
}

pre {
  font-family: monospace;
  padding-left: 4em;
  color: #008000;
}

ul { padding-left: 2em; }
ol {   padding-left: 2em; }
li {   margin: 0.3em; }
table { padding-left: 3em; }
-->
</style>
</head>
<body>

<!-- Title Block -->
<h1 class='title'>Haystack Java Toolkit</h1>
<h2 id='overview'>Overview</h2>

<p><a href='http://project-haystack.org/'>Project Haystack</a> defines a tagging model and REST API for sensor systems such as HVAC, lighting, and energy equipment. This toolkit provides a simple, small Java API for working with haystack:</p>

<ul>
<li><strong>Modeling</strong>: APIs for modeling tags values and grids</li>

<li><strong>Formats</strong>: encoding and decoding of grids using Zinc, JSON, CSV, etc</li>

<li><strong>Filter</strong>: Haystack query language AST and parser</li>

<li><strong>Client</strong>: full client side implementation of HTTP REST API</li>

<li><strong>Server</strong>: servlet and server side implementation of HTTP REST API with hooks to glue to specific database</li>
</ul>

<p>All code is written to work with Java 1.4 and J2ME (no use of newer Java features such as generics).  This code is all open sourced under the Academic Free License version 3.0 (same license used as Project Haystack).</p>

<h2 id='vals'>HVal APIs</h2>

<p>The <code>HVal</code> class is the common base class for classes used to model the scalar values of <a href='http://project-haystack.org/doc/TagModel#tagKinds'>tag kinds</a>:</p>

<ul>
<li><code>HMarker</code>: singleton value for marker tag</li>

<li><code>HBool</code>: true/false boolean values</li>

<li><code>HNum</code>: number as 64-bit double with optional unit name</li>

<li><code>HStr</code>: wraps java.lang.String</li>

<li><code>HUri</code>: models a URI as a string value</li>

<li><code>HRef</code>: reference with identifier string and optional display string</li>

<li><code>HDate</code>: date as year, month, day</li>

<li><code>HTime</code>: time as hour, minute, second, milliseconds</li>

<li><code>HDateTime</code>: date time with timezone offset and timezone name</li>

<li><code>HBin</code>: MIME typed binary blob</li>

<li><code>HCoord</code>: geographic coordinate as latitude and longitute</li>
</ul>

<p>All <code>HVal</code> classes are immutable, once created they cannot be modified.</p>

<h2 id='dict'>HDict API</h2>

<p>The <code>HDict</code> class models a set of tag name/value pairs.  The tag names are modeled as <code>String</code> and values as <code>HVal</code>.  The <code>HDict</code> class is immutable, once an instance is created it cannot be modified.  Use <code>HDictBuilder</code> to build an immutable <code>HDict</code> instance:</p>

<pre>// using builder API
HDict tags = new HDictBuilder()
                   .add("dis", "Building A")
                   .add("area", 13500)
                   .add("built", HDate.make(1970,6,3))
                   .add("site")
                   .toDict();</pre>

<p>Once an instance is created, you can query for the tags using the <code>HDict.get</code> method or iterate with <code>HDict.iterator</code> method:</p>

<pre>tags.get("dis")     // evalutes to HStr("Building A")
tags.get("site")    // evaluates to HMarker.VAL
tags.has("site")    // evaluates to true

// iterate all the name/value pairs
for (Iterator it = tags.iterator(); it.hasNext(); )
{
  Map.Entry e = (Map.Entry)it.next();
  String name = (String)e.getKey();
  HVal val    = (HVal)e.getValue();
}</pre>

<h2 id='grid'>HGrid API</h2>

<p>The <code>HGrid</code> class models a <a href='http://project-haystack.org/doc/Grids'>Haystack grid</a>. A grid is composed</p>

<ul>
<li>metadata tags modeled via <code>HDict</code></li>

<li>a set of one or more named columns modeld via <code>HCol</code></li>

<li>zero or more rows modeled by the <code>HRow</code> class which subclasses <code>HDict</code> so you can use it anywhere a <code>HDict</code> is expected.</li>
</ul>

<p>The <code>HGrid</code> class is immutable, once constructed it cannot be modified. Use the <code>HGridBuilder</code> class to construct a grid:</p>

<pre>HGridBuilder b = new HGridBuilder();
b.addCol("id");
b.addCol("dis");
b.addCol("area");
b.addRow(new HVal[] { HRef.make("a"), HStr.make("Alpha"), HNum.make(1200) });
b.addRow(new HVal[] { HRef.make("b"), HStr.make("Beta"),  null });
HGrid grid = b.toGrid();</pre>

<p>Helper methods on <code>HGridBuilder</code> can also be used to construct grids from a <code>HDict</code> or <code>HDict[]</code>.</p>

<p>The following snippets illustrate accessing grid structure:</p>

<pre>// check grid metadata for tag
grid.meta().has("err");

// lookup column by name (checked)
HCol col = grid.col("id");

// iterate columns
for (int i=0; i&lt;grid.numCols(); ++i)
{
  HCol col = grid.col(i);
}

// iterate rows
for (int i=0; i&lt;grid.numRows(); ++i)
{
  HRow row = grid.row(i);
}</pre>

<h2 id='client'>HClient API</h2>

<p>The <code>HClient</code> class is used to communicate over HTTP to a Haystack server via the <a href='http://project-haystack.org/doc/Rest'>REST API</a>.</p>

<pre>// open new client
HClient client = HClient.open("http://localhost/api/demo", "user", "pass");

// query server about info
client.about();

// read all records that have "site" tag
HGrid sites = client.readAll("site");</pre>

<h2 id='server'>HServer API</h2>

<p>The <code>HServer</code> class provides infrastructure to add server side support for the <a href='http://project-haystack.org/doc/Rest'>Haystack REST API</a>.</p>

<p>The <code>HServlet</code> class is designed to plug into a Java servlet namespace. It handles the basic URI routing, decoding, and error handling.</p>

<p>The <code>HStdOps</code> class defines all the <a href='http://project-haystack.org/doc/Ops'>standard operations</a> specified by Haystack.  You can also create your own operations by subclassing <code>HOp</code>.</p>

<p>The <code>HServlet</code> class defines the hooks for gluing the toolkit into your native database.</p>
</body></html>