Xenqtt Project Wiki Page

Update

We have moved to GitHub! While the repository here will continue to contain versions up to 0.9.6 of XenQTT as well as source code as of 02/12/2015 all future updates will be managed through GitHub.

Find us here: https://github.com/Jorgamundus/xenqtt

Project Overview

Xenqtt provides disparate features and services that help facilitate communication via the MQTT protocol. MQTT is a lightweight and simple protocol most often used by devices and services communicating in an M2M (machine-to-machine) or IoT (internet-of-things) architecture. Xenqtt helps clients work in this dynamic ecosystem by providing the following:

• A fully-featured MQTT client that operates in blocking and non-blocking modes
• An MQTT gateway that translates HTTP messages into MQTT and vice-versa
• An MQTT proxy that allows a farm of servers to act as a single MQTT client

The following sections provide more information on each of these Xenqtt features. Included in these sections are detailed overviews, code examples, and frequently asked questions with the related answers.

Xenqtt Features

Client

Xenqtt ships with a fully-featured MQTT client. This client gives users the ability to interact with an MQTT broker in two modes:

• Blocking (synchronous)
• Non-blocking (asynchronous)

The blocking client, as its name implies, will block on all client-originated MQTT operations. These include:

• Connecting
• Publishing data to a topic (this includes all relevant ACKs pursuant to the chosen QoS level)
• Subscribing for data from a topic
• Disconnecting

The non-blocking client will not block on any of the aforementioned operations, handling all of them in the background. Callbacks are employed at various points in the MQTT lifecycle that allow the user to take specific actions as-appropriate.

The following sections provide a detailed overview, along with code samples, for both the blocking and non-blocking clients.

Gateway

The HTTP Gateway is a Xenqtt feature that allows clients to send HTTP messages to an MQTT broker. It works by translating the HTTP message into an MQTT message and publishing it to the broker. Similarly clients can subscribe to messages over HTTP and, as messages are received by the gateway from chosen topics, get those messages published to a subscription back as HTTP messages.

Proxy

The proxy allows 1..n MQTT clients to act as a single client to the broker. This is extraordinarily useful in clustered environments where a farm of servers is used to process work due to scaling needs but the work must only be done on a single server. The proxy manages all client connections and uses the client ID to determine which group a particular client belongs to. Connections, subscriptions, and disconnections are only done once per-cluster. Messages received for subscriptions are routed to just one client with the proxy acting as a load balancer for the cluster.

Monitoring and Metrics

Logging

Xenqtt provides logging services and integration with log4j. If the application that uses the client contains log4j Xenqtt will attempt to integrate with the extant log4j configuration and use log4j as its logging source. Should log4j not be provided or if Xenqtt is run as a stand-alone JAR then Java Utility Logging (JUL) is used instead.

JUL

In the absence of log4j Xenqtt uses JUL to log events of interest and note to a log file. The specific details around JUL logging, when it is used, are as follows:

• All log events are written to a file called xenqtt.log.0
• Log files are rolled after they exceed 5 MB
• Log files are stored in the directory running the xenqtt.jar file

This page is a work-in-progress. Over time it will evolve into a more useful and informative document.