1. Jason Briggs Avatar Jason Briggs
  2. Untitled project
  3. haystack-cpp

Wiki

Clone wiki

haystack-cpp / Home

View History

Welcome to Haystack-CPP

Welcome, this page will give you an overview of Haystack-CPP

About

Haystack-CPP (hystack-cpp) is an implementation of the Haystack protocol project-haystack.org/ in C++. The project implements the scalar and complex Haystack types, serialization to and from Zinc text format, unit tests for the these and a reference HTTP Client and Server implementation.

The design follows the reference Haystack Java Toolkit implementation closely so you can easily cross reference concepts from the Java implementation. The reference implementation can be found here: haystack-java

PDF doc available here https://bitbucket.org/jasondbriggs/haystack-cpp/wiki/refman.pdf

HTML doc available here https://bitbucket.org/jasondbriggs/haystack-cpp/wiki/browse/html

Architecture overview

In order to better understand the concepts that are referenced from here on, please refer to the Project Haystack documentation project-haystack.org/doc

Data types

The fundamental data types in Haystack are:

  • Marker: the tag is merely a marker annotation and has no meaningful value. Marker tags are used to indicate a "type" or "is-a" relationship.
  • Bool: boolean "true" or "false".
  • Number: integer or floating point number annotated with an optional unit of measurement.
  • Str: a string of Unicode characters.
  • Uri: a Unversial Resource Identifier.
  • Ref: reference to another entity. Haystack doesn't prescribe a specific identity or reference mechanism, but they should be some way to cross link entities. Also see Containment. We format refs with a leading "@" and require a specific subset of ASCII characters be used: a-z, A-Z, 0-9, underbar, colon, dash, dot, or tilde.
  • Bin: a binary blob with a MIME type formatted as Bin(text/plain)
  • Date: an ISO 8601 date as year, month, day: 2011-06-07.
  • Time: an ISO 8601 time as hour, minute, seconds: 09:51:27.354.

  • DateTime: an ISO 8601 timestamp followed by timezone name:

    2011-06-07T09:51:27-04:00 New_York

    2012-09-29T14:56:18.277Z UTC

  • Coord: geographic coordinate in latitude/longitude formatted as C(lat,lng)

See TagModel

Haystack also defines these complex types:

  • Dict: a list of name: value pairs.
  • Grid: a list of Dicts.

Algorithms

Haystack uses the concept of Filter for applying expression on a Dict or Grid. These Filters form a simple query language that are decoupled from the underlying storage that a vendor might choose. Please refer to Filters

Encodind

Haystack is encoding agnostic, there is built in support for Zinc, Json and Csv formats.

Haystack-CPP includes a ZincEncoder and a ZincDecoder implementation for working with Grids.

Usually the encoding/decoding used while performing IO operations should be automatic. The reference HTTP REST API uses the HTTP headers Content-type and Accept for negotiating the exchange formats.

Input Output

Even though Haystack doesn't define a network transport layer and, thus implementers are free to use any protocol they see fit, most implementation will probably use the HTTP REST API to talk to a Haystack Server. See Rest

The REST API input comes from GET query parameters or from a POST Grid parameter. The output of any operation with the REST API is a Grid.

Errors occurred when performing a REST operation should be encoded as an error Grid.

Implementation

Talk about Haystack-CPP's project structure, build tools, unit tests, code organization and relationships, reference implementation HTTP Client and Server.

Project structure

haystack-cpp is hosted on bitbutcket haystack-cpp

Clone it from git@bitbucket.org:jasondbriggs/haystack-cpp.git

Here's the structure

haystack-cpp (root folder)

  • include (core haystack header files)
  • src (core haystack implementation)
  • tests (unit tests project)
  • http_client (a reference HTTP client project)
  • http_server (a reference HTTP REST server project)

Object hierarchies

Haystack-cpp models the basic data types inside the haystack name space.

The basic types are:

  • Marker
  • Bool
  • Num
  • Str
  • Uri
  • Ref
  • Bin
  • Date
  • Time
  • DateTime
  • Coord

All these types are polymorphic and derived from the base haystack type Val

Here is a simple diagram of the inheritance inheritance diagram

The utility classes:

  • DateTimeRange
  • TimeZone
  • HisItem
  • Filter

For working with Grids there are these types:

  • Dict
  • Grid
  • Col
  • Row

Serialization/de-serialization types:

  • GridReader
  • GridWriter
  • ZincReader
  • ZincWriter

IO types:

  • Proj
  • Server
  • Op
  • Watch

Please consult the project Docs for more details.

Dependencies

For core haystack-cpp and unit tests (tests) projects

tests project requires CATCH, which is included in the tests/include/ext/catch folder.

A modern C++ compiler is required (gcc 4.4+, visual studio 10+) to build the projects.

For http_client and http_server you'll also need Poco 1.4+

The Cmake scripts will automatically detect the required BOOST and POCO version for you. If the minimum requirements are met, then you'll get the build files generated for each project.

Building

haystack-cpp uses Cmake for build configuration. The minimum tested version is Cmake 2.8

For building the core haystack-cpp project as a static lib and for building the tests project on Windows using Visual Studio:

  • Download BOOST.
  • Unzip the BOOST archive.
  • Set the Env variable BOOST_ROOT to the location of the unzipped boost folder
  • Use cmake gui and point source code to the root haystack-cpp folder and binaries to haystack-cpp\vs folder.
  • Click Configure and select your desired configuration, click Generate
  • If config was done then the haystack-cpp\vs folder should contain a Visual Studio Haystack-cpp.sln file
  • Open the Haystack-cpp.sln file and build the solution

Running the unit tests and the client - server apps

A successful build should generate binaries under haystack-cpp\vs\bin\{Debug|Release} folder. For starters you should run the test_app.exe to run the unit-tests. Expect all to pass.

If POCO library was detect the Haystack-cpp.sln should contain http_server and http_client projects that upon a successful build should generate http_server.exe respectively http_client.exe under haystack-cpp\vs\bin\{Debug|Release} folder.

Runn http_server.exe to activate the Haystack HTTP REST API reference service. By default the server runs on port 8085, so make sure your firewall accepts it.

You can test the service by pointing your browser at http://localhost:8085/about that should return a Grid with details about the server and protocol.

The reference server implementation also exposes an endpoint that requires authentication, you can test it by opening this url: http://localhost:8085/auth. The default username is demo with the password demo.

Run http_client.exe to test the reference Haystack HTTP REST API client. The client requires a haystack server to run on http://localhost:8085/ so make sure the http_client.exe is running before you execute the client. When running, the client invokes some Ops using the Haystack HTTP REST API and displays their result in the console.

Updated