Mikeh at 22:18, 16 September 2006

Mikeh — Sat, 16 Sep 2006 22:18:00 GMT

New page

=Pointers for Further Development=
 The previous two chapters have demonstrated
how Jabber can be used to build applications and solutions in many
functional areas. They expanded upon and indeed went beyond the theme of
instant messaging (IM) to employ the fundamental features of contextual
messaging, presence, and request/response sequences, in a wide range of
scenarios.

While these scenarios have in some ways been inward looking, they are
natural progressions that originated inside the IM world and matured
into applications and solutions that retain much of the messaging
flavor. Let's consider what else Jabber has to offer as a messaging and
routing mechanism.

This chapter explores some "outward looking" scenarios, to give you
pointers and ideas for the future. With ''Demo::JBook'', we consider
the possibility of "Jabber without Jabber"—in other words, using Jabber
as an ''infrastructure'', in this case as a data store, without focus on
any particular Jabber client or IM functionality. We also explore how
Jabber is the perfect transport partner for procedure calls formalized
in XML: ''JabberRPCRequester'' and ''JabberRPCResponder'' are scripts
that exchange method calls and responses encoded in XML-RPC.

Using Jabber as a conduit to foreign systems is also a theme of this
chapter. With ''ldapr'', we build a script that reflects the hierarchy
and contents of an LDAP data store, allowing that store to be navigated
from a Jabber client. Finally, we look to the business world, employing
Jabber in a tiny but crucial role as a conduit between SAP systems and
their users.

 

== A Simple Jabber-Based Address Book ==
 With the availability of many
different off-the-shelf Jabber clients and the use of these clients as
generic tools to interact with diverse Jabber-based services, it's easy
to lose sight of the fact that Jabber can also be used to contribute to
''infrastructure'' solutions. That is, applications and utilities can be
built using the Jabber protocols, in conjunction with Jabber
server-based services, without the need for a Jabber client.

By way of illustration, let's build a simple two-level address book
using Jabber services. We'll call it ''Demo::JBook''. We'll use this
address book to look up details of our friends and colleagues while
we're on the move. The ideal platform for this is going to be a web
browser, in that it's accessible from personal workstations, airport web
consoles, cybercafés, and personal digital assistants (PDAs) that offer
access to the Internet.

The point of this illustration is not to show that there's a single
solution to the problem of disconnected, incompatible, and
unsynchronized directory information (because, despite any answers that
you may get to the contrary—no such solution exists). Instead, the goal
is to show that it's possible to make use of Jabber services and get to
information stored and managed by those services without having to use a
Jabber client.

 

=== Using the JUD and vCards ===
 The two levels in our address book are
going to reflect two distinct (but related) mechanisms in Jabber. We're
going to base our address book on the Jabber User Directory (JUD)
component and supply further information, in a "drill-down" action,
using vCards.

; The JUD
: Our address book will act as a query frontend for a user directory in
: the form of a JUD. It doesn't matter ''which'' JUD we use; obviously,
: that depends on how the application is to be deployed. On one hand, it
: might be appropriate to point it at your company's internal JUD, if
: you have one. On the other hand, it might also be just as appropriate
: to point it at one of the larger public JUDs, such as the one
: connected to the Jabber server running on ''jabber.org'' (which is
: ''users.jabber.org'').
; vCards
: Every Jabber entity—users, components, and servers—has the potential
: to have a vCard. We saw in Chapter 4 that the Jabber server itself,
: and many of the components connected to it, had a vCard definition.
: While the vCard standard is still fluid, the implementation within
: Jabber, as described in Section 6.5.1 in Chapter 6, is enough to be
: useful. The key to the application is that both the Jabber mechanisms
: that it relies upon—the JUD and vCards—can be accessed independently
: of the availability of the users that the information stored in those
: mechanisms represents. The JUD runs as an independent component and
: manages the directory information using its own data store. With the
: default JUD and XML Database (XDB) component configurations, this data
: store will be in the Jabber server's spool directory in a file called
: jud/global.xdb.

Users interact with the JUD to manage their information, using IQ
elements qualified by the <tt>jabber:iq:register</tt> namespace. User
vCard information is also stored at the server side, and users manage
the vCard contents using IQ elements qualified by the
<tt>vcard-temp</tt> namespace. Again, with the default configuration,
the vCard information, stored along with the rest of the user data
relevant to the Jabber server in user-specific spool files, will be held
in the Jabber server's spool directory in files called
[hostname]/[user].xml.

 

=== What Demo::JBook Will Do ===
 The JUD can be queried using a normal
Jabber client. In Figure 10-1, we can see the search form of Jabber
Instant Messenger (JIM).

[[image:jab_1001.png|Searching the JUD: the search form|conter|350 px]]
 </code> The search fields are not fixed;
instead, they're dynamically generated, according to the result of an
initial IQ-get in the <tt>jabber:iq:search</tt> namespace. Just as an
IQ-get in the <tt>jabber:iq:register</tt> namespace (as illustrated in
Section 8.3) is used for registering users, the
<tt>jabber:iq:search</tt> namespace is is used for search requests. This
is illustrated in Example 10-1, where an IQ-get is sent to the JUD at
<tt>jud.gnu.mine.nu</tt>.

''An IQ-get to a JUD in the jabber:iq:search namespace''

<code>SEND: <iq type="get" id="9138" to="jud.gnu.mine.nu">
<query xmlns="jabber:iq:search"/> </iq>

RECV: <iq from='jud.gnu.mine.nu' id='9138'
to='qmacro@jabber.org/study' type='result'> <query
xmlns='jabber:iq:search'> <first/> <last/>
<instructions> Fill in a field to search for any matching Jabber
users. </instructions> </query> </iq>
</code>
In response to the IQ-get request, the JUD sends back a list of fields
with which the directory can be searched, along with some simple
instructions.

The actual search follows the same registration pattern (using the
<tt>jabber:iq:register</tt> namespace) that we saw in Section 8.3. After
receiving a list of possible search fields, a search request is made
with an IQ-set, as shown in Example 10-2. The results, returned in an
IQ-result from the JUD, are listed with each entry contained in an
<tt><item/></tt> tag. The search results are shown in Figure 10-2.

[[image:title=Searching the JUD: the search
results|image=0596002025-jab_1002.png</code>

''The JUD search request and response''

<code>SEND: <iq type="set" id="2627" to="users.jabber.org">
<query xmlns="jabber:iq:search"> <last>adams</last>
</query> </iq>

RECV: <iq from='users.jabber.org' id='2627'
to='qmacro@jabber.org/study' type='result'> <query
xmlns='jabber:iq:search'> <item jid='qmacro@jabber.org'>
<nick>qmacro</nick> <first>DJ</first>
<email>dj.adams@gmx.net</email>
<last>Adams</last> </item> <item
jid='qmacro@jabber.com'> <nick>dj</nick>
<first>DJ</first>
<email>dj.adams@gmx.net</email>
<last>Adams</last> </item> <item
jid='joseph@gnu.mine.nu'> <nick>joseph</nick>
<first>Joseph</first>
<email>joseph@pipetree.com</email>
<last>Adams</last> </item>

... (more items) ...

</query> </iq>
</code>

 
==== Searching a JUD ====
 The first level that we'll build into
''Demo::JBook'' is the ability to query a JUD. The address book is to be
browser-based, so we'll generate HTML on the fly according to the search
fields we receive in response to our IQ-get. It should look something
like that shown in Figure 10-3.

[[image:jab_1003.png|JUD search form in HTML|center|350 px]]
 </code>
The items returned in the search results don't really provide much
information:

<code><item jid='joseph@gnu.mine.nu'>
<nick>joseph</nick> <first>Joseph</first>
<email>joseph@pipetree.com</email>
<last>Adams</last> </item>
</code>
Here, we have the user's first and last names, his nickname, and his
email address. One of the functions of the JUD is to determine which
fields are storable.

{{Sidebar|JUD FieldsThe fields in a JUD that are used to store the
directory data are determined either by a hardcoded list in the JUD
source itself or a configurable list that's stored and maintained
separate from the JUD code. The list fields allowed for searching a JUD
may or may not be used for storing the information; it may be a subset
(it makes no sense, of course, for it to be a superset). For example, if
the fields used to store information in a JUD are:

<code><name/> <email/> <first/> <last/>
<nick/> <text/></code> it may be that the fields available for
searching may be just:

<code><first/> <last/>
</code>
as shown in Example 10-1.

In case you're wondering how to discover the fields that can be used to
populate the information in the JUD, an IQ-get can be used in the
<tt>jabber:iq:register</tt> namespace to qualify a ''registration''
conversation with the JUD, which is where the information is
"registered," or stored. This is shown in Example 10-3.

</code>

''An IQ-get to a JUD in the jabber:iq:register namespace''

<code>SEND: <iq type='get' to='jud.gnu.mine.nu'> <query
xmlns='jabber:iq:register'/> </iq>

RECV: <iq from='jud.gnu.mine.nu' to='qmacro@jabber.com/study'
type='result'> <query xmlns='jabber:iq:register'> <nick/>
<first/> <email/> <last/> <text/> <name/>
<instructions> Fill in all of the fields to add yourself to the
JUD. </instructions> </query> </iq>
</code>
We can see in Figure 10-4 how the results will typically be rendered.

[[image:jab_1004.png|JUD search results as rendered in Demo::JBook|center|350 px
 </code>

 
==== Retrieving vCard information ====
 As well as registering with a
JUD, it's possible that a user has maintained more information about
himself—in his vCard. Depending on the Jabber client used, various user
information can be stored in a personal vCard, which is stored on the
server side. In Figure 10-5, we see the JIM client's vCard maintenance
window, titled User Profile.

The result of entering information and clicking the OK button in Figure
10-5 can be seen in Example 10-4, where an IQ-set in the
<tt>vcard-temp</tt> namespace is made to store the information (some of
the vCard tags have been omitted to keep the example short). Notice how
no <tt>to</tt> attribute is specified in the IQ-set and how the result
appears to come from the sender (<tt>qmacro@jabber.com/study</tt>). The
storage of personal—user-specific—vCard information is a function of the
Jabber Session Manager (JSM), which is where the <tt><iq/></tt>
element will be routed automatically, as it is coming in over a client
connection (defined by the <tt>jabber:client</tt> stream-level
namespace). This is further discussed in Section 5.4.3.1.

[[image:jab_1005.png|Updating personal vCard information with JIM|center|350 px </code>

''Setting vCard information in the vcard-temp namespace''

<code>SEND: <iq type="set"> <VCARD version="3.0"
xmlns="vcard-temp"> <N> <GIVEN>DJ</GIVEN>
<FAMILY>Adams</FAMILY> <MIDDLE/> </N>
<NICKNAME>qmacro</NICKNAME> <EMAIL> <INTERNET/>
<PREF/> dj.adams@gmx.net </EMAIL>

...

</VCARD> </iq>

RECV: <iq type='result' from='qmacro@jabber.com/study'
to='qmacro@jabber.com/study'/>
</code>
As well as being storable, the information in a personal vCard is also
retrievable by anyone, anytime. The idea of a personal vCard is that the
information it contains is permanently available. Because the vCard data
is stored server side, it can be retrieved anytime the user is online.

The key (literally and metaphorically) of each of the search result
items returned is a JID. We can see this in Example 10-2, where each
<tt><item/></tt> tag has a <tt>jid</tt> attribute. You won't be
surprised to know that the key to accessing someone's vCard is his JID
too. So we have a great way for ''Demo::JBook'' to jump from level 1,
which displays JUD search results, to level 2 by retrieving and
displaying a vCard via the JID. The results of jumping from a JUD result
entry to a vCard display for the selected user, via the JUD, can be seen
in Figure 10-6.

[[image:jab_1006.png|A vCard as displayed in Demo::JBook|center|350 px-</code>

 
=== Using Demo::JBook as an Apache Handler ===
 The ''Demo::JBook''
application is going to exist as an Apache ''mod_perl'' handler, that
is, we'll use the power of Perl's integration into the Apache web server
to write an Apache module in Perl. You can find out more about
''mod_perl'' at http://perl.apache.org.

Being a ''mod_perl'' module, ''Demo::JBook'' exists in the form of a
Perl module and is configured in Apache to service calls to
<tt>http://[</tt>''hostname''<tt>]/jbook</tt>. The configuration can be
comfortably placed in the main Apache configuration file, httpd.conf,
or, as is common in ''mod_perl'' installations, in an extra file usually
called perl.conf, which is linked to httpd.conf as follows:

<code><IfModule mod_perl.c> Include conf/perl.conf
</IfModule>
</code>
The configuration for ''Demo::JBook'' is placed in the perl.conf file,
as shown in Example 10-5.

''Configuring the module as a handler in Apache''

<code>require conf/startup.pl

...

<Location /jbook> SetHandler perl-script PerlHandler Demo::JBook
</Location>
</code>
The <tt>PerlHandler</tt> directive refers to the ''Demo::JBook'' module,
which is the JBook.pm file that exists in the Demo/ directory. The
module will be invoked to handle calls to the relative URL ''/jbook''.
You can add the location of the ''Demo::JBook'' module to ''mod_perl'''s
list of directories in the <tt>BEGIN</tt> section of the startup.pl
script, in the conf/ directory, like this:

<code>BEGIN { use Apache (); use lib '[the directory location of
Demo::JBook]';
}
</code>

 
=== The Demo::JBook Script ===
 Before taking the ''Demo::JBook'' script
apart, let's have a look at the script in its entirety, shown in
Example 10-6. Written in Perl, ''Demo::JBook'' uses the
<tt>Jabber::Connection</tt> library.

''The Demo::JBook script, written in Perl''

<code>package Demo::JBook;

use strict;

use Jabber::Connection; use Jabber::NodeFactory; use Jabber::NS qw(:iq
:misc);

use constant SERVER => 'gnu.mine.nu'; use constant USER =>
'jbook'; use constant PASS => 'pass'; use constant RESOURCE =>
'jbook'; use constant JUD => 'jud.gnu.mine.nu';

sub handler {

my $r = shift; my @a = $r->args;

my $nf = Jabber::NodeFactory->new;

$r->content_type('text/html'); $r->send_http_header;

$r->print("<html><head><title>JBook</title>
</head><body>"); $r->print("<h1><a
href="/jbook">JBook</a></h1>");

# Connect to the Jabber server
my $c = Jabber::Connection->new(server => SERVER); unless
($c->connect) { $r->print("Sorry, no connection to Jabber
available at ".SERVER); $r->print("</body></html>");
return;
}

$c->auth(USER, PASS, RESOURCE);

# No arguments: Instructions
if (scalar @a == 0) {

# Construct IQ-get in iq:search namespace
my $iq = $nf->newNode('iq'); $iq->attr('to', JUD);
$iq->attr('type', IQ_GET); $iq->insertTag('query', NS_SEARCH);

# Send the IQ-get
my $result = $c->ask($iq);

if ($result->attr('type') eq IQ_ERROR) { $r->print("sorry, no
connection to JUD available at ".JUD);
$r->print("</body></html>"); $c->disconnect;
return;
}

my $info = $result->getTag('', NS_SEARCH);

# Display the results in HTML
$r->print("".JUD."</p&gt
;\n");
$r->print("".$info->getTag('instructions')->data."
\n"); $r->print("<form><table>\n"); foreach
my $field ($info->getChildren) { next if $field->name eq
'instructions'; $r->print("<tr>");
$r->print("<td>".ucfirst($field->name)."</td>");
$r->print("<td><input type="text'
name="".$field->name.""></td>");
$r->print("</tr>\n");
}
$r->print("<tr><td></td><td><input
type="submit"></td></tr>\n");
$r->print("</table></form>\n");

}

# Multiple arguments: JUD lookup
elsif (scalar @a > 1) {

# Treat the arguments as a hash
my %a = @a;

# Construct an IQ-set
my $iq = $nf->newNode('iq'); $iq->attr('to', JUD);
$iq->attr('type', IQ_SET); my $query = $iq->insertTag('query',
NS_SEARCH);

while (my($name, $val) = each(%a)) {
$query->insertTag($name)->data($val) if $val;
}

# Make call
my $result = $c->ask($iq);

if ($result->attr('type') eq IQ_ERROR) { $r->print("sorry,
cannot query JUD"); $r->print("</body></html>");
$c->disconnect; return;
}

my $info = $c->ask($iq)->getTag('', NS_SEARCH);

my $items = 0;

$r->print("".JUD."</p&gt
;\n"); $r->print("<table border="1">\n");

foreach my $item ($info->getChildren) {

# Heading
unless ($items) { $r->print("<tr>"); foreach my $tag
($item->getChildren) {
$r->print("<th>".ucfirst($tag->name)."</th>");
}
$r->print("</tr>\n");
}

$r->print("<tr>"); my $flag = 0; foreach my $tag
($item->getChildren) { unless (length($tag->data) == 0 or
$flag++) { $r->print("<td><a
href="/jbook?".$item->attr('jid')."">");
$r->print($tag->data."</a></td>");
}
else { $r->print("<td>".$tag->data."</td>");
}
}
$r->print("</tr>\n");

$items++;
}
$r->print("</table>\n");

$r->print("$items results found");

}

# Single argument: vCard lookup
else {

# Construct query
my $iq = $nf->newNode('iq'); $iq->attr('to', $a[0]);
$iq->attr('type', IQ_GET); $iq->insertTag('vcard', NS_VCARD);

# Make call and retrieve results
my $result = $c->ask($iq);

if ($result->attr('type') eq IQ_ERROR) { $r->print("sorry,
cannot retrieve vCard for $a[0]");
$r->print("</body></html>"); $c->disconnect;
return;
}

my $vcard = $result->getTag('', NS_VCARD);

print ("$a[0]\n");

# Display each of the top-level tags if they contain data
foreach my $tag ($vcard->getChildren) { print
" ".$tag->name." : ".$tag->data."\n" if
$tag->data;
}

}

$r->print("</body></html>"); $c->disconnect;

return;

}

1;
</code>

 
=== Taking Demo::JBook Step by Step ===
 Now that we've got a hold on the
scope and scale of ''Demo::JBook'', let's take the script apart—step by
step—to see how it works.

 

==== Declarations ====
 Because ''Demo::JBook'' is an Apache handler, it
exists as a Perl module—hence the <tt>package</tt> declaration at the
top of the file:

<code>package Demo::JBook;

use strict;

use Jabber::Connection; use Jabber::NodeFactory; use Jabber::NS qw(:iq
:misc);

use constant SERVER => 'gnu.mine.nu'; use constant USER =>
'jbook'; use constant PASS => 'pass'; use constant RESOURCE =>
'jbook'; use constant JUD => 'users.jabber.org';
</code>
This code exists within the ''Demo::JBook'' package that was declared as
the handler for the <tt>http://[</tt>''hostname''<tt>]/jbook</tt>
location, shown in Example 10-5. We're going to make full use of the
<tt>Jabber::Connection</tt> library and bring in all three of its
modules for managing the Jabber server connection, for dispatching
elements that arrive (<tt>Jabber::Connection</tt>), for building and
manipulating elements (<tt>Jabber::NodeFactory</tt>), and using common
Jabber programming constants (<tt>Jabber::NS</tt>). In the case of
<tt>Jabber::NS</tt>, we need only a few namespaces to manage our JUD and
vCard queries, so the <tt>:iq</tt> and <tt>:misc</tt> tags will be used
to refer a collection of constants in <tt>Jabber::NS</tt>.

The constants <tt>SERVER</tt>, <tt>USER</tt>, <tt>PASS</tt>, and
<tt>RESOURCE</tt> define the connection to the Jabber server. This
connection doesn't have to be made to the JUD that will be queried by
''Demo::JBook''. By way of illustration, we have ''jabber.org'''s JUD
(<tt>users.jabber.org</tt>) specified as the value for the <tt>JUD</tt>
constant. For the purpose of this example, this will be the JUD that
''Demo::JBook'' will query.

You can use the ''reguser'' script, described in Section 7.4, to create
the ''Demo::JBook'' user. See Section 8.2.1.1 for an example of how this
can be done.

 

==== General handler preparation ====
 Following the script's
declarations, it's time to define the handler function that Apache will
call to handle incoming requests to the
<tt>http://[</tt>''hostname''<tt>]/jbook</tt> location. The name of the
handler must be <tt>handler()</tt>:

<code>sub handler {

my $r = shift; my @a = $r->args;

my $nf = Jabber::NodeFactory->new;

$r->content_type('text/html'); $r->send_http_header;

$r->print("<html><head><title>JBook</title>
</head><body>"); $r->print("<h1><a
href="/jbook">JBook</a></h1>");

# Connect to home Jabber server
my $c = Jabber::Connection->new(server => SERVER); unless
($c->connect) { $r->print("Sorry, no connection to Jabber
available at ".SERVER); $r->print("</body></html>");
return;
}

$c->auth(USER, PASS, RESOURCE);
</code>
The ''mod_perl'' mechanism hands the <tt>handler()</tt> function an
argument that is stored in a variable called <tt>$r</tt>. This is the
HyperText Transfer Protocol (HTTP) ''request'' that has been made, which
is handled by the function.

Calling the <tt>args()</tt> method on our request object gives us a list
of arguments. These arguments follow the question mark in a typical HTTP
GET request. In Figure 10-3, the URL in the Location bar is
http://www.pipetree.com/jbook. In this URL, there is neither a question
mark nor any arguments. The assignment to <tt>@a</tt> here:

<code> my @a = $r->args;
</code>
would leave <tt>@a</tt> empty.

{{Note|The first part of the URL containing the hostname is truncated by
the size of the browser window.

</code>
However, if the URL in the Location bar (shown in Figure 10-4) contained
question marks and/or arguments, such as:

<code>http://www.pipetree.com/jbook?name=&first=&last=adams&amp
;nick=&email=
</code>
the arguments that <tt>@a</tt> would receive follow the question mark
and are separated in pairs with ampersands and further separated with
equals signs. So here, <tt>@a</tt> would receive the arguments:

<code> name, (blank), first, (blank), last, adams, nick, (blank),
email, (blank)</code> In the final URL example, shown in Figure 10-6:

<code> http://www.pipetree.com/jbook?dj@gnu.mine.nu</code> the array
received by <tt>@a</tt> is just a single element:

<code> dj@gnu.mine.nu</code> The content of <tt>@a</tt> defines which stage
of the script takes the appropriate action. Queries will be generated
in the form of IQ-gets and IQ-sets to retrieve information from the JUD
as well as to retrieve personal vCards. To do this, we need to create an
instance of a node factory, so we can build elements:

<code> my $nf = Jabber::NodeFactory->new;
</code>
After retrieving the request arguments and creating a node factory
instance, it's time to generate some HTML that will be common to all of
''Demo::JBook'''s features. The <tt>print()</tt> method will be used on
the request object <tt>$r</tt> to send a response back to the requesting
web browser:

<code>
$r->print("<html><head><title>JBook</title>&
lt;/head><body>"); $r->print("<h1><a
href="/jbook">JBook</a></h1>");
</code>
Next, we need to create a connection to the Jabber server for each
request:

<code> # Connect to home Jabber server my $c =
Jabber::Connection->new(server => SERVER); unless ($c->connect)
{ $r->print("Sorry, no connection to Jabber available at ".SERVER);
$r->print("</body></html>"); return;
}

$c->auth(USER, PASS, RESOURCE);
</code>
It will be much more efficient to create a persistent connection that
could be used to serve further requests. One way to do this is to fork a
daemon that connects to the Jabber server, acting as a proxy for this
script. Rather than make direct requests to the Jabber server,
''Demo::JBook'' is used to send the IQ elements to the daemon, which in
turn uses its persistent Jabber connection to make queries on
''Demo::JBook'''s behalf. A setup like this is shown in Figure 10-7.

[[image:jab_1007.png|Using a persistent connection to Jabber|center|350 px]] </code>

 
==== State 1: Build the JUD query form ====
 Based upon how many
arguments we have in the <tt>@a</tt> array, as described earlier, we can
build the response, which will represent one of three states:

* JUD query form
* JUD query results
* vCard display If ''Demo::JBook'' is called without arguments (i.e.,
<tt>http://[</tt>''hostname''<tt>]/jbook</tt>), which we test for like
this:

<code>if (scalar @a == 0) {
</code>
then we want to build and present the JUD search form. This form—the
fields that the form consists of—will be specific to the particular JUD
that will be searched.

We construct an IQ-get to send to the JUD to ask for a list of search
fields and instructions. What we're looking for is something like the
IQ-get shown in Example 10-1, like this:

<code>SEND: <iq type="get" to="users.jabber.org"> <query
xmlns="jabber:iq:search"/> </iq>
</code>
To construct this, we start with a new node (''element'') created by
using the node factory:

<code> my $iq = $nf->newNode('iq'); $iq->attr('to', JUD);
$iq->attr('type', IQ_GET); $iq->insertTag('query', NS_SEARCH);
</code>
In previous recipes, we've called methods in the Jabber libraries
(<tt>Jabberpy</tt>, <tt>JabberBeans</tt>, <tt>Net::Jabber</tt>, and
<tt>Jabber::Connection</tt>) to send an element to the Jabber server.
Typically, such a method is called a <tt>send()</tt> method. Here, we
don't use a <tt>send()</tt> method. Instead, we use
<tt>Jabber::Connection</tt>'s <tt>ask()</tt>. Like
<tt>Net::Jabber</tt>'s <tt>SendAndReceiveWithID()</tt> method, and
<tt>Jabberpy</tt>'s method of the same name, <tt>ask()</tt> not only
''sends'' the element to the Jabber server, it waits for a reply.

A ''reply''—in Jabber terms—is a ''response'' in the form of an element
that comes back along the stream, ''with a
matching''<tt>id</tt>''attribute''. In this case, we're making an IQ-get
and are expecting a response back from the recipient of that IQ-get. One
way of expecting and handling the response would be to use a predefined
callback specified for <tt><iq/></tt> elements and send our IQ-get
with the <tt>send()</tt> method. However, this means that the script
receives the response in an element callback that's somewhat independent
of our call to <tt>send()</tt>. As well as catching the response in the
callback, we also need some way of matching it up with the original
request. Not to mention getting back on track with the flow of execution
that represented the logical sequence of events that we were in the
middle of following when we called <tt>send()</tt>.

There's an easier way, if we want to make a request and wait for the
response to that request before continuing on in the script. This way
makes use of the <tt>ask()</tt> method.

What the <tt>ask()</tt> method does is avoid the need to catch responses
in callbacks and match them up with their originating requests. It
<tt>send()</tt>s the element to the Jabber server and blocks until an
element with a matching <tt>id</tt> attribute value is received. Other
elements that might be received while waiting for the response are duly
dispatched as normal. It's not as if elements get queued up if the
response takes a moment or two to arrive. When the matching element
arrives on the stream, it is passed directly back to the caller of the
<tt>ask()</tt> method, in the same form as if it had been handed to a
callback—in object form, as an instance of a
<tt>Jabber::NodeFactory::Node</tt> object, in this case.

<code>my $result = $c->ask($iq);
</code>
So here, <tt>$result</tt> receives the response to the
<tt><iq/></tt> element just sent. This response will look
something like this:

<code>RECV: <iq from='users.jabber.org' id='43'
to='jbook@gnu.mine.nu/jbook' type='result'> <query
xmlns='jabber:iq:search'> <nick/> <first/> <email/>
<last/> <instructions> Fill in a field to search for any
matching Jabber users. </instructions> </query> </iq>
</code>
It's addressed to the JID that the script is using,
<tt>jbook@gnu.mine.nu/jbook</tt>. But hold on—there's something that
doesn't look quite right here, that is, when compared to the example of
the IQ-get we just sent. Indeed—there's an <tt>id</tt> attribute in the
response. We didn't specify one in the Perl code that built the
<tt><iq/></tt> element. The <tt>ask()</tt> method did it for us.
Knowing that it's going to have to check the <tt>id</tt> attribute on
every incoming element to find a match for the element it's just sent
off for us, the <tt>ask()</tt> method makes sure that the outgoing
element actually ''has'' an <tt>id</tt> attribute. If it doesn't, it
adds one, giving it a unique value. That way, it stands a fighting
chance of returning to the caller something this side of the end of
time.

{{Note|Talking of time, if you're uneasy about calling blocking
functions in general, you can always set an <tt>alarm()</tt> to
interrupt the call after a certain length of time.

</code>
For more information on matching requests and responses, see Section 2.5
in Chapter 2.

Now let's move on to the response to IQ-get, which we now have in
<tt>$result</tt>. While we're expecting an IQ-result in response to
IQ-get, the request might not have been succesful, and we simply bail
out gracefully if it isn't, ending our connection with the Jabber
server:

<code> if ($result->attr('type') eq IQ_ERROR) {
$r->print("Sorry, no connection to the JUD available at ".JUD);
$r->print("</body></html>"); $c->disconnect; return;
}
</code>
Otherwise, we're expecting a result, containing the search fields and
some instructions. These will be contained within the query tag
qualified by the <tt>jabber:iq:search</tt> namespace (the tag is usually
called <tt>query</tt>, but here, as elsewhere in the script, we're not
taking any chances and are looking for "the first (hopefully the only!)
occurrence of a child tag qualified by the <tt>jabber:iq:search</tt>
namespace."

<code> my $info = $result->getTag('', NS_SEARCH);
</code>
An HTML form is built from the instructions and the search fields; the
instructions are retrieved with:

<code>$info->getTag('instructions')->data
</code>
which retrieves the <tt><instructions/></tt> tag and extracts its
contents.

The <tt>getChildren()</tt> method is called upon our
<tt><query/></tt> tag to discover what fields are available. For
all those fields, barring the "instructions" one, we create an input
text field:

<code> # Display the results in HTML
$r->print("".JUD."\n"
);
$r->print("".$info->getTag('instructions')->data."\n"); $r->print("<form><table>\n"); foreach my
$field ($info->getChildren) { next if $field->name eq
'instructions'; $r->print("<tr>");
$r->print("<td>".ucfirst($field->name)."</td>");
$r->print("<td><input type="text'
name="".$field->name.""></td>");
$r->print("</tr>\n");
}
$r->print("<tr><td></td><td><input
type="submit"></td></tr>\n");
$r->print("</table></form>\n");

}
</code>
Once the form has been built, the work for this stage is complete—the
form is relayed to the user, who will submit a completed form, thereby
invoking the next state.

 

==== State 2: Query the JUD ====
 The submission of the HTML form will
cause a number of name/value pairs to be passed as part of the HTTP GET
request. These names and values are captured into the <tt>@a</tt> array
as described earlier. If we have more than one entry in <tt>@a</tt>, we
know it's a form submission and must respond to that by querying the JUD
and returning the results. In this case, as we know that the contents of
<tt>@a</tt> are name/value pairs, we can view those contents as a hash,
using a new variable <tt>%a</tt>:

<code> elsif (scalar @a > 1) { my %a = @a;
</code>
Now, <tt>%a</tt> will contain entries where the keys are the names of
the search fields and the values are the values entered in the form.

In the same way that we constructed an IQ-get to query the JUD for the
search fields and instructions, we construct an IQ-set to perform the
actual query:

<code> my $iq = $nf->newNode('iq'); $iq->attr('to', JUD);
$iq->attr('type', IQ_SET); my $query = $iq->insertTag('query',
NS_SEARCH);

</code>
Using the information in <tt>%a</tt>, we insert tags for each of the
search fields for which a value was specified in the form. For example,
if only the value <tt>adams</tt> was specified, in the field
representing the <tt><last/></tt> search field, as shown in Figure
10-3, we would only want to insert:

<code><last>adams</last>
</code>
as a child of the IQ-set's <tt><query/></tt> tag:

<code> while (my($name, $val) = each(%a)) {
$query->insertTag($name)->data($val) if $val;
}
</code>
Also in a similar way to handling state 1, we make the call by using the
<tt>ask()</tt> method; the response will be received into the
<tt>$result</tt> variable as an object representation of the IQ-result
(or IQ-error) element:

<code> my $result = $c->ask($iq);
</code>
We deal simply with any error situation:

<code> if ($result->attr('type') eq IQ_ERROR) {
$r->print("Sorry, cannot query the JUD");
$r->print("</body></html>"); $c->disconnect; return;
}
</code>
otherwise proceeding to extract the <tt><query/></tt> tag from the
search result. This tag will contain the <tt><item/></tt>s
representing the JUD entries found to match the search criteria
submitted (see the response in Example 10-2):

<code> my $info = $c->ask($iq)->getTag('', NS_SEARCH);
</code>
We want to display a simple table of results, with each table row
representing an <tt><item/></tt>:

<code> my $items = 0;

$r->print("".JUD."</p&gt
;\n"); $r->print("<table border="1">\n");

foreach my $item ($info->getChildren) {
</code>
During the first iteration of the <tt>foreach</tt> loop, that is, on our
first child tag of <tt><query/></tt>, we take the opportunity to
write out a heading row, using the HTML <tt><th/></tt> (table
heading) tags:

<code> unless ($items) { $r->print("<tr>"); foreach my
$tag ($item->getChildren) {
$r->print("<th>".ucfirst($tag->name)."</th>");
}
$r->print("</tr>\n");
}
</code>
The main part of our loop translates the information found in each
<tt><item/></tt> tag:

<code><item jid='joseph@gnu.mine.nu'>
<nick>joseph</nick> <first>Joseph</first>
<email>joseph@pipetree.com</email>
<last>Adams</last> </item>
</code>
into HTML table rows, with one table cell (<tt><td/></tt>) for
each item field:

<code> $r->print("<tr>"); my $flag = 0; foreach my $tag
($item->getChildren) { unless (length($tag->data) == 0 or $flag++)
{ $r->print("<td><a
href="/jbook?".$item->attr('jid')."">");
$r->print($tag->data."</a></td>");
}
else { $r->print("<td>".$tag->data."</td>");
}
}
$r->print("</tr>\n");
</code>
In this section of the code, we also make the link between the first and
second level of the address book. The JID, specified in each
<tt><item/></tt> tag's <tt>jid</tt> attribute, is the key to the
JUD entry that the item represents and also the key to the vCard of the
user that has that JID. For each of the item lines in the table, we need
to build a selectable link to lead the user to the second level, which
allows him to view the vCard. This is what we want each link to look
like:

<code> http://www.pipetree.com/jbook?dj@gnu.mine.nu
</code>
That is, a single argument, representing the JID, specified after the
question mark. The condition:

<code>unless (length($tag->data) == 0 or $flag++)
</code>
serves to ensure that the link is made on a single, nonempty field in
the JUD item. When registering with a standard JUD, none of the fields
are compulsory, so it's quite possible for there to be missing values
returned in the search results. So we want to make sure that the
<tt><a href="...">...</a></tt> link that we build actually
surrounds some value; otherwise, it wouldn't be clickable. The
<tt>$flag</tt> variable just ensures we build only one link and not a
link for every nonempty field.

Finally, the number of items found is displayed with:

<code> $items++;
}
$r->print("</table>\n");

$r->print("$items results found");

}
</code>

 
==== State 3: Retrieve a vCard ====
 If we receive a single argument in
the request, we'll take it to be a JID, passed from the link in the
table build in the previous state, and immediately build an IQ-get to
retrieve the vCard. The JID is to be found in the first element in the
<tt>@a</tt> array—<tt>$a[0]</tt>.

<code> else {

my $iq = $nf->newNode('iq'); $iq->attr('to', $a[0]);
$iq->attr('type', IQ_GET); $iq->insertTag('vcard', NS_VCARD);
</code>
Notice how the name of the query tag in this query is not
<tt>query</tt>, but <tt>vcard</tt>. See Section 6.5.1 in Chapter 6 for
details.

The retrieval query is in the form of an IQ-get, rather than an IQ-set.
As we needed to send information in our JUD query (the search criteria),
an IQ-set was appropriate. Here, an IQ-get is appropriate as we're not
including any information to qualify our request; all we need to send is
this:

<code><iq type='get' to='dj@gnu.mine.nu'> <vcard
xmlns='vcard-temp'/> </iq>
</code>
After sending the <tt><iq/></tt> element, waiting for the
response, and checking for any errors, we extract the vCard detail and
display it:

<code> my $result = $c->ask($iq);

if ($result->attr('type') eq IQ_ERROR) { $r->print("Sorry,
cannot retrieve the vCard for $a[0]");
$r->print("</body></html>"); $c->disconnect;
return;
}
</code>
The structure of the vCard namespace is rather complicated and
long-winded, and it's common for many of the fields to remain unfilled.
So to keep the script simple, we're going to display all the top-level
fields that aren't empty:

<code> my $vcard = $result->getTag('', NS_VCARD);

print ("$a[0]\n");

foreach my $tag ($vcard->getChildren) { print
" ".$tag->name." : ".$tag->data."\n" if
$tag->data;
}

}
</code>

 
==== General handler close ====
 Once we've dealt with the possible
states, we send the closing HTML statements common to all three of them,
and disconnect from the Jabber server:

<code> $r->print("</body></html>"); $c->disconnect;

return;
</code>
At this stage, there's nothing more for the module to do. Having
discerned the state from the arguments in the URL (and thereby the
appropriate action) and having carried out that action, the module ends,
handing control back to its ''mod_perl'' host. Remembering that
''Demo::JBook'' is an Apache handler in the form of a Perl module, we
need to ensure that the module itself returns a true value (as with any
Perl module):

<code>}

1;
</code>

 
=== Notes for Improvement ===
 The ''Demo::JBook'' script is merely an
example. On top of tightening up the error and exception handling, there
are a few other things that you might want to consider doing to improve
upon it:

; Jabber connectivity
: As mentioned already, you'll probably want to improve the connection
: efficiency to the Jabber server by holding a socket open and sharing
: this connection across multiple calls to the handler.
; Choice of JUD
: The JUD to be queried is fixed; you may prefer to allow the user to
: select which JUD will be searched. What's more, selection of more than
: one JUD would allow a powerful search across public Jabber user
: directories.
; Key handling
: We've seen how a JUD is queried in Example 10-2. Some JUDs use the
: simple key-based security and pass an additional <tt><key/></tt>
: tag containing random data—a sort of session key, as described in
: Section 6.2.11 and Section 6.2.13. Any <tt><key/></tt> tag
: received from the JUD in response to an IQ-get must be sent back
: verbatim to the JUD in the subsequent IQ-set. Otherwise the search
: will fail, and you'll get a response similar to that shown in Example
: 10-7.
; Visual impact
: Last but not least, the visual impact of the end result as shown here
: (in Figure 10-3, Figure 10-4, and Figure 10-6) lacks a certain
: something. You might want to do something about that—give it a grander
: design, make it more pleasing, or at least interesting, to the eye.
: The HTML has been kept deliberately basic in this recipe, so as not to
: cloud the real theme of "Jabber without Jabber."
''Failure to return a key could cause a search to fail''

<code>RECV: <iq from='users.jabber.com' id='jud33'
to='jbook@gnu.mine.nu/jbook' type='error'> <query
xmlns='jabber:iq:search'> <error code='405'>Keys do not
match.</error> </query> </iq>
</code>
 

== XML-RPC over Jabber ==
 XML-RPC is an easy way to get software that's
running on different operating systems to be able to make and respond to
procedure calls (the "RPC" part of the name stands for "Remote Procedure
Call") over the Internet.

The basis of XML-RPC is straightforward and is described at XML-RPC's
home page (http://www.xml-rpc.com). The procedure calls, each consisting
of the name of the procedure (or ''method'') to call and a set of
arguments to go with that call and the corresponding responses, each
consisting of a set of results, are encoded in an XML-based format. The
requests and responses, so encoded, are exchanged over HTTP, carried as
the payloads of POST requests.

Example 10-8 shows a typical request in XML-RPC encoding. It's calling a
procedure called <tt>examples.getStateName</tt>, and passing a single
integer parameter with the value 41.

''An XML-RPC request''

<code><?xml version="1.0"?> <methodCall>
<methodName>examples.getStateName</methodName>
<params> <param>
<value><i4>41</i4></value> </param>
</params> </methodCall>
</code>
Example 10-9 shows a typical response to that request. The response
consists of a single string value "South Dakota."

''An XML-RPC response''

<code><?xml version="1.0"?> <methodResponse> <params>
<param> <value><string>South
Dakota</string></value> </param> </params>
</methodResponse>
</code>
The choice of the word "payload" to describe the encoded requests and
responses is significant: each request, headed with an XML declaration
(<tt><?xml version="1.0"?></tt>) and encapsulated as a single tag
(<tt><methodCall/></tt>), and each response, also headed with an
XML declaration and encapsulated as a single tag
(<tt><methodResponse/></tt>), are succinct, fully formed, and
complete parcels that have meaning independent of their HTTP carrier.

While the XML-RPC specification stipulates that these parcels be carried
over HTTP, we could take advantage of the power and simplicity of the
''encoding'' and carry procedure calls and responses over Jabber.

 
=== Jabber-RPC ===
 Jabber-RPC is the name given to the marriage of
encoding from the XML-RPC specification and Jabber as the transport
mechanism. As well as building upon a stable specification, Jabber-RPC
brings advantages of its own to the world of procedure calls over the
Internet. Many of the potential XML-RPC responders are HTTP servers
behind corporate firewalls or one-way Network Address Translation (NAT)
mechanisms and are therefore unreachable from the Internet. Substituting
Jabber as a transport gives calls a better chance of reaching their
destination. If a Jabber-RPC responder—a program that connects to a
Jabber server, is addressable by a JID, and can receive (and respond to)
XML-RPC-encoded calls—is connected to a Jabber server visible to the
Internet, then request calls have to make it only to that Jabber server,
and internal packet routing within the server will allow the parcels to
reach their destinations behind the firewall, whether those destinations
are client-based or component-based responders.

It should be clear by now that the idea of Jabber-RPC is to transport
the XML-RPC-encoded parcels in an extension, an attachment, to an IQ
element. Just as the details for a search attempt (for example of a
Jabber User Directory) are carried in an IQ-set extension qualified by
the <tt>jabber:iq:search</tt> namespace (as shown in Example 10-2), so
the Jabber-RPC method calls are carried in an IQ-set extension qualified
by a namespace of its own. This namespace is a new one and is
<tt>jabber:iq:rpc</tt>.<ref>This was decided during a session at the
JabberCon conference in August 2001 and has since been approved as a
draft protocol. More details are available at
http://www.pipetree.com/jabber/jrpc.html. </ref>

Similarly, as the results of a JUD search are returned in an IQ-result,
so Jabber-RPC method responses are returned in an IQ-result. Example
10-10 shows a simple Jabber-RPC-based method call and response, using
the same XML-RPC-encoded parcels as shown in Example 10-8 and Example
10-9.

''A Jabber-RPC request/response conversation''

<code>SEND: <iq type='set' to='responder@company-a.com/jrpc-server'
id='1'> <query xmlns='jabber:iq:rpc'> <methodCall>
<methodName>examples.getStateName</methodName>
<params> <param>
<value><i4>41</i4></value> </param>
</params> </methodCall> </query> </iq>

RECV: <iq type='result' to='requester@company-b.com/jrpc-client'
from='responder@company-a.com/jrpc-server' id='1'> <query
xmlns='jabber:iq:rpc'> <methodResponse> <params>
<param> <value><string>South
Dakota</string></value> </param> </params>
</methodResponse> </query> </iq></code> It's clear that the
parcels of XML-RPC encoding lend themselves very well to being
transported in a meaningful way over Jabber and that Jabber's ultimate
flexibility makes this possible.

The only major difference between the payloads as carried in an HTTP
POST and the payloads as carried in an <tt><iq/></tt> element is
that there's no XML declaration. It's not possible of course, when you
consider the ''context'' of the IQ elements. They're document fragments
in the XML stream between the requester (or responder) and the Jabber
server. As explained in Section 5.3, these documents are fanfared with
their own XML declaration, and any further declaration within the
document is illegal from an XML point of view.

{{Sidebar|Jabber-RPC Requesters and RespondersA quick word about
Jabber-RPC requesters and reponders. Connection to a Jabber server is
possible in two main ways, as we've seen in the recipes so far: as a
client via the JSM or as a component connected directly to the jabberd
backbone. At the simplest level, all a Jabber-RPC requester or responder
is, is something that makes a Jabber connection, sends and receives IQ
elements, and uses a ''standard'' XML-RPC library to encode, decode, and
service the requests and responses.

It doesn't matter whether the requesters and responders are built as
clients or components. One could argue that the Jabber client model fits
more naturally into the role of a requester, and the Jabber component
model fits more naturally into the role of a responder, but this isn't a
requirement. Indeed, if you're not the Jabber server administrator and
don't have access to the server configuration (to be able to insert a
<tt><service/></tt> stanza for a new component—see Section
9.3.1.1), building a Jabber-RPC responder as a Jabber client may be the
path of least resistance.

</code>

 
=== Building a Requester and a Responder ===
 Let's have a look at the
power and flexibility of Jabber-RPC and how to build requesters and
responders. We're going to build a client-based requester, in Python,
and a client-based responder, in Java. There are two great XML-RPC
library implementations for Python and Java that we'll use to do the
legwork for us. Figure 10-8 shows what we want to build.

To keep things fairly simple, we'll just implement and call something
similar to the <tt>getStateName()</tt> function already shown in the
examples: <tt>getCountyName()</tt>.

[[image:jab_1008.png|The Jabber-RPC requester and responder|center|350 px </code>
 

==== The responder: JabberRPCResponder ====
 We'll start up the Java
client-based Jabber-RPC responder (imaginatively called
''JabberRPCResponder'') specifying a handler class that is to service
the XML-RPC-encoded method calls, get it to connect to a Jabber server,
and listen for incoming Jabber-RPC requests. It will use the Helma
XML-RPC library (at http://xmlrpc.helma.org) to service incoming
requests using the handler class.

Being a Java script, we'll use the JabberBeans library. We'll need to
extend the library's capabilities to handle extensions in the new
<tt>jabber:iq:rpc</tt> namespace.

 

==== The requester: JabberRPCRequester ====
 The Python client-based
Jabber-RPC requester will also start up and connect to a Jabber server.
We'll use a different server than the one the responder is connected to;
after all, the whole point of XML-RPC and Jabber-RPC is to make the RPC
world a smaller and bigger place at the same time, through the power of
the Internet. We're going to use the Pythonware XML-RPC library
(http://www.pythonware.com/products/xmlrpc/index.htm) to encode a
<tt>getCountyName()</tt> request and decode the response.

 
=== JabberRPCResponder ===
 Let's look at the Jabber-RPC responder first.
There is a single script, called ''JabberRPCResponder'', but there are
also a number of supporting classes that we need. Let's take things one
at a time.

 

==== The RPCHandler class ====
 The Helma XML-RPC library implementation
allows you to build XML-RPC responders independent of any particular
transport by using an instance of the <tt>XmlRpcServer</tt> object,
which represents an abstraction of an XML-RPC server. You can then
construct a class—the ''handler class''—containing your methods to be
callable via XML-RPC. The calling of these methods is coordinated by the
<tt>XmlRpcServer</tt> object, which you tell about your handler class
using the <tt>addHandler()</tt> method.

This is what the handler class, called <tt>RPCHandler</tt>, looks like:

<code>// RPCHandler: A class of XML-RPC-callable methods

public class RPCHandler {

// Note: This is a "traditional" list of counties!

private String county[] = {"Bedfordshire", "Berkshire",
"Buckinghamshire", "Cambridgeshire", "Cheshire", "Cornwall",
"Cumberland", "Derbyshire", "Devon", "Dorset", "Durham", "Essex",
"Gloucestershire", "Hampshire", "Herefordshire", "Hertfordshire",
"Humberside", "Huntingdonshire", "Kent", "Lancashire",
"Leicestershire", "Lincolnshire", "London", "Middlesex", "Norfolk",
"Northamptonshire", "Northumberland", "Nottinghamshire",
"Oxfordshire", "Rutland", "Shropshire", "Somerset", "Staffordshire",
"Suffolk", "Surrey", "Sussex", "Warwickshire", "Westmorland",
"Wiltshire", "Worcestershire", "Yorkshire"};

public RPCHandler() {}

public String getCountyName(int c) { return county[c - 1];
}

}
</code>
The class has three elements:

; The list of counties
: The names of counties are stored in a simple array, <tt>county[]</tt>.
; The constructor
: We don't need to do anything in the constructor,
: <tt>RPCHandler()</tt>, as there's no requirement to manipulate objects
: directly, so the constructor remains empty.
; The single available method
: All public methods in the class are available through the
: <tt>XmlRpcServer</tt> object. Here we have a single method for the
: purposes of this recipe: <tt>getCountyName()</tt> returns the name of
: the county for the index given. When we examine the
: ''JabberRPCResponder'' script (in Section 10.2.3.3) we'll see how the
: <tt>XmlRpcServer</tt> object is instantiated and how this
: <tt>RPCHandler</tt> class is used.

 

==== The IQRPC classes ====
 <tt>JabberBeans</tt> deals with Jabber
element extensions—<tt><query/></tt> and <tt><x/></tt>
tags—using individual helper classes. We've seen this in the
<tt>HostAlive</tt> recipe in Section 8.2, where the
<tt>IQAuthBuilder</tt> class is used to construct an authorization
extension:

<code><query xmlns='jabber:iq:auth'>
<username>alive</username> ... </query>
</code>
The helper classes are oriented around namespaces. Because we have a new
namespace to deal with (<tt>jabber:iq:rpc</tt>), <tt>JabberBeans</tt>
needs to have helper classes to handle extensions in that namespace.

We need a minimum of two helper classes. We need a class that represents
an extension—a <tt><query/></tt> tag—in the <tt>jabber:iq:rpc</tt>
namespace. If we are going to construct IQ elements containing such
Jabber-RPC extensions, we also need a class to ''build'' those
extensions. The class that represents the <tt>jabber:iq:rpc</tt>
extension is called <tt>IQRPC</tt>, and the class that is the builder
for the extensions is called <tt>IQRPCBuilder</tt>.

For an example we're already familiar with, look at the steps leading up
to the authorization phase in the ''HostAlive'' script (and indeed our
''JabberRPCResponder'' script, which is shown in the next section); the
authorization IQ element is constructed as follows:

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

iqb.setType("set");

iqAuthb.setUsername(user); iqAuthb.setPassword(pass);
iqAuthb.setResource(resource);

iqb.addExtension(iqAuthb.build());
</code>
If we bear in mind that this is what we want to end up with:

<code><iq type='set'> <query xmlns='jabber:iq:auth'>
<username>...</username>
<password>...</password>
<resource>...</resource> </query> </iq>
</code>
then we can understand what's going on:

* The <tt><query/></tt> tag in the <tt>jabber:iq:auth</tt>
namespace is built with an ''authorization builder'', <tt>iqAuthb</tt>,
which is an instance of <tt>IQAuthBuilder</tt>.
* Values for the tags within <tt><query/></tt>, such as <tt><username/></tt> and
<tt><password/></tt>, are set using methods belonging to that builder class.
* The actual extension is generated with a call to the
<tt>build()</tt> method. Using <tt>addExtension()</tt>, the newly
generated extension is added to the container representing the
<tt><iq/></tt> element being constructed by the ''IQ
builder''<tt>iqb</tt>, an instance of <tt>InfoQueryBuilder</tt>.

Figure 8-3 shows the relationship between these builders and the things
they create. (For a review of what's required to authenticate with a
Jabber server, see Section 7.3.)

Although necessary, the IQRPC classes aren't the focus of this recipe
and can be found in Appendix B. They are essentially modified copies of
the classes for the <tt>jabber:iq:time</tt> namespace: <tt>IQTime</tt>
and <tt>IQTimeBuilder</tt>. They just need to be compiled and made
available in the <tt>$CLASSPATH.</tt> Putting them in the same directory
as the ''JabberRPCResponder'' script will work fine.

 

==== The JabberRPCResponder script ====
 Example 10-11 shows the
''JabberRPCResponder'' script in its entirety. In the next section we'll
take it piece by piece.

''The JabberRPCResponder Script, written in Java''

<code>import org.jabber.jabberbeans.*; import
org.jabber.jabberbeans.Extension.*; import
org.jabber.jabberbeans.util.JID; import java.net.InetAddress; import
java.util.Enumeration; import java.io.*; import helma.xmlrpc.*;

public class JabberRPCResponder implements PacketListener { private
String server = "gnu.mine.nu"; private String user = "server";
private String pass = "pass"; private String resource =
"jrpc-server";

private XmlRpcServer responder;

private ConnectionBean cb;

// Constructor
public JabberRPCResponder() { responder = new XmlRpcServer();
responder.addHandler("examples", new RPCHandler());
}

// Main program
public static void main(String args[]) { JabberRPCResponder server =
new JabberRPCResponder(); try { server.start();
}
catch (Exception e) { System.out.println("Cannot start server: " +
e.toString());
}
}

public void start() throws Exception { cb = new ConnectionBean();
InetAddress addr;

cb.addPacketListener(this);

// Connect
cb.connect(addr=InetAddress.getByName(server));

// Authenticate
InfoQueryBuilder iqb = new InfoQueryBuilder(); IQAuthBuilder iqAuthb
= new IQAuthBuilder();

iqb.setType("set");

iqAuthb.setUsername(user); iqAuthb.setPassword(pass);
iqAuthb.setResource(resource);

iqb.addExtension(iqAuthb.build());

InfoQuery iq = (InfoQuery)iqb.build();

cb.send(iq);

// Send presence
PresenceBuilder pb = new PresenceBuilder(); cb.send(pb.build());

}

// Packet listener interface:

public void receivedPacket(PacketEvent pe) { Packet packet =
pe.getPacket(); System.out.println("RECV:" + packet.toString());

if (packet instanceof InfoQuery) { Enumeration e =
((InfoQuery)packet).Extensions(); if (e.hasMoreElements()) {
Extension ext = (Extension)e.nextElement();

String request = ext.toString(); String id =
((InfoQuery)packet).getIdentifier(); JID from =
((InfoQuery)packet).getFromAddress();

ByteArrayInputStream bis = new
ByteArrayInputStream(request.getBytes()); String result = new
String(responder.execute(bis));

String response = result; int pos = result.lastIndexOf("?>");
if (pos >= 0) { response = result.substring(pos + 2);
}

IQRPCBuilder iqrpcb = new IQRPCBuilder();
iqrpcb.setPayload(response);

InfoQueryBuilder iqb = new InfoQueryBuilder();

iqb.setType("result"); iqb.setIdentifier(id);
iqb.setToAddress(from); iqb.addExtension(iqrpcb.build());

InfoQuery iq; try { iq = (InfoQuery)iqb.build();
}
catch (InstantiationException ie) { System.out.println("Build
failed: " + ie.toString()); return;
}

cb.send(iq);

}
}
}

public void sentPacket(PacketEvent pe) { Packet packet =
pe.getPacket(); System.out.println("SEND:" + packet.toString());
}

public void sendFailed(PacketEvent pe) { Packet packet =
pe.getPacket(); System.out.println("failed to send:" +
packet.toString());
}

}
</code>
 

=== Looking at JabberRPCResponder Step by Step ===
 Now let's examine the
''JabberRPCResponder'' script step by step so we can see how it works:

<code>import org.jabber.jabberbeans.*; import
org.jabber.jabberbeans.Extension.*; import
org.jabber.jabberbeans.util.JID; import java.net.InetAddress; import
java.util.Enumeration; import java.io.*; import helma.xmlrpc.*;
</code>
We need to bring in the <tt>jabberbeans</tt> classes as shown, as well
as some core Java features that we'll see used in the script a bit
later: an <tt>InetAddress</tt> to represent the Jabber server's
hostname, an <tt>Enumeration</tt> interface to access the extensions in
the incoming IQ elements, and <tt>java.io</tt> features for feeding the
XML-RPC-encoded requests to the <tt>XmlRpcServer</tt> object. We also
bring in the classes from the Helma XML-RPC library.

<code>public class JabberRPCResponder implements PacketListener {
private String server = "gnu.mine.nu"; private String user =
"server"; private String pass = "pass"; private String resource =
"jrpc-server";

private XmlRpcServer responder;

private ConnectionBean cb;
</code>
The definition of our <tt>JabberRPCResponder</tt> class looks similar to
that of the <tt>HostAlive</tt> class in Section 8.2. However, rather
than merely connecting to a Jabber server and sending packets off down
the stream, we want to ''listen'' for incoming packets—in this case, IQ
elements carrying <tt>jabber:iq:rpc</tt>-qualified payloads—and handle
them. Accordingly, we specify that our main class implements
<tt>PacketListener</tt>, a JabberBeans interface that Jabber clients use
to receive notification of incoming packets. The interface describes
three methods: <tt>receivedPacket()</tt>, <tt>sentPacket()</tt>, and
<tt>sendFailed()</tt>. We'll define our <tt>receivedPacket()</tt>
method, described later in this section, to catch and process the
incoming Jabber-RPC requests.

We're going to use an <tt>XmlRpcServer</tt> object, in
<tt>responder</tt>, to provide the translation services between our
<tt>RPCHandler</tt> class that contains the methods we want to "expose,"
and the XML-RPC-encoded requests and responses.

Naturally, we also need a JabberBeans <tt>ConnectionBean</tt>, which
we'll hold in <tt>cb</tt>.

<code> public JabberRPCResponder() { responder = new XmlRpcServer();
responder.addHandler("examples", new RPCHandler());
}
</code>
The <tt>JabberRPCResponder</tt> class constructor,
<tt>JabberRPCResponder()</tt>, will be called in the <tt>main()</tt>
method later in the script. It is used to create an instance of the
Helma <tt>XmlRpcServer</tt> object, and associate our
<tt>RPCHandler</tt> class with it, as a ''handler'' for method calls.
The <tt>addHandler()</tt> method takes two arguments: the first is the
method prefix name, such as <tt>examples</tt> in the <tt>methodName</tt>
specification:

<code><methodName>examples.getCountyName</methodName>
</code>
and the second is the object—an instantiation of our handler class—which
contains the methods that the <tt>XmlRpcServer</tt> will use to
"service" requests. In other words, the <tt>XmlRpcServer</tt> object
will determine that a call to <tt>examples.getCountyName</tt> should be
handled, as <tt>getCountyName</tt>, by the <tt>RPCHandler</tt> object.

The <tt>main()</tt> method is quite short:

<code> public static void main(String args[]) { JabberRPCResponder
server = new JabberRPCResponder(); try { server.start();
}
catch (Exception e) { System.out.println("Cannot start server: " +
e.toString());
}
}
</code>
We instantiate our <tt>JabberRPCResponder</tt> object into
<tt>server</tt> and call the <tt>start()</tt> method. Various functions
in <tt>start()</tt> can raise exceptions; we take care of them all here
with a simple <tt>catch</tt> clause and abort if necessary, rather than
include all of <tt>start()</tt>'s functions here and have multiple
<tt>try</tt> and <tt>catch</tt> statements:

<code> public void start() throws Exception { cb = new
ConnectionBean(); InetAddress addr;

cb.addPacketListener(this);

// Connect
cb.connect(addr=InetAddress.getByName(server));

// Authenticate
InfoQueryBuilder iqb = new InfoQueryBuilder(); IQAuthBuilder iqAuthb
= new IQAuthBuilder();

iqb.setType("set");

iqAuthb.setUsername(user); iqAuthb.setPassword(pass);
iqAuthb.setResource(resource);

iqb.addExtension(iqAuthb.build());

InfoQuery iq = (InfoQuery)iqb.build();

cb.send(iq);

// Send presence
PresenceBuilder pb = new PresenceBuilder(); cb.send(pb.build());

}
</code>
Most of the content of this <tt>start()</tt> function should be fairly
familiar. We instantiate a <tt>ConnectionBean</tt> and will use that, in
<tt>cb</tt>, throughout the script to send elements to the Jabber
server. Our <tt>PacketListener</tt> is added as a listener to the
<tt>ConnectionBean</tt>, causing a method of that interface
(<tt>packetReceived()</tt>) to be invoked when an incoming element
appears on the stream managed by that <tt>ConnectionBean</tt>.

In the same way as described in Section 8.2.2 in Chapter 8, we build our
IQ element to authenticate, and send it to the server with the
<tt>ConnectionBean</tt>'s <tt>send()</tt> method. We also send an
initial availability, in the form of a simple <tt><presence/></tt>
element to the server.

Having connected to and authenticated with the server and sent initial
availability, we can sit back and relax. All the subsequent activity
will be initiated by the arrival of IQ elements on the stream. As
described already, these will be made known (and available) in the form
of calls to the <tt>receivedPacket()</tt> method of the
<tt>PacketListener</tt> interface:

<code> // Packet Listener interface:

public void receivedPacket(PacketEvent pe) { Packet packet =
pe.getPacket(); System.out.println("RECV:" + packet.toString());
</code>
The method receives a <tt>PacketEvent</tt> object, which represents both
the ''event'' of a packet (an element) arriving and the packet itself,
which we retrieve into <tt>packet</tt> with the <tt>getPacket()</tt>
method. For debugging purposes, we print out what we get.

Now to determine what has actually arrived:

<code> if (packet instanceof InfoQuery) { Enumeration e =
((InfoQuery)packet).Extensions(); if (e.hasMoreElements()) { Extension
ext = (Extension)e.nextElement();
</code>
We check to see if the element is an IQ element, and, if so, we retrieve
the extensions—the <tt><query/></tt> tags—that the element
contains. Calling the <tt>Extensions()</tt> method on the
<tt>packet</tt> object returns an <tt>Enumeration</tt> of those tags.

We're expecting only one tag, and we pull that into <tt>ext</tt> using
the <tt>nextElement()</tt> method on our <tt>Enumeration</tt>.

{{Note|For the sake of simplicity, we're not checking here whether the
<tt><query/></tt> tag received is qualified by the
<tt>jabber:iq:rpc</tt> namespace. You might wish to do that in your
version.

</code>

<code> String request = ext.toString(); String id =
((InfoQuery)packet).getIdentifier(); JID from =
((InfoQuery)packet).getFromAddress();
</code>
We can pull the extension into string form, with the <tt>toString()</tt>
method, ready for passing to our <tt>XmlRpcServer</tt> object. At this
stage, <tt>ext</tt> contains the complete XML-RPC-encoded parcel,
starting with the <tt><methodCall></tt> opening tag:

<code><methodCall>
<methodName>examples.getCountyName</methodName>
<params> <param>
<value><i4>14</i4></value> </param>
</params> </methodCall>
</code>
So that we can send a response back to the requester, we need two other
things from the incoming element besides the actual request payload. In
general, when an <tt><iq/></tt> element is sent, representing a
request, either as an IQ-get or an IQ-set, the sender is expecting the
response, either an IQ-result or an IQ-error, with the ''same value'' in
the <tt>id</tt> attribute. This is so the responses, once received, can
be matched up with the original requests. So we need to store the
<tt>id</tt> value, available to us through the <tt>getIdentifier()</tt>
method of the <tt>packet</tt> object. We also need the JID of the
sender, retrieved with the <tt>getFromAddress()</tt> method, so we can
specify it in the <tt>to</tt> attribute of the IQ-result we'll be
sending back.

Now it's time to service the request:

<code> ByteArrayInputStream bis = new
ByteArrayInputStream(request.getBytes()); String result = new
String(responder.execute(bis));
</code>
With the <tt>execute()</tt> method of our <tt>XmlRpcServer</tt> object
in <tt>responder</tt>, we convert the <tt><methodCall/></tt> into
a <tt><methodResponse/></tt>, in effect. The decoding of the
XML-RPC-encoded request, the determination of which method in which
class to call (in our case it will be the <tt>getCountyName()</tt>
method in our <tt>RPCHandler</tt> class), the calling of that method,
and the encoding of the result into an XML-RPC-encoded response are all
done magically and transparently for us by <tt>XmlRpcServer</tt> (thank
goodness, or this recipe would be unbearably long!).

There's a bit of jiggling about required before we can make the
<tt>execute()</tt> call, though. The method is expecting an
<tt>InputStream</tt> object, and we've got a <tt>String</tt>. Not to
worry, we just convert it with a <tt>ByteArrayInputStream</tt>, which
can take a byte array (from <tt>request.getBytes()</tt>) and produce an
<tt>InputStream</tt> object <tt>bis</tt>. Similarly, <tt>execute()</tt>
produces a byte array, so that is converted to a <tt>String</tt> by
wrapping the call with <tt>String()</tt>.

The incoming XML-RPC-encoded request, being carried in the IQ element,
will not include an XML declaration. Luckily, the <tt>XmlRpcServer</tt>
does not mind that one is not present before decoding and dispatching
the request. It will, however, include one on the encoded response it
emits. So we must check for that and strip it off if there is one:

<code> String response = result; int pos =
result.lastIndexOf("?>"); if (pos >= 0) { response =
result.substring(pos + 2);
</code>}
Now we have everything we need to return the XML-RPC-encoded response to
the requester. It's time to call on the services of our <tt>IQRPC</tt>
classes:

<code> IQRPCBuilder iqrpcb = new IQRPCBuilder();
iqrpcb.setPayload(response);
</code>
We create an instance of the <tt>IQRPCBuilder</tt> and call the single
method <tt>setPayload()</tt> to load the XML-RPC-encoded response into
the <tt><query/></tt> tag, which is qualified by the
<tt>jabber:iq:rpc</tt> namespace. This is effectively the "extension" in
<tt>JabberBeans</tt> parlance:

<code> InfoQueryBuilder iqb = new InfoQueryBuilder();

iqb.setType("result"); iqb.setIdentifier(id);
iqb.setToAddress(from); iqb.addExtension(iqrpcb.build());

InfoQuery iq; try { iq = (InfoQuery)iqb.build();
}
catch (InstantiationException ie) { System.out.println("Build
failed: " + ie.toString()); return;
}

cb.send(iq);

}
}
}
</code>
After creating an IQ element container using an
<tt>InfoQueryBuilder</tt> and setting the appropriate attributes, we
generate the <tt><query/></tt> tag (<tt>iqrpcb.build()</tt>) and
add it to the IQ element container with <tt>addExtension()</tt>.

The <tt><iq/></tt> is then generated—it now contains our
payload—and sent back to the server, where it will be routed to the
original requester.

That's pretty much all there is to it. We have a couple of other methods
belonging to the <tt>PacketListener</tt> interface:

<code> public void sentPacket(PacketEvent pe) { Packet packet =
pe.getPacket(); System.out.println("SEND:" + packet.toString());
}

public void sendFailed(PacketEvent pe) { Packet packet =
pe.getPacket(); System.out.println("Failed to send:" +
packet.toString());
}

}
</code>
We fill these methods with debugging-style output statements for our
convenience.

 
=== JabberRPCRequester ===
 Now that we've got our Jabber-RPC responder
all set up, it's time to turn our attention to our requester,
''JabberRPCRequester'', shown in Example 10-12. This is a Python script
that uses the <tt>Jabberpy</tt> library and Pythonware's
<tt>xmlrpclib</tt> library. It's a pretty simple affair.

''The JabberRPCRequester script, written in Python''

<code>import jabber import xmlrpclib import string import sys

Server = 'qmacro.dyndns.org' Username = 'client' Password = 'pass'
Resource = 'jrpc-client' Endpoint = 'server@gnu.mine.nu/jrpc-server';
Method = 'examples.getCountyName';

county = string.atoi(sys.argv[1])

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)

request = xmlrpclib.dumps(((county),), methodname=Method);

iq = jabber.Iq(to=Endpoint, type="set') iq.setQuery('jabber:iq:rpc')
iq.setQueryPayload(request)

result = con.SendAndWaitForResponse(iq)

if result.getType() == 'result': response =
str(result.getQueryPayload()) parms, func = xmlrpclib.loads(response)
print parms[0] else: print "Could not complete call"

con.disconnect()
</code>

 
=== Looking at JabberRPCRequester Step by Step ===
 After importing the
libraries that we will need:

<code>import jabber import xmlrpclib import string import sys
</code>
we specify a number of parameters:

<code>Server = 'qmacro.dyndns.org' Username = 'client' Password =
'pass' Resource = 'jrpc-client'

Endpoint = 'server@gnu.mine.nu/jrpc-server'; Method =
'examples.getCountyName';
</code>
The script connects to the Jabber server defined in <tt>Server</tt>,
with the username defined in <tt>Username</tt>. The resource that will
be passed in the authentication request is <tt>jrpc-client</tt>. There
is as much significance in this name as there is in the name of the
resource used by ''JabberRPCResponder'' (<tt>jrpc-server</tt>): none.
It's just a useful naming convention to adopt when writing requesters
and responders.

A single parameter, which will be interpreted as the index of the county
to retrieve via the call to <tt>examples.getCountyName</tt>, is
expected.

<code>county = string.atoi(sys.argv[1])
</code>
The method expects an integer, so we convert it directly. This has a
favorable secondary effect when we come to XML-RPC encode the request;
if we hadn't called the <tt>string.atoi()</tt> function and left
<tt>county</tt> as a string, this is what the XML-RPC-encoded parcel
would have looked like:

<code><methodCall>
<methodName>examples.getCountyName</methodName>
<params> <param>
<value><string>1</string></value> </param>
</params> </methodCall>
</code>
However, this is what we really want:

<code><methodCall>
<methodName>examples.getCountyName</methodName>
<params> <param>
<value><int>1</int></value> </param>
</params> </methodCall>
</code>
In the same way as in the previous Python recipes, we connect to the
Jabber server and authenticate:

<code>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>
Now all we have to do is compose our XML-RPC-encoded request and send it
on its way to the Jabber-RPC responder, which in our case, identified
here by the JID in the <tt>Endpoint</tt> variable, is our
''JabberRPCResponder'' script.

It's time to call on the services of the XML-RPC library. We use the
<tt>dumps()</tt> function to build an XML-RPC encoding, passing the
single parameter (in a tuple, which is required by <tt>dumps()</tt>)
representing the county index and the name of the method to call:

<code>request = xmlrpclib.dumps(((county),), methodname=Method);</code> We
build the IQ-set containing a <tt><query/></tt> element in the
<tt>jabber:iq:rpc</tt> namespace, by creating an instance of an
<tt>Iq</tt> object, and calling methods to specify that namespace
(<tt>setQuery()</tt>) and insert the XML-RPC encoding as the payload
(<tt>setQueryPayload()</tt>):

<code>iq = jabber.Iq(to=Endpoint, type='set')
iq.setQuery('jabber:iq:rpc') iq.setQueryPayload(request)</code> At this
stage, we need to send it off and wait for a response. You have probably
noticed that, unlike in previous Python recipes, this script hasn't
defined or registered a callback to handle incoming elements. This is
because we're approaching the task in a slightly different way in this
script. The method used to send the element to the Jabber
server—<tt>SendAndWaitForResponse()</tt>:

<code>result = con.SendAndWaitForResponse(iq)
</code>
is the rather verbose cousin of the <tt>Jabber::Connection</tt>
library's <tt>ask()</tt> method, as described in Section 10.1.5.3. It
does "exactly what it says on the tin," namely, send the element off to
the server and block until an element is received that is deemed, by a
matchup of the <tt>id</tt> attribute values on both elements, to be the
response. If no <tt>id</tt> attribute exists on the outgoing element, it
is stamped with one (with a value unique within the current usage of the
<tt>jabber</tt> class). Both are also relations of
<tt>Net::Jabber</tt>'s <tt>SendAndReceiveWithID()</tt>.

So <tt>result</tt> receives an element object. It's an IQ element, as
that is what a response to an IQ element will be. If the call
''transport'' (as opposed to the call itself) is successful, the
response will be an IQ-result. If not, for example, if the
<tt>Endpoint</tt> that we specified doesn't exist, then the response
will be an IQ-error.

<code>if result.getType() == 'result': response =
str(result.getQueryPayload()) parms, func = xmlrpclib.loads(response)
print parms[0] else: print "Could not complete call"
</code>
Conversely, while the call transport might have succeeded, the call
itself might have failed, for example, if we had specified a nonexistent
method name in <tt>Method</tt>. However, for our purposes, we're going
to assume that the call was successful. So we grab the payload (i.e.,
the contents of the <tt><query/></tt> tag) and string it with
<tt>str()</tt>.

The <tt>loads()</tt> function of <tt>xmlrpclib</tt> is used to extract
the details from an XML-RPC-encoded parcel; it will produce two values,
which we capture in <tt>resp</tt> and <tt>func</tt>. The first is the
set of parameters, common to either a request or a response, and the
second is the method name, if it exists in the encoding. We want to
decode a <tt><methodResponse/></tt> here, so there's no method
name present, but there should be a set of parameters.

We take the first (and only) element from the set of parameters in
<tt>resp</tt> and print it out.

 

=== Jabber-RPC in Perl ===
 Exciting as this recipe might be, it's not
very visual. There are no screenshots of note to show, just a couple of
STDOUTs from two scripts started at the command line. To fix this
"problem," we're going to round this recipe off with a quick look at
Jabber-RPC in Perl. Based on the <tt>Jabber::Connection</tt> library is
a fairly new Perl library called <tt>Jabber::RPC</tt>, which sports two
modules: <tt>Jabber::RPC::Client.pm</tt> and
<tt>Jabber::RPC::Server.pm</tt>.

If you're slightly perplexed about what it takes to extend Jabber
support in Java, take a look at Example 10-13 and Example 10-14. The
first is an implementation, in Perl, of the ''JabberRPCResponder'' and
all its class periphery. The second is an implementation of our
''JabberRPCRequester''.

''A Jabber-RPC Responder in Perl''

<code>use strict; use Jabber::RPC::Server;

my @county = ("Bedfordshire", "Berkshire", "Buckinghamshire",
"Cambridgeshire", "Cheshire", "Cornwall", "Cumberland", "Derbyshire",
"Devon", "Dorset", "Durham", "Essex", "Gloucestershire", "Hampshire",
"Herefordshire", "Hertfordshire", "Humberside", "Huntingdonshire",
"Kent", "Lancashire", "Leicestershire", "Lincolnshire", "London",
"Middlesex", "Norfolk", "Northamptonshire", "Northumberland",
"Nottinghamshire", "Oxfordshire", "Rutland", "Shropshire", "Somerset",
"Staffordshire", "Suffolk", "Surrey", "Sussex", "Warwickshire",
"Westmorland", "Wiltshire", "Worcestershire", "Yorkshire");

sub getCountyName { my $county = shift; return $county[$county - 1];
}

my $server = new Jabber::RPC::Server( server => 'gnu.mine.nu',
identauth => 'server:pass', resource => 'jrpc-server', methods
=> {'examples.getCountyName' => \&getCountyName}, );

$server->start;
</code>

''A Jabber-RPC Requester in Perl''

<code>use strict; use Jabber::RPC::Client;

my $client = new Jabber::RPC::Client( server =>
'qmacro.dyndns.org', identauth => 'client:pass', resource =>
'jrpc-client', endpoint => 'dj@localhost/jrpc-server', );

print $client->call('examples.getCountyName', $ARGV[0])
|| $client->lastFault;</code>
That's it. There's no more code than that. So don't lose heart. Just use
Perl; you know it makes sense.

 

== Browsing LDAP ==
 ''Browsing'', a relatively new Jabber feature
(introduced in Section 2.9 and described through its associated
namespace in Section 6.2.5), is an extremely powerful and flexible
beast. Whereas many of the standard Jabber namespaces such as
<tt>jabber:iq:oob</tt>, <tt>jabber:iq:auth</tt>, and
<tt>jabber:iq:register</tt> busy themselves with providing context for
relatively narrow areas of information (out-of-band information
exchange, authentication, and registration, respectively),
<tt>jabber:iq:browse</tt> is a namespace that qualifies, and therefore
defines, a flexible container that can be used to carry all sorts of
information—information that is wrapped in meaning and context and that
can have virtually unlimited levels of hierarchy. What's more, it can
deliver information in a standard way that can be understood by Jabber
clients.

{{Note|As of this writing, the only Jabber client to implement browsing
is WinJab.

</code>
Put another way, it means that we can extend the scope of Jabber
deployment to areas outside what we traditionally see as the "Jabber
world." The power and simplicity of the Jabber browsing namespace design
means that we can adapt its use to whatever purpose we have in mind. As
we push out the Jabber protocol and give entities within our networks
the gift of speech and presence (in other words, give them a JID and
graft on a Jabber connection stub), we will want to identify those
entities as something more than a collection of hazy objects that sit
behind Jabber addresses.

* Want to find out about dictionaries that are reachable by Jabber?
Browse to a directory and pull out those JIDs—the dictionaries'
addresses—that are identified as ''keyword/dictionary'' JID-types.
* Want to allow your users to navigate an information hierarchy outside
the Jabber space but from within the comfort of their Jabber client?
Build a "reflector" that navigates the hierarchy on behalf of your
Jabber users and transforms it into a Jabber browsing context—by
formulating the information in <tt>jabber:iq:browse</tt> terms. Jabber
browsing is one of those oddities that is so simple and so ultimately
flexible that it's sometimes better to demonstrate it than to talk about
it. Let's have a look at what browsing can do by building ''ldapr'', a
"reflector" for information in a database accessed by the Lightweight
Directory Access Protocol (LDAP).

 

=== Building the Reflector ===
 We're going to build the reflector as a
component that connects directly to the Jabber backbone. This makes
sense, as it's a service that we'll probably want to run continuously
(and perhaps start up and shut down in conjunction with the Jabber
server itself), rather than something more transient like a client-based
'bot, for example.

Before we go any further, have a look at Figure 10-9.

[[image:jab_1009.png|Basic browsing in WinJab|center|350 px]] </code>
This figure shows WinJab's browser window, which, when first opened,
requests the top-level browse information from the Jabber server that
WinJab is connected to (<tt>cicero</tt>, in this case). This is the
information in the <tt><browse/></tt> section of the JSM component
custom configuration, as described in Section 4.4.3.8, which looks like:

<code><browse> <conference type='public' jid='conf.cicero'
name='Public Chat'/> </browse></code> We can see just one icon,
representing the Public Chat conference service.

WinJab sensibly uses this location—the Jabber server (specifically the
JSM) itself— as a starting position for browsing navigation. From the
description of <tt>jabber:iq:browse</tt> in Section 6.2.5, we know that
each element within a <tt><browse/></tt> section is identified
with a JID, in the <tt>jid</tt> attribute. Here, the Public Chat element
has a JID of <tt>conf.cicero</tt>. If we click on the element's icon in
WinJab's browser window, it would make a further browse request—an
IQ-get with an empty extension qualified by the
<tt>jabber:iq:browse</tt> namespace—''to that JID''. Thus is a browse
hierarchy descended. Example 10-15 shows what that browse request might
look like.

''Browsing to the Public Chat service''

<code><iq type='get' to='conf.cicero' id='82A'> <query
xmlns='jabber:iq:browse'/> </iq>
</code>

 
==== Identifying ldapr in the browsing hierarchy ====
 This is exactly
where our reflector service, in the form of a script called ''ldapr'',
will fit in. In the same way as we described our RSS news agent
(''newsagent'') in the JSM configuration's <tt><browse/></tt>
section, we'll now describe ''ldapr''. We add it, like this:

<code><browse> <conference type='public' jid='conf.cicero'
name='Public Chat'/> <service type='x-ldap' jid='ldap.cicero'
name='LDAP Reflector'/> </browse>
</code>
There are a couple of things to note in the definition:

; service/x-ldap
: The LDAP reflector is a service, so we use the <tt>service</tt>
: category for the tag name used to describe it. While there are already
: many subtypes defined within the <tt>jabber:iq:browse</tt> namespace
: (such as <tt>irc</tt>, <tt>aim</tt>, and <tt>jud</tt>), none of them
: matches what this service is going to offer, so in the same way as we
: invent Multipurpose Internet Mail Extensions (MIME) subtypes in the
: <tt>x-</tt> space, we specify <tt>x-ldap</tt> for the <tt>type</tt>
: attribute here.
; ldap.cicero
: Each component has a JID. In browsing, the JID is the key to
: navigation. When the icon representing this service is clicked, it's
: to this JID that the browse request is sent. To provide a smooth
: navigational path through the hierarchy, it's up to the component to
: return browse data items that are identified by JIDs appropriate for
: further navigation. We'll see what this means in the next section.

 
==== Navigating into the LDAP hierarchy ====
 Having our reflector
component defined in the JSM's <tt><browse/></tt> list makes for a
smooth transition into the reflection. We're going to navigate the LDAP
hierarchy in a similar way to what was described in Section 6.2.5.1. On
receipt of an initial browse request, ''ldapr'' must return the top
level of the LDAP hierarchy it has been set up to reflect:

<code><iq type='get' to='ldap.cicero' id='7'> <query
xmlns='jabber:iq:browse'/> </iq>
</code>
Figure 10-10 shows the LDAP hierarchy we've discussed in Section
6.2.5.1. It's part of an imaginary structure devised to represent people
and departments in an organization. The base distinguished name, or
''base DN'' (an LDAP term meaning the common suffix used in the
identifiers of all elements in a particular LDAP structure), is
<tt>dc=demo,dc=org</tt>. A DN, or ''distinguished name'', can be thought
of as a key for a particular element. Levels within the LDAP structure
are identified with DNs of ever-increasing lengths, as they get more
specific the deeper the hierarchy is descended.

[[image:jab_1010.png|The LDAP hierarchy|center|350 px]] </code> If
<tt>ldapr</tt> were to reflect this hierarchy, we want the response to
an initial browse request to return information about the
<tt>People</tt> and <tt>Groups</tt> nodes. In Example 10-16, we see what
this response looks like.

''An initial browse request elicits a reflection of the People and
Groups nodes''

<code>SEND: <iq type="get" id="B88" to="ldap.cicero"> <query
xmlns="jabber:iq:browse"/> </iq>

RECV: <iq id='B88' type='result' to='dj@cicero/basement'
from='ldap.cicero'> <query xmlns='jabber:iq:browse'> <item
jid='ldap.cicero/ou=People' name='ou=People'/> <item
jid='ldap.cicero/ou=Groups' name='ou=Groups'/> </query>
</iq>
</code>
In the response, we're returning a single level of the LDAP hierarchy.
The <tt>People</tt> and <tt>Groups</tt> nodes are represented by
<tt><item/></tt> tags, within the generic container tag
<tt><query/></tt>.

This is in slight contrast to the browse <tt><iq/></tt> elements
shown in Section 6.2.5.1, in which, effectively, two levels of hierarchy
are returned:

<code>RECV: <iq type='result' id='B89' to='dj@cicero/basement'
from='ldap.cicero'> <item name='root entry'
xmlns='jabber:iq:browse' jid='ldap.cicero'> <item name='ou=People'
jid='ou=People@ldap.cicero'/> <item name='ou=Groups'
jid='ou=Groups@ldap.cicero'/> </item> </iq>
</code>
It's really up to you to decide how many levels of information you want
each browse response to emit. It depends on circumstances (will the
requester be able to interpret multiple levels of hierarchy?) and the
type of application scenario in which you're wanting to employ Jabber
browsing. In this case, despite the difference in appearance, WinJab
will interpret the information correctly whichever way you play it.

{{Sidebar|No Query Tag?This last example looks slightly odd, because the
familiar <tt><query/></tt> tag, usually the container for
information within various IQ namespaces, is conspicuously absent. It's
actually still there in spirit, in the form of the first
<tt><item/></tt> tag, which takes the <tt><query/></tt>
tag's role in carrying the <tt>xmlns='jabber:iq:browse'</tt> namespace
declaration.

</code>
So, we've got our first two LDAP levels back. Figure 10-11 shows how
they're displayed in WinJab's browser window. The JID we've just browsed
to—<tt>ldap.cicero</tt>—is shown in the Jabber Address field. The
''People'' and ''Groups'' nodes are represented by
<tt><item/></tt> tags within the
<tt>jabber:iq:browse</tt>-qualified result; these are translated into
folder icons in the browser window.

[[image:jab_1011.png|Showing the first hierarchy level in WinJab's browser|center|350 px]] </code> The browser displays folder
icons for these nodes because we've described them using
<tt>jabber:iq:browse</tt>'s generic "holder" tag <tt><item/></tt>.
While the namespace describes many categories to represent many
different things (service, conference, user, and so on), there's not
really a category that fits the "LDAP_ hierarchy node" description. So
we plump for the generic <tt><item/></tt>, reserved specially for
such occasions.

To navigate to the next level in the hierarchy, all we do is click on
one of the icons now displayed to us. WinJab will send this next browse
request to the JID that's associated with the icon we click. In the case
of the People icon, we know from the browse result shown in Example
10-16 that the JID is <tt>ldap.cicero/ou=People</tt>. This is what that
browse request and response look like:

<code>SEND: <iq type="get" id="B105" to="ldap.cicero/ou=People">
<query xmlns="jabber:iq:browse"/> </iq>

RECV: <iq id='B105' type='result' to='dj@cicero/basement'
from='ldap.cicero/ou=People'> <query xmlns='jabber:iq:browse'>
<item jid='ldap.cicero/ou=UK, ou=People' name='ou=UK'/> <item
jid='ldap.cicero/ou=France, ou=People' name='ou=France'/> <item
jid='ldap.cicero/ou=Germany, ou=People' name='ou=Germany'/>
</query> </iq>
</code>
The results of this browse request are shown in Figure 10-12. Again,
notice the JID displayed in the Jabber Address window—it's the JID that
we've just browsed to. The JIDs that are assigned to the items displayed
here reflect the next level in the hierarchy. And so it goes on.

[[image:jab_1012.png|Showing the first hierarchy level in WinJab's browser|center|350 px]] </code>

 
==== What the reflector is actually doing ====
 Each of the JIDs that are
browsed to look like this:

<code> [''component name'']/[''relative LDAP DN'']</code> such as:

<code>ldap.cicero/ou=UK, ou=People</code> The ''hostname'' part of the
JID—<tt>[</tt>''component_name''<tt>]</tt>—is the name of the LDAP
reflector component, and the ''resource'' part of the
JID—<tt>[</tt>''relative_LDAP_DN''<tt>]</tt>—reflects the DN of the node
(minus the base DN suffix) within the LDAP structure that the
<tt><item/></tt> with that JID represents.

The crucial bit is that the <tt>[</tt>''component_name''<tt>]</tt> part
remains the same (<tt>ldap.cicero</tt>) across every call. This means
that ''all'' of the <tt>jabber:iq:browse</tt> requests made in the
navigation sequence go to the component, in this case, the ''ldapr''
script.

Once the component receives these requests, it disassembles the JID,
extracting the resource part, and uses it to query the LDAP server on
the Jabber client's behalf. It then builds a response, in the form of an
IQ-result containing the all-important
<tt>jabber:iq:browse</tt>-qualified extension, containing the results of
the LDAP query.

JIDs are used to ''convey information'' to the component, as well as to
have the request delivered to the right place.

{{Sidebar|Using JID Parts to Convey InformationThe example from Section
6.2.5.1 showed the information being conveyed as the ''user'' part of
the JID:

<code><item name='ou=People' jid='ou=People@ldap.yak'/>
</code>
This is perfectly fine, as long as the information we want to convey
doesn't contain characters deigned illegal for that part of the JID.
There are far fewer restrictions on how the resource part of a JID may
be constructed. So it should usually be your first choice of location
for piggybacking information:

<code><item jid='ldap.cicero/ou=People' name='ou=People'/>
</code>
</code>

 
=== The ldapr script ===
 While the explanation might be long, the actual
script, shown in Example 10-17, is relatively short. Written in Perl,
the ''ldapr'' script uses the <tt>Jabber::Connection</tt> library.

''The ldapr script, written in Perl''

<code>use strict; use Jabber::Connection; use Jabber::NodeFactory; use
Jabber::NS qw(:all); use Net::LDAP;

my $ldapsrv = 'cicero'; my $basedn = 'dc=demo,dc=org';

my $ldap = Net::LDAP->new($ldapsrv) or die $@;

debug("connecting to Jabber"); my $c = new Jabber::Connection( server
=> 'localhost:9389', localname => 'ldap.cicero', ns =>
'jabber:component:accept', );

unless ($c->connect()) { die "Oops: ".$c->lastError; }

debug("registering IQ handlers");
$c->register_handler('iq',\&iq_browse);
$c->register_handler('iq',\&iq_notimpl);

debug("authenticating"); $c->auth('pass');

debug("waiting for requests"); $c->start;

sub iq_browse {

my $node = shift; return unless $node->attr('type') eq IQ_GET and
my $query = $node->getTag('', NS_BROWSE);

my ($obj) = $node->attr('to') =~ /\/(.*)$/; debug("request: $obj");

my $result = $ldap->search( base => $obj ? join(',', $obj,
$basedn) : $basedn, filter => "(objectclass=*)", scope =>
'one', );

if ($result->code) { debug("search error: ".$result->error);
}
else { foreach my $entry ($result->all_entries) { my $e =
strip($entry->dn, $basedn); debug("found: $e"); my $item =
$query->insertTag(isUser($e) ? "user" : "item");
$item->attr('jid', join('/', $ID, $e)); $item->attr('name',
[split(/,/, $e)]->[0]);
}
}

$node = toFrom($node); $node->attr('type', IQ_RESULT);

$c->send($node);

return r_HANDLED;

}

sub iq_notimpl {

my $node = shift; $node = toFrom($node); $node->attr('type',
IQ_ERROR); my $error = $node->insertTag('error');
$error->attr('code', '501'); $error->data('Not Implemented');
$c->send($node); return r_HANDLED;

}

sub strip {

my ($fqdn, $basedn) = @_; my @fqdn = split(/,/, $fqdn); my
@basedn_elements = split(/,/, $basedn); return join(',', @fqdn[0 ..
($#fqdn - scalar @basedn_elements)]);
}

sub toFrom { my $node = shift; my $to = $node->attr('to');
$node->attr('to', $node->attr('from')); $node->attr('from',
$to); return $node;
}

sub isUser {

my $rdn = shift; return $rdn =~ /^cn/ ? 1 : 0

}

sub debug {

print STDERR "debug: ", @_, "\n";

}
</code>

 
=== Looking at ldapr Step by Step ===
 Taking the script step by step, we
start on familiar ground:

<code>use strict; use Jabber::Connection; use Jabber::NodeFactory; use
Jabber::NS qw(:all); use Net::LDAP;

my $ldapsrv = 'cicero'; my $basedn = 'dc=demo,dc=org';
</code>
After declaring the modules we want to use (the only one we haven't seen
so far is the <tt>Net::LDAP</tt> module that we'll need to connect to
and query an LDAP server), we define a couple of variables.
<tt>$ldapsrv</tt> is the name of the LDAP server that ''ldapr'' is going
to be reflecting, and <tt>$basedn</tt> is the base distinguished name
that will be used as the suffix in all of the LDAP queries.

If you don't have an LDAP server of your own, a number of public ones
are available that you could point this script at. The two variables
<tt>$ldapsrv</tt> and <tt>$basedn</tt> go together—make sure you specify
the correct base DN for the LDAP server you want to reflect.

{{Note|Depending on the configuration, some LDAP servers will require
you to ''bind'' to them with a username and password before you can
perform searches. To do this, you'll need to include an extra step in
this script, using the <tt>bind()</tt> method in <tt>Net::LDAP</tt>.

</code>
Having opened our connection to the LDAP server:

<code>my $ldap = Net::LDAP->new($ldapsrv) or die $@;
</code>
we then proceed to connect to the Jabber server as a component. We're
connecting to <tt>localhost:9389</tt>, which means this component script
is going to run on the same host as the Jabber server, and connect to it
on port 9389:

<code>debug("connecting to Jabber"); my $c = new Jabber::Connection(
server => 'localhost:9389', localname => 'ldap.cicero', ns
=> 'jabber:component:accept', );

unless ($c->connect()) { die "cannot connect: ".$c->lastError; }
</code>
We'll also need a <tt><service/></tt> stanza in the Jabber
server's configuration file to describe this component. The stanza in
Example 10-18 would be appropriate. Refer to Section 9.3.1.1 for more
details on connecting to Jabber as a component.

''A component instance definition for ldapr''

<code><service id='ldap.cicero'> <accept>
<ip>localhost</ip> <port>9389</port>
<secret>secret</secret> </accept> </service>
</code>
The script isn't going to do much apart from reflect
<tt>jabber:iq:browse</tt> queries as LDAP searches. Consequently, it
doesn't need to be able to handle anything apart from incoming IQ
elements:

<code>debug("registering IQ handlers");
$c->register_handler('iq',\&iq_browse);
$c->register_handler('iq',\&iq_notimpl);
</code>
The <tt>iq_browse()</tt> function is where all the work will be done. As
in the <tt>newsagent</tt> recipe (Section 8.3)," we also have a
"catchall" function (<tt>iq_notimpl()</tt>) that cleans up any "stray"
IQ elements that it doesn't know about. Furthermore, because we aren't
registering any handlers for <tt><message/></tt> or
<tt><presence/></tt> elements, the dispatcher in
<tt>Jabber::Connection</tt> will just throw them away, leaving ''ldapr''
blissfully ignorant of them—which is what we want.

After authenticating with the server by calling the <tt>auth()</tt>
method to send the <tt><handshake/></tt> element:

<code>debug("authenticating"); $c->auth('secret');
</code>
it's time to set the main event loop going. With a call to
<tt>start()</tt>, we hand over control to <tt>Jabber::Connection</tt>,
safe in the knowledge that we have a function (<tt>iq_browse()</tt>) to
deal with the incoming requests that we're supposed to deal with, and
that we don't care a hoot about anything else:

<code>debug("waiting for requests"); $c->start;
</code>

 
==== Performing the actual reflection ====
 Now, let's move on to the
meat of the script. The main handler, <tt>iq_browse()</tt>, starts by
making sure it has an IQ element:

<code>sub iq_browse {

my $node = shift; return unless $node->attr('type') eq IQ_GET and
my $query = $node->getTag('', NS_BROWSE);
</code>
What we're looking for is an IQ-get with a
<tt>jabber:iq:browse</tt>-qualified query extension. If there isn't one,
we exit out of the function, and dispatching continues to the
<tt>iq_notimpl()</tt> function, because we didn't return the special
value represented by <tt>m_HANDLED</tt>.

If we do get a valid request, we first extract the relative DN from the
''resource'' part of the JID specified in the IQ-get's <tt>to</tt>
attribute—the JID. If the request was sent to <tt>ldap.cicero/ou=UK,
ou=People</tt>, then we extract the relative DN <tt>ou=UK,
ou=People</tt> into <tt>$obj</tt> like this:

<code> my ($obj) = $node->attr('to') =~ /\/(.*)$/; debug("request:
$obj");
</code>
Armed with a specification of what part of the LDAP hierarchy needs to
be searched, the next step is to call the <tt>search()</tt> method on
the LDAP object in <tt>$ldap</tt>:

<code> my $result = $ldap->search( base => $obj ? join(',',
$obj, $basedn) : $basedn, filter => "(objectclass=*)", scope =>
'one', );
</code>
As you can see, we're specifying three parameters in the
<tt>search()</tt> method:

; base
: This is the point within the LDAP hierarchy from which to start
: looking. We must specify this as a full DN, so we append the base DN
: (<tt>dc=demo,dc=org</tt>) to the relative DN received in the request
: to make an absolute DN:
<code>ou=UK, ou=People, dc=demo, dc=org</code>

; filter
: Specifying <tt>(objectclass=*)</tt> effectively means "look for
: anything."
; scope
: There may be many levels below the point in the hierarchy that we're
: going to start searching from. Specifying 1 for the <tt>scope</tt>
: parameter tells the search to descend only one level. After all, we
: want to return only one level back to the requester in the reflection.
: If the search failed for some reason (e.g., if a relative DN specified
: in the request didn't exist in the hierarchy),<ref>This is an easy
: error to simulate using WinJab's browser window, as the Jabber Address
: bar is (thankfully) editable. </ref> then don't bother checking the
: results. Instead, a warning debug message with the error details is
: issued:

<code> if ($result->code) { debug("search error:
".$result->error);
}
</code>
However, if the search succeeded, the results should be translated into
the <tt>jabber:iq:browse</tt> extension:

<code> else { foreach my $entry ($result->all_entries) { my $e =
strip($entry->dn, $basedn); debug("found: $e"); my $item =
$query->insertTag(isUser($e) ? "user" : "item");
$item->attr('jid', join('/', $ID, $e)); $item->attr('name',
[split(/,/, $e)]->[0]);
}
}
</code>
Calling the <tt>all_entries()</tt> method on the search results returns
a list of LDAP entries, in the form of objects. Calling the
<tt>dn()</tt> method on one of these objects (in <tt>$entry</tt>)
returns us its full DN. Searching with a <tt>base</tt> of:

<code>ou=UK, ou=People, dc=demo, dc=org
</code>
in the demonstration database would return two entries:

<code>cn=Janet Abrams, ou=UK, ou=People, dc=demo, dc=org cn=Paul
Anthill, ou=UK, ou=People, dc=demo, dc=org
</code>
The task of this section of the <tt>iq_browse()</tt> function is to turn
the information, in the form of these two entries, into something like
this:

<code><iq id='B25' type='result' to='dj@cicero/basement'
from='ldap.cicero/ou=UK, ou=People'> <query
xmlns='jabber:iq:browse'> <user name='cn=Janet Abrams'
jid='ldap.cicero/cn=Janet Abrams, ou=UK, ou=People'/> <user
name='cn=Paul Anthill' jid='ldap.cicero/cn=Paul Anthill, ou=UK,
ou=People'/> </query> </iq>
</code>
which in turn should be rendered into something like the contents of
WinJab's browser window as shown in Figure 10-13.

[[image:jab_1013.png|Showing the third level of hierarchy in WinJab's browser window|center|350 px]] </code> The function <tt>strip()</tt>
takes two arguments and strips away a base DN from a fully qualified DN
to leave the significant, relative part. Calling <tt>strip()</tt> on
this:

<code>cn=Janet Abrams, ou=UK, ou=People, dc=demo, dc=org
</code>
when specifying the base DN in <tt>$basedn</tt>, would return this:

<code>cn=Janet Abrams, ou=UK, ou=People
</code>
For each of the entries found, we insert a tag into the
<tt><query/></tt> extension. The name of the tag is either
<tt>item</tt>, if the entry is simply an LDAP hierarchy node, or
<tt>user</tt> (a valid <tt>jabber:iq:browse</tt> category), if the entry
points to a person. We make the decision on the basis of the first part
of the DN—if it's <tt>cn=</tt>, then it's a reference to a person. The
<tt>isUser()</tt> function makes this decision for us.

Once inserted, we embellish the <tt><item/></tt> or
<tt><user/></tt> tag with <tt>name</tt> and <tt>jid</tt>
attributes. The <tt>jid</tt> attribute is crucial, as it represents the
path to further descend within the LDAP hierarchy on the next request.
It is given the whole of the relative DN as a value. The <tt>name</tt>
attribute is simply given the most significant portion of the DN as a
value.

Whether we found something or not, we still want to return a result to
the requester:

<code> $node = toFrom($node); $node->attr('type', IQ_RESULT);

$c->send($node);
</code>
So we swap around the <tt>to</tt> and <tt>from</tt> attributes
(remembering we're a component, and not a client) change the IQ
element's type from <tt>get</tt> to <tt>result</tt>, and send it back.

We end the function by telling the dispatcher that the element has been
handled:

<code> return r_HANDLED;

}
</code>

 
==== Supporting functions ====
 The rest of the script consists of minor
functions that play roles in assisting the core <tt>iq_browse()</tt>.

The <tt>iq_notimpl()</tt> function is exactly the same as in the
newsagent script in Section 8.3; it serves to catch stray IQ elements
that in this case aren't IQ-gets containing a <tt>jabber:iq:browse</tt>
query, and send them back with a "Not Implemented" error. With IQs, this
is preferable to not responding at all, as responses are usually
expected, even if those responses are IQ-errors. It's different with
<tt><message/></tt> and <tt><presence/></tt> elements, as
they can be seen as "one-way" and valid fodder for an element-sink.

<code>sub iq_notimpl {

my $node = shift; $node = toFrom($node); $node->attr('type',
IQ_ERROR); my $error = $node->insertTag('error');
$error->attr('code', '501'); $error->data('Not Implemented');
$c->send($node); return r_HANDLED;

}
</code>
The <tt>strip()</tt> function, as described already, removes a base DN
from a fully qualified DN:

<code>sub strip {

my ($fqdn, $basedn) = @_; my @fqdn = split(/,/, $fqdn); my
@basedn_elements = split(/,/, $basedn); return join(',', @fqdn[0 ..
($#fqdn - scalar @basedn_elements)]);
}
</code>
As well as sharing the <tt>iq_notimpl()</tt> function with the
''newsagent'' script, ''ldapr'' also shares the <tt>toFrom()</tt>
function, which flips around the values of the <tt>to</tt> and
<tt>from</tt> attributes of an element:

<code>sub toFrom { my $node = shift; my $to = $node->attr('to');
$node->attr('to', $node->attr('from')); $node->attr('from',
$to); return $node;
}
</code>
The <tt>isUser()</tt> function, also described earlier, makes an
arbitrary distinction between LDAP nodes that it thinks are
<tt>People</tt> and those that it thinks aren't:

<code>sub isUser {

my $rdn = shift; return $rdn =~ /^cn/ ? 1 : 0

}
</code>
Last but not least, we have a simple <tt>debug()</tt> function, which in
this case is simply an abstraction of the classic "print to STDERR"
method:

<code>sub debug {

print STDERR "debug: ", @_, "\n";

}
</code>

 
== Building an ERP Connection ==
 To some extent, SAP's R/3, an
Enterprise Resource Planning (ERP) system, has until recently been a
monolithic piece of software, both from an actual and psychological
perspective.

The drive to replace disparate and incompatible business system
"islands" with an integrated software solution that covered business
processes across the board was strong in the 1980s and 1990s. With good
reason. For example, SAP delivered the ability for companies to manage
their different end-to-end processes coherently, without requiring
custom-built interfaces between logistics and financial accounting
packages. The flow of information was automatic between the application
subsystems that were standard within SAP's R/2 and R/3 products.

The upside to this was, of course, the seamless integration of data and
functions within the SAP universe, a universe vast enough to offer
application coverage for pretty much every conceivable business
function.

The downside was, ironically, the universe itself. All-encompassing as
SAP's products were, and indeed they were forever changing and expanding
to meet business demands, it was never enough, if you wanted to break
out of the mould formed by the omnipresent standard proprietary client
called SAPGUI. Sure, these days, with a huge installed base of R/2 and
R/3 systems in production around the world, there are a multitude of
ways to get data in and out of SAP systems, but despite the varied
successes of alternative client initiatives, user interaction with the
business processes remains largely orientated around the SAPGUI.

This recipe is extremely simple compared to the others in this chapter.
It breaks out of the SAPGUI mold and the monolithic software culture to
use open source tools and technologies to add value to our SAP business
processes. The point of this recipe is not particularly what the script
looks like or how it's written, but what it does and how it does it.

 
=== Building an Order Approval Notification Mechanism ===
 We're going to
use a standard Jabber client as an SAP R/3 client—obviously not to
replace SAPGUI, rather to allow someone who perhaps has a single
R/3-related task to perform and connects only to SAP occasionally. In
stark contrast to the SAPGUI client, an off-the-shelf Jabber client is
much smaller. It takes up less screen space, memory, and CPU and
generally for focused access is a great way for someone to play his part
in business processes from the comfort of familiar communication
surroundings—his IM client.

Of course, the available Jabber clients don't have any built-in R/3
functionality per se, but as clients that can receive messages and
recognize URLs,<ref>This recognition is a client feature, not
necessarily related to the XHTML namespace described in Section 6.5.2.
</ref> they provide enough horsepower for us to achieve our goal.

That goal is to notify a supervisor whenever a sales order is placed
that requires his approval. The notification will arrive in the form of
a <tt><message/></tt> element, carrying some descriptive text and,
crucially, a URL, which points to an Apache-based handler. When invoked,
the handler pulls the relevant information for the order out of R/3,
requests verification of the viewer's identity, and offers a chance to
approve the order with the click of a button.

Effectively we're building a miniworkflow scenario: in one direction a
notification is transmitted out of the bounds of the SAP universe to the
approver, and in the other direction the notification process is turned
around in a one-step approval cycle via Apache. Figure 10-14 shows this
scenario and where our Jabber client and script, called ''approv'', fits
in.

[[image:jab_1014.png|An external order approval workflow|center|350 px]] </code> The goal here is to get the
notification message out of R/3 and send it to the supervisor's JID
along with a URL that he can follow back into the R/3 system to carry
out the approval process. The return process via Apache is outside this
recipe's scope and has been left as an exercise for you.

 
==== Getting the notification out of R/3 ====
 As we've already
mentioned, there are many ways of getting data in and out of SAP. We're
going to use a generic, lowest common denominator feature of the R/3
Basis system to invoke a script and pass it parameters.

{{Note|At this stage, if you're squeamish about R/3 Basis or SAP's ABAP
language or are of another ERP persuasion, it's time to look away. What
we're going to do here is not rocket science, nor is the general process
specific to R/3. We're just going to call a script, at the operating
system level, from within an application inside R/3.

</code>
The function group <tt>SXPT</tt> encompasses a number of function
modules related to the definition, management, and execution of
operating system commands. Each of these commands is described within
sets of configuration parameters that define how and where they can be
invoked. Using the program ''RSLOGCOM'', you can create definitions for
these operating system commands manually.

We need to define such a command that refers to the ''approv'' script.
Figure 10-15 shows the ''RSLOGCOM'' definition of ''approv'' as an
external command that is called <tt>ZNOTIFY</tt>.

[[image:jab_1015.png|Defining approv as an external command with RSLOGCM|center|350 px]] </code> Once ''approv'' has been defined
this way, it can be invoked by passing parameters with a call to a
function module in the <tt>SXPT</tt> function group
(<tt>SXPG_EXECUTE_COMMAND</tt>). Example 10-19 shows how the script
might be invoked using this function module in ABAP. Code like this
could typically be installed in a ''customer exit''—a place in a
standard R/3 application where custom processing can be added without
having to go through the involved process of creating and carrying out a
modification request.

''Calling approv, via ZNOTIFY, from within R/3''

<code>data: sxpg_exec_protocol like btcxpm occurs 0 with header line,

sxpg_add_parms like SXPGCOLIST-PARAMETERS,

sxpg_target_system like RFCDISPLAY-RFCHOST value 'gnu.mine.nu'.

concatenate ordernumber approver into sxpg_add_parms separated by space.

call function 'SXPG_COMMAND_EXECUTE' exporting commandname =
'ZNOTIFY' additional_parameters = sxpg_add_parms operatingsystem =
sy-opsys targetsystem = sxpg_target_system stdout
= 'X' stderr = 'X' terminationwait = 'X' table
exec_protocol = sxpg_exec_protocol exception others
= 1.

if sy-subrc <> 0. raise notification_failed. endif.
</code>
We pass two parameters to ''approv'' via the
<tt>SXPG_COMMAND_EXECUTE</tt>: the number of the order that needs
approving (from <tt>ordernumber</tt>) and the JID of the approver (from
<tt>approver</tt>). The SXPG mechanism invokes the ''approv'' script
with the two parameters, and the notification starts its journey.

 

=== The approv Script ===
 As mentioned already, the ''approv'' script
(shown in Example 10-20) is rather small and insignificant. Its purpose
is to take the order number it receives, wrap it in a descriptive
message that includes a URL, and send it to the approver's JID. Written
in Perl, the ''approv'' script uses a minimum set of features from the
<tt>Jabber::Connection</tt> library.

''The approv script, written in Perl''

<code>use strict; use Jabber::Connection;

my ($order, $approver) = @ARGV; my $c = new Jabber::Connection(server
=> 'qmacro.dyndns.org'); die "Cannot connect: ".$c->lastError
unless $c->connect(); $c->auth('approv','secret','approv');

$c->send(<<EO_MSG); <message to="$jid">
<subject>Order Approval Required</subject> <body> An
order ($order) requiring your approval has been placed. Please visit
http://qmacro.dyndns.org/approv?$order to approve.

Thank you. </body> </message> EO_MSG

$c->disconnect;</code> The script receives the two parameters passed from
R/3 into the <tt>$order</tt> and <tt>$approver</tt> variables. Having
connected to the Jabber server at <tt>qmacro.dyndns.org</tt> and
authenticated as the user <tt>approv</tt>, it sends off a formatted
message to the approver, before disconnecting.

The script itself is extremely simple and is not of primary importance.
What is crucial here is the role that Jabber is playing. The
<tt><message/></tt> element of Jabber's protocol is used to span
the R/3 world with the IM world, enabling a business process cycle to
take place ''outside'' the normal boundaries of R/3 interaction. On a
simple level, that's all it takes to merge the ERP business process
world with the world of IM.

The return path to R/3, via the Apache-based CGI application, is
initiated when the user clicks on the URL in the message, as shown in
Figure 10-16.

[[image:jab_1016.png|Receipt of an order approval request in Jarl|center|350 px]] </code> Here we see that Jarl has
recognized the ''http://'' address and has rendered it as an active
link. That's all it has to do. There's no attempt on Jarl's part to make
an HTTP request to the Apache server and render the HTML received.
Focusing on "the right tools for the right job," we should leave that
role to a web browser, as indeed Jarl does, starting up the browser of
our choice.<ref>Specified in Jarl's configuration options. </ref>

 

=== Taking This Further ===
 The journey through the recipes in the last
three chapters of the book has taken us from the simplest CVS
notification mechanism with the ''cvsmsg'' script (Section 8.1) through
a fairly involved RSS component (Section 9.3) to the transporting of
XML-RPC-encoded requests and responses with our ''JabberRPCRequester''
and ''JabberRPCResponder'' scripts (Section 10.3).

This chapter, and indeed the book, ends on a simple note, in the form of
the ''approv'' script. Not without reason, we've completed the circle of
script and application complexity. While we can build very useful and
successful applications that are naturally complex, a Jabber-powered
solution doesn't necessarily have to be. To employ the Jabber
philosophy, the technology, and the protocol elements to build bridges
between previously separate systems, and to span different areas of
technology, open and proprietary alike, using Jabber's open, extensible,
and flexible protocol, is what it's all about.

Finally, it's hopefully clear from the diversity of recipes shown in
this part of the book that deploying solutions with Jabber, as noted in
the preface, really ''is'' fun!

←Older revision		Revision as of 01:33, 26 July 2010
Line 389:		Line 389:

	# No arguments: Instructions		# No arguments: Instructions
-	if (~~scalar~~ @a ~~== 0~~) {	+	if (!@a) {

	# Construct IQ-get in iq:search namespace		# Construct IQ-get in iq:search namespace
Line 514:		Line 514:

	$r->print("</body></html>"); $c->disconnect;		$r->print("</body></html>"); $c->disconnect;
-		+
	return;		return;

Line 523:		Line 523:

	<br>		<br>
		+
	=== Taking Demo::JBook Step by Step ===		=== Taking Demo::JBook Step by Step ===
	<br>Now that we've got a hold on the		<br>Now that we've got a hold on the

←Older revision		Revision as of 14:23, 18 September 2009
Line 1:		Line 1:
		+	{{Content Programming Jabber}}
	=Pointers for Further Development=		=Pointers for Further Development=
	<br>The previous two chapters have demonstrated		<br>The previous two chapters have demonstrated

←Older revision		Revision as of 22:28, 16 September 2006
Line 108:		Line 108:


-	[[image:jab_1001.png\|Searching the JUD: the search form\|~~conter~~\|350 px]]	+	[[image:jab_1001.png\|Searching the JUD: the search form\|center\|350 px]]
	<br></code> The search fields are not fixed;		<br></code> The search fields are not fixed;
	instead, they're dynamically generated, according to the result of an		instead, they're dynamically generated, according to the result of an
Line 297:		Line 297:

	<br>		<br>
		+
	=== Using Demo::JBook as an Apache Handler ===		=== Using Demo::JBook as an Apache Handler ===
	<br>The ''Demo::JBook''		<br>The ''Demo::JBook''

JabChapter 10 - Revision history

Newacct: /* The Demo::JBook Script */

Newacct at 01:30, 26 July 2010

Newacct at 08:01, 10 December 2009

Uncopy: content navi added

Mikeh: /* What Demo::JBook Will Do */

Mikeh at 22:18, 16 September 2006

←Older revision		Revision as of 08:01, 10 December 2009
Line 1,890:		Line 1,890:
	''The JabberRPCRequester script, written in Python''		''The JabberRPCRequester script, written in Python''

-	<code>import jabber import xmlrpclib ~~import string~~ import sys	+	<code>import jabber import xmlrpclib import sys

	Server = 'qmacro.dyndns.org' Username = 'client' Password = 'pass'		Server = 'qmacro.dyndns.org' Username = 'client' Password = 'pass'
Line 1,896:		Line 1,896:
	Method = 'examples.getCountyName';		Method = 'examples.getCountyName';

-	county = ~~string.atoi~~(sys.argv[1])	+	county = int(sys.argv[1])

	con = jabber.Client(host=Server) try: con.connect() except IOError, e:		con = jabber.Client(host=Server) try: con.connect() except IOError, e:
Line 1,923:		Line 1,923:


-	<code>import jabber import xmlrpclib ~~import string~~ import sys	+	<code>import jabber import xmlrpclib import sys
	</code>		</code>
	we specify a number of parameters:		we specify a number of parameters:
Line 1,947:		Line 1,947:


-	<code>county = ~~string.atoi~~(sys.argv[1])	+	<code>county = int(sys.argv[1])
	</code>		</code>
	The method expects an integer, so we convert it directly. This has a		The method expects an integer, so we convert it directly. This has a
	favorable secondary effect when we come to XML-RPC encode the request;		favorable secondary effect when we come to XML-RPC encode the request;
-	if we hadn't called the <tt>~~string.atoi~~()</tt> function and left	+	if we hadn't called the <tt>int()</tt> function and left
	<tt>county</tt> as a string, this is what the XML-RPC-encoded parcel		<tt>county</tt> as a string, this is what the XML-RPC-encoded parcel
	would have looked like:		would have looked like: