README

This is ubf-jsonrpc, a framework for integrating UBF, JSF and
JSON-RPC.  This repository depends on the ubf, gmt-util, and mochiweb
open source repositories.


To download
===========

1. Configure your e-mail and name for Git

    $ git config --global user.email "you@example.com"
    $ git config --global user.name "Your Name"

2. Install Repo

    $ mkdir -p ~/bin
    $ wget -O - http://android.git.kernel.org/repo > ~/bin/repo
    $ chmod a+x ~/bin/repo

3. Create working directory

    $ mkdir working-directory-name
    $ cd working-directory-name
    $ repo init -u git://github.com/norton/manifests.git -m ubf-jsonrpc-default.xml

    NOTE: Your "Git" identity is needed during the init step.  Please
    enter the name and email of your GitHub account if you have one.
    Team members having read-write access are recommended to use "repo
    init -u git@github.com:norton/manifests.git -m
    ubf-jsonrpc-default-rw.xml".

    TIP: If you want to checkout the latest development version of UBF
    JSON-RPC, please append " -b dev" to the repo init command.

4. Download Git repositories

    $ cd working-directory-name
    $ repo sync

For futher information and help for related tools, please refer to the
following links:

- Erlang - http://www.erlang.org/
  * *R14B01 has been tested most recently*
  * *R13B01 or newer*
- Git - http://git-scm.com/
  * *Git 1.5.4 or newer*
  * _required for Repo and GitHub_
- GitHub - https://github.com
- Python - http://www.python.org
  * *Python 2.4 or newer (CAUTION: Python 3.x might be too new)*
  * _required for Repo_
- Rebar - https://github.com/basho/rebar/wiki
- Repo - http://source.android.com/source/git-repo.html


To build - basic recipe
=======================

1. Get and install an erlang system
   http://www.erlang.org

2. Build UBF
   $ cd working-directory-name/src
   $ make compile

3. Run the unit tests
   $ cd working-directory-name/src
   $ make eunit


To build - optional features
============================

A. Dialyzer Testing _basic recipe_

   A.1. Build Dialyzer's PLT _(required once)_

   $ cd working-directory-name/src
   $ make build-plt

   TIP: Check Makefile and dialyzer's documentation for further
   information.

   A.2. Dialyze without specs

   $ cd working-directory-name/src
   $ make dialyze

   CAUTION: If you manually run dialyzer with the "-r" option, execute
   "make clean compile" first to avoid finding duplicate beam files
   underneath rebar's .eunit directory.  Check Makefile for further
   information.

   A.3. Dialyze with specs

   $ cd working-directory-name/src
   $ make dialyze-spec


Documentation -- Where should I start?
======================================

This README is a good first step.  Check out and build using the "To
build" instructions above.

The UBF User's Guide is the best next step.  Check out
http://norton.github.com/ubf/ubf-user-guide.en.html for further
detailed information.

Eunit tests can be found in the test/eunit directory.  These
tests illustrate an inets-based httpd module that uses UBF's contract
manager for checking JSON-RPC requests and responses.


What is UBF?
============

UBF is the "Universal Binary Format", designed and implemented by Joe
Armstrong.  UBF is a language for transporting and describing complex
data structures across a network.  It has three components:

   * UBF(A) is a "language neutral" data transport format, roughly
     equivalent to well-formed XML.

   * UBF(B) is a programming language for describing types in UBF(A)
     and protocols between clients and servers.  This layer is
     typically called the "protocol contract".  UBF(B) is roughly
     equivalent to Verified XML, XML-schemas, SOAP and WDSL.

   * UBF(C) is a meta-level protocol used between a UBF client and a
     UBF server.

See http://norton.github.com/ubf for further details.


What is JSF?
============

JSF is an implementation of UBF(B) but does not use UBF(A) for
client<->server communication.  Instead, JSON (RFC 4627) is used.

"JSF" is short for "JavaScript Format".

There is no agreed-upon convention for converting Erlang terms to JSON
objects.  This library uses the convention set forth by MochiWeb's
JSON library (see URL above).  In addition, there are a couple of
other conventions layered on top of MochiWeb's implementation.

   The UBF(B) contract checker has been modified to make a distinction
   between an Erlang record and an arbitrary Erlang tuple.  An
   experience Erlang developer would view such a distinction either
   with skepticism or with approval.

   For the skeptics, the contract author has the option of having the
   UBF(B) contract compiler automatically generate Erlang -record()
   definitions for appropriate tuples within the contract.  Such
   record definitions are very convenient for developers on the Erlang
   side of the world, but they introduce more complication to the
   JavaScript side of the world.  For example, JavaScript does not
   have a concept of an arbitrary atom, as Erlang does.  Also, the
   JavaScript side must make a distinction between {foo, 42} and {bar,
   42} when #foo is a record on the Erlang side but #bar is not.

This extra convention creates something slightly messy-looking, if you
look at the raw JSON passed back-and-forth.  The examples of the
Erlang record {foo, 42} and the general tuple {bar, 42} would look
like this:

   record (defined in the contract as "foo() = #foo{attribute1 = term()};")

      {"$R":"foo", "attribute1":42}

   general tuple

      {"$T":[{"$A":"bar"}, 42]}

However, it requires very little JavaScript code to convert objects
with the "$R", "$T", and "$A" notation (for records, tuples, and
atoms) into whatever object is most convenient.


TIP: Gemini Mobile Technologies, Inc. has implemented a module for
classifying the input character set to detect non-UTF8 JSON inputs.
This module has been released to the open-source world
(http://github.com/norton/gmt-util/blob/master/src/gmt_charset.erl).


What is JSON-RPC?
=================

JSON-RPC is a remote procedure call protocol encoded in JSON.  See
http://json-rpc.org/ for full details.


Credits
=======

Many, many thanks to Joe Armstrong, UBF's designer and original
implementor.

Thanks to MochiWeb.  UBF-JSONRPC relies on the MochiWeb
(i.e. mochijson2.erl) application for encoding and decoding JSON in
erlang.

Gemini Mobile Technologies, Inc. has approved the release of this
repository under an MIT license.