Installing, Configuring and Deploying components to Jabberwocky

Last week I talked about a project I was working on call Jabberwocky which is a runtime container for XMPP components (XEP-0114). At the end of the post, I provided a pre-alpha binary for those brave enough to try it; I also promised to provide a detail write of of installing, configuring and deploy components in my next blog. So here we are;


Get the Jabberwocky version 0.1 or later bundle from here. The unzipped bundle contains the following

  • jabberwocky_support.jar, xmpp-gf-container.jar – these files are the container
  • weather.xar, uppercase.xar – these are the sample application
  • readme.txt – a simplified installation instruction


In theory Jabberwocky should would with any XMPP server that supports XEP-0114 but I’ve only ever tested it with Openfire. For the rest of this post, I’ll be using Openfire. You can download a copy from here and install it.


We will also need a copy of Glassfish application server. Download a copy of Glassfish from here and install it. Make sure you get v3.0.1.

Copy jabberwocky_support.jar and xmpp-gf-container.jar into $GF_HOME/glassfish/modules directory where $GF_HOME is Glassfish’s installation directory.

Add $GF_HOME/bin to your PATH variable.

Create a new domain to test Jabberwocky. To create a domain call mydomain in /opt/tmp directory, run the following command

asadmin create-domain –domaindir /opt/tmp mydomain
Using default port 8080 for HTTP Instance.
Using default port 7676 for JMS.
Using default port 3700 for IIOP.
Using default port 8181 for HTTP_SSL.
Using default port 3820 for IIOP_SSL.
Using default port 3920 for IIOP_MUTUALAUTH.
Using default port 8686 for JMX_ADMIN.
Using default port 6666 for OSGI_SHELL.
Distinguished Name of the self-signed X.509 Server Certificate is:
[CN=batcomputer,OU=GlassFish,O=Oracle Corporation,L=Santa Clara,ST=California,C=US]
No domain initializers found, bypassing customization step
Domain mydomain created.
Domain mydomain admin port is 4848.
Domain mydomain allows admin login as user “admin” with no password.
Command create-domain executed successfully.

Start the domain with the following command

asadmin start-domain –domaindir /opt/tmp mydomain
Waiting for DAS to start …
Started domain: mydomain
Domain location: /opt/tmp/mydomain
Log file: /opt/tmp/mydomain/logs/server.log
Admin port for the domain: 4848
Command start-domain executed successfully.

Just to be on the safe side, we will verify that Glassfish has loaded our container. Note the OSGI_SHELL port number 6666. telnet to that port and type find jabberwocky at the prompt as below

telnet localhost 6666
Trying ::1…
Connected to localhost.
Escape character is ‘^]’.

Felix Remote Shell Console:

-> find xmpp
   ID   State         Level  Name
[ 221] [Resolved   ] [    1] jabberwocky_support (0)
[ 222] [Active     ] [    1] XMPP Container for Glassfish V3 (1.0.0.SNAPSHOT)
-> exit

If you see the above 2 lines, this means that Glassfish has successfully registered Jabberwocky.

Initializing Jabberwocky

Create a default configuration for Jabberwock by executing the following command

asadmin create-xmpp-configuration
Configuration created

The configuration is created in /opt/tmp/mydomain/conf/domain.xml file. List the configuration with the following command

asadmin list-xmpp-configuration
Current configuration

Container configuration
    Initial worker threads: 25
    Maximum worker threads: 25
    Keep alive time for idle worker threads when exceeds initial: 15,000 ms
    Keep alive time for connection: 30,000 ms
NIO configuration
    I/O poll time: 3,000 ms
    IQ reply timeout: 1,000 ms
    I/O buffer size: 8,192 bytes

Command list-xmpp-configuration executed successfully.

The configuration defines how many work thread to create, buffer size for I/O, timeouts, etc. These are all tunables.

You only need to perform this step once.

Configuring Domain and Subdomain

To setup Openfire and Jabberwocky to run the example applications, you’ll now need to create subdomains and shared secret. This is part of the requirement to deploy XMPP components. Assuming that our XMPP server is running on domain/server verona, we will be configuring the following two subdomain (and their corresponding shared secret) so that we can test out the two bundled sample application

Subdomain Shared secret
landofthegiants uppercase
weatherman willards

First you need to add the above two pieces of information into Openfire. Login to your Openfire’s administration and create the two external components. I’ve described how perform this here.

The next thing that you’ll need to do is add the above two pieces of data into Jabberwocky. First create the verona domain with the following command

asadmin create-xmpp-domain –domain verona
Domain verona:5275 created

This will add verona with the default port 5275 into domain.xml.

Now add the two subdomains landofthegiants and weatherman along with their corresponding shared secret to verona with the following command

asadmin create-xmpp-subdomain –domain verona –subdomain landofthegiants –sharedSecret uppercase
asadmin create-xmpp-subdomain –domain verona –subdomain weatherman –sharedSecret willards

Verify you have added the  domain and subdomains correctly with the following command

asadmin list-xmpp-domains

    Domain: batcomputer, Port: 5,275, Default shared secret: [not set]
        Subdomain: weatherman, Shared secret: willards
        Subdomain: landofthegiants, Shared secret: uppercase
    Domain: verona, Port: 5,275, Default shared secret: [not set]
        Subdomain: weatherman, Shared secret: willards
        Subdomain: landofthegiants, Shared secret: uppercase

Note: the batcomputer domain is a default domain installed when we run create-xmpp-configuration.

If you don’t feel like typing all the asadmin command, just go into domain.xml and add it manually .

Configure and Deploy XMPP Components

Edit the file xep-0114.xml in weather.xar and uppercase.xar. The two .xar files are just JAR archive so you can use any ZIP compatible tools to manipulate them. Change the following line

<subdomain name=… domain=’batcomputer‘ port=’5275’>

from batcomputer to verona or whatever your domain happens to be

<subdomain name=… domain=’verona‘ port=’5275’>

Re-JAR  those files and change the suffix from .jar to .xar.

Deploy the two components using the standard Glassfish deloy command

asadmin deploy uppercase.xar
asadmin deploy weather.xar

Don’t forget to keep your fingers crossed and pray that the demo Gods have accepted your offerings. If you’ve successfully deployed the applications, you can now view them with the following command

asadmin list-xmpp-components –type verbose
Deployed components

Id(*transient*): 97i63qrt, Name: weather
    Component name: US Weather
    Description: Weather component – sample component
    Domain: weatherman.verona, Port: 5,275
    Subdomain: weatherman, Key hint: subdomain
    Component class:
    Uptime: 1/12/11 5:01 PM
Id(*transient*): NN7yuxy1, Name: uppercase
    Component name: Upper case
    Description: Echos your message back to you in upper case
    Domain: landofthegiants.verona, Port: 5,275
    Subdomain: landofthegiants, Key hint: subdomain
    Component class: com.kenai.jabberwocky.example.uppercase.UppercaseComponent
    Uptime: 1/12/11 5:01 PM

Testing the Sample Components


Uppercase echos back everything that you type in uppercase. Fire up your Jabber client and start a chat with fred@landofthegiants.verona. The Jabber user can be anyone; uppercase component will ignore the user. The screenshot below shows uppercase component in action


Weather is a component that uses Google’s weather API to display the weather of a city as shown in the following screenshot.

Again weather component ignores the user part of the JID.

Undeploying XMPP Components

To undeploy both the applications use the name weather and uppercase

asadmin undeploy weather
asadmin undeploy uppercase

Currently the name defaults to the XAR bundle name (minus the .xar suffix). This may change in the future. A better way is find the deployment name is to use the  list-xmpp-components command. The component name is under the Name header shown in green above.

Also all the Jabberwocky asadmin commands can be found by executing

asadmin list-commands

Look for all the commands with xmpp in it.

In my next post, I’ll talk about how to develop and package XMPP components to run in Jabberwocky.
In the meantime, if you are interested in the source code of weather and uppercase, you can find them here. Weather implements org.xmpp.component.Component and Uppercase extends from com.kenai.jabberwocky.xmppcontainer.AbstractComponent which is a drop in replacement for org.xmpp.component.AbstractComponent.

If you are trying out Jabberwocky I’d love to hear from you. If you have found any bugs please file them at the Jabberwocky project site.

Till next time

Jabberwocky – a Jabber Component (XEP 0114) Container for Glassfish

Personally I think that writing Jabber component (XEP-0114) (in Java) should be alot easier than the current state of the art. After struggling with it and documenting my experiences in my post, I’ve decided that I would like to make it a little easier, for me at least.

So let me introduce Jabberwocky, a Jabber component container, (à la JavaEE), for Glassfish application server. The purpose of Jabberwocky, currently, is twofold:

  1. To ease the development of Jabber component by allowing developers to focus only on their component and leave the runtime environment to Jabberwocky. What this means is that you focus on writing the component by either implementing Component or extend AbstractComponent, package it in a XAR file (a regular JAR file with the suffix renamed to XAR) and deploy it, using standard Glassfish tools, to the container. You don’t have to write the ‘server’ to host your component as I’ve shown in this blog. The XAR package contains among other things the component’s class files, any dependent JARs and a deployment file.
  2. To ease the management of the components by integrating into Glassfish so what we get is out of the box start/stop/deploy/suspend/resume, configuration management, and with a little bit of work publish statistics and other management control via Glassfish’s JMX infrastructure.

There is actually a third goal, which is a stretch goal,  so lets just focus on the two that I’ve listed first.

The figure below shows how Jabberwocky is used:

You need to run an instance of Glassfish with Jabberwocky (the green box); you then deploy your component in a XAR package into glassfish (the white box). If the XAR package is successfully deployed the component will now start communicating with the XMPP server. XMPP users and other applications can communicate with the component in the usual manner.

One of the side effect of running the components in Glassfish is that you can deploy multiple XAR files; each of the component is isolated from each other. Also in order to make the container more scalable, I’ve reimplemented  igniterealtime‘s ExternalComponent and other related classes with non blocking I/O. There is a thread which polls all selectors every 2 seconds. This value is tunable.

For those of you who are keen to try out, I’ve got a pre alpha binary here. There is a readme file documenting the installation process. I’ve also included 2 examples. There will be a better release soon (next week I hope) with another posting in technicolor detail how to install.

%d bloggers like this: