The JXTA Shell is a sample application that demonstrates some of the
key concepts of
the JXTA platform for the developer. What you have downloaded
is prototype code
that demonstrates some of the features of the shell. This is
not considered final code,
and you may experience bugs. In addition, as with most distributed
systems, JXTA
benefits from a network effect of increasing numbers of peers on the
network. Since
today's Project JXTA Network of peers is limited (only a few people
have
had access to the code and set themselves up in this environment),
there
may be some delays in your initial process.
This guide gives a quick tour on how to install, configure and start using the Shell.
Install the JXTA ShellOther documents which may be of interest:
Quick Shell Configuration
Troubleshooting
Quick Start
Shell Release Notes
Shell Build Process
Quick Shell Command Guide
If your system is behind a Firewall, you need to configure the HTTP
transport. If your
web proxy was auto-detected, the tool will show the proxy found, if
no proxy was
found, you need to select and enter a proxy configuration.
If you system is behind NAT, you need to configure the HTTP transport.
You do not
need to select a web proxy. This is done in the default configuration.
We recommend that you always configure HTTP. By default, JXTA
is shipped with the HTTP transport configured (see JXTA configurator
tool).
In order to configure HTTP you need to select:
This is
a partial list of available JXTA rendezvous routers you can use. Please
select the first peer in the list and enter it into the Router Selection
box of the JXTA Configurator Tool. These routers are randomly ordered,
so try the first one before trying others.
In order to use the folowing list of routers you need unfortunatly to manually update the PlatformPeerGroup and PlatformConfig configuration files adding the new entries in the "jxta.service.resolver" service param list (Params Tag). You can list as as many rendezvous as you want. Additional routers may be available. Consult your application provider or the JXTA Project webpages for the names and addresses of more routers. If the router you chose does not seem to work, ie. you cannot see rendezvous peers with the rdvstatus Shell command or peers with the peers Shell Command select another rendezvous from this. To reconfigure JXTA, just run the peerconfig Shell command and restart JXTA. NOTE: If the Rendezvous server you use is not shown in bold above you must add the address of the rendezvous server to the "ResolverProxies" property of the jxtaConfig file. Once you have added the server you must reconfigure your JXTA enviroment by executing the "peerconfig" Shell command. |
All configurations in the "Advanced Users" dialog box (JXTA rendezvous
and router)
are optional and only apply to advanced users. We encourage users to
read the
full Release Notes
documentation about the platform configuration to configure
your peer as router or rendezvous peers for others.
When the Shell console appears, you can use
the rdvstatus shell command to verify that your
configuration is correct. The command should display the rendezvous
peers that were
discovered. The discovery may take some time depending on your network
configuration
(30seconds-10 minutes probably).
JXTA>rdvstatus ======= Rendezvous status ====== This peer is connected to the following rendezvous: Rendezvous id: jxta://59616261646162614A78746150325033C5CB4603DBA3456D83FCB6AA96C00AC6...zeros omitted...0301 This peer is not a rendezvous JXTA> |
In order to discover information beyond your initial subnet, it is necessary
that you find
at least one rendezvous. To reconfigure the Shell just execute the
peerconfig
command
and exit the Shell via the exit command. Restart the Shell and
the config tool will reappear.
Try first to make sure to remove any configuration files jxtaConfig,
PlatformConfig,
PlatformPeerGroup, and the cm directory.
If you still have problem, you may want check if you have IE 5.5 installed.
We recommend that you use this version.
If you have Java installed on your system you can also run directly:
java -cp ../lib/jxta.jar;../lib/jxtashell.jar net.jxta.impl.peergroup.Boot
You cannot run two instances of
the platform on the same peer.
You need to change the TCP/IP transport port binding to enable two
instances of the
platform running on the same node.
Cannot find peers via the 'peers' command
No peers are running on your subnet. You don't have a reachable
rendezvous (check the rendezvous via the Shell command rdvstatus).
The command
should tell you that you are connected to a least one rendezvous. If
it is not the case.
Try to configure Jxta with a different JXTA router (see Quick Shell
Configuration).
Try to ping the IP address of the JXTA router to see if you can be
located under
your network configuration.
If you are behind a firewall or NAT you need
to configure the HTTP transport.
If you are behind a firewall, you need to have enter a valid web proxy.
At any time you can reconfigure JXTA by entering the Shell command
'peerconfig'
HTTP was configured, but you want to modify
the configuration
Run peerconfig and restart JXTA.
Platform fails to boot
Remove all config files jxtaConfig, PlatformPeerGroup Platform
Config and the cm directory
Quick Shell Scenario Guide:
In the examples below you will see monospace text enclosed in frames. This text is a transcript from the JXTA Shell. The text which is bold is text you should type to produce results similar to the sample results shown in these examples.
Find all the commands available in the ShellFor a quick look at what other commands are available, use the man
command. It is the
primary help system for the JXTA Shell:
JXTA>man displays man page about the Shell The following is the list of commands available: cat Display the content of an environment variable chpgrp Change the default peer group clear Clear the shell's screen env Display all environment variables exit Exit the Shell exportfile Export a Shell variable into an external file get Extract a message tag body from a pipe messsage grep Search for matching patterns groups Discover and list peer groups help On-line Help about commands importfile Import an external file into a Shell variable join Join a new peer group leave Leave a peer group mkadv Make a new pipe or peer group advertisement mkmsg Make a new pipe message mkpgrp make a new peer group mkpipe Make a new pipe more Browse or page through a Shell object peerconfig Peer configuration peers Discover and list peers put Put a new tag body into a pipe message recv Receive a pipe message search Search a shared advertisement in a peer group send Send a pipe message setenv Set the value of an environment variable share Share an advertisement in a peer group Shell Fork a new Shell talk Instant messaging talk command version Display version and build info wc Count lines, words, and characters whoami Display peer and peer group information JXTA> |
To get help on a specific command, type man <command name>.
For example:
JXTA>man exit NAME exit SYNOPSIS exit - exit the Shell DESCRIPTION 'exit' command is used to exit the Shell SEE ALSO Shell |
To find out who you are, use the whoami command. This will provide
all the relevant information about
how the computer sees you, including the peer name, keywords search
value associated with the peer,
the unique peer ID and the current address of the peer.The most important
information for you will most
likely be on the first line. This is the name you entered during the
configuration.
JXTA>whoami <Peer>me</Peer> <Keywords>NetPeerGroup by default</Keywords> <PeerId>jxta://59616261646162614A78746150325033FEE11FF6BC4E476797E2A76FD28AE561...zeros omitted...301</PeerId> <TransportAddress>tcp://129.144.38.126:6001/</TransportAddress> <TransportAddress>http://JxtaHttpClient59616261646162614A787461503250331EB5F2F009AC4363ABCA85B51DD064A3...zeros omitted...301 |
The first time the command peers is run it
will find only the local peers or pre-configured rendezvous peers.
Each additional time it is run, the discovery will expand, and new
peers may be shown :
JXTA>peers -r peer discovery message sent |
...after waiting a bit...
JXTA>peers peer0: name = jxta-test peer1: name = diox.dioxine.com peer2: name = hs1 peer3: name = diox.dioxine.com peer4: name = idvh peer5: name = skipstone peer6: name = Matt_UK peer7: name = luxor peer8: name = jgris peer9: name = toolbox peer10: name = bondolo peer11: name = sidus |
NOTES:
Currently, depending on the network latency, peers discovery can be
instantaneous or
take from 2-4 minutes. Peer discovery on slow transports such HTTP,
or when a remote
connection involves lot of hops in case of firewalls or NAT configuration
will take more time.
This process continues to be optimized.
At this release, JXTA is configured to list a random selection of peers
found.If you are looking
for a specific peer you know has registered, then you can use the peer
-a -v options
(see man pages ) to specify specific attributespeer discovery message
sent
The groups command is used to discover peer groups.As with the peers
command, the groups-r
remote option is used to asynchronously discover new peer groups. Without
this option, the groups
command shows only the peer groups that have been previously found.
JXTA>groups -r peer discovery message sent |
JXTA>groups group0: name = NetPeerGroup group1: name = toto group2: name = chacha group3: name = mynet group4: name = ooga group5: name = once group6: name = kaja group7: name = surfer group8: name = JXTA-webcast |
The groups command can be issued any number of times to list
the new peer groups that may have
been created and discovered. Depending on the network latency, groups
discovery can be
instantaneous or take from 2 to 4 minutes. Peer group discovery on
slow transports such as
HTTP, or when a remote connection involves lot of hops in case of firewalls
or NAT configuration
will take more time. We continually work on optimizing search times,
and we anticipate
future implementations to be more efficient.
When you first run the shell you are, by default, joining a world peer
group. This is usually not what you
want as most likely you will be looking to join a specific group and
communicate with them. The join
command is used to join a peer group.Used alone, the join command
lists any peer groups the peer
has already joined and which group your shell is currently active in.
The first time you use the
command, no groups are shown.
JXTA>groups group0: name = NetPeerGroup group1: name = toto group2: name = chacha group3: name = mynet group4: name = hiking group5: name = once group6: name = kaja group7: name = surfer group8: name = JXTA-webcast |
JXTA>join -d group4 |
If you are looking for a specific peer group
you known has registered, then you can use the groups
command -a -v options to specify search specific attributes.
To find the group 'funstuff' and join it.
JXTA>groups -r -a Name -v funstuff |
...after waiting a bit...
JXTA>groups group0: name = NetPeerGroup group1: name = toto group2: name = chacha ... group11: name = funstuff JXTA>join -d group11 |
To join a peer group, one needs to have already discovered it. After
using the groups -r command above,
and then the groups command, you should have a list of groups
to choose from. Used alone, the join
command lists the groups you have already joined. To join a group,
you must include the join -d argument,
which means document. At this time, JXTA only recognizes the environment
variables which are
used to store the group advertisements, ie. "group" and some number.
In this example, we will join the hello group.
JXTA>join -d group12 |
Enter the identity you want to use while
a member of this peergroup
1Identity: jxta_user1 JXTA> |
Each peer group has a mechansim for identifying its members. When you
join a group you must provide
the group the identity you wish to use while you are a member of the
group. In some groups many
users may share the same identity, eg. "Anonymous", while in other
groups, each user may have t
heir own identity. The process for establishing your identity, such
as passwords, certificates, etc.,
is established by each peer group according to its definition.
Once you have joined, you should be able
to see the group you are in by using the join command by itself.
JXTA>join Joined Group: hello (current) JXTA> |
When you have joined several groups, the
join command will give you a list, and show which one is current.
JXTA>join Unjoined Group : JXTA-webcast Unjoined Group : passwordtest Unjoined Group : improv-tech Joined Group: hello (current) JXTA> |
After joining a peer group, a peer can discover peers that are members of this peer group via the peers command.
NOTE:
Currently, JXTA is configured to list a random selection of groups found. If you are looking
for a specific group you know has registered, then you can use the groups -a -v option
command to specify specific attributes.
JXTA>groups -r -aName -vbaseball* |
Use to search for a group which name contain 'baseball'. The '*' character is used as wilcard
matching character (match any string containing the string 'baseball'). The search is XML based ie. <tag>value</tag>.
Once you are in a group, you can try talking with other peers within
that group.The talk
command implements a simple messaging command where two users
on two remote peers can
exchange text messages. Messages are displayed on the Shell console.
In order to use talk, the user needs to register, and set up a pipe for listening. This is done via the following steps:
Register via talk -register <username> command.
This command creates a Talk advertisement for that user. This has
to be done only once; the first time the user registers with talk in
a specific group.
Login via talk -login <username> command.
This command logs the user and starts a listener daemon. This command
has to
be issued every time the peer is restarted.
Initiate talk with another user via the command talk -u <myusername>
<destusername>
This command will prompt the user to enter the message he/she wants
to send.
NOTE:
In order to talk to someone else, one must have obtained the other user login name
(this is not always the same as the user's peer name, and needs to be done done outside
the scope of the talk command, by a separate email or by phone), and that user must be
'listening,' i.e. the user must have also entered these steps.
JXTA>talk -register jxta_user1 ...... User : jxta_user1 is now registered JXTA>talk -login jxta_user1 ...... User : jxta_user1 is now logged in JXTA>talk -u jxta_user1 jxta2 talk is connected to user jxta2 Type your message. To exit, type '.' at begining of line |
At thist point the user may enter as many lines as he/she wants. Each
time "return" is pressed,
that line is sent to the recipient. To end your message, enter a line
beginning with a '.'
To stop receiving any more talk messages. The user can stop the talklistener
daemon by entering the command talk -logout <username>
The 'leave' command is used to leave a peer group.
JXTA>leave JXTA> |
JXTA>exit |