Getting Started with JXTA for J2ME

Print-friendly Version

JXME Chat Application

Devices in a peer-to-peer (P2P) network talk directly to each other instead of using central servers. The traditional approach to computing on the World-Wide Web is a star pattern of client computers grouped around a central server. In P2P networks devices connect directly to each other, forming a flexible, decentralized network fabric.

The P2P model is particularly interesting to wireless developers because it enables them to assemble ad hoc networks quickly, without imposing configuration chores on users. In the wired world, networking is somewhat stable and dependable. Wireless networking is usually less reliable because it's subject to the vagaries of electromagnetic wave propagation, interference, and battery exhaustion. Devices may come and go without warning or visible reason. P2P networking provides a model that is well suited to the vicissitudes of wireless devices.

In this article, you'll learn about a set of protocols for P2P networking called JXTA (the name is derived from the word "juxtapose"), how these protocols are extended to MIDP, and how to install and run JXTA demonstration programs for MIDP.

Introduction to JXTA

The JXTA 1.0 protocols support various aspects of P2P networking, including the discovery of other computers and services and the ability to exchange information or invoke services.

The JXTA specifications are simply communications protocols; they do not mandate particular hardware or software. The protocols are being implemented in many different languages. Two complete implementations are available, one written in the Java programming language, the other in C.

JXTA peers communicate by exchanging XML messages. Messages called advertisements announce the availability of a peer.

The JXTA protocols and reference implementation are developed by an open community. For more details about JXTA, see:

• JXTA Home Page
• Brendon Wilson's free book about JXTA

Introduction to JXTA for J2ME

The goal of the JXME project is to bring JXTA functionality to MIDP devices. Several requirements in the JXTA protocols make it hard to implement on MIDP:

• Because JXTA messages are in XML, a peer must include an XML parser. Although it is possible to parse XML in MIDP, an XML parser pushes at the memory limits of MIDP devices.
• The state of the network needs to be cached, which essentially means that advertisements for peers and other JXTA entities must be saved, further straining the limited memory MIDP devices afford.
• JXTA peers listen for incoming network information at the socket and datagram level. MIDP mandates support for HTTP, but socket and datagram connections are optional.

Because the basic requirements of the JXTA protocols exceed the minimum requirements of MIDP, the JXME architecture relies on a JXTA relay to do most of the heavy lifting. The JXTA relay is the true JXTA peer; it participates in the JXTA network on behalf of one or more J2ME devices. Connected devices use a simplified protocol, and exchange HTTP-based binary messages with the JXTA relay.

Running the Examples

"Enough yappin'!" you say. "Get to the good stuff." There are two ways to run the JXME demonstrations. This section describes how to download the built applications (binaries) and run them using the J2ME Wireless Toolkit. If you want to get your hands a little dirtier, read the next section to learn how to download the source code, and build and run the examples yourself.

To run the JXME demonstrations, you will need to have installed the J2ME Wireless Toolkit.

Download jxme.zip and unzip it in the location of your choice. The resulting midp/demo/chat/dist directory contains the chat application, packaged as chat.jad and chat.jar. From the J2ME Wireless Toolkit, simply double-click on chat.jad to start the application in the MIDP emulator. That's it.

Note that two other demonstrations are included: a Tic-Tac-Toe MIDlet, which should also be double-clickable, and a chat implementation for Personal Profile clients. While you are welcome to experiment with these, this article discusses only the chat application for MIDP.

If you don't want to find out how to obtain the JXME source code, skip ahead to the section on Using the Chat Demonstration.

Tooling Up

Building the JXME demonstrations requires some finesse on your part. You'll need to become a member of the JXME project, then obtain the source code, then build and run the examples. If this sounds like too much work, go back to the preceding section and run the binaries instead.

The following instructions are an expanded version of the build instructions at the JXME web site. If you're already adept with Apache's Ant build utility, the CVS source-code control system, and J2ME, you may want to follow the more concise instructions instead of stepping through the rest of this article.

Joining the JXME project is simple enough. First, you'll need to register to be a member of Project JXTA. Browse to the JXME home page, and in the left column find the Developer Resources folder. Click on the Join Project JXTA link. You'll need to choose a user name and to supply an email address and your real name.

Once you're logged in as a member of Project JXTA, navigate back to the JXME home page. You will see a link for Join This Project on the right side of the page. Click on this link and follow the directions. Most likely you will want to join as a Contributor.

To obtain and build the source code, you'll need the following tools:

• J2SE SDK
• J2ME Wireless Toolkit
• Ant
• A CVS client

Getting the Source Code

Linux and other Unix-like operating systems come with a cvs command-line tool you can use to obtain the source code. Windows users can follow my instructions for using WinCvs 1.2.

When WinCvs first starts, it will ask you for a CVSROOT, which is essentially the location of the files you want. Enter the following:

:pserver:<username>@cvs.jxta.org:/cvs

Just below the CVSROOT box, change Authentication to "password" file on the cvs server.

Next, log in to the CVS server. In WinCvs, choose Admin > Login. Type your password. If everything goes well, a message will tell you CVS exited normally.

Create a directory on your local disk to hold the JXME source. Then, in WinCvs, choose Create > Checkout Module. Specify the module name to be jxme/midp, and in Local folder to checkout to supply the name of your local directory. WinCvs will chug along for a while as it downloads the source tree. When it's finished, choose Admin > Logout, then quit WinCvs.

Building and Running the Source Code

Before you can build and run the chat demonstration using Ant, you need to define some environment variables. The chat build script uses JAVA_HOME, ANT_HOME, and MIDP_HOME.

• JAVA_HOME points to the J2SE installation on your computer. On my computer, it's set to \j2sdk1.4.0.
• ANT_HOME is the location of Ant. (The build script needs to know where to find Ant so it can install a custom task.) On my computer, the value is \jakarta-ant-1.4.1.
• The build script uses MIDP_HOME to locate the preverify tool it runs during the build, and Ant uses the same variable to find the emulator it uses to run the application.

Once all the environment variables are defined, open a command-line window and navigate to jxme\midp. Install the custom Ant build action:

ant tools

You have to do this step only once. Next build the JXME projects:

ant

Now move to jxme\midp\demo\chat. Use Ant to run the chat example:

ant run

Using the Chat Demonstration

When the emulator window first pops up, it shows the name of a single MIDlet, JxtaMidpChat. Launch the MIDlet. You'll see a mostly empty screen. From the menu choose the Configuration command. You can accept most of the default settings, but you'll probably want to specify an Identity. This is a name that will be used to identify you to other chat users.

When you're finished with the settings, select OK. You will see a screen titled Buddy List. This screen lists groups. Just select the default, IP2PGRP, and then choose the Chat command to return to the main screen. Then choose Connect from the menu. The chat client will connect to the relay server and return to the main screen. You are now connected to the JXTA network and can exchange messages with people on all types of JXTA clients. Thanks to the relay server, your emulator is part of the JXTA network.

Digging Deeper into P2P

If the P2P bug has bitten you, there are several other aspects of JXTA you might want to think about:

• If no one else is eager to chat with you, you can run the JXME chat application in two instances of the emulator and send messages between them. You may wish to change the identity on one of them to convince yourself it's working.
• You can also chat between the JXME chat application and instantp2p. The instantp2p application is a GUI interface to the JXTA network that supports chatting and file sharing. Note that you should configure instantp2p to use the same relay server as the JXME chat application. Although it is possible in theory to use different relay servers, messages may take a long time to travel from one device to another. Another possible chat client is chat-pp, a chat application designed for devices supporting the Personal Profile. The Sharp Zaurus is one example of such a device. See Java Programming on the Sharp Zaurus for more information.
• The JXME project has a very simple API, comprising just three classes.  The chat application and the Tic-Tac-Toe application demonstrate the use of the API, which is documented online. Two tutorial examples are provided.

Summary

JXME introduces you to a whole new world of possibilities. P2P networking offers a decentralized network fabric. JXTA furnishes an XML-based, platform-independent set of protocols that enable P2P networking, and the JXME project brings JXTA functionality into the MIDP world. This article also described how to run the JXME chat application, either by downloading binaries or by downloading and building the source code.