Starting and Using the Shell

If you opted for a full download of the JXTA libraries in Chapter 16, you already have the code to run the JXTA Shell. If you did not use a graphical installer, go to the directory where you installed the JXTA libraries and find the shell subdirectory. If you don't have that directory, you will need to download the JXTA Shell from http://www.jxta.org.

Inside that directory, find jxta.exe (or on Unix, the run.bat file) and execute it. This batch file will cause the JXTA Shell to start up. As with all JXTA applications based on the J2SE JXTA binding, you will need to ensure that the JXTA environment has been properly set up. Please refer to Chapter 16 for an overview of the JXTA Configurator. After the JXTA Shell starts up, you will see a window similar to Figure 17.3.

Figure 17.3. The JXTA Shell.

Using the man Command

The best way to get acquainted with the JXTA Shell is to type in the man command, which stands for manual pages. The output of that command will be a list of all the commands the shell recognizes, along with a one-line description for each command. If you are familiar with some of the Unix shells, you will recognize many of the commands.

We've already seen the cat and grep commands, but the JXTA shell has the equivalent of clear, env, more, talk, wc (word count), who, whoami, and help, to mention just a few. If you type man followed by any of the JXTA shell commands, a detailed manual page for that command will be displayed.

Differences Between the JXTA Shell and Unix

The main difference between the JXTA Shell and its typical Unix relative is that the JXTA Shell's primary function is to let you interact with the JXTA virtual network, whereas the Unix shell enables you to interface with the operating system. As a result, the JXTA Shell supports only minimal interaction with the operating system; it is not able to run arbitrary OS commands, for instance. As well, each shell command interacts with objects relevant to the JXTA P2P network, not with objects defined by an operating system.

To appreciate that difference, consider the cat command in the context of the JXTA Shell. In the Unix version of that command, it concatenates a set of files, producing its output in the shell's standard output. JXTA does not directly interact with the filesystem; the JXTA equivalent of a "file" would be Document. The shell has to be able to identify a Document, and the cat command then takes as its parameter that document identifier and displays the document's content.

Environment Variables

The JXTA Shell takes advantage of the shell environment to associate JXTA-specific objects with variables. If you type the env command, it displays all the variables the current JXTA Shell instance knows of. Variable assignment occurs either explicitly, via the set or setenv commands, or implicitly as a result of executing certain commands.

Among the commands that implicitly assign environment variables are those that manipulate peers, peer groups, pipes, advertisement, and documents. The peers command, for example, prints a list of all peers the shell is aware of. Recall that peers are represented by peer advertisements; the peers shell command displays the peer advertisements it has discovered in its local cache, a behavior that corresponds to DiscoveryService's getLocalAdvertisements() method. For the advertisement search to propagate throughout the JXTA network, use the -r flag: peers -r (-r meaning remote). The command itself exits, but the discovery messages will propagate via relay peers, causing newly discovered peer advertisements to add to the local cache. Thus, issuing peers again after a while will likely produce a list including those newly discovered peers:

 JXTA>peers  peer0: name = aristotle peer1: name = aquinas 

As this example shows, the peers command assigns environment variables, which are listed on the left side. For instance, peer1 corresponds to a peer by the name aquinas. You can use the cat command to display the contents of that environment variable (see Listing 17.1).

Listing 17.1 Displaying a Peer Advertisement's Content

 JXTA>cat peer1 <?xml version="1.0"?> <!DOCTYPE jxta:PA> <jxta:PA xmlns:jxta="http://jxta.org">     <PID>      urn:jxta:uuid-59616261646162614A78746         150325033F09E3FC87DD34E52864FB8CDEB0398B803     </PID>       <GID>          urn:jxta:jxta-NetGroup       </GID>       <Name>          aquinas       </Name>       <Svc>       <MCID>          urn:jxta:uuid-DEADBEEFDEAFBABAFEEDBABE0000000605       </MCID>         <Parm>           <Rdv>             true           </Rdv>        </Parm>      </Svc>      <Svc>       <MCID>           urn:jxta:uuid-DEADBEEFDEAFBABAFEEDBABE0000000805       </MCID>       <Parm>         <Addr>            tcp://192.168.1.10:9701/         </Addr>         <Addr>           jxtatls://uuid- 59616261646162614A78746150325033F09E3FC87DD 34E52864FB8CDEB0398B803/TlsTransport/jxta-WorldGroup         </Addr>         <Addr>           jxta://uuid-59616261646162614A78746 150325033F09E3FC87DD34E52864FB8CDEB0398B803/         </Addr>         <Addr>            http:// JxtaHttpClientuuid-59616261646162614A78746150325033F09E3FC87DD34E52864FB8CDEB0398B803/         </Addr>      </Parm>      </Svc>      <Svc>      <MCID>         urn:jxta:uuid-DEADBEEFDEAFBABAFEEDBABE0000000105      </MCID>      <Parm>         <RootCert> MIICPDCCAaWgAwIBAgIBATANBgkqhki G9w0BAQUFADBmMRUwEwYDVQQKEwx3d3 cu anh0YS5vcmcxCzAJBgNVBAcTAlNGMQswCQ YDVQQGEwJVUzEUMBIGA1UEAxMLZnNv bW1lcnMtQ0ExHTAbBgNVBAsTFDA2M0E xNEZGODREOUQwMEI2NDUyMB4XDTAyMDQw  ODA1MDYyOVoXDTEyMDQwODA1MDYyOVo wZjEVMBMGA1UEChMMd3d3Lmp4dGEub3Jn MQswCQYDVQQHEwJTRjELMAkGA1UEBhMCVVM xFDASBgNVBAMTC2Zzb21tZXJzLUNB MR0wGwYDVQQLExQwNjNBMTRGRjg0 RDlEMDBCNjQ1MjCBmzALBgkqhkiG9w0BAQED  gYsAMIGHAoGBALwcEz8GNFp/7RybRFK 3Nw/Qz2bHjeLGA2XZqZi0Xlh6TUHumbE5  0VFPUuZBzRbIbp/vikRmy16NeG4MLM8 /iTT3HfKjxXNByDKtOtrCQPfLnQXiGLkM vXY2ksI4FHfmI6QbIEW2S/ND6jcVZ gtRddhr3XJUX3z5CjCAx8E8YRr/AgERMA0G CSqGSIb3DQEBBQUAA4GBAC7Uh+Q0WzRkMM 0TYmMDyLNiph5a7vxUO7RM/kI/qS7i  i59e3rJDRtV2hFrK2J6q003Vj9o9TOX cAxzzv31JDTGutSC9IaoHnKWFj973tk+j wjghmbtPFTDppZsqjvDJVf/rBxP1tVBVP gqc+vZfEox4ZETbrT9XQqvQI4JnKbok         </RootCert>        </Parm>     </Svc> </jxta:PA> 

As you can see, the content of the peer1 environment variable corresponds to a peer advertisement. If you call cat with the -p argument, it will display the content a variable refers to in a "pretty" format (without the XML tags). The groups command similarly displays peer groups (peer group advertisements). If presented with the -r argument, it likewise initiates remote peer group discovery.

The JXTA shell enables you to search for any sort of advertisement on the JXTA network. The following command searches for module spec advertisements with a Name attribute JXTASPEC:com.sams.p2p.primecruncher:

 JXTA>search -a Name  v JXTASPEC:com.sams.p2p.primecruncher -r  

The -a and -v parameters signify an attribute and value pair, whereas the -r parameter indicates that we'd like to propagate the discovery request on the JXTA network to remote peers. If you run the JXTA service application from Chapter 16 and type the search command again, in a few seconds you should have at least one advertisement matching that search criteria. You can then look at the contents of that advertisement with the cat command. Listing 17.2 locates the advertisement for the prime number-searching service. The module spec includes a pipe specification through which a client can contact the service.

Listing 17.2 Locating the Advertisement for the Prime Number-Searching Service

 JXTA>cat adv0 <?xml version="1.0"?> <!DOCTYPE jxta:MSA> <jxta:MSA xmlns:jxta="http://jxta.org">      <MSID>           urn:jxta:uuid-C4919B07BDBD4BDD923189BB 623CCF96D14DC34ECEE04C9688688FAEFE56DEBB06      </MSID>      <Name>           JXTASPEC:com.sams.p2p.primecruncher      </Name>      <Crtr>           Sams Publishing      </Crtr>      <SURI>           http://www.samspublishing.com/p2p/primecruncher      </SURI>      <Vers>           Version 1.0      </Vers>      <Desc>           Specification for a prime number crunching service      </Desc>      <jxta:PipeAdvertisement xmlns:jxta="http://jxta.org">           <Id>                urn:jxta:uuid-59616261646162614E50472050325 0333BA0BA91BA4A48F48E98AB94400A8EF704           </Id>           <Type>                JxtaUnicast           </Type>           <Name>                JXTAPIPE:com.sams.p2p.primecruncher           </Name>      </jxta:PipeAdvertisement> </jxta:MSA> 

You can also assign the contents of a file to an environment variable with the importfile command. As an example, consider the pipe advertisement created by the prime number compute server in Chapter 16. To persist the pipe information, that JXTA service wrote its pipe advertisement to a file. Using the importfile command, we can assign the contents of that file to a shell environment variable:

 JXTA>importfile -f /export/home/myfiles/primeserver_pipe.adv primepipe  

If you subsequently run the env command, you will notice the new environment variable primepipe. Running cat on the primepipe variable displays the contents of the advertisement file. As you can see, the advertisement read from the file is identical to the pipe advertisement section of the module spec advertisement we discovered via the search command:

 JXTA>cat primepipe  <?xml version="1.0"?> <!DOCTYPE jxta:PipeAdvertisement> <jxta:PipeAdvertisement xmlns:jxta="http://jxta.org">      <Id> <urn:jxta:uuid-59616261646162614E5047 2050325033AD6840F7B55347E4AE79AD0A65D5C42004      </Id>      <Type>           JxtaUnicast      </Type>      <Name>           JXTAPIPE:com.sams.p2p.primecruncher      </Name> </jxta:PipeAdvertisement> 

After you have that file content assigned to an environment variable, you can create an actual pipe advertisement from it with the mkadv command:

 JXTA>primepipeadv = mkadv -p -d primepipe  

The -p argument signifies that you want to create a pipe advertisement (mkadv can also create group advertisements with the -g argument), whereas the -d argument requests that the advertisement be created from the specified document. (We assigned the document name primepipe earlier.)

With a pipe advertisement in hand, you can create the actual pipe that connects to the prime search service. Because that service referred to its input pipe via the published pipe advertisement, you will need to create an output pipe to connect to that input pipe:

 JXTA>primeservice = mkpipe -o primepipeadv  

The mkpipe command creates output pipes with the -o parameter, and can create input pipes if you specify the -i parameter. When creating an output pipe, mkpipe returns only when that pipe is actually resolved. (Recall from Chapter 16 that an output pipe must first resolve the pipe's endpoint, which can take time.) When mkpipe returns, the primeservice shell variable contains a reference to an actual input pipe to the service.