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;

Jabberwocky

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

Openfire

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.

Glassfish

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…
Trying 127.0.0.1…
Connected to localhost.
Escape character is ‘^]’.

Felix Remote Shell Console:
============================

-> find xmpp
START LEVEL 1
   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
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: com.kenai.jabberwocky.example.weather.WeatherComponent
    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.xar

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.xar

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