WebSocket XMPP Gateway (WXG) - README
=====================================
WXG (pronounce as "Wixig") is a Java-implementation of a gateway enabling communication 
with native XMPP[1] servers over the WebSocket protocol[2] and API[3], as specified in [4].

Until now, one of the common techniques in using XMPP in JS-powered Web applications was 
to make use of BOSH[5] and XMPP over BOSH[6]. However, with the advent of the WebSocket 
protocol and API already widely available in modern Web browsers, the unstable and slow 
BOSH technique should be replaced. Currently, most XMPP servers are not equipped with 
connectors for receiving and delivering stanzas over the WebSocket protocol as specified in [4].

The following scheme shows the basic functionality of WXG:

Client  <---->  ws(xmpp)  <---->  WXG  <---->  xmpp  <---->  XMPP Server

As such, WXG realizes two basic use cases:

1) When a client sends an XMPP stanza encapsulated in a WebSocket message, WXG "unpacks" the 
stanza and forwards it to the XMPP server natively.

2) When an XMPP server directs a stanza to one of its clients, WXG receives the native stanza, 
wraps it into a WebSocket message and forwards it to the client.

In the following we describe how to build, configure, and run WXG.

Prerequisites
=============
- for running WXG, an installed Java Runtime Environment is required.
- for building WXG, an installed Java SDK is required.
- for performing automated builds of WXG, an installation of Apache Ant (http://ant.apache.org/) 
  is required to run the bundled build script.

Check-out and build WXG
=======================

Perform the following steps to build WXG:

1) check out a copy of the git repository from github

	git clone git@github.com:gordin/wxg

2) change to the root directory of the WXG working copy

	cd wxg
	
3) perform an automated build using Apache Ant

	ant

The result of the building process is a JAR file wxg.jar 

Configure WXG
=============

Perform the following steps to configure WXG:

1) change to the conf directory relative to the WXG root directory

	cd ${WXG_HOME}/conf

2) edit the configuration file "server.xml" to your needs

All configurable parameters are documented in the configuration file.
 
Run WXG
=======

Perform the following steps to run WXG:

1) change to the WXG root directory

2) run WXG 

	java -jar wxg.jar
	
Access WXG from client-side
==========================

Open a new WebSocket and point it to ws://${WXG_HOSTNAME}:${WXG_PORT} where ${WXG_HOSTNAME} is the IP address
or the hostname of the interface WXG is bound to and ${WXG_PORT} is the port specified in conf/server.xml.
Keep in mind that according to [4] "xmpp" must be registered as subprotocol in the WebSocket object.
WXG waits until the opening stream tag arrives and then reads the "to" attribute. Three options are available
to define the hostname of the XMPP server to which the stream should be forwared:

1) Pass the desired hostname and port in the WebSocket URL
   Example: ws://localhost:8080/?xmpphost=jabber.com&xmppport=5222

2) Use the aliases db in conf/aliases.conf to rewrite the hostname set in the "to"
   attribute of the opening stream tag

3) Use the hostname set in the "to" attribute of the opening stream tag

The options are applied in the given order.

A simple testbed is available in ${WXG_HOME}/www/testbed.html. It can be accessed by pointing the browser
to http://${WXG_HOSTNAME}:${WXG_PORT}/testbed.html (standard config: http://localhost:8080/testbed.html) 

References
==========
[1] P. Saint-Andre. Extensible Messaging and Presence Protocol (XMPP): Core. RFC3920. Oct 2004. http://www.ietf.org/rfc/rfc3920.txt
[2] I. Fette.  The WebSocket protocol. HyBi Working Group Internet Draft. Jun 2011. http://tools.ietf.org/html/draft-ietf-hybi-thewebsocketprotocol-09
[3] I. Hickson. The WebSocket API. W3C Editor's draft. Jun 2011. http://dev.w3.org/html5/websockets/
[4] J. Moffit, E. Cestari. An XMPP Sub-protocol for WebSocket. HyBi Working Group Internet Draft. Dec 2010. http://tools.ietf.org/html/draft-moffitt-xmpp-over-websocket-00
[5] I. Paterson, D. Smith, P. Saint-Andre, J. Moffitt. XEP-0124: Bidirectional-streams Over Synchronous HTTP (BOSH). XSF Draft Standard. Jul 2010. http://xmpp.org/extensions/xep-0124.html
[6] I. Paterson, P. Saint-Andre. XEP-0206: XMPP Over BOSH. XSF Draft Standard. Jul 2010. http://xmpp.org/extensions/xep-0206.html