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.
The pipe advertisement created by the above command does not denote a secure pipe. All messages passing through such a pipe are unencrypted, and any sniffers placed on the network can easily detect them. So if you intend to have a truly secure conversation, you must use:
JXTA>talk -register myNick -secure
In this case, the pipe advertisement created is for a secure pipe that passes encrypted messages. On the flip side, your chat might become slower -- obviously, that's the penalty you pay for increased security.
To create a pipe advertisement with an alternate method, you must use the
mkadv command with the
JXTA>chatPipeAdv = mkadv -p
Create the pipe
Use the talk command
The next step is to log in to the chat, which actually entails creating a pipe out of the advertisement that you created in the previous step. Not only that, but when you log in, you also listen to this newly created pipe:
JXTA>talk -login myNick
To achieve the same effect using shell commands, you must create an input pipe. For this, use the
JXTA>inpPipe = mkpipe -i chatPipeAdv
Send a message
Use the talk command
Try sending a message to yourself first:
JXTA>talk -u myNick myNick
Don't forget to end your message with a period (
To talk to other users, you need to search for them on the Jxta network. To search, use the
talk command with the search option:
To send a message through a pipe with a shell command, you must first create a message object:
JXTA>chatMessage = mkmsg
Right now the message is blank and lacks data. To handle the message's data portion, create a simple text file called
hello.txt containing the string
"Hello Pipe Talk". Then, import this text file's contents into a shell object called
JXTA>importfile -f d:\hello.txt chatMessageText
That command creates a
chatMessageText object containing your message. Now you need to put this data into your message object:
JXTA>put chatMessage messageTag chatMessageText
messageTag is the name of the tag associated with the message.
To send the message, first create an output pipe:
JXTA>outPipe = mkpipe -o chatPipeAdv
Once you have an output pipe, use the
send command to send the message:
JXTA>send outPipe chatMessage
Now comes the difference between the shell command pipe chat and the
talk command pipe chat. The
talk -login command not only creates a pipe but also listens to it; however, the shell command pipes are not being listened to for any message. Use the
recv command to listen to an existing input pipe:
JXTA>message =recv inpPipe
Here, the shell listens to the input pipe
inpPipe. Whatever message the input pipe receives is put in the message object. Note that the
recv command is a blocking command. However, you can specify a timeout for this command by using a
To retrieve the transmitted text from the message object, use the
JXTA>messageText = get message messageTag
Finally, print the contents to the shell console using the
Run multiple peers
The straightforward way to run multiple peers is to use different machines that are all connected to the Jxta network. In most cases, however, you would probably prefer to use your own machine to run multiple peers. To do that, make a copy of the
JXTA_Demo folder in a different location. Launch the
shell.exe in this folder's shell subdirectory. Make sure that your shell is running.
However, this approach has a small problem. When you copy the
JXTA_Demo folder, you also copy all the configuration information you provided for the first shell. But you need to reconfigure the second peer to make it work properly. To do this, after launching the shell, type
peerconfig followed by
exit. Relaunch the shell to receive the Jxta Configurator window. You might want to change the peer name. Although peer names don't have to be unique in the network, it might be easier to keep track of your peers if they have different names. What you do need to change is the HTTP and TCP/IP settings in the Advanced tab. Change the port numbers for both these transports. For example, change the HTTP port number 9700 to 9710 and the TCP port number 9701 to 9711. This change ensures that both peers do not use the same ports. Click OK to run both peers.
Get cracking with the Jxta shell
In this article, we explored all the rudiments you need to get started with the Jxta shell, namely installation, configuration, and the shell environment. We also looked into some simple shell commands. The shell features many more commands not discussed in this article; use the
man command to explore them.
Remember that the shell commands are nothing but Java programs running in the Jxta shell context. In the next article, we'll look into the shell internals. You will also learn to write your own shell commands, which can help you build complex applications running over the Jxta shell.
Learn more about this topic
- Jxta demo installation
- Jxta shell project home
- log4j home
- "The Jxta Solution to P2P," Navaneeth Krishnan (JavaWorld, October 2001)
- For more articles on Enterprise Java, browse the JavaWorld Topical Index
- Speak out in our Enterprise Java discussion
- Sign up for JavaWorld's free weekly Enterprise Java email newsletter
- You'll find a wealth of IT-related articles from our sister publications at IDG.net