adds documentation for long-poll transport

Author: Alexander Goedde

doc/index.rst

@@ -82,7 +82,7 @@ Features
 * supports WAMP v2, works with any WAMP server
 * works both in the browser and Node.js
 * provides asynchronous RPC and PubSub messaging patterns
-* uses WebSocket with a HTTP long-poll fallback
+* uses WebSocket or HTTP long-poll as transport
 * easy to use Promise-based API
 * pluggable promises/deferreds: use `when.js <https://github.com/cujojs/when>`_  (built-in), `jQuery <http://api.jquery.com/category/deferred-object/>`_ , `Dojo <http://dojotoolkit.org/reference-guide/1.7/dojo/Deferred.html>`_ , ECMA Script 6 or others
 * no dependencies

doc/programming.rst

@@ -60,7 +60,7 @@ Connections are handled via an |ab| ``connection`` object, which is created by
       realm: "votesapp"
    });
 
-* WAMP uses WebSocket as its standard transport - so the url uses the ``ws`` **scheme** for WebSocket instead of ``http`` (or ``wss`` for secure WebSocket connections).
+* WAMP uses WebSocket as its standard transport - so the url uses the ``ws`` **scheme** for WebSocket instead of ``http`` (or ``wss`` for secure WebSocket connections). For using alternative transports see the :doc:`reference` for connection options.
 * Since we're running our WAMP router locally, we use localhost (i.e. ``127.0.0.1``) as the **IP**.
 * The **port** (``8080``) and **path** (``/ws``) for the WebSocket endpoint that we're connecting to can be configured in Crossbar.io, the WAMP router we are using. (This allows serving Web assets under different paths on the same IP.)
 * Each connection is connected to a **Realm**. A Realm is a routing namespace and an administrative domain for WAMP. For example, a single WAMP router can manage multiple Realms, and those realms are completely separate: an event published to topic T on a Realm R1 is NOT received by a subscribe to T on Realm R2.

doc/reference.rst

@@ -82,7 +82,7 @@ A new connection is created using
 
    :returns: *object* - autobahn connection object
 
-Example: **Create a new connection**
+Example: **Create a new connection using WebSocket as a transport**
 
 .. code-block:: javascript
 
@@ -91,6 +91,7 @@ Example: **Create a new connection**
                               realm: 'realm1'
                            });
 
+This is the brief syntax which uses the default WebSocket transport and just gives a single connection URL. You can alternatively define a list of transports to try successively - see :ref:`connection-options`.
 
 Connection Methods
 ++++++++++++++++++
@@ -151,15 +152,42 @@ The **connection close callback** is fired when the connection has been closed e
 
 ``details`` is an object containing the ``reason`` and ``message`` passed to :js:func:`autobahn.Connection.close`, and thus does not apply in case of ``"lost"`` or ``"unreachable"``.
 
+
+.. _connection-options:
+
 Connection Options
 ++++++++++++++++++
 
 The constructor of :js:func:`autobahn.Connection` provides various options.
 
 **Required** options:
 
-* ``url``: *string* - the WebSocket URL of the WAMP router to connect to, e.g. ``ws://myserver.com:8080/ws``
 * ``realm``: *string* - The WAMP realm to join, e.g. ``realm1``
+* a target to connect to, for which there are two options:
+
+   * ``url``: *string* - the WebSocket URL of the WAMP router to connect to, e.g. ``ws://myserver.com:8080/ws`` via WebSocket, or
+   * a list of transports to try successively
+
+Supported transports are WebSocket and HTTP long-poll.
+
+As an example, with the options below, |ab| first attempts to establish a WebSocket connection and if this fails a HTTP long-poll connection to the respective URLs given.
+
+.. code-block:: javascript
+   var connection = new autobahn.Connection({
+      transports: [
+         {
+            'type': 'websocket',
+            'url': 'ws://127.0.0.1:9000/ws'
+         },
+         {
+            'type': 'longpoll',
+            'url': 'http://127.0.0.1:9000/lp'
+         }
+      ],
+      realm: 'realm1'
+   });
+
+Not all WAMP routers support all transports, so take a look at the documentation for your router. (The above configuration with both WebSocket and HTTP long-poll on the same port is something which Crossbar.io allows.)
 
 .. note:: We recommend that you use encrypted connections (using TLS). On the client side in |ab|, do this by setting the schema part of the connection URL to ``wss`` instead of ``ws``.