Published on OpenP2P.com (http://www.openp2p.
com/) See this if you're having trouble printing code examples
Learning the JXTA Shell
by Rael Dornfest 04/25/2001 I want to talk about the implications for that marvelous aspect of the fundamental UNIX design: the pipe, and its ability to connect small independent programs so that they could collectively perform functions beyond the capability of any of them alone. What is the equivalent of the pipe in the age of the Web? -- Tim O'Reilly, JavaOne Keynote: "The Network Really is the Computer." The JXTA shell is a command-line interface to Sun's JXTA (pronounced "Juxta") peer-to-peer framework. Originally written as a debugging tool for developers, the JXTA Shell affords a ground-floor view of the JXTA environment, much like a traditional shell drops one into the thick of a *nix operating system. The JXTA shell is a fine demonstration of some of the key features of the JXTA platform. The shell itself is nothing more than a framework for dynamically loading and binding commands (read: classes) to the JXTA underpinnings. This allows you, the user, to extend the shell to your heart's content. Who'll be the first to write alias and less ;-) As we'll see in this article, inter-peer messages in JXTA are nothing more than XML Table of Contents documents, a fact that provides various interesting intersections with Web Services (via •Login XML-RPC and SOAP), syndication (via RSS), Instant Messaging a la Jabber, and •Old Favorites more. •Getting to know me This article is an introductory tour of the JXTA shell. We'll step through some of its •Peers simple commands and move to more interesting examples constructed from these core •Peer Groups building blocks. (For an overview of the JXTA platform, see the accompanying article, •P2P Piping The JXTA Position.) •Can we talk? •Logout Anyone familiar with command-line shells, whether DOS or *nix, will feel right at •Gotchas! home in the JXTA shell. There are basic commands: man, cat, env, grep, more, and more. Commands can, of course, be sewed together using pipes to create compound commands: env | wc. Multiple commands on one line are separated by semicolons: clear ; whoami ; man man. All in all, aside from the fact that it's easy to forget that it's not a complete shell (see "Gotchas"), there are few surprises.
First things first; we'll download, install and launch the JXTA shell.
Leave the defaults as they are. Windows 2000 users may have trouble with the JXTA Shell commands Windows installer launching and disappearing without doing much of anything. install and launch the JXTA shell. save perhaps hanging around in the background. Position as well as ZIP archives and CVS access. "Hello.exe icon in the shell subdirectory of wherever you put the installation.jxta. the JXTA Configurator dialog will appear.org/easyinstall/.
1. If this happens.
. JXTA!" 2.org site at JXTA Takes Its http://download. we'll download. Joy Announces JXTA
JXTA Application Icon 3. Launch the JXTA shell by double-clicking on the jxta. Installers are available for various platforms. you may want The JuxtaNet to download the latest nightly build. The first time you run the shell. all you need do is fill in a name for your peer (anything will do) in the Peer Name field and click the OK button to move on. Note: At the time of this writing.First things first. The JXTA Shell is freely downloadable from the Jxta.
.The JXTA Configurator 4. The JXTA shell window should appear and you're ready to go.
We'll start with a few old shell favorites. along with a list of available commands. If at any point you need help. If.The JXTA Shell Note: I found a couple of bugs that can cause the shell not to launch. This article was written using version 0. type version at the command-line.9 (build 14e. the standard *nix man provides man(ual) pages for supported functionality. mind you) and log in again before continuing. For versioning. 04-22-2001).exe icon to relaunch. after closing the configurator. The usage of man is: JXTA> man <commandName> For instance typing
. double-click the jxta. Windows 2000 users may find this makes no difference and will need to log out (not reboot.
JXTA>man The 'man' command is the primary manual system for the JXTA shell. Typing just man displays information about man itself. the shell does not appear momentarily.
JXTA>env peer0 = stored local peer advertisement (class net.jxta.ShellInputPipe) Shell = Root Shell (class net. The same is true for the shell Tell us your first console's consin/consout. who whoami JXTA> Display the content of an environment variable Change the default peer group Display member identity in a peer group Display peer and peer-group information
(For a complete list of JXTA shell commands.bin. We'll delve more into pipes in a bit..3. albeit a little more interesting than the standard printing of my username.shell.impl.peergroup.impl. displays all defined shell environment variables.impl. see "JXTA Commands.jxta. shall we? The whoami command functions as expected.ShellOutputPipe) stdin = Default InputPipe (class net.jxta.shell.Shell.ShellInputPipe) stdgroup = Default Group (class net.")
One thing to note in the above readout is that standard input (reading keyboard Have you input) and output (displaying output to the console) are JXTA pipes.PeerGroupAdv) stdout = Default OutputPipe (class net.
JXTA>whoami <Peer>milne</Peer> <Keywords>NetPeerGroup by default</Keywords> <PeerId>jxta://59616261646162614A78746150325033237B7161401449269 6789EFFBC49968B0000000000000000000000000000000000000000000000000000000 000000301</PeerId> <TransportAddress>tcp://1.shell.JXTA> man Shell displays man page about the Shell The following is the list of commands available: cat chpgrp .shell.impl.jxta.2..ShellOutputPipe) consin = Default Console InputPipe (class net. the same explored JXTA? conduits by which peers communicate with each other. impressions and let others know what Here are a few more simple commands to try for fun: you've learned so far.4:6001/</TransportAddress>
man | wc env | grep -i stdin cat peer0 | more Shell -s
Post your findings
Getting to know me
Let's get to know ourselves a little.Shell) consout = Default Console OutputPipe (class net.impl.impl.shell.
0 Keywords : resolver PipeService : Params : http://216. and via an HTTP proxy if behind a firewall/NAT.3.com -----More-----
. there's whoami -l .resolver</Service> <Service>jxta.132.. Note that even though I may be using HTTP to get past my firewall.service.jar Provider : sun.144. direct TCP communication is still useful for peers on my LAN. This is but a pretty representation of the actual peer advertisement. The second whoami provides a little more detail about my current peer-group membership.discovery</Service> <Service>jxta.service.service. a member of the "NetPeerGroup" -.service. "jxta://596162.resolver Version : JXTA1.36. I am communicating via TCP directly at IP address 1.membership</Service> <Service>jxta. viewable in its native XML by printing the "peer0" environment variable we saw above.188. port 6001. by default.pipe</Service> <Service>jxta..<TransportAddress>http://JxtaHttpClient59616261646162614A7874615 0325033237B71614014492696789EFFBC49968B0000000000000000000000000000000 000000000000000000000000000000301/</TransportAddress> JXTA>whoami -g <PeerGroup>NetPeerGroup</PeerGroup> <Keywords>NetPeerGroup by default</Keywords> <PeerGroupId>jxta://59616261646162614A757874614D5047000000000000 0000000000000000000000000000000000000000000000000000000000000000000000 00000000000201</PeerGroupId> <Service>jxta.115.132:6002 Uri : http:/www.more on groups in a moment.2.peerinfo</Service> </code></pre>
The first whoami claims that I am a peer named "milne" with the unique identifier. including group identifier and available services.service.228:6002 Params : http://206.4.14:6002 Params : tcp://129.15.239:6002 Params : http://63.org/download/jxta.service.154.jxta.
JXTA>whoami -l | more jxta:PeerGroupAdvertisement : Name : NetPeerGroup PeerName : milne Keywords : NetPeerGroup by default Pid : jxta://59616261646162614A78746150325033237B7161401449269 6789EFFBC49968B0000000000000000000000000000000000000000 00000000000000000000301 Gid : jxta://59616261646162614A757874614D504700000000000000000 00000000000000000000000000000000000000000000000000000000 00000000000000000000201 isRendezvous : false Services : jxta:ServiceAdvertisement : Name : jxta." I am.60.25. For more details.190:6001 Params : http://209.99.
for the preamble.NET JXTA>peers -l [the -l option provides more detail] peer0: ID = 38e6af70 name = milne addr = http://JxtaHttpClient59616261646162614A787461503250337E00F 24A221C48BD8C09B1B5BA37BC9600000000000000000000000000000000000000 00000000000000000000000301/ peer1: ID = 796f3ac4 name = DIOXINE. then.dioxine. To reconfigure your JXTA peer from within the shell. The peers command displays all peers already known to my peer. is just a matter of propagating a remote discovery request using peers -r. let's get on to the interesting P2P pieces.JXTA>cat peer0 | more <?xml version="1. take a gander at the peerconfig command (type: man peerconfig).net:6002/
Discovering other peers.
JXTA>peers peer0: name = milne peer1: name = DIOXINE. initially only myself and possibly a peer I'm using as an intermediary outside my firewall/NAT.
JXTA>peers -r peer discovery message sent [time passes] JXTA>peers JXTA>peers peer0: name = piglet peer1: name = Platform PeerGroup
.0"?> <!DOCTYPE jxta:PeerGroupAdvertisement> <jxta:PeerGroupAdvertisement> <Name>NetPeerGroup</Name> <PeerName>milne</PeerName> <Keywords>NetPeerGroup by default</Keywords> <Pid>jxta://59616261646162614A78746150325033237B7161401449269 6789EFFBC49968B00000000000000000000000000000000000000000 00000000000000000000301</Pid> <Gid>jxta://59616261646162614A757874614D504700000000000000000 00000000000000000000000000000000000000000000000000000000 00000000000000000000201</Gid> <isRendezvous>false</isRendezvous> -----More-----
These settings reflect the initial JXTA configurator settings we breezed through earlier. So much. peers of peers and so on.
Each application tapping into JXTA is a peer. Your JXTA shell running on your desktop right now is a peer. as is mine on my laptop.NET addr = http://jxta.
To leave. Here I join the "tiggers" group. use peers -f. to propagate a group remote discovery request.. to find out what groups are known to your peer. A peer group logically limits the scope of peers with whom you will be communicating. look around for peers and leave.
name name name name name
= = = = =
Platform PeerGroup milne NetPeerGroup by default pooh Platform PeerGroup
Discovered peers (technically. we function within a particular community and can assume the presence of a limited number of appropriate peers.. The majority of the time.peer2: peer3: peer4: peer5: peer6: . one sees only other member peers. anything will do. By default.
Each peer belongs to a peer group. You are prompted for an identity. Upon joining a peer group. however. their peer announcements) are cached locally. use groups -r
JXTA>groups group0: name = NetPeerGroup JXTA>groups -l [the -l option provides more detail] group0: GID = 12274c77 name = NetPeerGroup addr = http://JxtaHttpClient59616261646162614A787461503250337E00F 24A221C48BD8C09B1B5BA37BC9600000000000000000000000000000000000000 00000000000000000000000301/ JXTA>groups -r group discovery message sent [time passes] JXTA>groups group0: name group1: name group2: name group3: name group4: name group5: name . technically a UUID.
JXTA>join -d group1 JXTA>whoami -g
. where every phone number is globally unique. analagous to a world without area codes. To flush all known peers and begin again. analagous to your local telephone area code... use the groups command. each peer is a member of the global "NetPeerGroup" group. As with peers.
= = = = = =
piglets tiggers test NetPeerGroup foo foofoo
To join a group. simply use join -d group# where "group#" is the environment variable in which the group advertisement is stored. stored in environment variables "peer#" where # is the sequential integer associated with a particular peer. use (surprisingly enough) leave.
an output pipe connection can be dynamically disconnected and reconnected to a different input pipe.pipe</Service> <Service>jxta. JXTA pipes are unidirectional and asynchronous. -. we'll open two shell windows (call them Pooh and Piglet) and pipe a couple of simple text messages between them (from Piglet to Pooh). an environment variable ("pigletmsg") is readied to receive input from our input pipe. like peers.membership</Service> <Service>jxta. Pretend for a moment that these are two separate peers running on machines on opposite sides of the Hundred Acre Wood.discovery</Service> <Service>jxta.the receiving end. We leave this shell
.service.service. This disconnection operation can be performed multiple times over the lifetime of the pipe.
JXTA>pipeadv = mkadv -p apipe JXTA>inpipe = mkpipe -i pipeadv JXTA>Shell -s JXTA>pigletmsg = recv inpipe
First.<PeerGroup>tiggers</PeerGroup> <Keywords>myhost</Keywords> <PeerGroupId>jxta://3FEAEE2E776F4670AC5E81EB9B5BA4800000000000000000000 000000000000000000000000000000000000000000000000000000000000000000000 00000201</PeerGroupId> <Service>jxta. The ability to transparently redirect output of pipes is an essential feature to build highly available services in a loosely coupled and unreliable environment such as peer-to-peer networks. He uses this pipe advertisement to create an input pipe ("inpipe") -. flush them using groups -f.peerinfo</Service> JXTA>peers -r [time passes] JXTA>peers peer0: name = tigger peer1: name = milne . Since JXTA pipes are asynchronous.JXTA Shell Documentation (PDF) While not quite as elegant as using the | character.. are cached locally.service.
The JXTA shell extends the concept of the piping between local commands (as in man | wc) to inter-peer communication. After launching another shell window (Shell -s) for Piglet.service.service. As an example.resolver</Service> <Service>jxta. JXTA>leave JXTA>
Discovered group announcements.. Pooh creates a pipe advertisement and gives it a name ("pipeadv"). piping from one peer to another in JXTA is almost trivial.
. so as to be able to sort them at the other end. Pooh! </Item> </ShellDoc> JXTA>data1 = get pigletmsg hello JXTA>cat data1 <?xml version="1. Piglet sends his message via the output pipe and .
recv has received a message JXTA>cat pigletmsg Tag: hello Body: <?xml version="1. Pooh! </Item> </ShellDoc>
. Pooh! </Item> </ShellDoc> JXTA>data2 = get pigletmsg bye JXTA>cat data2 <?xml version="1. Finally. Pooh! </Item> </ShellDoc> Tag: bye Body: <?xml version="1." The contents are packed into "mymsg" with an associated arbitrary tag..0"?> <ShellDoc> <Item> Goodbye. In turn. each file is imported and stuffed into the variables "file1" and "file2.0"?> <ShellDoc> <Item> Hello.window in a waiting state and wander over to Piglet's.0"?> <ShellDoc> <Item> Goodbye." Now Piglet has created a couple of text files named hellopooh and byepoo containing one line of text apiece. A new message is created and stored in the environment variable "mymsg.
JXTA>opipe = mkpipe -o pipeadv JXTA>mymsg = mkmsg JXTA>importfile -f hellopooh file1 JXTA>put mymsg hello file1 JXTA>importfile -f byepooh file2 JXTA>put mymsg bye file2 JXTA>send opipe mymsg
Piglet uses the same pipe advertisement to create an output pipe ("opipe").0"?> <ShellDoc> <Item> Hello.
who has not yet registered as a talk user. syndication (via RSS). Pooh receives Piglet's message. this provides various interesting intersections with Web Services (via XML-RPC and SOAP). To exit...Instantly (or so the theory goes). We use Shell -s to create a new shell for Piglet. talk resembles the *nix write functionality. type ".. User : piglet is now registered JXTA>talk -login piglet
Piglet creates a talk user "piglet" and logs in. More a piping demonstration than anything else... Piglet!
Pooh tries again. He tries to find Piglet.. the shell does actually have some rudimentary instant-messaging functionality. and more.
JXTA>talk -register pooh . Instead of simply being displayed. User : pooh is now registered JXTA>talk -login pooh JXTA>talk piglet . Simply printing the value of the "pigletmsg" variable reveals a message composed of a couple of XML documents and the associated tags given to them by Piglet." at begining of line Hello. talk: piglet is not a registered user JXTA>Shell -s
Pooh registers a talk user (read: talk advertisement) "pooh" and logs in (read: starts a listener daemon)... with each peer establishing its own talk connection to the other. Piglet!
. this time successful in finding Piglet and sending him a greeting..
Can we talk?
While the example above provided some insight into message passing via pipes under JXTA.. Since inter-peer messages are nothing more than XML documents.
JXTA>talk piglet found user's advertisement attempting to connect talk is connected to user piglet Type your message.
JXTA>talk -register piglet . individual documents can be extracted from the message and assigned to a variable using the get command...
JXTA>talk: from jxta://59616261646162614A787461503250333DA927976125 4559B209922BACA69E190000000000000000000000000000000000000000000000000 000000000000301 to piglet Message: Hello.... Instant Messaging a la Jabber.
ShellInputPipe) . however.0"?> <!DOCTYPE jxta:PipeAdvertisement> <jxta:PipeAdvertisement> <id> jxta://59616261646162614A787461503250333DA9279761254559B209922 BACA69E1900000000000000000000000000000000000000000000000000000 00000000301 </id> <name> JxtaTalkUserName:pooh </name> </jxta:PipeAdvertisement>
JXTA>talk piglet found user's advertisement attempting to connect talk is connected to user piglet Type your message. env and cat. Piglet! talk: from piglet to pooh Message: And a hello to you too. So Piglet establishes his own talk session to Pooh. type ". JXTA>talk -logout pooh JXTA>talk: stop listening for user :pooh
Once our friends are ready to conclude their chat. as I mentioned a moment ago. each enters a period on a line by itself and optionally logs out. To exit.shell. .impl.
JXTA>env stdout = Default OutputPipe (class net. Incidently. Pooh. Note that talk advertisements created by talk -register hang around between shell sessions.shell." at begining of line Hello.PipeAdv) stdgroup = Default Group (class net.. as talk is a one-way piped message. We can take a closer look using our old friends.impl.
Piglet receives Pooh's message -. one must talk -login to start a new listener.albeit in rather ugly form.impl.JXTA>talk -u piglet pooh found user's advertisement attempting to connect talk is connected to user pooh Type your message. To exit. Now." at begining of line And a hello to you too. before one can chat..impl. a talk registration is simply a JXTA advertisement stored in a local environment variable. adv0 = local jxta advertisement (class net. Pooh.protocol.ShellOutputPipe) stdin = Default InputPipe (class net. You'll notice the slightly different form of talk -u piglet pooh.StdPeerGroup) JXTA>cat adv0 <?xml version="1. Piglet can't simply reply to Pooh. type ".jxta.jxta.jxta. resulting in a much cleaner message with proper attribution in Pooh's shell.
Where to go for more.org/issues/show_bug. such talk functionality has already been implemented in InstantP2P. Windows 2000 users may need to skip the installer and download the latest nightly build ZIP file. To start from scratch.
.org The JXTA Position Project JXTA Documents JXTA Shell Quick Start Guide JXTA Shell commands "Hello. groups and other advertisements. Windows (espectially Windows 2000) users may need to log out and back in.jxta. and completely confounds those more at home on the DOS or *nix command-line. type exit at the prompt or just close the shell window. delete the following files/directories: PlatformConfig.
To log out of the JXTA shell.
JXTA. JXTA!" Disclosure: The author has been a member of the JXTA's Technical Advisory Committee during its pre-launch development. the former copies selected text and the latter does nothing at all.. or even reboot. cached peers. a Java AWT-based GUI chat/file-sharing demonstration application. To clear your peer or group caches. and cm. Closing or exiting from the primary shell closes the entire application and all windows. Ctrl commands behave very much as Windows GUI users expect. Inc.cgi?id=2 Talk is currently extremely slow when not simply talking to yourself from one shell window to another. Sometimes launching the shell does absolutely nothing.Hardly user-friendly in its shell implemention. Shells spawned via Shell -s are not truly independent. At the time of this writing. there are a few gotchas and bugs: As mentioned above. Quite a bit of information is retained between shell sessions including settings.
Copyright © 2009 O'Reilly Media.
Bear in mind that the JXTA shell is only for demonstration and debugging purposes and should not be relied upon to be absolutely stable or emulate a full shell. See http://shell. ^C isn't interrupt and ^Z isn't suspend. use the -f option mentioned earlier. PlatformPeerGroup.