#Universal Binary Format and JSON-RPC#

Copyright (c) 2011-2012 by Joseph Wayne Norton

Authors: Joseph Wayne Norton ([email protected]).

This is UBF-JSONRPC, a framework for integrating UBF, JSF and JSON-RPC. This repository depends on the UBF and MOCHIWEB (actually only the mochijson2.erl module) open source repositories.

This repository is intended for production deployment and is deployed in carrier-grade systems.

To download, build, and test the ubf_jsonrpc application in one shot, please follow this recipe:

$ mkdir working-directory-name
$ cd working-directory-name
$ git clone https://github.com/ubf/ubf-jsonrpc.git ubf_jsonrpc
$ cd ubf_jsonrpc
$ make deps clean compile test

For an alternative recipe with other "features" albeit more complex, please read further.

This README is a good first step.

The UBF User's Guide is the best next step. Check out http://ubf.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.

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://ubf.github.com/ubf for further details.

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.

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

1. Configure your e-mail and name for Git

   $ git config \--global user.email "[email protected]"
   $ git config \--global user.name "Your Name"

2. Install Repo

   $ mkdir -p ~/bin
   $ wget -O - https://dl-ssl.google.com/dl/googlesource/git-repo/repo > ~/bin/repo
   $ chmod a+x ~/bin/repo

3. Create working directory

   $ mkdir working-directory-name
   $ cd working-directory-name
   $ repo init -u https://github.com/ubf/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 [email protected]:ubf/manifests.git -m ubf-jsonrpc-default-rw.xml".

   Tip	If you want to checkout the latest development version, please append " -b dev" to the repo init command.

4. Download Git repositories

   $ cd working-directory-name
   $ repo sync

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

• Erlang - http://www.erlang.org/

  • R13B04 or newer, R15B02 has been tested most recently

• Git - http://git-scm.com/

  • Git 1.5.4 or newer, Git 1.8.0 has been tested most recently

  • required for Repo and GitHub

• GitHub - https://github.com

• Python - http://www.python.org

  • Python 2.4 or newer, Python 2.7.2 has been tested most recently (CAUTION: Python 3.x might be too new)

  • required for Repo

• Rebar - https://github.com/rebar/rebar/wiki

• Repo - http://source.android.com/source/git-repo.html

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

2. Build

   $ cd working-directory-name
   $ make compile

3. Run the unit tests

   $ cd working-directory-name
   $ make eunit

1. Dialyzer Testing basic recipe

   1. Build Dialyzer's PLT (required once)

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

      Tip	Check Makefile and dialyzer's documentation for further information.

   2. Dialyze with specs

      $ cd working-directory-name
      $ 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.

   3. Dialyze without specs

      $ cd working-directory-name
      $ make dialyze-nospec

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

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.

##Modules##