Published on ONJava.com (http://www.onjava.com/)
 See this if you're having trouble printing code examples

O'Reilly Book Excerpts: JXTA in a Nutshell

Getting Started with JXTA, Part 1

Related Reading

JXTA in a Nutshell
By Scott Oaks, Bernard Traversat, Li Gong

by Scott Oaks, Bernard Traversat and Li Gong

In part one in this series of book excerpts from JXTA in a Nutshell, learn about setting up the JXTA Java environment as well as JXTA class files, shells, and peers.

Getting Started with JXTA

In this chapter, we'll see how to get started with JXTA. Although JXTA is a language- and platform-neutral specification, we'll focus on using the standard JXTA applications for the Java platform. The basic concepts that you'll learn in this chapter are applicable to any JXTA implementation using any language; we chose to illustrate the concepts of JXTA using the Java platform because it allows for the simplest discussion of JXTA concepts, and because the Java platform gives us a common basis for our examples, regardless of the computer on which you might run them.

We'll start by discussing how to set up a Java environment to run JXTA programs. Then we'll look in depth at one particular program: the JXTA Shell. Examining the shell will allow us to look in depth at each of the protocols and techniques that JXTA defines; working through the examples in this chapter should provide you with a working knowledge of the key concepts of the JXTA platform and how programs operate within that platform.

Setting Up a Java Environment

The first step in using JXTA is to set up your environment. In this case, that means setting up a Java environment to run JXTA, for which you'll need three things: a Java platform, the JXTA Java class libraries, and any JXTA programs that you want to run.

The Java Platform

In This Series

Getting Started with JXTA, Part 5
In this fifth and final excerpt on getting started with JXTA from JXTA in a Nutshell, learn about advertisements: structured XML documents for JXTA infrastructure.

Getting Started with JXTA, Part 4
In part four in this series of book excerpts from JXTA in a Nutshell, learn about JXTA pipes.

Getting Started with JXTA, Part 3
In part three in this series of excerpts from JXTA in a Nutshell, learn how to configure a JXTA application.

Getting Started with JXTA, Part 2
In part two of this series of book excerpts on getting started with JXTA, from JXTA in a Nutshell, learn about peergroups and discovery, which are important for understanding peer-to-peer Web services.

For the Java platform, you'll need the Java 2 Standard Edition (J2SE), Version 1.3.1 or later (Version 1.4 is preferred). Work is ongoing in the JXTA community to allow JXTA to run on the Java 2 Micro Edition platform (J2ME); once that work is complete, then the steps we discuss here should work on a J2ME platform as well.

This chapter focuses on running and explaining existing JXTA applications. Therefore, if you're using the Java 2 platform, you need only the Java 2 runtime environment (J2RE). If you plan on programming with JXTA (using the examples in subsequent chapters), then you'll need the Java 2 Software Developer's Kit (SDK).

There are a number of ways to obtain current releases of the Java platform. If your system is running Solaris, Microsoft Windows, or Linux, the simplest way is to download the SDK from http://java.sun.com/j2se/. For other operating systems, check with your system vendor. More commonly, many integrated development environments (IDEs) come with support for Java (and hence a Java platform).

Once you've obtained and installed Java, you must make sure that the java executable is in your standard path.

The JXTA Class Files and Programs

You can obtain all the JXTA files you need at http://download.jxta.org/easyinstall/install.html. On this page, you can obtain the JXTA demo package for a variety of platforms. In fact, the JXTA demo implementation at this site is written completely in Java; the difference between the platforms lies only in how the parts of the implementation are packaged and how they are installed. Therefore, for Microsoft Windows, download an executable (.exe) file; for Solaris, download a shell script, and so on.

When you execute the installation program, you are prompted for a directory in which to install the code. On Unix systems, the default directory is ./JXTA_Demo; on Microsoft Windows, the default directory is C:\Program Files\JXTA_Demo. Within the directory you select, the installation creates the following:

This directory contains a set of jar files that contains the JXTA implementation and another set that contains implementations of the JXTA demo applications.

The JXTA Shell is an interactive application that lets you look at the JXTA environment and try out basic JXTA functionality. We'll examine the shell in detail later in this chapter.

This is another sample JXTA application; it contains functionality to chat one-on-one, chat with a group, and share files. This application uses all of the standard facilities of JXTA, so it is a good example on which to model other JXTA P2P applications.

This is all you need to use JXTA technology, both as an end user and as a developer. If you're going to do JXTA development, you should add each of the jar files in the lib directory to your classpath. If you're simply going to run the sample applications, there are scripts in each application directory that set up the classpath and run the application.

In our examples throughout this book, we assume that you've installed this hierarchy into /files/JXTA_Demo (C:\files\JXTA_Demo). We'll also assume that your classpath contains the current directory and the necessary jar files from the lib directory:

As you become more familiar with JXTA, you may want to get involved with other JXTA projects, use other JXTA applications, or examine the JXTA source code. You can download all of these things from http://www.jxta.org/project/www/download.html.

Basic JXTA Concepts

Now that we have all of this software, we'll use it to explain a little more about the basic JXTA concepts we outlined in Chapter 1, including how a JXTA application is constructed. We'll use the JXTA Shell as the basis for our exploration, since it provides us with an interactive tool that uses the JXTA platform to perform its operations.

JXTA Shell Syntax

Before we dive into the shell, here are some notes on its syntax. Like any shell, the JXTA Shell issues a prompt (JXTA>) at which you type in commands.

Shell commands have two kinds of output. Most of them simply send their output to the screen. Some commands, however, produce an object as their output. These objects should be saved in a shell variable. If you do not save the object, most commands will create a new object with a default name to hold the return value; if you're going to need the object, it's easier to assign a name to it yourself. Shell variables are created in JXTA by assigning a new name to the output of such a command.

Here are some simple examples. The env command produces as its output a list of all the shell variables and their values:

stdin = Default InputPipe (class net.jxta.impl.shell.ShellInputPipe)
parentShell = Root Shell (class net.jxta.impl.shell.bin.Shell.Shell)
Shell = Root Shell (class net.jxta.impl.shell.bin.Shell.Shell)
stdout = Default OutputPipe (class net.jxta.impl.pipe.NonBlockingOutputPipe)
consout = Console OutputPipe (class net.jxta.impl.shell.ShellOutputPipe)
consin = Default Console InputPipe (class net.jxta.impl.shell.ShellInputPipe)
stdgroup = Default Peergroup (class net.jxta.impl.peergroup.StdPeerGroup)

Shell variables are created by assigning a new name to the output of a command that creates an object. mkadv is such a command; here we store the object it creates in the myadv shell variable:

JXTA>myadv = mkadv -p

You can print out the content of certain variables by using the cat command. If the variable has structured data, cat will print it out:

JXTA>cat myadv
<?xml version="1.0"?>
<!DOCTYPE jxta:PipeAdvertisement>

A list of all shell commands can be obtained via the man command; the man command can also print out help for a specific command (e.g., man mkadv). A complete shell reference appears in Chapter 12.

JXTA Peers

We'll start our examination of JXTA's key concepts with the notion of a peer. As defined in the JXTA specification, a peer is a device that implements one or more JXTA protocols. The key idea is that something implements the protocols. Don't get too hung up on the notion of a device--a device is not necessarily a machine. A single machine can host multiple JXTA programs, each of which is really a peer. The program is really a virtual device.

Of course, peers normally communicate with each other over a network, so a JXTA community typically has many different machines within it. However, some of these machines could be running multiple JXTA peers. A single JXTA peer could be a distributed application running across multiple machines. And if you're following the example in this chapter at home on your own single computer, you'll end up running many peers on your local system.

To start our first peer, we'll execute the JXTA Shell. On Microsoft Windows systems, you can do this by selecting Programs -> Jxta -> JXTA Shell from the start menu. On other platforms, you can do this by executing these commands:

piccolo% cd /files/JXTA_Demo/Shell
piccolo% sh shell.sh

When you first start the shell, you'll see the window displayed in Figure 2-1. This allows you to configure the shell for the network on which it will run. We explain the configurator in detail later in this chapter. For now, we'll just step through the two required elements that you must configure.[1]

Figure 2-1

The JXTA configurator tool

First, fill in the peer name with a string of your choice (we chose "Test Shell 1") and press the OK button. On the next screen, fill in the username you'd like to use and a password for that username. In Figure 2-2, we've specified myusername and entered a password.

Figure 2-2

Entering a username into the configurator

The next window that comes up is the JXTA Shell itself. This is the first JXTA peer that we've created. The shell is interactive; its command prompt is JXTA>, and it accepts more than 40 commands. For now, we'll just look at the commands that illustrate the basic JXTA concepts.

One of these commands is the peers command; it displays a list of all the peers that the shell knows about. If you execute that command now, you'll see the following:

peer0: name = Test Shell 1
peer1: name = JXTA.ORG 237
peer2: name = JXTA.ORG 235

More information can be printed this way:

JXTA>peers -l
peer0: ID = uuid-
59616261646162614A78746159325933A69CA85997D6433D82BDA4A4D0953AC603 name 
= Test Shell 1 addr = tcp://
peer1: ID = uuid-59616261646162614A787461593259336ACC981CFAF047CFA name = 
JXTA.ORG 237 addr = tcp://
peer2: ID = uuid-59616261646162614A7874FAEDBB84753E1E16503C14495AE name = 
JXTA.ORG 235 addr = tcp://

All peers have names (in the case of our peer, "Test Shell 1"). In addition, peers carry other important pieces of information: the peergroup to which they belong (which we'll explain later in this chapter), a unique peer ID, and information about what network addresses can be used to contact the peer. You can see this information in the shell with the whoami command:

<Peer>Test Shell 1</Peer>

The peer ID is unique across all JXTA peers. The transport addresses contain the information about how the peer may be contacted.

You can discover a peer explicitly using its peer ID like this:

JXTA> peers -p jxta://59616261646162614A78746150325033D13E08EF

This technique is easier to imagine programatically, where you wouldn't have to type in the entire string. You can, for example, save a peer ID and use it in later sessions as the default peer to provide a service (assuming that the program can handle the fact that the default peer may no longer be available); in fact, peer IDs are often saved by the JXTA platform itself when it performs caching.

Peers keep configuration information within their current directory. If you want to start a second instance of the shell on the same machine, you cannot do so from the same directory. Instead, you must follow the instructions on advanced configuration that we give later in this chapter.

In the next installment, learn about peergroups.

1. This default configuration assumes that your computer is directly connected to the Internet. If you are not connected to the Internet directly or connect to the Internet through a proxy, then you must take additional steps as outlined in the detailed section on the configurator tool later in this chapter.

Scott Oaks is a Java Technologist at Sun Microsystems, where he has worked since 1987. While at Sun, he has specialized in many disparate technologies, from the SunOS kernel to network programming and RPCs.

Bernard Traversat is a well-known developer in the Java Community and an active member of the Project JXTA. Bernard is the Engineering Manager for the JXTA CORE.

Li Gong is a well-known developer in the Java Community and an active member of the Project JXTA. Li is the JXTA Engineering Director for the JXTA CORE.

Return to ONJava.com.

Copyright © 2009 O'Reilly Media, Inc.