With many technology pundits hailing peer-to-peer computing as a key technology for tomorrow's Internet, many Java developers have started showing interest in Sun Microsystems' Jxta, a network computing platform that holds promise as an infrastructure for peer-to-peer development. Unfortunately, Jxta is still in its early development stages. With few applications and resources available, Jxta proves difficult for an average Java programmer to master.

Perhaps the easiest way to learn Jxta is by exploring the Jxta shell, possibly the most important Jxta application available today. In Part 1 of this two-part series, I will introduce you to the Jxta shell, its installation and configuration, and its simple commands. My intent is to help you get started right away with Jxta.

In Part 2, I will discuss the shell internals and explain how to extend the shell functionality to build complex shell applications. I assume that you have had at least a brief introduction to Jxta; if not, read my previous article, "The Jxta Solution to P2P" (JavaWorld, October 2001).

Jxta shell overview

The Jxta shell is an application built on top of the Jxta Java Binding, the Jxta reference implementation in Java. The shell serves three basic purposes:

  1. It demonstrates how easily you can build a meaningful application on top of Jxta.
  2. It acts as a valuable reference for developers on how to use the Jxta APIs. Whenever I am confused about the API usage, I refer to the shell source code and, more often than not, find my answer painlessly.
  3. It serves as an environment where developers can directly interact with the Jxta platform without any programming. Thus, developers can get the concepts right even before they write any source code.

Developers interact with the shell through user commands called shell commands. The shell acts as an interpreter. First, the shell waits for a user command. Then, upon receiving the command, the shell executes it and waits for the next command. During the wait state, the shell displays a JXTA> prompt.

Now, don't be surprised if that sounds familiar; a Unix or DOS shell behaves similarly. As a matter of fact, the Jxta shell was intentionally designed to resemble the Unix shell so that most developers would be familiar with it right away. For the same reason, most shell commands resemble Unix commands as well. You will definitely notice these similarities as we proceed.

Obtain and install the Jxta shell

The first step is to get the shell running on your system. You need to download the shell from jxta.org. The shell comes with the Jxta demo, and the installable can be found in Resources.

Download the installable appropriate for your operating system. Note that Jxta uses JDK 1.3.1; hence, you need at least version 1.3.1 of the JRE (Java Runtime Environment) for Jxta to run on your system.

Once the download is complete, installation is pretty straightforward, with an InstallAnywhere wizard guiding you through the process. The default installation location is C:\Program Files\JXTA_Demo. Note that I use Windows NT as my operating system and hence use Windows conventions in this article; however you can easily find equivalents for other operating systems.

Configure the Jxta shell

The next step is to configure the shell. You can launch it by using the Programs menu on your Windows machine. Alternatively, you could go to your installation location and launch the shell.exe application, available under the Shell subfolder.

Once you launch the shell, a Jxta Configurator, as shown in the figure below, will greet you.

The Jxta Configurator. Click on thumbnail to view full-size image.

The Configurator has four tabs:

  • The Basics tab: Whenever you start Jxta, remember that you are starting a new peer on the network, so your peer must be assigned a name. Enter a name of your choice in the Peer Name text field. If you are behind a firewall and access the Internet through a proxy server, you must fill in the requested information in the Proxy Address field. Generally, this is the same information you would provide in your browser settings.
  • The Advanced tab: As its name suggests, this tab is for more experienced users who want to play around with the shell. It captures Trace Level, the mode in which you want to run the shell. Jxta shell uses log4j internally and corresponds directly to the log4j priorities. Since the shell can use either TCP/IP or HTTP as its transport protocol, this tab provides configuration options for both.
  • The Rendezvous/Routers tab: A rendezvous peer stores information about other peers in its network and therefore helps peers discover each other in the network. If you want your peer to be a rendezvous peer, check the Act as Rendezvous option. In addition, your peer could either use a gateway peer or act as a gateway peer. A gateway peer helps peers behind a firewall connect to the Internet. If your peer uses a gateway peer or acts as one, you must fill in the HTTP Gateway Settings.
  • The Security tab: Every peer requires a username and password to ensure secure access to the peer. Input this data through the Security tab.

If you are a new user, try filling in the information in the Basics and Security tabs only and leave the others as they are. This approach should work most of the time; if it fails, you need to look into other options. You can address all issues concerning troubleshooting, installation, and configuration to the user mailing list at jxta.org, which is a special mailing list dedicated to this purpose.

The security environment

You must remember the secure username and password that you entered in the Jxta Configurator. All subsequent access to the shell requires that information for a good reason: unlike a conventional Unix shell, the Jxta shell does not have a concept of a user. Once you configure and start a new shell, you are in fact configuring and starting a new peer. In this case, the peer corresponds one-on-one to you, the user. You can use the shell to interact with other users, chat, offer your own services, create your own groups, and so on. Therefore, allowing any other user to run the shell would imply that you are being impersonated. Thus, such a security environment is needed.

Shell commands

As I mentioned before, most Jxta commands resemble Unix commands. A Jxta shell command features the following basic format:

commandName [-commandOptions] [commandArguments]

The commandName is the name of the shell command to be executed. commandArguments are the inputs given to the command. You might want to alter the command's behavior to some extent, using commandOptions, indicated by a dash symbol (-).

The help system

The man command is probably the most useful command for a Jxta newbie. It is an online help (manual) system that retrieves information about any specific command. For example, the clear command clears the display in the current screen:


To receive more information on the clear command, you can use the manual system:

JXTA>man clear

When used with no arguments, the man command displays the list of all available Jxta commands:


Some basic shell commands

The Jxta shell defines seven environment variables by default. Explore them using the env command:


In addition to the predefined shell environment variables, you can also create your own shell variables -- often referred to as shell objects. There are many ways to do this. The simplest approach imports an existing file into a shell object with the importfile command. To demonstrate this, we will import a file called PlatformConfig, created by Jxta itself. The file stores the information you have entered through the Jxta Configurator. All the process requires is a simple command:

JXTA> importfile -f PlatformConfig plat

This command imports PlatformConfig's content into a shell variable called plat.

Try the env command now; you will notice the new shell object. In this case, since the PlatformConfig was in the Jxta shell's root, we did not have to provide a path to the file. If you want to import a file from a different location, don't forget to give a full path.

Now that we have a new shell object, you might be curious to see what it contains. This is where our good old Unix cat command comes to the rescue. Try:

JXTA>cat plat

It displays the plat variable's contents.

Unix users should also be familiar with the grep command:

JXTA> grep -i -n jxta plat

The shell command grep searches for matches of the string jxta in the plat variable. The -i option tells the command to ignore cases. The -n option prints the line number of the matches found.

The wc command retrieves word/character/line counts:

JXTA>wc -l plat

The above command gives you the number of lines in plat.

The history command provides a listing of previously typed commands:


You can save time by reusing commands in the history list. You can invoke any command in the history list by typing !(number), where (number) denotes the command's position in the list:


The version command tells you which shell version you are using:


Beyond the basics

None of the commands mentioned above has anything to do with actual network interactions. They work regardless of whether you are connected to a network or not. That is why I chose to call them basic. Let us now proceed further.

To work with any network communication, you must first check whether or not you are connected properly to a rendezvous peer. The rdvstatus command gives you that information:


It tells you about your connections to the rendezvous. If you are not connected to any rendezvous, you might consider reconfiguring your peer. This means you need to bring up the Jxta Configurator once again when you run the shell. To do this, use the peerconfig command and then exit the shell:


Once you have a correct configuration, you will see that you are connected to a rendezvous peer. You can now discover other peers in the network. First send a request for discovering remote peers:

JXTA>peers -r

Then try the peers command to see the list of peers your peer has discovered:


It might take a few seconds for this discovery to occur; if you don't see any immediate results, wait a few seconds and retry the peers command.

The same applies for peer groups. To see, discover, and enumerate peer groups, use the groups command:

JXTA>groups -r


All Jxta resources, including peers and peer groups, are published through advertisements (see "The Jxta Solution to P2P" for more information on advertisements). In fact, by now your peer should know the advertisements for all the peers that you discovered using the peers command. To see the advertisement for the peer referred to as peer0 by the list, type:

JXTA>cat peer0

You can apply the same analogy to groups as well.

Moving along, the mkadv command easily creates advertisements:

JXTA> jwGroupAdv = mkadv -g jwGroup

Here, the jwGroupAdv object contains a peer group advertisement created for a peer group called jwGroup. You can verify this fact using the cat command:

JXTA>cat jwGroupAdv

Now that you have created a peer group advertisement, you might as well create a peer group. Do that with the mkpgrp command:

JXTA> mkpgrp -d jwGroupAdv jwGroup

You have created a new group called jwGroup. To verify that the group was created, use the groups command.

Even though you created a new peer group, you are not yet part of it. By default, you are part of the NetPeerGroup only. To join the newly created peer group, try:

JXTA>join jwGroup

And to leave it, type:


To find out which group you currently belong to, use the whoami command:

JXTA>whoami -g

Try the command above before joining and after leaving the jwGroup.

The whoami command is useful and, when used without options, gives information about your peer:


Pipes and the talk command

In Jxta, pipes serve as an important abstraction. Pipes are virtual communication channels in the Jxta environment. They are communication channels because all peers on the Jxta network communicate with each other using pipes. They are virtual because you don't need to know their actual network addresses to use them. Pipes form the basis for many important functionalities. The talk command is a good example.

You can use the talk command to demonstrate a simple instant messaging facility provided by the Jxta shell. In the following section, I will demonstrate how to use the talk command. I will also demonstrate how you can achieve the same effects directly by using simpler shell commands. My intent is to help you understand how the talk command works. After reading the following section, try experimenting with the talk command alone initially. Once you are comfortable with it, try using the alternative methods to achieve the same effects.

For now, to see what the talk's help command has to offer, type:

JXTA>man talk

Create pipe advertisements

Use the talk command

The first step when using the


command is to register a nickname with the talk service. For example, if you choose


for your nickname, register by typing:

JXTA>talk -register myNick

Internally, the Jxta shell implements this command by creating an advertisement for a pipe and publishing it.