The CAXL Book :: Chapter 1

1.0 Quick Start

Here is the ultra-fast guide to getting started with CAXL:

Download and unzip the zipfile.
Copy jabberwerx.js, jabberwerx.cisco.js, jabberwerx.ui.js, and the resources/ directory to your web server.
In the connectArgs object of each example you use or script that you write, set the httpBindingURL to the BOSH URL for your XMPP server (see Deploying CAXL-Based Applications).
Copy some of the examples to your web server to verify that your installation is working.
Write your own code using CAXL.

1.2 What is CAXL?

This book provides a friendly introduction to the Cisco AJAX XMPP Library (CAXL). CAXL gives you the tools to add presence and real-time messaging to your web applications through JavaScript libraries and user interface components that leverage the XMPP-based features of Cisco WebEx and Cisco Unified Presence.

1.2.1 Design Goals

CAXL was designed with the following goals in mind:

Object-oriented: CAXL follows a strict object-oriented programming model, thus making it easy for you to understand the API and build your own real-time web applications.
XMPP-based: The Extensible Messaging and Presence Protocol (XMPP) is a industry-standard technology for real-time collaboration. Thoughout this book, we reference both IETF RFCs and XSF XEPs that define various aspects of the XMPP protocol stack.
Client-side: XMPP is a client-server technology. CAXL is a library for building applications that function as XMPP clients, where the XMPP server is Cisco WebEx or Cisco Unified Presence (CUP).
BOSH-enabled: XMPP was originally defined to use long-lived TCP sockets. However, the XMPP Standards Foundation has also defined an HTTP long-polling technique called BOSH that is ideal for web applications (see XEP-0124 and XEP-0206). CAXL uses BOSH to enable XMPP functionality in web browsers.
Extensible: XMPP provides an extensible framework for real-time collaboration, and CAXL too contains many extension points.

1.2.2 Modules

CAXL is comprised of four modules:

jQuery: an open-source library for searching, traversing, and manipulating the browser's Document Object Model (DOM); strictly speaking this is a dependency, not a module of CAXL itself.
CAXL Minimal API: a high-level API for sending and receiving XMPP stanzas.
CAXL Core API: a high-level API for messaging and presence.
CAXL UI API: HTML user interface components built on top of the CAXL Core API.

You can use CAXL as an API or as a web UI, or both. Because the CAXL Core API does not depend on the CAXL UI API, you are free to build your own user interfaces. While the internals of the library use jQuery for low-level JavaScript tasks, the UI components have no dependency on any JavaScript UI framework.

1.3 Installing CAXL

1.3.1 Contents

The release version of CAXL is available at http://wikicentral.cisco.com/display/CODEV/JabberWerx+-+Downloads and is distributed as a zipfile. Once you unzip the file, you will see a directory structure like this:


doc/
jabberwerx.cisco.js
jabberwerx.js
jabberwerx.ui.js
resources/
tests/

The doc/ directory contains documentation, including this book and many helpful code examples.

The resources/ directory contains a themes/ subdirectory, which is the home for the default stylesheet and images used by the UI components. The resources/ directory also contains a translations/ subdirectory, which includes code for localization into several languages.

The tests/ directory contains HTML and JavaScript for integration tests, unit tests, and a third-party test automation framework called QUnit.

The .js files comprise the code for CAXL, bundled into three files:

jabberwerx.js contains the code for standard XMPP functionality as defined in the base RFCs and the XMPP Extension Protocols (XEPs) supported by Cisco WebEx and Cisco Unified Presence.
jabberwerx.cisco.js contains code for Cisco-specific (non-standard) XMPP extensions that are used in Cisco WebEx and Cisco Unified Presence.
jabberwerx.ui.js contains code for the user interface components.

Both jabberwerx.js and jabberwerx.ui.js are standalone files that contain everything you need to get started (with the difference that jabberwerx.ui.js includes the UI API whereas jabberwerx.js does not). You will include one or the other of these JavaScript files, but not both. Also note that if you are using Cisco-specific extensions, you need to include jabberwerx.js or jabberwerx.ui.js before you include jabberwerx.cisco.js.

Note: The three .js files in the release version concatenate a large number of individual files from the CAXL source code. They are not built for readability but instead are designed as a compact representation that you can use to create or enhance your own web applications by following the code examples contained in the examples/ subdirectory. For information about obtaining and using the debug version of CAXL, see below.

1.3.2 Configuring Your Development Environment

In order to start working with CAXL, you need to set up a development environment. Specifically, you will need to install a local or network-accessible web server such as Apache and then copy the three .js files and the resources/ directory to your desired location on the web server. You will also need a backend XMPP server and a frontend BOSH service for interfacing between your web application and the XMPP server. Detailed information about configuration is provided under Deploying CAXL-Based Applications below.

1.3.3 Supported Browsers

Before you start developing, make sure that you have one of the following supported browsers:

Windows

Chrome (latest two versions)
Firefox (latest two versions)
Internet Explorer 8 and above

Mac OS X

Chrome (latest two versions)
Firefox (latest two versions)
Safari 4 and above

Linux

Chrome (latest two versions)
Firefox (latest two versions)

1.4 Deploying CAXL-Based Applications

There are two deployment models for CAXL-based applications. One uses Cross-Origin Resource Sharing (CORS), and the other uses a BOSH proxy. The CORS method is recommended, but we provide documentation of the proxy method as a fallback.

1.4.1 CORS

Most CAXL-based applications run in a web browser. However, browsers have strict rules about interacting with web servers, typically referred to as the "same origin policy" (see RFC 6454). Essentially, the browser uses the scheme, host, and port of a URI as the scope of authority, so that https://example.com/ is not the same origin as http://example.com/ or http://secure.example.com/ (and so on). For our purposes, this is important because you will be interfacing with a Cisco-hosted BOSH service (e.g., "https://im1.ciscowebex.com:5280/httpbind") but your web application will be served from a different domain (e.g., "https://webapp.example.com/"). The same-origin policy would prevent you from building a web application that uses a Cisco-hosted BOSH service.

The solution is Cross-Origin Resource Sharing (CORS), a W3C technology for allowing controlled access to client-side cross-origin requests (see http://www.w3.org/TR/cors/ for details). CORS allows you to specify a particular scheme-host-port combination that is authorized for BOSH connectivity, and CAXL provides a facility for doing so using the connectArgs object:


var connectArgs = {
    httpBindingURL: "https://im1.ciscowebex.com/http-bind"
};
client.connect(userJid, password, connectArgs);

You might be wondering how you determine what value to specify for the httpBindingURL. For domains that are deployed in the WebEx cloud, the answer depends on what cluster your domain is assigned to. You can discover this using a few DNS lookups:


$ dig +short srv _xmpp-server._tcp.example.com.
5 0 5269 s2s.example.com.webexconnect.com.

$ dig +short s2s.example.com.webexconnect.com.
s2s.sj2.webex.com.
isj2jxf.webexconnect.com.
global-isj2jxf.webexconnect.com.
173.243.12.79

Those 'dig' commands (you can do the same with 'host' and other tools) help you discover the domain that is delegated to provide server-to-server XMPP connectivity for your source domain; here the source domain is "example.com" and the delegated domain is "s2s.example.com.webexconnect.com". Then you need to discover the exact machines that you would connect to for that delegated domain; here those machines are "s2s.sj2.webex.com." and "isj2jxf.webexconnect.com." and so on, indicating that example.com uses cluster 2 in the WebEx cloud. Thus the httpBindingURL for example.com would be "https://im2.ciscowebex.com/http-bind". If you specify that value in your deployed code, your CAXL-based application will be able to connect to the appropriate cluster for XMPP communication.

[[FIXME: What about connections to Cisco Unified Presence (CUP)?]]

Note: There is a bug in Internet Explorer 8 and 9, such that the URI scheme for your web application needs to be the same as the URI scheme for the CORS domain. Because the WebEx cloud serves BOSH connectivity on HTTPS for strong security, your web application will also need to be served on HTTPS (which is a good idea anyway). This bug will be fixed in Internet Explorer 10.

1.4.2 Proxy

It is also possible to configure a reverse proxy to the BOSH service. Although this is not recommended, we will cover it later in the book.

1.5 Debugging CAXL

1.5.1 Contents

The debug version of CAXL is available at http://wikicentral.cisco.com/display/CODEV/JabberWerx+-+Downloads and is distributed as a zipfile. In practice, we have found that few developers of CAXL-based applications feel the need to use the debug version. However, we make it available so that you can perform more intensive debugging if necessary.

Although the directory structure for the debug version is the same as the release build, you will notice that the primary JavaScript files are approximately three times larger:


  30488 jabberwerx.cisco.js
1042525 jabberwerx.js
 387393 jabberwerx.min.js
1375184 jabberwerx.ui.js

These debug versions are not "minified" as the release versions are, making them much more readable. In addition, they contain code that enables more fine-grained control over debug data. Of special interest is the jabberwerx._config.debug object in the jabberwerx.js and jabberwerx.ui.js files:


    jabberwerx._config.debug = {
    /*DEBUG-BEGIN*/
        streams: {
            rawStanzaLogging: false,
            connectionStatus: false,
            clientStatus: false,
            entityLifeCycle: false,
            stanzaSelectors: false, // a LOT of info ...
            persistence: false,
            observers: false,
            collectionControllers: false 
        },    
    /*DEBUG-END*/
        on: true
    };

You will also notice a number of statements bracketed by the lines /*DEBUG-BEGIN*/ and /*DEBUG-END*/, which actually generate debug data as controlled by the properies of the debug object.

The debug object properties are all boolean and are defined as follows:

clientStatus: If true, provides information about the availability of the client (disconnected, connected, connecting, etc.).
collectionControllers: [Currently unused.]
connectionStatus: [Currently unused.]
entityLifeCycle: [Currently unused.]
observers: [Currently unused.]
persistence: If true, provides information about the persistence status of an object. Mostly used in relation to persistent storage associated with the namespace `_js_store__`.
rawStanzaLogging: If true, provides all of the XML elements exchanged over the stream. Currently used only for inbound XML (see the _handleElementsReceived method). Note that enabling this property can produce a large amount of data.
stanzaSelectors: If true, provides data about jQuery selector strings that are run against XML stanzas. Currently used only in relation to the selectNodes method. Note that enabling this property can produce a large amount of data.

Naturally, enabling debug output not only can produce large amounts of data but also can slow performance. We encourage you to run the debug release only in test environments and not in production.

The CAXL Book :: Chapter 1 - Introduction