Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Universal Binary Format 2.2
Erlang Java Python Other

This branch is even with master

README.md

Universal Binary Format

Copyright (c) 2011-2015 by Joseph Wayne Norton

Authors: Joseph Wayne Norton (norton@alum.mit.edu).

This is UBF, a framework that permits Erlang and the outside world to talk with each other. This repository is based on Joe Armstrong's original UBF code with an MIT license file added to the distribution. Since then, a large number of enhancements and improvements have been added.

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

Quick Start Recipe

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

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

Documentation

Where should I start?

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.

One of the better places to start is to look in the "doc" directory. See the "Reference Documentation" section for suggestions on where to find greater detail.

The unit tests in the "test/unit" directory provide small examples of how to use all of the public API. In particular, the client.erl files contain comments at the top with a list of prerequisites and small examples, recipe-style, for starting each server and using the client.

The eunit tests in the "test/eunit" directory perform several smoke and error handling uses cases. The stateless_plugin and stateful_plugin test applications are concrete examples on how to integrate one or more UBF listeners into an Erlang/OTP application.

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

What is EBF?

EBF is an implementation of UBF(b) but does not use UBF(a) for client and server communication. Instead, Erlang-style conventions are used instead:

  • Structured terms are serialized via the Erlang BIFs term_to_binary() and binary_to_term().

  • Terms are framed using the gen_tcp {packet, 4} format: a 32-bit unsigned integer (big-endian?) specifies packet length.

    +-------------------------+-------------------------------+
    | Packet length (32 bits) | Packet data (variable length) |
    +-------------------------+-------------------------------+

The name "EBF" is short for "Erlang Binary Format".

What about JSF and JSON-RPC?

See the ubf-jsonrpc open source repository https://github.com/ubf/ubf-jsonrpc for details. ubf-jsonrpc is a framework for integrating UBF, JSF, and JSON-RPC.

What about TBF and Thrift?

See the ubf-thrift open source repository https://github.com/ubf/ubf-thrift for details. ubf-thrift is a framework for integrating UBF, TBF, and Thrift.

What about ABNF?

See the ubf-abnf open source repository https://github.com/ubf/ubf-abnf for details. ubf-abnf is a framework for integrating UBF and ABNF.

What about EEP8?

See the ubf-eep8 open source repository https://github.com/ubf/ubf-eep8 for details. ubf-eep8 is a framework for integrating UBF and EEP8.

Tools

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

What's New in UBF 2.2

  • Added support for 17.0. Removed support for R14.

  • QuickCheck and PropEr related features and tests are unsupported until further notice.

  • Deprecate repo tool.

What's New in UBF 2.1

This section highlights new features and key changes in UBF 2.1. This release of UBF is backwards compatible with UBF 2.0. However, you must recompile UBF and all applications that depend directly on UBF.

  • Added support for R16B. Removed support for R13B04.

  • Fixed issue with UBF listener's shutdown sequence.

  • Improved layout and presentation of the UBF User's Guide.

What's New in UBF 2.0

This section highlights new features and key changes in UBF 2.0. This release of UBF is not backwards compatible with older versions of UBF.

  • The syntax for UBF(b) has been modified to align closer (but not identical) with Erlang's native type and spec declarations defined by EEP8 (http://www.erlang.org/eeps/eep-0008.html). A subset of EEP8 types are now available as UBF(b) builtin types.

  • The UBF(b) builtin types proplist() and string() have been renamed to ubfproplist() and ubfstring(), respectively.

  • An Erlang "header" file corresponding to each UBF(b) contract is automatically created in an application's ebin directory. This file contains Erlang type, spec, and record declarations that can be included by a UBF(b) contract's implementation module or by other Erlang modules.

  • The API and internal implementation of UBF's contract parser, contract manager, contract driver, and contract plugin handler has changed (in some places).

  • For the above Quick Start Recipe, a Makefile has been added to automate and document common recipes. This Makefile is also used for Travis CI (https://travis-ci.org) integration.

Roadmap

Note BERT-RPC is UBF/EBF with a specialized contract and plugin handler implementation for BERT-RPC. UBF/EBF already supports all of the BERT data types. UBF is the text-based wire protocol. EBF is the binary-based wire protocol (based on Erlang's binary serialization format).

Credits

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

Gemini Mobile Technologies, Inc. has approved the release of its extensions, improvements, etc. under an MIT license. Joe Armstrong has also given his blessing to Gemini's license choice.

Modules

contract_driver
contract_lex
contract_manager
contract_manager_tlog
contract_parser
contract_proto
contract_yecc
contracts
contracts_abnf
ebf
ebf_driver
proc_socket_server
proc_utils
qc_ubf
qc_ubf_impl
qc_ubf_types
ubf
ubf_client
ubf_driver
ubf_plugin_handler
ubf_plugin_meta_stateful
ubf_plugin_meta_stateless
ubf_plugin_stateful
ubf_plugin_stateless
ubf_server
ubf_types_builtin
ubf_utils
Something went wrong with that request. Please try again.