Design

The P2P game is a standalone application designed to have two main components: a user interface (client/front end) and JXTA integration (back end), which utilizes the latest JXTA platform release. The user interface displays peer and group information for monitoring purposes. The updating of such information is handled by the JXTA integration.

The P2P game places players (peers) in a jail community (group). In order to leave this jail community, a player must pass the jail token to a peer, but if that player doesn't have the jail token, she must first obtain the jail token from the peer who has it and then pass it on to another peer. After leaving, the player cannot return to the jail. It is easy to restructure the game to enable players to return to the jail, but after leaving, who in their right mind would want to return?

The first player in the P2P game creates the jail community, enters the jail, and automatically generates the only key (that is, the jail token) that would let anyone leave the jail. Others might join the jail, but they do not yet have the key. The key is not required to enter the jail, but is required to leave.

The P2P game demonstrates how messages are passed from peer to peer using direct connections as well as broadcast methods.

Application Details

This section outlines the highlights of the P2P game. To run this application, you need to have JDK 1.2 or higher installed on your machine.

The code for this application is contained in a zip file. Extract the contents of this zip file to a directory on your local disk. For your convenience, subdirectories for clients, namely the peers participating in this game, are also available in this directory. Each of the client subdirectories has a runCreate.bat file and a runJoin.bat file. The runCreate.bat file launches the application, and the runJoin.bat file lets a participant join the game.

Creating the Jail With One Peer

First you must create the jail with one peer. To create the jail with peer1, run the runCreate.bat application in the client01 subdirectory. The application launches a window for entering the configuration information about this peer. Select the Basics tab, seen in Figure 21.1.

Figure 21.1. JXTA Configurator Basic settings panel.

Enter a name for the peer in the Peer Name text field; for example, peer1. Click the OK button to proceed and provide other configuration details for this peer.

In the window that pops up, select the Advanced tab (see Figure 21.2).

Figure 21.2. JXTA Configurator Advanced settings panel.

Under the Advanced tab, note the TCP port number, which must be unique for this peer.

Select the Security tab. Under the Security tab, provide a unique username and password for this peer, as shown in Figure 21.3.

Figure 21.3. JXTA Configurator Security settings panel.

Select the Rendezvous/Routers tab. Make sure that the Use a Gateway box is unchecked, as shown in Figure 21.4.

Figure 21.4. JXTA Configurator Rendezvous/Routers settings panel.

Click the OK button. The program launches a client window for this first peer (peer1), as shown in Figure 21.5.

Figure 21.5. Client window for peer1.

You can perform queries at this point using the Help options, as shown in Figure 21.6. peer1 uses the F option to find out where the jail token is, and discovers that she has the token.

Figure 21.6. Using the Help options.

Creating peer2 and Playing the Game

To create the second peer, (peer2), run the runJoin.bat application in the client02 subdirectory. The application launches a window and prompts for information about this peer. Create this peer similarly to peer1, ensuring that this peer has a unique port number, username, and password.

By creating the second peer, the application creates the jail community, and peer2 joins the community, as shown in Figure 21.7.

Figure 21.7. peer2 is created and joins the jail community.

peer2 can use the Help options to check for the presence of other peers, check on who has the jail token, and request the token. peer2 uses the R option to request the jail token, and receives it (see Figure 21.8).

Figure 21.8. peer2 requests and receives the token.

The window for peer1 displays the message about sending the token to another peer (peer2 in this case) in Figure 21.9.

Figure 21.9. peer1 sends the token to peer2.

Now peer2 wants to pass the token to another peer. Therefore, peer2 uses the P option to search for peers, and discovers that there is only one other peer, namely peer1 (see Figure 21.10).

Figure 21.10. peer2 searches for peers and discovers only one other peer.

peer2 can transfer the token to peer1 by using the T <client> option, as seen in Figure 21.11.

Figure 21.11. peer2 passes the token to peer1.

Now the jail token is back with peer1. At this point, you can create peer3 to join the jail community.

peer3 Joins the Jail Community

To create the third peer, run the runJoin.bat application in the client03 subdirectory. The application launches a window and prompts for information about this peer. Create this peer similarly to peer1 and peer2, ensuring that this peer has a unique port number, username, and password. Now all the peers are ready to play the game.

peer3 Receives the Key from peer1

peer1 wants to transfer the jail token to peer3, and using the T <client> Help option, transfers the token to peer3. (A similar transfer appears in Figure 21.11.)

peer3 receives the jail token from peer1 in Figure 21.12.

Figure 21.12. peer3 receives the token from peer1.

peer3 Leaves the Jail Community

peer3 wants to leave the jail. In this game, peers have to pass the token to another peer in order to leave. Therefore, peer3 transfers the jail key to peer2 using the L <client> Help option and leaves the jail (see Figure 21.13).

Figure 21.13. peer3 passes the token to peer2 and leaves the jail.

The client window for peer2 broadcasts a message that peer2 received the jail token from peer3 in Figure 21.14.

Figure 21.14. peer2 receives the token from peer3.

Now the jail token is with peer2.

Transferring the Jail Token

In this game, the player who has the jail token cannot leave the jail without passing the token to a peer. In Figure 21.15, peer2, who has the jail token, attempts to leave the jail using the L <client> Help option without specifying a peer to receive the token.

Figure 21.15. peer2 tries in vain to leave the jail.

Scenarios

A perfect example of the P2P game is in creating a sales proposal document that many peers need to review before having it sent out. There is no specific hierarchy/ordering required, and everyone needs to sign off on the proposal.

Document Passing

Often it is necessary to circulate a document that needs to be edited by several people without using a central repository system. However, if only one person can edit the document, it is necessary to obtain the latest version of the document from the person who has that copy.

To facilitate such an operation, everyone interested in the document must communicate with one another to determine who has the latest version of the document, and there must also be a mechanism to request the document.

Approvals

In a purchase order scenario, several approvals from different supervisors/departments must be acquired before the purchase order is accepted. After a supervisor (peer) gives an approval, the purchase order can be sent to the next supervisor.

In enterprises, typically a purchase order must traverse a certain approval pathway to be converted into a real order. The pathway is often dictated by organizational roles and potential purchasing power. In the jail game, if we imagine that the jail token is a purchase order, we can also imagine multiple peer groups that represent multiple approval levels at a corporation. Each peer is then responsible for perhaps altering a component on the JXTA advertisement ("approve" flag), then publishing to a higher-ranking group for acceptance of the token (purchase order). We might need to extend the logic in each peer for the groups to send the token to a finance group if a "disapprove" flag is set at any level. After the token has traversed to a group that matches the highest approval level on the token (purchase order), the token is returned to the finance department for processing.

In the current jail game example, there is no hierarchy. However, the hierarchy can be implemented by building new peer groups.

Class Design

The JailGameClient class is responsible for setting up the jail community, as well as publishing its JXTA group advertisement remotely. If a client wants to join, the client has to search for the jail advertisement and join the group.

The client has the capability to do a broadcast message using the JXTA resolver service to acquire the jail token. The token can also be sent directly to another user.