forked from skyfoundry/haystack-java
-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathindex.html
199 lines (141 loc) · 6.32 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
<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<grid.numCols(); ++i)
{
HCol col = grid.col(i);
}
// iterate rows
for (int i=0; i<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>