Platform Configuration

The Document provides configuration information about the Jxta Platform:

1. Platform Configuration
2. NetPeerGroup Configuration
3. Transport Configuration
3.1  TCP/IP Transport Configuration
3.2  HTTP Transport Configuration
3.2.1  Configure HTTP as a peer client
3.2.2  Configure HTTP as a peer router
4. Rendezvous Configuration
4.1 Configure a peer as a rendezvous
4.2 Configure default rendezvous for a peer
5
. Default NetPeerGroup Application
6
. Platform Class Loader
7
. Configuration Files
8
. Debug Mode

1. Platform Configuration

The JXTA platform is configured via the the JXTA Configurator GUI tool. The Configurator tool generates the following two config files: the jxtaConfig and the PlatformConfig file. The PlatformConfig file contains all the configuration information necessary to configure the JXTA Platform and start the default "NetPeerGroup". The configuration menu offers a user-friendly means of editing the most usefull configuration items. The jxtaConfig file contains information to configure the "NetPeerGroup". From the two configuration files, the PlatformPeerGroup Advertisement file is created. The PeerGroupAdvertisement is the advertisement for the Platform or World Peer group. All peers belongs to this groups when the platform is started.

The configuration process involves the configuration of:

1.1 Platform Configuration

If the jxtaConfig is not found in the current directory the jxtaConfig and PlatformConfig configuration files are created. Any properties can be modified. For the new value to be taken into account the "PlatformPeerGroup" and "PlatformConfig" files needs to be removed.  If either the "PlatformPeerGroup" or the "PlatformConfig" file is present, the jxtaConfig file is ignored.

At startup the platform looks for the files "PlatformPeerGroup" "PlatformConfig" and "jxtaConfig", in that exact priority order. If the "PlatformPeerGroup" file is found, the platform loads its configuration from it. This file contains a textual representation of a special peer group of that very name. If the "PlatformPeerGroup" file is missing, the configuration is restored from the "PlatformConfig" file which acts as a backup, and the configuration menu is displayed. After the user is done modifying the configuration and the platform starts, the new configuration is saved in "PlatformPeerGroup" and "PlatformConfig".

If "PlatformConfig" is also missing, then the configuration is initialized from the "jxtaConfig" file and the configuration menu is displayed. After the user is done modifying the configuration and the platform starts, the new configuration is saved in "PlatformPeerGroup" and "PlatformConfig".

If none of these files are found, then a default version of "jxtaConfig" is created first. Then initialization proceeds as described above. It is always a good idea to remove the Cache Manager directory ("cm") when the config is changed. 

2. NetPeerGroup Configuration

The JXTA platform is by default configured to start the "StartNetPeerGroup"  sample peer group. The Platform can be reconfigured to start a different application for the NetPeerGroup by changing the "InitialNetPeerGroupAppCode" property in the jxtaConfig file.

Example of jxtaConfig file:


MembershipAuthenticator=NullAuthenticator

MembershipIdentity=somebody

InitialNetPeerGroupAppCode=net.jxta.impl.shell.bin.Shell.Shell

InitialNetPeerGroupAppCodeURL=http:/www.jxta. Org/download/jxta.jar



The "StartNetPeerGroup" class is provided as a sample platform application that shows how the platform can be configured to boot into a specific peer group: the "NetPeerGroup". The intent of the NetPeerGroup is to provide a default group that peers belong to after completion of the platform boot process. The NetPeerGroup provides a default set of  policies to discover, resolve  and create pipes. There is a null authenticator for peer group membership. The NetPeerGroup demonstrate a way by which JXTA device vendors or domain administrators can control the point of access (Rendezvous) and capabilities of JXTA devices booted in their network domain.

Starting the NetPeerGroup enables them to enable peers in a  controlled  and well defined peergroup environment. In other more open environment, the NetPeerGroup can be left undefined and peers can define their own initial peer group and starting application. A peer may or may not decide to join an existing peer group upon booting or decide to publish its existence to only few other peers.

2.1 NetPeerGroup Discovery

The "NetPeerGroup" configuration is performed in three main way:

3. Transport Configuration

3.1 TCP/IP

TCP/IP is configured mainly via the Configurator GUI

Multiple instances of the platform can be run on a peer by changing the Transport.TCP.Port number to bind each instances to a different port. Users can simulate multi-subnet discovery
by configuring each platform instances on two different multicast port.

Users can also selects which network interface they want to use for JXTA. A peer may have multiple network interfaces.

3.2 HTTP

A peer needs to be configured with an HTTP transport if the peer is behind a firewall or behind a NAT.  A peer can also be configured as a router to other peers. Peer rendezvous will usually act as routers and be configured as HTTP server, but this is not required. A rendezvous peer does not have to be a router. The HTTP transport is configured via the configurator menu. The configuration menu appears the first time JXTA is started, or the next time JXTA is started after invoking the peerconfig Shell Command, if the Shell was configured.

The HTTP transport can be configured in two ways depending upon the peer responsibility. A peer can be configured as a router (route messages between different networks traversal scheme). Typically a peer router is used by a peer that is located behind a firewall to communicate with a peer that is located behind another firewall. Peer Routers are used as message gateways and have the capability to temporarily hold messages for their connected peers. A peer can also be configured as a simple HTTP client using the HTTP transport to cross firewalls.

3.2.1 Configure HTTP for a Peer client

The peer needs to enable the HTTP transport in the basic configuration page. The configuration tool will automatically pre-set an HTTP router from one of its builtin configuration file. However, the peer user is encouraged to go into the advanced configuration page if there is a problem: the builtin configuration that comes with the delivery can be outdated, or the HTTP router can be either down or busy.

In that case, it is wised to add more HTTP routers into the list. This is simply done by going onto (http...) to have the most recent list of available HTTP router, and add two or threee on them into the HTTP router box.

TIP: after a peer is started, wait a minute, and using the JXTA Shell, type the Shell command "rdvstatus". If the command does not report any connection to a rendezvous, this is very likely that the HTTP conection to the configured HTTP router failed. In that case, change the list of the HTTP routers with a more up to date list of HTTP routers.

The user just needs to enable the box in the configurator HTTP menu. If the peer is behind a firewall the user needs also to enter a valid proxy-server information to correctly configure the platform.

3.2.2 Configure HTTP as a Peer Router

In the advanced user menu, the user can enable a peer to be a peer router by checking the router box.

4. Rendezvous Configuration

Rendezvous provides a determined location where peers can find about each others, and get information about peer groups. Any peers, in a peer group, can be elected to be a  rendezvous peer. Peer rendezvous have the ability to cache peers and group  information for easing the discovery of peers and peer groups within JXTA. Rendezvous forms central meeting points where peers can easily find information. Rendezvous are typically used to bootstrap a peer, The peer will usually cache information obtained from the rendezvous, so it does not need to go back to the rendezvous peer to get information. It will only go back either to refresh its information or look for new information.

Rendezvous configuration

4.1 Configure a peer as a Rendezvous

A peer can be configured as a rendezvous peer by selecting the rendezvous box in the advanced menu section.

4.2 Configure default rendezvous and routers for a peer

Rendezvous and routers can be configured for the peer via the advanced configurator menu. Users can add or remove rendezvous and routers to match their needs.

The list of available rendezvous is maintained at Rendezvous Available

Upon booting the platform will configure the rendezvous and routers that are reachable from the peer . A ping message is sent to each rendezvous to verify that these rendezvous are valid. Whenever a peer discover new peers  in a peer group they can check if that peer  is a rendezvous via the peer advertisement. Each peer group discovery policy can decide  at that point to add the peer as a new rendezvous or to replace an existing one.

WARNING: The list of routers and rendezvous needs to be the same . This is only true for clients

5. NetPeerGroupDefault Application

A NetPeerGroup application can be configured via the 'InitialNetPeerGroupAppCode'property in the jxtaConfig file. The application needs to implement the 'net.jxta.platform.Application' interface. The default application is launched after the NetPeerGroup was successfully instantiated.

6. JXTA Class loader

The Platform has a class loader that enables the platform to download new code for the  Platform services, NetPeerGroup services and services. URL properties in the jxtaConfig file can be defined to specify the location where class files can be downloaded.

WARNING: This code download feature is not yet enabled in the platform. All classes need to be local.

7. Configuration Files

jxtaConfig                                     Platform Configuration file
PlatformPeerGroup                     Platform PeerGroup Advertisement
PlatformConfig                        Platform PeerGroup Advertisement last known configuration
cm                                                  Cache Manager Directory
cm/ShellConfig                           Shell specific configuration file
cm/"PeeGroupId"/                       PeerGroup Cache (one directory each peer group known)
                               /Groups          PeerGroup Advertisement discovered in this group
                               /Peers             Peer Advertisement for members discovered
                               /PeerInfo        Peer Monitoring and Management Information
                               /Adv                Pipe Advertisement discovered
                               /private          Private Advertisement
                               /public           /* Not used */
                               /tmp               /* Not used */
cm/HttpTransport/

  1. Debug Mode

The debug mode box can be checked in the Configurator tool to enable debugging. The debugging provides a debug trace of the different component of the platform (transport, resolver, discovery, cm).