HJsonWriter support for new JSON encoding, add HNA

Author: briansfrank

index.fandoc

@@ -13,7 +13,7 @@ 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:
 
  - **Modeling**: APIs for modeling tags values and grids
- - **Formats**: encoding and decoding of grids using Zinc, CSV, etc
+ - **Formats**: encoding and decoding of grids using Zinc, JSON, CSV, etc
  - **Filter**: Haystack query language AST and parser
  - **Client**: full client side implementation of HTTP REST API
  - **Server**: servlet and server side implementation of HTTP REST API
@@ -38,6 +38,7 @@ the scalar values of [tag kinds]`http://project-haystack.org/doc/TagModel#tagKin
  - 'HTime': time as hour, minute, second, milliseconds
  - 'HDateTime': date time with timezone offset and timezone name
  - 'HBin': MIME typed binary blob
+ - 'HCoord': geographic coordinate as latitude and longitute
 
 All 'HVal' classes are immutable, once created they cannot be modified.
 

index.html

@@ -56,14 +56,14 @@
 
 <!-- Title Block -->
 <h1 class='title'>Haystack Java Toolkit</h1>
-<h2 id='overview'>Overview </h2>
+<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, CSV, etc</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>
 
@@ -74,7 +74,7 @@ <h2 id='overview'>Overview </h2>
 
 <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>
+<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>
 
@@ -98,11 +98,13 @@ <h2 id='vals'>HVal APIs </h2>
 <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>
+<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>
 
@@ -128,7 +130,7 @@ <h2 id='dict'>HDict API </h2>
   HVal val    = (HVal)e.getValue();
 }</pre>
 
-<h2 id='grid'>HGrid API </h2>
+<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>
 
@@ -172,7 +174,7 @@ <h2 id='grid'>HGrid API </h2>
   HRow row = grid.row(i);
 }</pre>
 
-<h2 id='client'>HClient API </h2>
+<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>
 
@@ -185,7 +187,7 @@ <h2 id='client'>HClient API </h2>
 // read all records that have "site" tag
 HGrid sites = client.readAll("site");</pre>
 
-<h2 id='server'>HServer API </h2>
+<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>
 

src/org/projecthaystack/HBin.java

@@ -38,19 +38,33 @@ public boolean equals(Object that)
     return this.mime.equals(((HBin)that).mime);
   }
 
+  /** Encode as "b:<mime>" */
+  public String toJson()
+  {
+    StringBuffer s = new StringBuffer();
+    s.append("b:");
+    encodeMime(s);
+    return s.toString();
+  }
+
   /** Encode as "Bin(<mime>)" */
   public String toZinc()
   {
     StringBuffer s = new StringBuffer();
     s.append("Bin(");
+    encodeMime(s);
+    s.append(')');
+    return s.toString();
+  }
+
+  private void encodeMime(StringBuffer s)
+  {
     for (int i=0; i<mime.length(); ++i)
     {
       int c = mime.charAt(i);
       if (c > 127 || c == ')') throw new IllegalArgumentException("Invalid mime, char='" + (char)c + "'");
       s.append((char)c);
     }
-    s.append(')');
-    return s.toString();
   }
 
 }

src/org/projecthaystack/HBool.java

@@ -38,6 +38,9 @@ public class HBool extends HVal
   /** Encode as "true" or "false" */
   public String toString() { return val ? "true" : "false"; }
 
+  /** Raise UnsupportedOperationException */
+  public String toJson() { throw new UnsupportedOperationException(); }
+
   /** Encode as "T" or "F" */
   public String toZinc() { return val ? "T" : "F"; }
 

src/org/projecthaystack/HCoord.java

@@ -87,6 +87,17 @@ public boolean equals(Object that)
     return ulat == x.ulat && ulng == x.ulng;
   }
 
+  /** Return "c:lat,lng" */
+  public String toJson()
+  {
+    StringBuffer s = new StringBuffer();
+    s.append("c:");
+    uToStr(s, ulat);
+    s.append(',');
+    uToStr(s, ulng);
+    return s.toString();
+  }
+
   /** Represented as "C(lat,lng)" */
   public String toZinc()
   {

src/org/projecthaystack/HDate.java

@@ -91,16 +91,25 @@ public int compareTo(Object that)
   /** Day of month as 1-31 */
   public final int day;
 
+  /** Encode as "d:YYYY-MM-DD" */
+  public String toJson()
+  {
+    StringBuffer s = new StringBuffer();
+    s.append("d:");
+    encode(s);
+    return s.toString();
+  }
+
   /** Encode as "YYYY-MM-DD" */
   public String toZinc()
   {
     StringBuffer s = new StringBuffer();
-    toZinc(s);
+    encode(s);
     return s.toString();
   }
 
   /** Package private implementation shared with HDateTime */
-  void toZinc(StringBuffer s)
+  void encode(StringBuffer s)
   {
     s.append(year).append('-');
     if (month < 10) s.append('0'); s.append(month).append('-');
@@ -178,4 +187,4 @@ public int weekday()
   private static final int daysInMon[]     = { -1, 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31 };
   private static final int daysInMonLeap[] = { -1, 31, 29, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31 };
 
-}
+}

src/org/projecthaystack/HDateTime.java

@@ -79,8 +79,8 @@ public static HDateTime make(long millis, HTimeZone tz)
     return ts;
   }
 
-  /** Parse from string fomat "YYYY-MM-DD'T'hh:mm:ss.FFFz zzzz" 
-    * or raise ParseException 
+  /** Parse from string fomat "YYYY-MM-DD'T'hh:mm:ss.FFFz zzzz"
+    * or raise ParseException
     */
   public static HDateTime make(String s)
   {
@@ -162,13 +162,28 @@ public int compareTo(Object that)
     return 0;
   }
 
+  /** Encode as "t:YYYY-MM-DD'T'hh:mm:ss.FFFz zzzz" */
+  public String toJson()
+  {
+    StringBuffer s = new StringBuffer();
+    s.append("t:");
+    encode(s);
+    return s.toString();
+  }
+
   /** Encode as "YYYY-MM-DD'T'hh:mm:ss.FFFz zzzz" */
   public String toZinc()
   {
     StringBuffer s = new StringBuffer();
-    date.toZinc(s);
+    encode(s);
+    return s.toString();
+  }
+
+  private void encode(StringBuffer s)
+  {
+    date.encode(s);
     s.append('T');
-    time.toZinc(s);
+    time.encode(s);
     if (tzOffset == 0) s.append('Z');
     else
     {
@@ -181,9 +196,8 @@ public String toZinc()
       if (zm < 10) s.append('0'); s.append(zm);
     }
     s.append(' ').append(tz);
-    return s.toString();
   }
 
   private static final TimeZone utc = TimeZone.getTimeZone("Etc/UTC");
 
-}
+}

src/org/projecthaystack/HMarker.java

@@ -28,6 +28,9 @@ private HMarker() {}
   /** Encode as "marker" */
   public String toString() { return "marker"; }
 
+  /** Encode as "m:" */
+  public String toJson() { return "m:"; }
+
   /** Encode as "M" */
   public String toZinc() { return "M"; }
 

src/org/projecthaystack/HNA.java

@@ -0,0 +1,37 @@
+//
+// Copyright (c) 2015, Brian Frank
+// Licensed under the Academic Free License version 3.0
+//
+// History:
+//   09 Jun 2015  Brian Frank  Creation
+//
+package org.projecthaystack;
+
+/**
+ * HNA is the singleton value used to indicate not available.
+ *
+ * @see <a href='http://project-haystack.org/doc/TagModel#tagKinds'>Project Haystack</a>
+ */
+public class HNA extends HVal
+{
+  /** Singleton value */
+  public static final HNA VAL = new HNA();
+
+  private HNA() {}
+
+  /** Hash code */
+  public int hashCode() { return 0x6e61; }
+
+  /** Equals is based on reference */
+  public boolean equals(Object that) { return this == that; }
+
+  /** Encode as "na" */
+  public String toString() { return "na"; }
+
+  /** Encode as "z:" */
+  public String toJson() { return "z:"; }
+
+  /** Encode as "NA" */
+  public String toZinc() { return "NA"; }
+
+}

src/org/projecthaystack/HNum.java

@@ -112,16 +112,31 @@ public int compareTo(Object that)
     return 1;
   }
 
+  /** Encode as "n:<float> [unit]" */
+  public String toJson()
+  {
+    StringBuffer s = new StringBuffer();
+    s.append("n:");
+    encode(s, true);
+    return s.toString();
+  }
+
   /** Encode as floating value followed by optional unit string */
   public String toZinc()
   {
     StringBuffer s = new StringBuffer();
+    encode(s, false);
+    return s.toString();
+  }
+
+  private void encode(StringBuffer s, boolean spaceBeforeUnit)
+  {
     if (val == Double.POSITIVE_INFINITY) s.append("INF");
     else if (val == Double.NEGATIVE_INFINITY) s.append("-INF");
     else if (Double.isNaN(val)) s.append("NaN");
     else
     {
-      // don't let fractions
+      // don't encode huge set of decimals if over 1.0
       double abs = val; if (abs < 0) abs = -abs;
       if (abs > 1.0)
         s.append(new DecimalFormat("#0.####", new DecimalFormatSymbols(Locale.ENGLISH)).format(val));
@@ -130,11 +145,11 @@ public String toZinc()
 
       if (unit != null)
       {
+        if (spaceBeforeUnit) s.append(' ');
         for (int i=0; i<unit.length(); ++i)
           s.append(unit.charAt(i));
       }
     }
-    return s.toString();
   }
 
   /**

src/org/projecthaystack/HRef.java

@@ -59,7 +59,16 @@ public String dis()
   /** Encode as "@id" */
   public String toCode() { return "@" + val; }
 
-  /** Encode as "@id <dis>" */
+  /** Encode as "r:<id> [dis]" */
+  public String toJson()
+  {
+    StringBuffer s = new StringBuffer();
+    s.append("r:").append(val);
+    if (dis != null) s.append(' ').append(dis);
+    return s.toString();
+  }
+
+  /** Encode as "@<id> [dis]" */
   public String toZinc()
   {
     StringBuffer s = new StringBuffer();

src/org/projecthaystack/HRemove.java

@@ -28,6 +28,9 @@ private HRemove() {}
   /** Encode as "remove" */
   public String toString() { return "remove"; }
 
+  /** Encode as "x:" */
+  public String toJson() { return "x:"; }
+
   /** Encode as "R" */
   public String toZinc() { return "R"; }
 

src/org/projecthaystack/HStr.java

@@ -49,6 +49,12 @@ public String toString()
     return val;
   }
 
+  /** Encode as "s:" if string contains a colon */
+  public String toJson()
+  {
+    return val.indexOf(':') < 0 ? val : "s:"+val;
+  }
+
   /** Encode using double quotes and back slash escapes */
   public String toZinc()
   {