It’s been a while since I wrote about XMPP and XMPP4r. I’m glad because my introductory posts on this topic were very well received. Today I want to push further and share with you a tutorial-like post explaining step by step how to build a simple application with a XMPP interface. The complete listing is also available on bitbucket

The application

I couldn’t find something better than writing a xmpp weather bot. You type the name of a city and the bot answers with the current temperature and forecast information using the Google Weather API. Simple enough for this tutorial.

The gems you’ll need to install

XMPP4r : sudo gem install xmpp4r

json_pure, to convert ruby hashes into json: sudo gem install json_pure

Crack, a xml and json parser: sudo gem install crack

starling, a ruby message queue: sudo gem sources -a http://gems.github.com/ && sudo gem install starling-starling Then, start the starling daemon by typing : sudo starling -d

Why using a message queue like starling?

starling is a message queue library that speaks the memcache protocol. It is my opinion that a message queue is often a very clever and powerful way to establish a direct communication between the various parts of an application or even between different applications. For the sake of this tutorial, I wanted to separate our application into two distinct components and I didn’t want these components to talk to each other via the http protocol.

We won’t install a XMPP server

We won’t go to the pain of installing a XMPP server like ejabberd or openfire because it would be beyond the scope of this article. Instead, we’ll simply use a Google account for our bot

Application architecture

Like I said, I wanted to separate the application into 2 components : The xmpp listener and the backend logic. You probably already guessed that the xmpp listener component job will be to send and receive xmpp stanzas to the user at the other end. To get the weather data, our listener will send the request to the backend component via a starling message queue that we’ll name backend. The backend component will do what is needed to compute the weather data and it will send the result back to the listener component via another starling message queue that we’ll name listener

This setup might be overkill for our simple app but one of my objective was to show you how easy and interesting it can be to work with message queues. Let’s get the ball rolling.

The listener component

create a new file in your code editor and give it the name listener.rb. Here is the complete source code for this file. I will add comments at the bottom of the listing. To copy this code in your clipboard, don’t forget to click on the small “view plain” link at the top or else you will copy the line numbers as well.

[ruby]

require ‘starling’

require ‘json/pure’

require ‘xmpp4r’

require ‘xmpp4r/roster’

require ‘cgi’

class Fleebie

include Jabber

attr_accessor :jid, :password

attr_reader :client, :roster

def initialize

self.jid = ARGV[0]

self.password = ARGV[1]

@client = Client.new(self.jid)

Jabber::debug = true

connect

end

def connect

@client.connect

@client.auth(@password)

@client.send(Presence.new.set_type(:available))

#the "roster" is our bot contact list

@roster = Roster::Helper.new(@client)

#…to accept new subscriptions

start_subscription_callback

#…to do something with the messages we receive

start_message_callback

#When the backend application has done its job, it tells the listener

#via the "listener" message queue.

process_queue

end

private

#Whatever we receive, we send it to our "backend" message queue. It’s

#not our job to parse and decode the actual message

def start_message_callback

@client.add_message_callback do |m|

@starling.set(‘backend’,{:from => m.from, :body => m.body}.to_json)

unless m.composing? || m.body.to_s.strip == ""

end

end

#whenever someone adds the bot to his contact list, it gets here

def start_subscription_callback

@roster.add_subscription_request_callback do |item,pres|

#we accept everyone

@roster.accept_subscription(pres.from)

#Now it’s our turn to send a subscription request

x = Presence.new.set_type(:subscribe).set_to(pres.from)

@client.send(x)

#let’s greet our new user

m=Message::new

m.to = pres.from

m.body = "Welcome! Type a location to get the weather forecast"

@client.send(m)

end

end

#The backend application talks to this XMPP interface via starling.

#in process_queue we process our job list.

def process_queue

@starling = Starling.new(‘127.0.0.1:22122’)

th = Thread.new do

Thread.current.abort_on_exception = true

loop do

item = @starling.get(‘listener’)

unless item.nil?

jitem = JSON.parse(item) rescue nil

msg = Message::new(jitem["from"])

msg.type=:chat

if jitem["success"] == true

msg.body = "

"

msg.body += jitem["message"] + "

"

msg.body += "Current temp: #{jitem["details"]["current_temperature"]}

"

msg.body += "Winds: #{jitem["details"]["winds"]}



"

msg.body += "<b>TODAY</b>

"

msg.body += jitem["details"]["today"]["condition"] + "

"

msg.body += "Min/Max : #{jitem["details"]["today"]["low_f"]} / "

msg.body += jitem["details"]["today"]["high_f"] + " ("

msg.body += jitem["details"]["today"]["low_c"] + " / "

msg.body += jitem["details"]["today"]["high_c"] + ")



"

msg.body += "<b>TOMORROW</b>

"

msg.body += jitem["details"]["tomorrow"]["condition"] + "

"

msg.body += "Min/Max : #{jitem["details"]["tomorrow"]["low_f"]} /"

msg.body += jitem["details"]["tomorrow"]["high_f"] + " ("

msg.body += jitem["details"]["tomorrow"]["low_c"] + " / "

msg.body += jitem["details"]["tomorrow"]["high_c"] + ")

"

msg.add_element(prepare_html(msg.body))

msg.body = msg.body.gsub(/<.*?>/, ”)

else

msg.body = jitem["message"]

end

@client.send(msg)

end

end

end

end

def prepare_html(text)

h = REXML::Element::new("html")

h.add_namespace(‘http://jabber.org/protocol/xhtml-im’)

# The body part with the correct namespace

b = REXML::Element::new("body")

b.add_namespace(‘http://www.w3.org/1999/xhtml’)

# The html itself

t = REXML::Text.new(text.gsub("

","<br />"), false, nil, true, nil, %r/.^/ )

# Add the html text to the body, and the body to the html element

b.add(t)

h.add(b)

h

end

end

Fleebie.new

Thread.stop

[/ruby]

Important parts of this listing

I hope that you will find the code above self explaining. However, here are a few important things about the listing. At line 98-99, we set 2 versions of the same message that will be sent to the XMPP user : one in plain text, the other in XHTML. If the client at the other end has support for XHTML messages, the XHTML version will be displayed, otherwise the plain text version will be used. This is a pretty interesting feature of the XMPP protocol.

The process_queue method

We start a new thread, we subscribe to the ‘listener’ message queue and we process our job list until the program ends or gets interrupted (by typing Ctrl-C for example). You can see that by using a message queue, we move away from the traditional “Request / Response” paradigm. In our case the request (line #44) is “disconnected” from the response (line #103).

Finally, at line #129 we stop the main thread (not the same thread that we started in process_queue). We do this for an obvious reason : we don’t want our script to terminate once it will reach the end of the file. We just ask him to wait until the other threads are done executing.

The backend component

It is here that we will fetch, compute and prepare the actual weather data. For the sake of this tutorial I use the google weather API but it could have been anything else. Create a new file in your code editor and call it backend.rb

require 'starling' require 'crack' require 'net/http' require 'cgi' require 'iconv' require 'json' class Backend def run process_queue end private def process_queue @starling = Starling.new('127.0.0.1:22122') th = Thread.new do Thread.current.abort_on_exception = true loop do item = @starling.get('backend') unless item.nil? jitem = Crack::JSON.parse(item) rescue nil google_api_url = "http://www.google.com/ig/api?weather=#{CGI::escape(jitem["body"])}" ig_weather = Crack::XML.parse(Iconv.conv('UTF-8', 'ISO-8859-1', Net::HTTP.get(URI.parse(google_api_url)) ) ) rescue nil if jitem && ig_weather process_job(jitem,ig_weather) else puts jitem["from"] @starling.set('listener', { :from => jitem["from"], :success => false, :message => "An error occured while accessing Google Weather API. You may try again later" }.to_json) unless jitem.nil? end end end end end def process_job(jitem,ig_weather) if ig_weather["xml_api_reply"]["weather"]["problem_cause"] @starling.set('listener',{ :from => jitem["from"], :success => false, :message => "Data not available. Try being more precise when typing your location (ex. trois-rivières, québec)" }.to_json) else weather = ig_weather["xml_api_reply"]["weather"] data = { :forecast_obj => weather["forecast_conditions"], :city => weather["forecast_information"]["city"]["data"], :winds => weather["current_conditions"]["wind_condition"]["data"], :unit_system => weather["forecast_information"]["unit_system"]["data"], :temp_f => weather["current_conditions"]["temp_f"]["data"], :temp_c => weather["current_conditions"]["temp_c"]["data"], } @starling.set('listener', { :from => jitem["from"], :success => true, :message => "Weather data for #{data[:city]}:", :details => { :current_temperature => "#{data[:temp_f]} ° F / #{data[:temp_c]} ° C", :unit => data[:unit_system], :winds => data[:winds], :today => temperatures( data[:unit_system], data[:forecast_obj][0] ).merge(:condition => data[:forecast_obj][0]["condition"]["data"]), :tomorrow => temperatures( data[:unit_system], data[:forecast_obj][1] ).merge(:condition => data[:forecast_obj][1]["condition"]["data"]) } }.to_json) end end def temperatures(source_unit,obj) x = {} if(source_unit == "US") #we convert to Celcius x["low_c"] = obj["low"]["data"].to_i.to_celcius x["high_c"] = obj["high"]["data"].to_i.to_celcius x["low_f"] = "#{obj["low"]["data"]} ° F" x["high_f"] = "#{obj["high"]["data"]} ° F" else #we convert to farenheit x["low_f"] = obj["low"]["data"].to_i.to_farenheit x["high_f"] = obj["high"]["data"].to_i.to_farenheit x["low_c"] = "#{obj["low"]["data"]} ° C" x["high_c"] = "#{obj["high"]["data"]} ° C" end x end end class Fixnum def to_celcius ((self - 32) / 1.8).round.to_s + " °C" end def to_farenheit (self * 1.8 + 32).round.to_s + " °F" end end Backend.new.run #Always remember to pause the main thread at the end since it does not contain any #blocking call. Thread.stop

This code is not very sexy… It just queries the google api, parse the result, convert temperatures from Farenheit to Celcius or the other way around (because the Google API doesn’t do that by itself) and send back the response to the listener component via the corresponding message queue.

Launch the script

Create a shell script and call it launcher.sh (don’t forget to chmod +x). put the following in it :

#!/bin/bash export RUBYOPT=rubygems d=`dirname $0` ruby $d/backend.rb & ruby $d/listener.rb [email protected] somepassword

Now you can type ./launcher.sh and you should be ready to go. If you encounter a problem while following the tutorial, don’t hesitate to post a comment and I’ll do my best to help you resolve it.