== '''Ariba 0.9.x Series''' ==

The ariba 0.9.x development branch brings great performance and stability improvements at cost of backward compatibility.

It contains optimizations on the binary level, also some prior design descisions have been reconsidered to provide easier, faster and less error-prone interfaces. Therefore the new ariba 0.9.x series is not compatible with prior ariba version; not in terms of network connectivity, also most applications won't compile without some modifications. The latter is especially due the introduction of a new configuration format (using json or xml) and a cleaner interface to startup ariba in the application. Also bluetooth and the bootstrap modules have not been ported to some new internal interfaces, yet and can't be used at the moment.

''Please note that the ariba documentation on this site still refers to the old ariba 0.8.x series. In order to work with the new ariba 0.9.x series, please consider the interface changes presented on this page.''

=== ''' Changelog ''' ===

A brief list of changes between ariba 0.8.x and 0.9.x:

improvements:
    - new message classes (reboost, zero-copy)
    - "fast path" for direct links (skip overlay layer)
    - link-properties accessible from the application
    - System-Queue can call boost::bind functions
    - protlib compatibility removed (32bit overhead saved in every message)
    - addressing2, (a new interface for ip-/bluetooth addresses)
    - Address-Discovery discoveres only addresses on which we're actually listening
    - ariba serialization usage reduced (sill used in OverlayMsg)
    - Node::connect, easier and cleaner interface to start-up ariba from the application
    - ariba configs via JSON, XML, etc (boost::property_tree)
    - keep-alive overhead greatly reduced
    - (relayed) overlay links can actually be closed now
    - lost messages are detected in most cases
    - notification to the application when link is transformed into direct-link
    - overlay routing: send message to second best hop if it would be dropped otherwise
    - Sequence-Numbers (only mechanisms so far: upward compatibility)
    - various small fixes
  
regressions:
    - bluetooth is not yet working again
    - bootstrap modules deactivated
    - liblog4xx is not working (use cout-logging)

== Using ariba 0.9.x ==

To get to code, please check out the latest trunk version from our svn: [https://i72projekte.tm.uka.de/SpoVNet-KA/entwicklung/ariba/trunk Ariba-SVN]

=== ''' Configuration format ''' ===
Ariba 0.9.x uses a new configuration format, based in boost::property_tree. Hence you can use the JSON format to store ariba configs. Other formats (e.g. XML) are supported, too. Please refor to the documentation: [http://www.boost.org/doc/libs/1_46_1/doc/html/property_tree.html Boost.PropertyTree]

'''Example configuration file'''
{{{ 
//JSON
{
    "ariba": {
        "node_name": "Node1",
        "spovnet_name": "pingpong",
        
        "listen_on": [
            {"category": "TCPIP", "addr": "::", "port": 5000 }
        ],
        
        "bootstrap": {
            "direct": [
                {"category": "TCPIP", "addr": "127.0.0.1", "port": 41322 }
            ],
        }
    }
}
}}}

  - As in earlier ariba versions the ''node_name'' and the ''spovnet_name'' can be specified. Please keep in mind that node names must be unique and all nodes must use the same spovnet name in order to communicate.
  - ''listen_on'' describes an array of local addresses, on which ariba will listen.
    - Since bluetooth is currently disabled, `category` must be `TCPIP`
    - `addr` can either be an ipv4 or ipv6 address ("::" is the ipv6 any-address)
    - a port can be specified, if port 0 is given, ariba will try to find a usable port (starting with port 41322)
  - ''bootstrap'' defines the bootstrap hints, the nodes ariba tries to connect in order to join the spovnet
    - Since the bootstrap modules are currently disabled, only direct bootstrapping is available
    - ''direct'' describes an array of remote endpoints ariba tries to connect to (same syntax as the `listen_on` field)

Note that all ariba related config is stored in a field named `ariba`. The same JSON file can be used to store application specific config data as well.

=== ''' Ping-pong example ''' ===
The ping-pong code in the SVN trunk differs from the detailed explanation in the wiki. Especially the new config format (see above) and `Node::connect`, the new easy and clean interface to start-up ariba (see below) is used.

Please note that the ping-pong example still uses the old deprecated ariba messages (see next section "Message formats" for more information).

{{{
#!cpp
void PingPong::startup()
{
    using boost::property_tree::ptree;
    using boost::property_tree::json_parser::read_json;
    
    logging_info( "[PINGPONG]\t starting up PingPong service ... " );

    // read config
    ptree config;
    try
    {
        read_json(config_file, config);
    }
    catch ( exception& e )
    {
        logging_warn("ERROR: Failed to read config file »" << config_file << "«: ");
        logging_warn(e.what());
        logging_warn("---> Using fallback config.");
        
        config.put("ariba.spovnet_name", "pingpong");
    }
    
    // use node name also in the application
    name = config.get("ariba.node_name", "NO_NAME");
    
    // bind communication and node listener
    node.bind( this );                              /*NodeListener*/
    node.bind( this, PingPong::PINGPONG_SERVICEID); /*CommunicationListener*/

    // connecting
    logging_debug( "connecting ... " );

    node.connect(config.get_child("ariba"));

    // ping pong started up...
    logging_info( "[PINGPONG]\t pingpong starting up with"
			<< " [spovnetid " << node.getSpoVNetId().toString() << "]"
			<< " and [nodeid " << node.getNodeId().toString() << "]" );
}
}}}

  - `ptree config;` is an yet empty instance of boost::property_tree::ptree.
  - `read_json(config_file, config);` reads a config file (like the JSON file showed in the previous section) into the ptree instance `config`. The path of the JSON file is stored in `config_file`.
    - If the read fails, the except handler prints a warning and initiates a default config directly within the code via: `config.put("ariba.spovnet_name", "pingpong");`
  - The node variable is defined as attribute: `ariba::Node node;` (initialized with the standard constructor). Thoe follwing registers the callbacks from ariba:
    - `node.bind( this );`
    - `node.bind( this, PingPong::PINGPONG_SERVICEID);`
  - The following command starts ariba with the config stored in the ptree
    - `node.connect(config.get_child("ariba"));`

''' Interfaces '''
  - The callbacks (functions in the application that are called from ariba) are declared in:
    - `ariba/CommunicationListener.h`.
  - The ariba interface (functions in ariba that can be called from the application) are declared in:
    - `ariba/Node.h`.

=== ''' Message formats ''' ===

The ping pong example still uses the old deprecated ariba::message messages with the ariba built-in serialization. For future applications please use the new reboost::message_t messages. Data is stored in high efficient zero-copy buffers of type reboost::shared_buffer_t. These buffers hold plain data, so you have to serialize the data "on your own".

We recommend third-party serialization libraries like:
  - Protocol Buffers (http://en.wikipedia.org/wiki/Protocol_Buffers)
  - Message Pack      (http://en.wikipedia.org/wiki/MessagePack)


''' reboost::message_t '''

The reboost::message_t is an Copy-on-Write Message with Shared Buffers.

A message holds a limited (defined by `message_max_buffers`, typically `8`) number of shared buffers. One can add new buffers and messages in front and at the end of a message. If the no. of buffers exceed `message_max_buffers`, then the two smallest successive buffers are compacted to one buffer.

Typical operations:
  - void message_t::push_back(shared_buffer_t)
  - void message_t::push_front(shared_buffer_t)
  - shared_buffer_t message_t::linearize()
  - size_t message_t::size()

For more information refer to the source code: ariba/utility/transport/messages/message.hpp

''' reboost::shared_buffer_t '''