Mikeh at 03:02, 16 September 2006

2006-09-16T03:02:30Z

New page

=Using Messages and Presence=
 Now that we have a decent grounding in the
Jabber protocol and technology, let's put it to work for us. This
chapter fits Jabber into solutions for two or three common problems and
shows how the technology and features lend themselves very well to
application-to-person (A2P) scenarios.

By way of introduction, we'll have a look at constructing and sending
simple Jabber messages, to effect an "in-your-face" notification
mechanism for a version control system. We'll also introduce a usage of
the <tt><presence/></tt> element as an availability indicator for
connecting systems. Finally we'll combine the two features
(<tt><message/></tt> and the concept of ''availability'') to make
the notification mechanism "sensitive" to the presence of the person
being notified.

 

== CVS Notification via Jabber ==
 CVS—the Concurrent Versions
System—allows you to comfortably create and manage versions of the
sources of your project. The most common use for CVS is to create and
manage versions of program source code, but it can be readily used for
any text files. For example, this book was written using DocBook SGML
(http://www.docbook.org), and a CVS ''repository'' was used to manage
different versions of the manuscript throughout the writing and editing
process. CVS allowed us to maintain the original source files for the
chapters, to compare those versions against edited files, and served as
a place from which older versions could be retrieved. You can find out
more about CVS at http://www.cvshome.org.

That's the "Versions System" part of CVS's name. The "Concurrent" part
means that this facility is given an extra dimension in the form of
group collaboration. With CVS, more than one person can share work on a
project, and the various chunks of work carried out by each participant
are coordinated—automatically, to a large extent—by CVS. Multiple
changes by different people to the same file can be merged by CVS; any
unresolvable conflicts (which may for example arise when more than one
person changes exactly the same line of source code) are flagged and
must be resolved by the participants involved.

The general idea is that you can create a project containing files and
directories and have it stored centrally in a CVS repository. Depending
on what sort of access is granted to this repository, other project
participants can pull down a copy of the project—those files and
directories—and work on it independently. In this way, each
participant's work is isolated (in time and space) from the others. When
the work is done, the work can be sent back to the repository and the
changes will be merged into the central copy. After that, those merged
changes are available to the rest of the participants.

 

=== CVS Watches and Notification ===
 While CVS automatically handles
most of the tedious merging process that comes about when more than one
person works on a project, it also offers a facility that allows you to
set a "watch" on one or more files in the project and be alerted when
someone else starts to work on those watched files. This is useful if
you wish to preempt any automatic merging process by contacting the
other participant and coordinating your editing efforts with him.

There are two CVS commands involved in setting up watches and
notifications. There are also a couple of CVS administrative files that
determine how the notifications are carried out. Let's look at these
commands and files in turn.

 

==== CVS commands ====
 The CVS commands cvs watch and cvs notify are
used, usually in combination, by project participants to set up the
notification mechanism:

; cvs watch on|off
: Assuming we have a CVS-controlled project called ''proj1'' and we're
: currently inside a local checked-out copy of the project's files, we
: first use cvs watch to tell CVS to watch a file ("turn a watch
: ''on''") that we're interested in, which is file4 in this example: :
<code>yak:~/projects/proj1$ <tt>cvs watch on file4</tt></code>
: This causes CVS to mark file4 as "watched," which means any time a
: project participant checks out the file from the central repository,
: the checked-out working copy is created with read-only attributes.
: This means the participant is (initially) prevented from saving any
: changes to that working copy. It is, in effect, a reminder to that
: participant to use the CVS command cvs edit, specifying file4, before
: commencing the edit session. Using cvs edit causes CVS to: # Remove
: the read-only attribute for the file
# Send out notifications (to those who have requested them with the cvs
# watch add) that the participant has commenced editing it

; cvs watch add|remove
: While running cvs watch on against a file will set a marker causing
: the file to be replicated with the read-only attribute when checked
: out (which has the effect of "suggesting" to the participant editing
: the file that he use the cvs edit command to signal that he's to
: start editing), the actual determination of the notification
: recipients is set up using the cvs watch add command. : Running the
: command: :
<code>yak:~/projects/proj1$ <tt>cvs watch add file4</tt></code>
: will arrange for the CVS notification to be sent to ''us'' when
: someone else signals their intention (via cvs edit) to edit file4.
 
==== CVS administrative files ====
 A number of administrative files used
to control how CVS works are kept in the central CVS repository. Two of
these files, notify and users, are used to manage the watch-based
notification process:

; notify
: The standard notify file contains a line like this: :
<code> ALL mail %s -s "CVS notification" </code>
: The <tt>ALL</tt> causes the formula described here to be used for any
: notification requirements (an alternative to <tt>ALL</tt> is a
: regular expression to match the directory name in which the edit
: causing the notification is being carried out). : The rest of the line
: is the formula to use to send the notification. It is a simple
: invocation of the mail command, specifying a subject line (<tt>-s
: "CVS notification"</tt>). The <tt>%s</tt> is a placeholder that CVS
: replaces with the address of the notification's intended recipient.
: The actual notification text, generated by CVS, is piped into the mail
: command via STDIN.
; users
: The users file contains a list of notification recipient addresses: :
<code> dj:dj.adams@pobox.com piers:pxharding@ompa.net
robert:robert@shiels.com ...</code>
: This is a mapping from the user IDs (<tt>dj</tt>, <tt>piers</tt>, and
: <tt>robert</tt>) of the CVS participants, local to the host where the
: CVS repository is stored, to the addresses (''dj.adams@pobox.com'',
: ''pxharding@ompa.net'',and ''robert@shiels.com'') that are used to
: replace the <tt>%s</tt> in the formula described in the notify file.

==== The notification ==== If the contents of the notify and users files
have been set up correctly, a typical notification, set up by DJ using
the cvs watch on file4 and cvs watch add file4 commands, and triggered
by Piers using the cvs edit file4 command, will be received in DJ's
inbox looking like the one shown in Example 8-1.

''A typical email CVS notification''

<code> Date: Fri, 8 Jun 2001 13:10:55 +0100 From: piers@ompa.net To:
dj.adams@pobox.com Subject: CVS notification

testproject file4 --- Triggered edit watch on
/usr/local/cvsroot/testproject By piers</code>
 

=== CVS Notifications via Jabber ===
 While email-based notifications are
useful, we can add value to this process by using a more immediate (and
penetrating) form of communication: Jabber. Although mail clients can be
configured to check for mail automatically on a regular basis, using an
IM-style client has a number of immediately obvious advantages:

* It's likely to take up less screen real estate. * No amount of
tweaking of the mail client's autocheck frequency (which, if available,
will log in, check for, and ''pull'' emails from the mail server) will
match the immediacy of IM-style message ''push''. * In extreme cases,
the higher the autocheck frequency of the mail client, the higher the
effect on overall system performance. * Depending on the configuration,
an incoming Jabber message can be made to pop up, with greater effect. *
A Jabber user is more likely to have a Jabber client running permanently
than an email client. * It's more fun! The design of CVS's notification
mechanism is simple and abstract enough for us to put an alternative
notification system in place. If we substitute the formula in the notify
configuration file with something that will call a Jabber script, we
might end up with something like:

<code> ALL python cvsmsg %s </code>

Like the previous formula, it will be invoked by CVS to send the
notification, and the <tt>%s</tt> will be substituted by the recipient's
address determined from the users file. In this case, the Python script
''cvsmsg'' is called. However, now that we're sending a notification
via Jabber, we need a Jabber address—a JID—instead of an email address.
No problem, just edit the users file to reflect the new addresses.
Example 8-2 shows what the users file might contain if we were to use
JIDs instead of email addresses.

''Matching users to JIDs in the notify file''

<code> dj:dj@gnu.pipetree.com piers:piers@jabber.org
robert:shiels@jabber.org</code>

As Jabber user JIDs in their most basic form (i.e., without a
''resource'' suffix) resemble email IDs, there doesn't appear to be that
much difference. In any case, CVS doesn't really care, and it takes the
portion following the colon separator and simply passes it to the
formula in the notify file.
 

=== The cvsmsg Script ===
 Let's now have a look at the script, called
''cvsmsg''. It has to send a notification message, which it receives on
STDIN, to a JID, which it receives as an argument passed to the script,
as shown in Example 8-3.

''The cvsmsg Python script''

<code>import jabber import sys

Server = 'gnu.pipetree.com' Username = 'cvsmsg' Password = 'secret'
Resource = 'cvsmsg'

cvsuser = sys.argv[1] message = ''

for line in sys.stdin.readlines(): message = message + line

con = jabber.Client(host=Server)

try: con.connect() except IOError, e: print "Couldn't connect: %s" % e
sys.exit(0)

con.auth(Username,Password,Resource) con.send(jabber.Message(cvsuser,
message, subject="CVS Watch Alarm")) con.disconnect()

</code>

It's not that long but worth breaking down to examine piece by piece.

We're going to use the <tt>Jabberpy</tt> Python library for Jabber, so
the first thing we do in the script is import it. We also import the
<tt>sys</tt> module for reading from STDIN:

<code>import jabber import sys

</code>

As the usage of the script will be fairly static, we can get away here
with hardcoding a few parameters:

<code>Server = 'gnu.pipetree.com' Username = 'cvsmsg' Password =
'secret' Resource = 'cvsmsg'

</code>

Specified here are the connection and authentication details for the
<tt>cvsmsg</tt> script itself. If it's to send a message via Jabber, it
must itself connect to Jabber. The <tt>Server</tt> variable specifies
which Jabber server to connect to, and the <tt>Username</tt>,
<tt>Password</tt>, and <tt>Resource</tt> variables contain the rest of
the information for the script's own JID
(<tt>cvsmsg@gnu.pipetree.com/cvsmsg</tt>) and password.

<code>cvsuser = sys.argv[1] message = ''

for line in sys.stdin.readlines(): message = message + line

</code>

The <tt>sys.argv[1]</tt> refers to the notification recipient's JID,
which will be specified by the CVS notification mechanism, as it is
substituted for the <tt>%s</tt> in the notify file's formula. This is
saved in the <tt>cvsuser</tt> variable. We then build up the content of
our message body we're going to send via Jabber by reading what's
available on STDIN. Typically this will look like what we saw in the
email message body in Example 8-1:

<code>testproject file4 --- Triggered edit watch on
/usr/local/cvsroot/testproject By piers
</code>

<code>con = jabber.Client(host=Server)

</code>

Another <tt>Jabberpy</tt> module, <tt>xmlstream</tt>, handles the
connection to the Jabber server. We don't have to use that module
explicitly, however; the <tt>jabber</tt> module wraps and uses it,
shielding us from the details—hence the call to instantiate a new
<tt>jabber.Client</tt> object into <tt>con</tt>, to lay the way for our
connection to the host specified in our <tt>Server</tt> variable:
<tt>gnu.pipetree.com</tt>. If no port is explicitly specified, the
standard port (5222), on which the <tt>c2s</tt> service listens, is
assumed.

The instantiation causes a number of parameters and variables to be
initialized, and internally an <tt>xmlstream.Client</tt> object is
instantiated; various parameters are passed through from the
<tt>jabber.Client</tt> object (for example, for logging and debugging
purposes), and an XML parser object is instantiated. This will be used
to parse fragments of XML that come in over the XML stream.

<code>try: con.connect() except IOError, e: print "Couldn't connect:
%s" % e sys.exit(0)

</code>

A connection is attempted with the <tt>connect()</tt> method of the
connection object in <tt>con</tt>. This is serviced by the
<tt>xmlstream.Client</tt> object and an XML stream header, as described
in Section 5.3, is sent to <tt>gnu.pipetree.com:5222</tt> in an attempt
to establish a client connection. An <tt>IOError</tt> exception is
raised if the connection cannot be established; we trap this, after a
fashion, with the <tt>try: ... except</tt> as shown.

Once connected (meaning the client has successfully exchanged XML stream
headers with the server) we need to authenticate:

<code>con.auth(Username,Password,Resource)
</code>

The <tt>auth</tt> method of the <tt>jabber.Client</tt> object provides
us with a simple way of carrying out the authentication negotiation,
qualified with the <tt>jabber:iq:auth</tt> namespace and described in
detail in Section 7.3. Although we supply our password here in the
script in plaintext (<tt>secret</tt>), the <tt>auth</tt> method will use
the IQ-get (<tt><iq type='get'...></tt>) to retrieve a list of
authentication methods supported by the server. It will try to use the
most secure, "gracefully degrading" to the least, until it finds one
that is supported. This is shown in Figure 8-1.

[[image:jab_0801.png|Graceful degradation in authentication|center|350 px]]
 </code> Note the presence of
<tt>Resource</tt> in the call. This is required for a successful client
authentication regardless of the authentication method. Sending an
IQ-set (<tt><iq type='set'...></tt>) in the
<tt>jabber:iq:auth</tt> namespace without specifying a value in a
<tt><resource/></tt> tag results in a "Not Acceptable" error 406;
see Table 5-3 for a list of standard error codes and texts.

We're connected and authenticated. "The world is now our lobster," as an
old friend used to say. We're not necessarily ''expecting'' to receive
anything at this stage, and even if we did, we wouldn't really want to
do anything with what we received anyway. So we don't bother setting up
any mechanism for handling elements that might appear on the stream.

<code>con.send(jabber.Message(cvsuser, message, subject="CVS Watch
Alarm"))
</code>

The next step is to send the notification message (in <tt>message</tt>)
to the user (in <tt>cvsuser</tt>). There are actually two calls here.
The innermost call, <tt>jabber.Message()</tt>, creates a simple message
element that looks like this:

<code><message to='[value in cvsuser variable]'>
<subject>CVS Watch Alarm</subject> <body>[value in
message variable]</body> </message>
</code>

It takes two positional (and required) parameters; any other information
to be passed (such as the <tt>subject</tt> in this example) must be
supplied as ''key=value'' pairs. The outermost call,
<tt>con.send()</tt>, sends whatever it is given over the XML stream that
the <tt>jabber.Client</tt> object <tt>con</tt> represents. In the case
of the <tt>jabber.Message</tt> call, this is the string representation
of the object so created (i.e., the <tt><message/></tt> element).

Once the notification message has been sent, the script's work is done.
We can therefore disconnect from the server before exiting the script:

<code>con.disconnect()
</code>

Calling the <tt>disconnect()</tt> method of the <tt>jabber.Client</tt>
sends an ''unavailable'' presence element to the server on behalf of
the user who is connected:

<code><presence type='unavailable'/>
</code>

This is sent regardless of whether a <tt><presence/></tt> element
was sent during the conversation but does no harm if one wasn't.

After sending the unavailable presence information, the XML stream is
closed by sending the stream's closing tag:

<code></stream:stream>
</code>

This signifes to the server that the client wishes to end the
conversation. Finally, the socket is closed.

 

== Dialup System Watch ==
 These days, it's becoming increasingly common
to have a server at home with a dialup connection to the Internet. Your
data, your latest developments, and your mail are stored on there. This
works really well when you're telecommuting and pulling those late night
hacking sessions at home; you have access to all your information and
can connect to the Net.

For many people, however, the reality is that it's not just at home
where the work gets done. Consultants, freelancers, and people with many
customers have their work cut out for them in traveling to different
sites to complete jobs. One of the biggest issues in this respect,
especially in Europe where dialup and pay-per-minute connections still
outweigh fixed or flat-rate connections, is the accessibility of the
information on the server at home, sitting behind a modem. In a lot of
cases, the expense of leaving the server dialed up for the duration of
the trip is far too great to be justified.

One solution is to have the server dial up and connect to the Internet
at regular intervals, say, every hour or two, and remain connected for
5 or 10 minutes. If you need access to the information or need to log on
to your server and run a few tests, you can hold the connection open,
once you've connected to it, by running a ping, for example.

The problem here, though, is timing. Due to the inevitable
synchronization problems between wristwatch and PC clock, eddies in the
space-time continuum, and the fact that people simply forget to check
the time, the online window of the server's dialup is often missed.

The essence of this problem is a ''presence'' thing. We need to know
about the presence, the availability, of our server at home, with
respect to the Internet.

Using Jabber as your IM mechanism at work, it's likely that you'll have
a Jabber client of some sort on your laptop or desktop at the customer
sites. Whether it's WinJab on Windows, Jarl in Command Line Interface
(CLI) mode on a remote server over an SSH connection, or any other type
of Jabber client and connection, the point is that the client turns out
to be an ideal ready-made component for solving the dialup timing
problem. Here's how it works:

* Get the server to dial up and connect to the Internet regularly. * On
connection, start a script that sends Jabber presence to you. * On
disconnection, get the script to end. If you add to your roster a JID
that represents the server at home, it would be possible to subscribe to
the server's presence and know when it was available—connected to the
Internet—and when it wasn't.

The script we're going to write to send Jabber presence is called
''HostAlive''.

 

=== Making Preparations for Execution ===
 Before diving into the script,
it's necessary to do a bit of preparation. We're going to be using the
''presence subscription'' concept, which was described in Chapter 5 and
is covered in more detail in the next section in this chapter. We're
also going to have to get the script to run, and stay running, when the
dialup connection is made and have it stop when the dialup connection is
ended.

 

==== Presence ====
 Rather than get involved in the nitty-gritty of
presence subcriptions right now, let's use the tools that are around us
to get things set up. In order for this to work, we need to be
subscribed to the presence of the script that will be invoked when the
server dials up and connects to the Internet. The script will connect to
the Jabber server using a JID with a username that represents the Linux
server: ''myserver@gnu.pipetree.com''. My JID in this case is
''dj@gnu.pipetree.com'', so we just use whatever Jabber client happens
to be at hand, say, Jabber Instant Messenger (JIM), to effect both sides
of the subscription.

; Step 1: Create JID myserver@gnu.pipetree.com
: We need to create the script's JID if it doesn't already exist. We can
: use the reguser script we wrote in Section 7.4 to do this: :
<code> [dj@yak dj]$ <tt>./reguser gnu.pipetree.com username=myserver
password=secret</tt> [Attempt] (myserver) Successful registration
[dj@yak dj]$ </code>

; Step 2: Subscribe to myserver's presence
: We start JIM with the JID ''dj@gnu.pipetree.com'' and then add
: ''myserver@gnu.pipetree.com'' to the roster. This should automatically
: send a presence subscription request to the JID. Adding the JID to the
: roster using JIM is shown in Figure 8-2.
; Step 3: Accept presence subscription as myserver
: Using the JIM client, we reconnect with the ''myserver'' JID and
: accept the presence subscription request from Step 2, so that
: ''dj@gnu.pipetree.com'' will automatically receive
: ''myserver@gnu.pipetree.com'''s availability information. Whether or
: not ''myserver'' subscribes to ''dj'''s presence is irrelevant in this
: case, as the script itself is not interested in the availability of
: anyone at all.
[[image:jab_0802.png|Adding myserver@gnu.pipetree.com to the
roster|center|350 px]]
</code> At this stage, the entry in
''dj@gnu.pipetree.com'''s roster that represents the Linux server will
indicate whether the script run at dialup time is active. If we continue
to use the JIM client, we will see that active status is shown by a
yellow bulb and inactive by no icon at all.

 

==== Starting and stopping the script ====
 The dialup connection is set
up using the Point-to-Point Protocol daemon pppd. This uses a program
such as chat to talk to the modem and get it to dial the ISP. The pppd
mechanism affords us an ideal way to start and stop a script on the
respective connection and disconnection of the line. When the
connection has been made, the script /etc/ppp/ip-up is invoked and
passed a number of connection-related parameters. Similarly
/etc/ppp/ip-down is invoked when the connection is closed.

Some implementations of pppd also offer /etc/ppp/ip-up.local and
/etc/ppp/ip-down.local, which should be used in place of the ip-up and
ip-down scripts if they exist. These <tt>.local</tt> versions are
intended to separate out system-specific connection-related activities
from general connection-related activities, in a similar way to how the
rc.local file allows system-specific startup activities to be defined in
the /etc/rc.d/ Unix System V set of runlevel directories.

So what we want to do is start ''HostAlive'' with
<tt>ip-up[.local]</tt> and stop it with <tt>ip-down[.local]</tt>. What
these starter and stopper scripts might look like is shown in Example
8-4 and Example 8-5. They are simply shell scripts that share the
process ID (PID) of the Jabber script via a temporary file. The starter
starts the Jabber script and writes the PID of that script to a file.
The stopper kills the script using the PID.

''An ip-up starter script''

<code>#!/bin/sh

# Change to working directory
cd /jabber/java/

# Call the Jabber script and put to background
/usr/java/jdk1.3.1/bin/java -classpath jabberbeans.jar:. HostAlive $5
/&

# Write the running script's PID
echo $! > /tmp/HostAlive.pid
</code>

''An ip-down stopper script''

<code>#!/bin/sh

# Simply kill the process using the JID written by the starter script
/bin/kill `cat /tmp/HostAlive.pid`

# Remove the PID file
/bin/rm /tmp/HostAlive.pid

</code>

Example 8-4 shows that we're passing through one of the parameters that
pppd gives to the ''ip-up'' script: the remote IP address—by which the
server is known during its temporary connection to the Internet—in the
<tt>$5</tt> variable.<ref>The parameters that are passed from pppd to
the ''ip-up'' script are: ''interface-name'', ''tty-device'',
''speed'', ''local-link-local-address'', ''remote-link-local-address'',
and ''ipparam''. It's the ''remote-link-local-address'' that we're
interested in here. </ref> This IP address can be passed along as part
of the availability information in the <tt><presence/></tt>
element, so that the recipient (''dj'') can see what IP address has been
assigned to the server.

 

=== The HostAlive Script ===
 As you might have guessed from looking at
Example 8-4, we're going to write ''HostAlive'' in Java, shown in
Example 8-6. We'll use the <tt>JabberBeans</tt> library; see Section P.4
in the Preface for details of where to get this library and what the
requirements are.

''The HostAlive script, written in Java''

<code>import org.jabber.jabberbeans.*; import
org.jabber.jabberbeans.Extension.*; import java.net.InetAddress;

public class HostAlive { public static final String SERVER =
"gnu.pipetree.com"; public static final String USER = "myserver";
public static final String PASSWORD = "secret"; public static final
String RESOURCE = "alive";

public static void main(String argv[]) {

ConnectionBean cb=new ConnectionBean();

InetAddress addr;

try { cb.connect(addr=InetAddress.getByName(SERVER));
}
catch (java.net.UnknownHostException e) {
//from getByName()
System.out.println("Cannot resolve " + SERVER + ":" +
e.toString()); return;
}
catch (java.io.IOException e) {
//from connect()
System.out.println("Cannot connect to " + SERVER); return;
}

InfoQueryBuilder iqb=new InfoQueryBuilder(); InfoQuery iq;
IQAuthBuilder iqAuthb=new IQAuthBuilder();

iqb.setType("set");

iqAuthb.setUsername(USER); iqAuthb.setPassword(PASSWORD);
iqAuthb.setResource(RESOURCE);

try { iqb.addExtension(iqAuthb.build());
}
catch (InstantiationException e) {
//building failed ?
System.out.println("Fatal Error on Auth object build:");
System.out.println(e.toString()); System.exit(0);
}

try {
//build the full InfoQuery packet
iq=(InfoQuery)iqb.build();
}
catch (InstantiationException e) {
//building failed ?
System.out.println("Fatal Error on IQ object build:");
System.out.println(e.toString()); return;
}

cb.send(iq);

PresenceBuilder pb=new PresenceBuilder(); pb.setStatus(argv[0]);

try { cb.send(pb.build());
}
catch (InstantiationException e) { System.out.println("Fatal Error
on Presence object build:"); System.out.println(e.toString());
return;
}

while (true) { try { Thread.sleep(9999);
}
catch (InterruptedException e) { System.out.println("timeout!");
}
}

</code>

 
=== Step by Step ===
 We'll examine the script a chunk at a time. We
start by importing the libraries (the classes) we would like to use:

<code>import org.jabber.jabberbeans.*; import
org.jabber.jabberbeans.Extension.*; import java.net.InetAddress;

</code>

The <tt>JabberBeans</tt> library is highly modular and designed so we
can pick only the features that we need; in this case, however, we're
just going to import the whole set of classes within the
<tt>org.jabber.jabberbeans</tt> and
<tt>org.jabber.jabberbeans.Extension</tt> packages, for simplicity.

We're also going to be manipulating the Jabber server's hostname, so we
pull in the <tt>InetAddress</tt> class for convenience.

The script must connect to the Jabber server on ''gnu.pipetree.com'' as
the ''myserver'' user. We define some constants for this:

<code>public class HostAlive { public static final String SERVER =
"gnu.pipetree.com"; public static final String USER = "myserver";
public static final String PASSWORD = "secret"; public static final
String RESOURCE = "alive";

</code>

In the same way as with the Python-based CVS notification script earlier
in this chapter, we also start off by building a connection to the
Jabber server. As before, it's a two-stage process. The first stage is
to create the connection object:

<code> public static void main(String argv[]) {

ConnectionBean cb=new ConnectionBean();

</code>

A <tt>ConnectionBean</tt> object represents the connection between the
script and the Jabber server. All XML fragments (Jabber elements) pass
through this object.

Then it's time to attempt the socket connection and the exchange of XML
stream headers:

<code> InetAddress addr;

try { cb.connect(addr=InetAddress.getByName(SERVER));
}
catch (java.net.UnknownHostException e) {
//from getByName()
System.out.println("Cannot resolve " + SERVER + ":" +
e.toString()); return;
}
catch (java.io.IOException e) {
//from connect()
System.out.println("Cannot connect to " + SERVER); return;
}

</code>

We create an Internet address object in <tt>addr</tt> from the hostname
assigned to the <tt>SERVER</tt> constant. As the creation of the
<tt>addr</tt> instance may throw an exception (''Unknown Host''), we
combine the instantiation with the <tt>connection()</tt> call on the
<tt>ConnectionBean</tt> object, which may also throw an exception of its
own—if there is a problem connecting.

At this stage, we're connected and have successfully exchanged the XML
stream headers with the Jabber server. So now we must authenticate:

<code> InfoQueryBuilder iqb=new InfoQueryBuilder(); InfoQuery iq;
IQAuthBuilder iqAuthb=new IQAuthBuilder();

iqb.setType("set");

iqAuthb.setUsername(USER); iqAuthb.setPassword(PASSWORD);
iqAuthb.setResource(RESOURCE);

try { iqb.addExtension(iqAuthb.build());
}
catch (InstantiationException e) {
//building failed ?
System.out.println("Fatal Error on Auth object build:");
System.out.println(e.toString()); System.exit(0);
}

try {
//build the full InfoQuery packet
iq=(InfoQuery)iqb.build();
}
catch (InstantiationException e) {
//building failed ?
System.out.println("Fatal Error on IQ object build:");
System.out.println(e.toString()); return;
}

cb.send(iq);

</code>

Yes, that's an awful lot. Let's take it bit by bit.

Figure 8-3 shows how the objects in this section of code interrelate
and represent various parts of what we're trying to do—which is to
construct an authorization packet. This takes the form of an IQ-set
containing a <tt><query/></tt> tag qualified by the
<tt>jabber:iq:auth</tt> namespace like this:<ref>We're not bothering in
this example to ask the server for the authentication methods it
supports and are just going ahead with a plaintext attempt. </ref>

<code><iq type='set'> <query xmlns='jabber:iq:auth'>
<username>myserver</username>
<password>secret</password>
<resource>alive</resource> </query> </iq>
</code>

Constructing Jabber elements with the <tt>JabberBeans</tt> library uses
so-called ''builders'' that allow individual element components to be
created separately and then fused together into a final structure. In
the code, we use two builders: an <tt>InfoQueryBuilder</tt> to construct
the <tt><iq/></tt> envelope and an <tt>IQAuthBuilder</tt> to
construct the <tt><query/></tt> content.

Taking the code step by step, we create or declare each of the three
things, <tt>iqb</tt>, <tt>iq</tt>, and <tt>iqAuthb</tt>:

<code> InfoQueryBuilder iqb=new InfoQueryBuilder(); InfoQuery iq;
IQAuthBuilder iqAuthb=new IQAuthBuilder();
</code>

; <tt>iqb</tt>
: This is the builder object with which we can build
: <tt><iq/></tt> elements.
; <tt>iq</tt>
: This is the <tt><iq/></tt> element that we're going to build.
; <tt>iqAuthb</tt>
: This is another builder object with which we can build IQ extensions
: (<tt><query/></tt> tags) qualified by the
: <tt>jabber:iq:auth</tt> namespace. The process of creating the
: authorization packet is detailed in Figure 8-3.

[[image:jab_0803.png|Creating the authorization packet|center|350 px]]</code> There are numbered steps in
Figure 8-3; these follow what happens in the rest of the authentication
preparation:

; Step 1: Set the type attribute of the IQ
: We call the <tt>setType()</tt> method on the <tt>iqb</tt> object that
: represents the outer IQ envelope to set the value of the <tt>type</tt>
: attribute: :
<code> iqb.setType("set");

</code>

; Step 2: Set the values for the parts of the authorization section of
the element
: Having constructed the <tt>iqAuthb</tt> object, which represents the
: <tt><query/></tt> portion of the element, we fill the values
: with these calls: :
<code> iqAuthb.setUsername(USER); iqAuthb.setPassword(PASSWORD);
iqAuthb.setResource(RESOURCE);

</code>

; Steps 3a and 3b: Generate iqAuthb and add it to the iqb object
: Once the values inside the authorization <tt><query/></tt> tag
: are set, we can call the <tt>build()</tt> method on the object
: representing that tag in <tt>iqAuthb</tt> to generate an extension
: object (in other words, to ''assemble'' the tag) that can then be
: attached to the <tt>iqb</tt> object using the <tt>addExtension()</tt>
: method: :
<code> try { iqb.addExtension(iqAuthb.build());
}
...

</code>

; Step 4: Generate iqb and assign it to the IQ object
: In the same way that we generated the authorization
: <tt><query/></tt> tag, we can generate the whole element and
: assign it to <tt>iq</tt>: :
<code> try {
//build the full InfoQuery packet
iq=(InfoQuery)iqb.build();
}
...

</code>
Once we've constructed the authorization element, now held as the
<tt>iq</tt> object, we can send it down the stream to the Jabber server
with the <tt>send()</tt> method of the <tt>ConnectionBean</tt> object
<tt>cb</tt>:

<code> cb.send(iq);

</code>

Finally, once we've authenticated, we can construct the presence packet
and send it using the same technique as before.<ref>We're assuming the
password is correct here, to keep this example straightforward. If it
isn't correct, there's not much we can do at this point anyway. </ref>

We construct a new object to represent the presence packet denoting
general availability—<tt><presence/></tt>:

<code> PresenceBuilder pb=new PresenceBuilder();

</code>

In this case, there are no namespace-qualified extensions to add to the
<tt><presence/></tt> element, but we do want to add the IP
address that was passed into the script and available in
<tt>argv[0]</tt>. We can use the <tt>setStatus()</tt> method on the
presence object to set the optional <tt><status/></tt> to contain
that IP address:

<code> pb.setStatus(argv[0]);

</code>

After this, we can go ahead and generate the element, which will look
like this:

<code><presence> <status>123.45.67.89</status>
</presence>
</code>

After the generation with the <tt>build()</tt> call, we send it down the
stream in the same way as the authorization <tt><iq/></tt>
element:

<code> try { cb.send(pb.build());
}
catch (InstantiationException e) { System.out.println("Fatal Error
on Presence object build:"); System.out.println(e.toString());
return;
}

</code>

As for each of the <tt>build()</tt> calls, we must trap a possible
exception that <tt>build()</tt> throws if it can't complete (for
example, due to lack of information). This is the
<tt>InstantiationException</tt>.

We can see the results of ''myserver'' sending such an information-laden
<tt><presence/></tt> element to ''dj'' in Figure 8-4. As the
server connects to the Internet, the Java script is started via the
''ip-up'' script, and it relays the assigned IP address, which is shown
in Jarl's status bar as the availability information reaches ''dj'''s
client.

[[image:jab_0804.png|myserver becoming available and relaying its IP address|center|350 px]]
 </code> All that remains for the script
to do now is to hang around. While the XML stream to the Jabber server
remains, and the connection is not broken, its availability will remain
as it was as described by the simple <tt><presence/></tt> element
we sent. So we simply go into a sort of hibernation. We have no hope of
escaping, but it should be taken care of by the ''ip-down'' script as
described earlier.

<code> while (true) { try { Thread.sleep(9999);
}
catch (InterruptedException e) { System.out.println("timeout!");
}
}

</code>

In fact, when the ''ip-down'' script kills the script, the socket
connection will be closed, but there was no clean disconnect—no
<tt><presence type='unavailable'/></tt> was sent by the script to
the Jabber server. In this case, the Jabber server will notice that the
socket was closed and generate an unavailable
<tt><presence/></tt> element on behalf of the client.

 

== Presence-Sensitive CVS Notification ==
 In Section 8.1 early in this
chapter, we replaced the email-based CVS notification mechanism with a
Jabber-based one. The script used was extremely simple—it connected to
the Jabber server specified, authenticated, and sent off the
notification message to the recipient JID.

What if we wanted to make the script "sensitive"? Jabber's presence
concept could help us here; if we extended the mechanism to allow for
the building of presence-based relationships between the notification
script and the notification recipients, we can make the sending of the
notification message dependent on the recipient's availability.
"Presence-based relationships" refers to the ''presence subscription''
mechanism described in Section 5.4.2.3.

Here's how it would work:

* Each potential recipient adds the JID used by the CVS notification
script to his roster and sends a subscription request to it.<ref>The
process of adding a JID to the roster and making a subscription request
is an atomic action in many clients. It is generally assumed that
adding a JID to your roster means that you're going to want to know when
that entity is available, so the action of adding a JID to the roster
will often generate a presence subscription request automatically.
</ref>
* The notification script, called ''cvsmsg-s''
("cvsmsg-''sensitive''"), on receipt of the presence subscription from a
recipient, accepts the request and reciprocates by sending a
subscription request back to that recipient.
* On receipt of the
presence subscription from the notification script, the recipient
accepts the request.
* When the notification script starts up to send a
message, it announces its own availability with a
<tt><presence/></tt> element, which causes the availability of
the JIDs to which it has a presence subscription to be sent to it. Based
on these <tt><presence/></tt> packets received, it can make a
decision as to whether to send the notification message or not.
* The
decision we're going to use here is an arbitrary one: if the recipient
is online, we'll send the message, unless he's specified that he doesn't
want to be disturbed, with the <tt><show>dnd</show></tt>
element.
 

=== Subscription Relationships ===
 This method will result in "balanced"
subscription relationships between script and recipients. In other
words, the script is subscribed to a recipient's presence, and vice
versa.

Of the two presence subscription "directions," the one where the
''notification script'' subscribes to the ''recipient's'' presence (as
opposed to the one where the ''recipient'' subscribes to the
''notification script's'' presence) is by far the most important. While
it's not critical that the recipients know when the notification script
is connected and active, it's essential that the notification script
know about a recipient's availability at the time it wants to send a
message.

So would it be more appropriate to create "unbalanced" subscription
relationships?

An unbalanced relationship is one where one party knows about the other
party's availability but ''not'' vice versa. The idea for sensitizing
the notification script will work as long as the script can know about
the availability of the recipients. Whether or not the opposite is true
is largely irrelevant.

Nevertheless, it's worth basing the interaction on balanced, or
reciprocal, presence subscriptions, primarily for simplicity's sake and
also for the fact that most Jabber clients (and most ''users'' of these
clients) tend to cope well and consistently with balanced subscriptions,
whereby the representation and interpretation of unbalanced
relationships is dealt with and understood in different manners. Some
clients use a <tt>lurker</tt> group to classify one-way presence
subscriptions from other JIDs (a "lurker" being one that can see you
while you can't see it).

Far from being nebulous concepts, balanced and unbalanced subscription
relationships are characterized technically by values of a certain
attribute specified in each item—each JID—in a roster: the
<tt>subscription</tt> attribute of the <tt><item/></tt> tags
within the roster. As we progress through the extensions to the CVS
notification script,we'll be examining these values at various stages in
this recipe description in Section 8.3.3.

{{Sidebar|AnthropomorphismIt's worth pointing out at this stage that
adding a JID that's used by a ''script'' to connect to Jabber is
slightly symbolic of the extension of the instant messaging world into
the wider arena of A2P messaging. Adding a ''service'' JID to your
roster and sharing presence information with that service immediately
widens the scope of what's possible with a humble instant messaging
client, and blurs the boundaries between people and applications.

</code>

 
=== The cvsmsg-s Script ===
 The script, as it stands in Section 8.1.3,
is what we want to extend and make sensitive to presence. Example 8-7
looks at the extended script, ''cvsmsg-s'', and then walks through the
additions.

''The cvsmsg-s script''

<code>import jabber import sys from string import split

Server = 'gnu.pipetree.com' Username = 'cvsmsg' Password = 'secret'
Resource = 'cvsmsg'

cvsuser = sys.argv[1] message = ''

def presenceCB(con, prs):

type = prs.getType() parts = split(prs.getFrom(), '/') who =
parts[0]

if type == None: type = 'available'

# Subscription request: - Accept their subscription - Send request
# for subscription to their presence
if type == 'subscribe': print "subscribe request from %s" % (who)
con.send(jabber.Presence(to=who, type='subscribed'))
con.send(jabber.Presence(to=who, type='subscribe'))

# Unsubscription request: - Accept their unsubscription - Send
# request for unsubscription to their presence
elif type == 'unsubscribe': print "unsubscribe request from %s" %
(who) con.send(jabber.Presence(to=who, type='unsubscribed'))
con.send(jabber.Presence(to=who, type='unsubscribe'))

elif type == 'subscribed': print "we are now subscribed to %s" %
(who)

elif type == 'unsubscribed': print "we are now unsubscribed to %s" %
(who)

elif type == 'available': print "%s is available (%s/%s)" % (who,
prs.getShow(), prs.getStatus()) if prs.getShow() != 'dnd' and who ==
cvsuser: con.send(jabber.Message(cvsuser, message, subject="CVS
Watch Alarm"))

elif type == 'unavailable': print "%s is unavailable" % (who)

for line in sys.stdin.readlines(): message = message + line

con = jabber.Client(host=Server)

try: con.connect() except IOError, e: print "Couldn't connect: %s" % e
sys.exit(0)

con.auth(Username,Password,Resource)

con.setPresenceHandler(presenceCB) con.requestRoster()
con.sendInitPresence()

for i in range(5): con.process(1)

con.disconnect()
</code>

 

=== Taking the cvsmsg-s Script Step by Step ===
 Now it's time to examine
the script step by step. We'll concentrate mostly on the additions to
the original ''cvsmsg'' script.

We bring in a string function that we'll be needing later in the script
to chop up JIDs into their component parts (''username'', ''hostname'',
and ''resource''):

<code>import jabber import sys <tt>from string import split</tt>

Server = 'gnu.pipetree.com' Username = 'cvsmsg' Password = 'secret'
Resource = 'cvsmsg'

cvsuser = sys.argv[1] message = ''

</code>

 

==== Presence callback ====
 The next addition to the script is a
callback to handle <tt><presence/></tt> elements. The callback in
this script takes the form of a subroutine called <tt>presenceCB()</tt>
("presence callback"). Callbacks, in relation to programming with
Jabber, are explained in Section 8.3.4.

This is what the callback for handling <tt><presence/></tt>
elements looks like:

<code>def presenceCB(con, prs):

type = prs.getType() parts = split(prs.getFrom(), '/') who =
parts[0]

if type == None: type = 'available'

# Subscription request: - Accept their subscription - Send request
# for subscription to their presence
if type == 'subscribe': print "subscribe request from %s" % (who)
con.send(jabber.Presence(to=who, type='subscribed'))
con.send(jabber.Presence(to=who, type='subscribe'))

# Unsubscription request: - Accept their unsubscription - Send
# request for unsubscription to their presence
elif type == 'unsubscribe': print "unsubscribe request from %s" %
(who) con.send(jabber.Presence(to=who, type='unsubscribed'))
con.send(jabber.Presence(to=who, type='unsubscribe'))

elif type == 'subscribed': print "we are now subscribed to %s" %
(who)

elif type == 'unsubscribed': print "we are now unsubscribed to %s" %
(who)

elif type == 'available': print "%s is available (%s/%s)" % (who,
prs.getShow(), prs.getStatus()) if prs.getShow() != 'dnd' and who ==
cvsuser: con.send(jabber.Message(cvsuser, message, subject="CVS
Watch Alarm"))

elif type == 'unavailable': print "%s is unavailable" % (who)

</code>

Phew! Let's take it a bit at a time. The first thing to note is what's
specified in the subroutine declaration:

<code>def presenceCB(con, prs):
</code>

As a handler, the subroutine <tt>presenceCB()</tt> will be passed the
''connection object'' in <tt>con</tt>, and the ''presence node'' in
<tt>prs</tt>. <tt>con</tt> is the same connection object that is created
later in the script (<tt>con = jabber.Client(host=Server)</tt>) and is
passed in for convenience, as it's quite likely we're going to want to
use it, say, to send something back over the stream.

The presence node in <tt>prs</tt> is an object representation of the XML
fragment that came in over the stream and was parsed into its component
parts. The object is an instance of the <tt>jabber.Presence</tt> class,
which is simply a specialization of the more generic
<tt>jabber.Protocol</tt> class, as are the other classes that represent
the other two Jabber protocol elements that are to be expected:
<tt>jabber.Message</tt> and <tt>jabber.Iq</tt>. The
<tt>jabber.Protocol</tt> class represents protocol elements in general.

As such, there are a number of <tt><presence/></tt>
element-specific methods we can call on the <tt>prs</tt> object, such as
<tt>getShow()</tt> and <tt>getStatus()</tt> (which return the values of
the <tt><show/></tt> and <tt><status/></tt> tags—children
of the <tt><presence/></tt> element—respectively) and general
element methods such as <tt>getID</tt>, which returns the value of any
<tt>id</tt> attribute assigned to the element, and <tt>setTo()</tt>,
which can be used to address the element—to set the value of the
<tt>to</tt> attribute.

The first thing the handler does is to call a few of these element
methods to determine the ''type'' of <tt><presence/></tt> element
(presence types are described in Section 5.4.2), and who it's coming
from:

<code> type = prs.getType() parts = split(prs.getFrom(), '/') who =
parts[0]

</code>

When the notification script is called, the JID found in the CVS users
file is substituted for the <tt>%s</tt> in the formula contained in the
CVS notify file. So if the user ''dj'' were to be notified, the JID
passed to the script would be ''dj@gnu.pipetree.com''.

The way JIDs are passed around ''independently'' of the context of a
Jabber session is usually in the simpler
form—''username''<tt>@</tt>''hostname'', that is, without the resource
suffix—''username''<tt>@</tt>''hostname''<tt>/</tt>''resource''. As
described in Chapter 5, the resource is primarily used to distinguish
individual sessions belonging to one Jabber user.

But when the Jabber library—and subsequently a handler subroutine in the
script—receives an element, it contains a <tt>from</tt> attribute whose
value has been stamped by the Jabber server as it passes through. The
value represents the session, the ''connection'', from which the
<tt><presence/></tt> element was sent and, as such, includes a
resource suffix. So in order to properly match up the source JID for any
incoming <tt><presence/></tt> element with the JID specified when
the script was invoked (contained in the <tt>cvsuser</tt> variable), we
need to strip off this resource suffix. The remaining
''username''<tt>@</tt>''hostname'' part is captured in the <tt>who</tt>
variable.

There's one more step to determine the presence type. The <tt>type</tt>
attribute is ''optional''; its absence signifies the default presence
type, which is <tt>available</tt>. So we effect this default
substitution here to make the subsequent code clearer:

<code> if type == None: type = 'available'

</code>

At this stage, we want to take different actions depending on what sort
of presence information has arrived. Recalling the sequence of events in
the reciprocal presence subscription exchange described earlier in this
chapter, one of the activities is for a potential notification recipient
to subscribe to the presence of the script's JID.

This subscription request is carried in a <tt><presence/></tt>
element, with a type of <tt>subscribe</tt>. Example 8-8 shows what a
typical subscription request would look like.

''A presence subscription request from dj@gnu.pipetree.com''

<code><presence type='subscribe' to='cvsmsg@gnu.pipetree.com'
from='dj@gnu.pipetree.com/work'/>
</code>

At this stage, ''dj@gnu.pipetree.com'' has just sent a request to
subscribe to the script's presence. The subscription relationship
between the two parties is nondescript, and this is reflected in the
details of the item in ''dj'''s roster that relates to the script's JID:

<code><item jid='cvsmsg@gnu.pipetree.com' subscription='none'
ask='subscribe'/>
</code>

The relationship itself is reflected in the <tt>subscription</tt>
attribute, and the current state of the relationship is reflected in the
<tt>ask</tt> attribute.

If a subscription request is received, we want the script to respond by
accepting the subscription request. Once the request has been accepted,
a presence subscription request is made in return.

This incoming subscription request is handled here:

<code> # Subscription request:
# - Accept their subscription - Send request for subscription to
# their presence
if type == 'subscribe': print "subscribe request from %s" % (who)
con.send(jabber.Presence(to=who, type='subscribed'))
con.send(jabber.Presence(to=who, type='subscribe'))

</code>

Each call to the <tt>jabber.Presence</tt> class constructor creates a
node representing a <tt><presence/></tt> element. The two
parameters passed in the call are fairly self-explanatory: we specify
''to whom'' the <tt><presence/></tt> element should be sent, and
the ''type''.

If the presence subscription request came in from the JID
''dj@gnu.pipetree.com'', then the XML represented by the node created in
the first call here (specifying a presence type of <tt>subscribed</tt>)
would look something like that in Example 8-9.

''Acceptance of a presence subscription request from
dj@gnu.pipetree.com''

<code><presence type='subscribed' to='dj@gnu.pipetree.com'/>
</code>

{{Sidebar|Addressing <presence/> ElementsIt's worth pointing out
here that there's a subtle difference between sending
<tt><presence/></tt> elements in a presence subscription
conversation and sending general "availability"
<tt><presence/></tt> elements.

In the first case, we use a <tt>to</tt> attribute, because our
conversation is one-to-one. In the second, we don't; our unaddressed
availability information is caught by the server and in turn sent on to
those entities that are subscribed to your presence.

Although you ''can'' send <tt><presence/></tt> elements that
convey availability information directly ''to'' a JID, it's not normal.
However, explicitly addressing the elements in a subscription scenario
is essential.

There's another situation in which such "directed" (explicitly
addressed) <tt><presence/></tt> elements are used—to partake of
the services of the availability tracker. This is described in the
Section 5.4.2.4.

</code>
Once constructed, each of the <tt>jabber.Presence</tt> nodes is sent
back along the stream with the <tt>con.send()</tt> calls.

Now that the script has accepted ''dj'''s subscription request, ''dj'''s
roster item for the script reflects the new relationship:

<code><item jid='cvsmsg@gnu.pipetree.com' subscription='to'/>
</code>

<tt>subscription='to'</tt> denotes that the subscription relationship is
currently one way—''dj'' has a subscription to the script. There's no
<tt>ask</tt> attribute as there's no current request going from ''dj''
to the script.

While ''dj'''s roster item for the script shows a <tt>subscription</tt>
value of <tt>to</tt>, the ''script'''s roster item for ''dj'' shows a
<tt>subscription</tt> value of <tt>from</tt>:

<code><item jid='dj@gnu.pipetree.com' subscription='from'
ask='subscribe'/>
</code>

which shows that the script has a subscription ''from''''dj''.

Furthermore, remember that the script not only accepts ''dj'''s
subscription request, it sends a reciprocal one of its own. (Hence the
<tt>ask="subscribe'</tt> status in the item.) When ''dj'' accepts this
request, the roster item changes yet again to reflect the balanced
relationship:

<code><item jid='cvsmsg@gnu.pipetree.com' subscription='both'/>
</code>

We want the script to handle requests to <tt>unsubscribe</tt> from its
presence in the same way:

<code> # Unsubscription request:
# - Accept their unsubscription - Send request for unsubscription to
# their presence
elif type == 'unsubscribe': print "unsubscribe request from %s" %
(who) con.send(jabber.Presence(to=who, type='unsubscribed'))
con.send(jabber.Presence(to=who, type='unsubscribe'))

</code>

The only difference between this section and the previous one is that it
deals with requests to <tt>unsubscribe</tt> as opposed to
<tt>subscribe</tt> to presence. Otherwise it works in exactly the same
way. A sequence of <tt><presence/></tt> elements used in an
"unsubscription conversation" between ''dj'' and the script, and the
changes to the roster <tt><item/></tt> tags on each side, is shown
in Figure 8-5.

[[image:jab_0805.png|<presence/> elements and roster <item/>s in
an unsubscription conversation|center|350 px]]
 </code> While we
must take action on presence types <tt>subscribe</tt> and
<tt>unsubscribe</tt>, we don't really need to do anything for their
''acknowledgment'' counterparts: <tt>subscribed</tt> and
<tt>unsubscribed</tt> ("I have accepted your request, and you are now
subscribed/unsubscribed to my presence").

Nevertheless, just for illustration purposes, we'll include a couple of
conditions to show what's going on when the script runs:

<code> elif type == 'subscribed': print "we are now subscribed to
%s" % (who)

elif type == 'unsubscribed': print "we are now unsubscribed to %s" %
(who)

</code>
Apart from the types of <tt><presence/></tt> element covering the
presence subscription process, we should also expect the basic
availability elements:

<code><presence>...</presence>
</code>

and

<code><presence type='unavailable'/>
</code>

It's an available <tt><presence/></tt> element that the
functionality of the script hinges on:

<code> elif type == 'available': print "%s is available (%s/%s)" %
(who, prs.getShow(), prs.getStatus()) if prs.getShow() != 'dnd' and who
== cvsuser: con.send(jabber.Message(cvsuser, message, subject="CVS Watch
Alarm"))

</code>

This <tt>presenceCB()</tt> subroutine is set up to handle
<tt><presence/></tt> elements. In a typical execution scenario,
where the script is subscribed to the presence of many potential CVS
notification recipients, the subroutine is going to be called to handle
the availability information of all recipients who happen to be
connected to Jabber at the moment of notification. We're interested in
the availability information of only one particular recipient (<tt>who
== cvsuser</tt>), and we want to check on the contents of the
<tt><show/></tt> tag.

If we get a match, we can send the notification message by creating a
<tt>jabber.Message</tt> node that will look like this:

<code><message to='dj@gnu.pipetree.com'> <subject>CVS Watch
Alarm</subject> <body> testproject file4 --- Triggered edit
watch on /usr/local/cvsroot/testproject By piers </body>
</message>
</code>

As in the ''cvsmsg'' script, once created, the node can be sent with the
<tt>con.send()</tt> method call.

Like the conditions for the presence subscription and unsubscription
acknowledgments, we're including a final condition to deal with the case
where a recipient disconnects from the Jabber server during the
execution of the script: an
<tt>unavailable</tt><tt><presence/></tt> element will be sent:

<code> elif type == 'unavailable': print "%s is unavailable" % (who)

</code>

We're simply logging such an event for illustration purposes.

 

==== Connection and authentication ====
 Most of the main part of the
script is the same as the nonsensitive version from Section 8.1: reading
in the notification message, preparing a connection to the Jabber
server, and trying to connect:

<code>for line in sys.stdin.readlines(): message = message + line

con = jabber.Client(host=Server)

try: con.connect() except IOError, e: print "Couldn't connect: %s" % e
sys.exit(0)

con.auth(Username,Password,Resource)

</code>

 

==== Registration of <presence/> handler ====
 While we've
''defined'' the <tt>presenceCB()</tt> subroutine to handle
<tt><presence/></tt> packets, we haven't actually told the Jabber
library about it. The call to the <tt>setPresenceHandler()</tt> method
of the connection object does this for us, performing the "Register
handler" step shown in Figure 8-6. The steps shown in Figure 8-6 are
described in Section 8.3.4.

<code>con.setPresenceHandler(presenceCB)

</code>

[[image:jab_0806.png|Handlers and the relationship between the Jabber library
and your script|center|350 px]]
 </code>
 
==== Request for roster ====
 It's easy to guess what the next method
call does:

<code>con.requestRoster()
</code>

It makes a request for the roster by sending an IQ-get with a query
qualified by the <tt>jabber:iq:roster</tt> namespace:

<code><iq type='get' id='3'> <query
xmlns="jabber:iq:roster'/> </iq>
</code>

to which the server responds with an IQ-result:

<code><iq type='result' id='3'> <query
xmlns='jabber:iq:roster'> <item jid='dj@gnu.pipetree.com'
subscription='both'/> <item jid='piers@jabber.org'
subscription='both'/> <item jid='shiels@jabber.org'
subscription='both'/> ... </query> </iq>
</code>

However, as there are no explicit references to the roster anywhere in
the script, it's not as easy to guess why we request the roster in the
first place. We know that the client-side copy is merely a "slave" copy,
and, even more relevant here, we know that <tt>subscription</tt>
information in the roster <tt><item/></tt> tags is managed by the
server—we as a client don't need to (in fact, ''shouldn't'') do anything
to maintain the <tt>subscription</tt> and <tt>ask</tt> attributes and
keep them up to date.

So why do we request it? Basically, it's because there's a fundamental
difference between <tt><presence/></tt> elements used to convey
availability information and <tt><presence/></tt> elements used to
convey presence subscription information. If John sends Jim availability
information in a <tt><presence/></tt> element, whether directly
(with a <tt>to</tt> attribute) or indirectly (through the distribution
of that element by the server to Jim as a subscriber to John's
presence), and Jim's offline on holiday, it doesn't make sense to store
and forward the message to him when he next connects:

<blockquote>Jabber server: "''Here's some availability information for
John, dated 9 days ago.''"

Jim: "''Who cares?''"

</blockquote>The <tt><presence/></tt> elements conveying
availability information are ''not'' stored and forwarded if they can't
be delivered because the intended recipient is offline. What would be
the point?

However, <tt><presence/></tt> elements that convey subscription
information are a different kettle of fish. While it's not important
that a user is sent out of date availability information when he next
connects to his Jabber client, any subscription (or unsubscription)
requests or confirmations that were sent to him ''are'' important. So
they need to be stored and forwarded.

As we've already seen, the presence subscription mechanism and rosters
are inextricably linked. And if we look briefly under the covers, we see
how this is so. When a presence subscription request is sent to a user,
it runs the gauntlet of modules in the JSM (see Section 4.4.4 for
details on what these modules are). The roster-handling module
''mod_roster'' grabs this request, and, just in case the recipient turns
out not to be connected, ''stores'' it.

And here's how intertwined the presence subscription mechanism and
rosters really are: the request is stored as a cluster of attribute
details within an <tt><item/></tt> tag in the roster belonging to
the ''recipient'' of the presence subscription request. It looks like
this:

<code><item jid='user@hostname' subscription='none' subscribe=''
hidden=''/>
</code>

On receipt of a presence subscription request, the ''mod_roster'' module
will create the roster item if it doesn't exist already and then assign
the attributes related to presence
subscription—<tt>subscription="none'</tt> and <tt>subscribe="'</tt>—to
it. There's no <tt>ask</tt> attribute, as this is assigned only to the
item on the roster belonging to the ''sender'', not the one belonging to
the ''receiver'', of the subscription request.

The <tt>subscribe</tt> attribute is used to store the reason for the
request, that, if specified, is carried in the <tt><status/></tt>
tag of the <tt><presence/></tt> element that conveys the request.
If no reason is given, the value for the attribute is empty, as shown
here. Otherwise, it will contain what was stored in the
<tt><status/></tt> tag. Example 8-10 shows a presence subscription
request that carries a reason.

''A presence subscription request with a reason''

<code><presence to='dj@gnu.pipetree.com'> <status>I'd like
to keep my eye on you!</status> </presence>
</code>

The <tt>hidden</tt> attribute here:

<code><item jid='user@hostname' subscription='none' subscribe=''
hidden=''/>
</code>

is used internally by ''mod_roster'' to mark the item as nondisplayable;
it effectively is a pseudo <tt><item/></tt> that, when brought to
life, actually turns out to be a <tt><presence/></tt> element. So
when a request for the roster is made, ''mod_roster'' makes sure that it
doesn't send these "hidden" items. The <tt>hidden</tt> attribute always
has an empty value, as shown here.

After storing the subscription request, ''mod_roster'' will actually
send the original <tt><presence/></tt> element that conveyed that
request to the recipient—that is, if the recipient is online ''and'' if
the recipient has already made a request for his roster. As sending an
availability presence packet:

<code><presence/>
</code>

causes the ''mod_offline'' module to forward any messages stored
offline in that user's absence, so requesting the roster:

<code><iq type='get'><query
xmlns='jabber:iq:roster'/></iq>
</code>

causes the ''mod_roster'' module to forward any subscription requests
stored offline in that user's absence.

 

==== Sending of availability information ====
 OK. We've connected,
authenticated, defined, and registered the callback to handle
<tt><presence/></tt> elements, and requested the roster, so
''mod_roster'' will send us any presence subscription (or
unsubscription) requests. Now we need to make an availability
announcement in the form of a simple <tt><presence/></tt> element:

<code><presence/>
</code>

We can do this by calling the <tt>sendInitPresence()</tt> method on the
connection object:

<code>con.sendInitPresence()
</code>

This availability information will be distributed to all the entities
that are subscribed to the script's presence and are online at that
moment. It will also signify to the Jabber server that we are properly
online—in which case it can forward to us any messages that had been
stored up in our absence.

We're not really expecting any <tt><message/></tt> elements;
indeed, we haven't set up any subroutine to handle them, so they'd just
be thrown away by the library anyway. The real reason for sending
presence is so that the server will actively go and probe those in a
presence subscription relationship with the script and report back on
those who are available (who have themselves sent their presence during
their current session). This causes <tt><presence/></tt> elements
to arrive on the stream and make their way to the <tt>presenceCB()</tt>
handler.

 
==== Waiting for packets ====
 Once everything is set up, and the script
has announced its presence, it really just needs to sit back and listen
to the <tt><presence/></tt> elements that come in. If one of
these is from the intended notification recipient, and the availability
state is right (i.e., not in <tt>dnd</tt> mode), we know that the
circumstances are appropriate for sending the notification.

But the elements being sent over the stream from the server don't
spontaneously get received, parsed, and dispatched; we can control when
that happens from the script. This is the nub of the symbiosis between
the element events and the procedural routines, and it's name is
<tt>process()</tt>.

Calling <tt>process()</tt> will check on the stream to see if any XML
fragments have arrived and are waiting to be picked up. If there are
any, Steps 3 through 5, shown in Figure 8-6 and described in Section
8.3.4, are executed. The numeric value specified in the call to
<tt>process()</tt> is the number of seconds to wait for incoming
fragments if none is currently waiting to be picked up. Specifying no
value (or 0) means that the method won't hang around if nothing has
arrived. Specifying a value of 30 means that it will wait up to half a
minute. We really want something in between, and it turns out that
waiting for up to a second for fragments in a finite loop like this:

<code>for i in range(5): con.process(1)
</code>

will allow for a slightly stuttered arrival of the
<tt><presence/></tt> elements that are sent to the script as a
result of the server-initiated probes.

 

==== Finishing up ====
 We're just about done. The
<tt><presence/></tt> elements that arrive and find their way to
the callback are examined, and the CVS notification message is sent off
if appropriate. Once the <tt>process()</tt> calls have finished, and,
implicitly, the (potentially) multiple calls to <tt>presenceCB</tt>,
there's nothing left to do. So we simply disconnect from the Jabber
server, as before:

<code>con.disconnect()
</code>

 

=== Jabber Programming and Callbacks ===
 When programming all but the
simplest Jabber scripts, you're going to be using ''callbacks'', as
we've seen in this recipe. Callbacks are also known as ''handlers''.

Rather than purely procedural programming ("do this, then do that, then
do the other"), we need a different model to cope with the
''event-based'' nature of Jabber or, more precisely, the event-based
nature of how we converse using the Jabber protocol over an XML stream.
Although we control what we ''send'' over the XML stream connection
that we've established with the Jabber server, we can't control what we
''receive'', and more importantly, we can't control ''when'' we receive
it. We need an event-based programming model to be able to ''handle''
the protocol elements as they arrive.

The libraries available for programming with Jabber offer ''callback''
mechanisms. With these callback mechanisms, we can register subroutines
with the part of the library that's handling the reception of XML
document stream fragments. Then, whenever an element appears on the
incoming stream (a fragment in the stream document that the Jabber
server is sending to us), the library can pass it to the appropriate
subroutine in the script for us to act upon—to be "handled." This
passing of elements to be handled by callbacks is referred to as
''dispatching''.

Figure 8-6 shows the relationship between the library and script, and
the sequence of events surrounding registering a handler and having it
called. Here are the steps shown:

; Step 1: Register handler
: The script uses a library function to register a subroutine—in this
: case, it's <tt>presenceCB()</tt>—as a handler with the library. In the
: registration, the subroutine is assigned as a handler for
: <tt><presence/></tt> elements.
; Step 2: <presence/> element arrives
: An XML fragment arrives on the stream, sent by the Jabber server.
; Step 3: Parse, and create node
: The fragment is parsed into its component parts by an XML parser, and
: a node is created. A "node" is simply a term used to describe a
: succinct XML fragment—containing attributes, data, and child tags—that
: is usually in the form of an object that is programmatically
: accessible. The node creation step is theoretically optional; we could
: have the library pass on the fragment in a simple string
: representation form, but that would put the onus on the script to
: parse the string before being able to manipulate the fragment that the
: string represented.
; Step 4: Determine handler
: Once parsed, the library looks at what sort of element, or node, the
: fragment is and determines what (if any) handler has been registered.
: In this case, it's a <tt><presence/></tt> element, and it finds
: that the subroutine <tt>presenceCB()</tt> has been registered as a
: handler for <tt><presence/></tt> elements.
; Step 5: Call handler
: The library calls the handler <tt>presenceCB()</tt> in the script,
: passing in the node. It may pass in other information too (for
: example, the <tt>Jabberpy</tt> library also passes in the stream
: connection object, as we saw earlier, and the Perl library
: <tt>Net::Jabber</tt> also passes in a session ID relating to the
: stream).<ref>This session ID is currently part of a new development
: within the <tt>Net::Jabber</tt> library and is currently not used for
: anything. </ref></content></chapter>

←Older revision		Revision as of 14:22, 18 September 2009
Line 1:		Line 1:
		+	{{Content Programming Jabber}}
	=Using Messages and Presence=		=Using Messages and Presence=
	<br>Now that we have a decent grounding in the		<br>Now that we have a decent grounding in the

JabChapter 8 - Revision history

Newacct at 08:08, 10 December 2009

Uncopy: content navi added

Mikeh at 03:02, 16 September 2006

←Older revision		Revision as of 08:08, 10 December 2009
Line 1,094:		Line 1,094:
	''The cvsmsg-s script''		''The cvsmsg-s script''

-	<code>import jabber import sys ~~from string import split~~	+	<code>import jabber import sys

	Server = 'gnu.pipetree.com' Username = 'cvsmsg' Password = 'secret'		Server = 'gnu.pipetree.com' Username = 'cvsmsg' Password = 'secret'
Line 1,103:		Line 1,103:
	def presenceCB(con, prs):		def presenceCB(con, prs):

-	type = prs.getType() parts = ~~split(~~prs.getFrom(), '/') who =	+	type = prs.getType() parts = prs.getFrom().split('/') who =
	parts[0]		parts[0]

Line 1,133:		Line 1,133:
	elif type == 'unavailable': print "%s is unavailable" % (who)		elif type == 'unavailable': print "%s is unavailable" % (who)

-	for line in sys.stdin~~.readlines()~~: message = ~~message +~~ line	+	for line in sys.stdin: message += line

	con = jabber.Client(host=Server)		con = jabber.Client(host=Server)
Line 1,158:		Line 1,158:
	the original ''cvsmsg'' script.		the original ''cvsmsg'' script.

-	We bring in a string function that we'll be needing later in the script
-	to chop up JIDs into their component parts (''username'', ''hostname'',
-	and ''resource''):

-		+	<code>import jabber import sys
-	<code>import jabber import sys ~~<tt>from string import split</tt>~~	+

	Server = 'gnu.pipetree.com' Username = 'cvsmsg' Password = 'secret'		Server = 'gnu.pipetree.com' Username = 'cvsmsg' Password = 'secret'
Line 1,181:		Line 1,177:
	("presence callback"). Callbacks, in relation to programming with		("presence callback"). Callbacks, in relation to programming with
	Jabber, are explained in Section 8.3.4.		Jabber, are explained in Section 8.3.4.
		+
		+	We use a string method, <tt>split</tt>,
		+	to chop up JIDs into their component parts (''username'', ''hostname'',
		+	and ''resource'').

	This is what the callback for handling <tt><presence/></tt>		This is what the callback for handling <tt><presence/></tt>
Line 1,188:		Line 1,188:
	<code>def presenceCB(con, prs):		<code>def presenceCB(con, prs):

-	type = prs.getType() parts = ~~split(~~prs.getFrom(), '/') who =	+	type = prs.getType() parts = prs.getFrom().split('/') who =
	parts[0]		parts[0]

Line 1,261:		Line 1,261:


-	<code> type = prs.getType() parts = ~~split(~~prs.getFrom(), '/') who =	+	<code> type = prs.getType() parts = prs.getFrom().split('/') who =
	parts[0]		parts[0]

Line 1,551:		Line 1,551:


-	<code>for line in sys.stdin~~.readlines()~~: message = ~~message +~~ line	+	<code>for line in sys.stdin: message += line

	con = jabber.Client(host=Server)		con = jabber.Client(host=Server)