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:
- It demonstrates how easily you can build a meaningful application on top of Jxta.
- 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.
- 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
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
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 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.
As I mentioned before, most Jxta commands resemble Unix commands. A Jxta shell command features the following basic format:
commandName [-commandOptions] [commandArguments]
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
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:
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
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
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:
It displays the
plat variable's contents.
Unix users should also be familiar with the
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.
wc command retrieves word/character/line counts:
JXTA>wc -l plat
The above command gives you the number of lines in
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) denotes the command's position in the list:
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:
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
The same applies for peer groups. To see, discover, and enumerate peer groups, use the
JXTA>groups -r JXTA>groups
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:
You can apply the same analogy to groups as well.
Moving along, the
mkadv command easily creates advertisements:
JXTA> jwGroupAdv = mkadv -g jwGroup
jwGroupAdv object contains a peer group advertisement created for a peer group called
jwGroup. You can verify this fact using the
Now that you have created a peer group advertisement, you might as well create a peer group. Do that with the
JXTA> mkpgrp -d jwGroupAdv jwGroup
You have created a new group called
jwGroup. To verify that the group was created, use the
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:
And to leave it, type:
To find out which group you currently belong to, use the
Try the command above before joining and after leaving 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:
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.