O'Reilly Book Excerpts: JXTA in a Nutshell

Getting Started with JXTA, Part 3

Related Reading

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

by Scott Oaks, Bernard Traversat and Li Gong

In part three in this excerpt from JXTA in a Nutshell, learn how to configure a JXTA application.

JXTA Application Configuration

The dialog box that we showed in Figure 2-1 (in part one of this book excerpt) should make a little more sense now. That box is called the JXTA configurator tool, and it's a basic feature of the JXTA platform. All JXTA applications use this tool when they are first configured.

Configuration information is stored by this tool in the local directory. The configuration information also includes a local port number on which the JXTA application will listen. For that reason, you cannot run two instances of the shell (or any other application) on the same machine from the same directory. Instead, you must do the following:

When this shell starts, you will again be presented with the configuration box from Figure 2-1. You'll need to perform some advanced configuration in order for this second shell to run.

The configurator has four panels:

  1. Basic: The basic panel of the configurator allows you to assign a name to your peer. Any string can be entered (we chose "Test Shell 1"): it can represent a person's name, a hostname, or any other identifier. The name you enter is not guaranteed to be unique. No centralized naming service is used by the configurator; therefore, two peers may end up with the same name. This is okay, since the peer name is intended to be used only as a hint for searching or identifying peers. Also, each peer is assigned a peer ID that is guaranteed to be unique for every peer in the JXTA network.

    This panel also allows you to specify whether your machine is behind a firewall. If you are behind a firewall, select the option to use a proxy server and enter the proxy server's name and port into the given boxes. When a proxy server is enabled, requests to the rendezvous peers will be wrapped into HTTP messages before they are sent to the peer.

  2. Advanced: The advanced panel allows you to set up network information about the peer. JXTA v1.0 supports two transports: TCP/IP and HTTP. By default, the configurator tool preconfigures both a TCP/IP and HTTP transport to communicate with other peers.

    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 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.

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

    You should enable the TCP settings if there are other JXTA peers on your local network that you want to discover through the broadcast mechanism of PDP. The choice menu lists all the networks that the machine knows about; these are the networks on which the shell could listen for broadcast messages from other peers. Note, however, that you can select only one network on which to listen for messages.

    The text box in the TCP/IP configuration section contains the network port that will be used for application-level messages to other peers. If you are running multiple instances of the JXTA platform on a single computer, you must change the port number parameter: each JXTA application needs to have its own port number to bind a listening socket to the port.

    Similarly, enable the HTTP settings if you want to make connections to the rendezvous hosts we listed above. Note that you enable this to use HTTP to rendezvous to those hosts regardless of whether you're behind a firewall or use Network Address Translation (NAT). The message here is a little misleading. If you're behind a firewall, then you should enable the proxy server on the basic panel and fill in its name and port number as appropriate. Making connections through the HTTP rendezvous ports can take some time; while you're experimenting with JXTA on your local network, it's more efficient to disable this feature (though you'll lose the ability to interact with other peers on the Internet while this feature is disabled). If you are not connected to the Internet, you must disable the HTTP settings.

    One more note about the TCP port. Peers on a local TCP network discover each other through a multicast message. However, once they've discovered each other, they communicate directly over a specific port (known as the endpoint). The value of the endpoint is embedded within the PDP messages that the peers exchange. A peer listens for connections on this port; one peer contacts another by making a connection to the second peer's endpoint. That's why we had to change the port number when we started a second shell on the same machine: each shell needs an unused port number on the machine. If you run two shells on different machines, changing the port isn't necessary.

  3. Rendezvous/relays: The rendezvous/relays panel allows you to specify specific hosts to be used as rendezvous and/or relay peers. By default, JXTA peers will download the lists of HTTP rendezvous peers by connecting to http://rdv.jxtahosts.net/cgi-bin/httpRdvsProd.cgi and HTTP relay peers by connecting to http://rdv.jxtahosts.net/cgi-bin/routersProd.cgi. If you press the Download relay and rendezvous lists button at the bottom of this panel, you can specify a different location from which to load these lists. When the lists are loaded, you'll see that the default addresses for JXTA.ORG 235 and 237 have been added as both rendezvous and relay peers. You may delete either of these peers or add any other peers through the fields on this panel.

    Note that if you disabled the HTTP transport on the advanced panel that the HTTP rendezvous and relay settings are not available.

  4. Security: The final panel is one we've seen: it requires you to enter a name and password for access to this peer. Whenever the peer is restarted from this directory, you will be prompted for the values you entered into this panel.

Re-Entering Configuration Information

Network configuration information that you enter in the configurator is stored in the PlatformConfig file of the current directory. When a JXTA application starts, it consults this file to determine how it should configure itself. Information about your username and password is stored in files within the ./pse directory.

The first time that you start an application in a directory, the configurator will run and automatically create those files. After that, if you need to change the configuration information, you must remove the PlatformConfig file (to change the network information) and/or the pse directory (to change the username and password). Alternately, you can create a file called reconf in the current directory, in which case the configurator will run, and you'll be allowed to change the network information (but not the username and password).

From the shell, you can create the reconf file with the peerconfig command:

peerconfig: Please exit restart the jxta shell to reconfigure !!!!!

Then exit the shell and restart it; the configurator will reappear, and you can enter new network information.

Firewall and NAT Traversal

A fundamental problem P2P systems such as JXTA need to address is the ability to create a connection between two peers located at the edges of the Internet. Firewalls and NAT solutions currently deployed on the Internet create logical partitioned zones that preclude peers from talking directly with each other.

Firewall solutions are primarily deployed to create protected regions and to limit incoming traffic from the outside world. Many companies on the Internet today use firewall software to protect their internal networks from unwanted external intruders and traffic; home firewalls are becoming increasingly popular for individual users as well.

NAT solutions address the limitation on the number of IP addresses that can be assigned on a particular local network. These limitations stem from two areas. First, the sheer number of devices that are connected to the Internet is greater than the present address space of IP addresses. Second, many users (particularly home users with small networks) prefer to use NAT to shield information about their network topology from the outside world and to limit the number of IP addresses they must purchase from their service provider. IPv6 will eventually solve the first of these issues, but not the second.

So both firewalls and NAT address real problems; they will be a reality of public networks for the foreseeable future. P2P networks such as JXTA need to provide traversal and piercing capabilities to enable any peer on the network to talk with any other peer. JXTA assumes uniform reachability between peers, independently of their physical location in the network (e.g., behind a firewall or NAT).

Therefore, JXTA implementations must support firewall traversal and NAT piercing. This is accomplished in JXTA 1.0 using HTTP; it's important to set the fields of the configurator correctly to take advantage of these features.

Command Line-Based Configuration

In certain environments, it may not be convenient to configure the JXTA platform via a graphical interface. In that case, you must configure the environment by hand. There are two issues here: the network configuration and the security configuration.

The network configuration information is stored within the PlatformConfig file located in the current directory. If you want to change network parameters, you can edit this file by hand before starting your JXTA application. If you are running a brand new JXTA application, you can copy an existing PlatformConfig file, make any necessary changes to it, and then run your application. Alternately, if no windowing system is available when the JXTA application starts, it will prompt you as to whether it should continue:

The window-based configurator does not seem to be usable.
Do you want to stop and edit the current configuration ? [no]:
Using the current configuration.

If you answer this question with anything other than the string "yes," JXTA will create a default PlatformConfig file and run with the network parameters set in that file. If you do answer "yes," the application will throw an exception and exit, allowing you to edit the PlatformConfig file.

You must configure the username and password differently. The username and password information is stored within the pse directory. If that directory does not exist, then the platform will always attempt to run the configurator. If the configurator cannot run, you will get the same prompt as above, but there is no default username or password, and the application will ultimately fail.

What you must do in this case is specify the desired username and password on the command line by setting these two properties:


Note that the password must be specified in "the clear"; it will not echo as a series of asterisks. Using these properties will initialize the correct entries in the pse directory and allow your application to continue.

The username and password must be specified every time a JXTA application runs; the second time you run the shell, you'll get a pop-up window asking you to specify the username and password. To avoid this pop-up window, you may specify these properties when you start the application.

There's an interesting difference here: if the application prompts you for the username and password, you will not be able to proceed unless you type in the correct values. If you specify the username and password via command-line properties, the application will continue to function until those values are needed. In most JXTA applications, the username and password are needed only to create secure (encrypted) pipes. Therefore, unless your application uses secure pipes, it will work perfectly even if you specify the incorrect username and password via the command line. We'll explore this a little bit further in Chapter 7.


The JXTA Shell caches information about peers it has discovered in the ./cm directory. If you shut down a shell and then restart it, you'll notice that it still knows about the same peers, even before you execute a peers -r command. This caching feature is used by many JXTA applications, though it is not a requirement of JXTA: it's up to the application to determine how (or if) it should cache information about previously discovered peers.

So when the JXTA Shell restarts, it still knows about all of the previously discovered peers. But what happens if these peers have disconnected? In that case, you need to flush the list of peers. This is done with the peers -f command:

peer0: name = Test Shell 1
peer1: name = Test Shell 2
JXTA>peers -f
peer0: name = Test Shell 1

The point is that peers are strictly transient by nature, and you cannot assume that a peer will continue to exist if you restart a session (or even during the same session). Peers come, peers go, and it's up to JXTA applications to be prepared to deal with this fact.

The caching of peer information by the shell is a specific case of advertisement caching. Every network resource in JXTA is described by an advertisement. Advertisements are XML documents that publish the availability of a resource and specify how to access the resource (we'll discuss them in more detail later in this chapter). When we discovered a peer, what we really discovered was the advertisement for that peer.

Advertisements may be cached by peers. Caching advertisements facilitates advertisement discovery, as more peers are likely to cache the requested advertisement. Without caching, peers would have to crawl through the entire network to find the advertisement they are looking for. Thus, caching reduces the exponential growth of messages sent within the network to discover a resource.

Each advertisement contains a time-to-live value that specifies the lifetime of the advertisement in the JXTA network. The lifetime is specified as a time relative to when the advertisement was published; when the lifetime expires, the advertisement is purged from the cache. This enables the network to maintain itself without centralized control.

As we mentioned, the JXTA specification does not specify how peers cache information; each peer is free to use a caching policy appropriate for its own environment. A PDA may cache very few advertisements only for its own usage. An enterprise server may cache more advertisements and supply them to other peers in the network. However, the standard JXTA API bindings that we discuss in later chapters automatically perform this caching. So by default, most JXTA applications will cache their advertisements.

In the next installment, learn about Pipes.

JXTA in a Nutshell

Related Reading

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

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 © 2017 O'Reilly Media, Inc.