Documentation of the JTella library

A. Davoust February 2009

This is the documentation of the JTella implementation of the Gnutella protocol by Ken McCrary, modied by Daniel Meyers, IBK Ajila, Alan Davoust.

Overview

The Jtella component described in this document is an implementation of the network interface layer for a P2P application. It implements the Gnutella network protocol v.0.6 [1].

Figure 1: Overview of the JTella implementation

Use Cases
Open Connections: The P2P Client starts the JTella component, initiating connections from the HostCache. Network Search Session: The P2P Client initiates a search session. Query messages are output to all connected hosts, and the system periodically checks for new connections (and sends the query to any new connection), until the P2P Client closes the search session. 1

Uses cases initiated by the local P2P Client:

Uses cases initiated by a Remote Host: Gnutella Connect: A remote host opens a new connection. Gnutella Message: A remote host with an existing connection sends a Message of the Gnutella protocol, which is one of : Ping / Pong / Query / QueryHit / Push. The details of the routing rules are described in [1]. Ping messages are answered with a Pong message, and propagated. Pong messages are routed back to the initiator of the corresponding Ping. If the Pong originates from an unknown host, the component attempts to open a new connection with this host. Query messages are propagated and are also sent to the P2P system, which may then respond with a QueryHit message. QueryHit messages are either routed to the initiator of the corresponding Query, if the query originated from another host, or if the Query originated from the local P2P Client, the QueryHit is extracted and given to the P2P Client. Push Messages are either routed to the initiator of the corresponding QueryHit, if the QueryHit originated from another host, or if the QueryHit originated from the local P2P client, then the push message is extracted and sent to the local P2P Client.

Overview of the Implementation

The general structure of the JTella component is presented in the class diagram 3. Some classes are omitted from this general diagram, and shown in the follwoing sections, which focuses on specic aspects of the component functionality. 2

The Jtella component is heavily multithreaded. The central class Gnutella Connection maintains a list of NodeConnection objects, which each manage a connection with a remote host. The NodeConnection runs with its own thread, waiting for new messages from its remote host, and maintains a priority queue of outgoing messages, which are sent by an AsyncSender. For each received Gnutella message, the NodeConnection passes the message to the Router, which saves the message identier in a routing table and propagates it according to the rules established by the Gnutella Protocol [1], by sending outgoing messages to the other NodeConnections. These NodeConnections are created by two Connection Managers. An IncomingConnectionManager waits for new connections from remote hosts, and an OutgoingConnectionManager attempts to connect to hosts listed in the HostCache (a list a hosts extracted from a le).

Connections

Figure 2 shows the details of a Connection implementation.

Figure 2: Connections in JTella A Connection is a connection to a single remote host. The Abstract class Connection is the base class for NodeConnection and InformationConnection. NodeConnections handle active connections, whereas InformationConnections are used when the Gnutella component already has enough active connections: if a new peer tries to connect, the InformationConnection sends a series of Pong messages (prividing the addresses of other hosts to connect to) and closes. The AsyncSender manages outgoing messages using the priority queue of Messages. Ping and Pong messages are low priority, whereas queries, query hits, and push messages have higher priority. Each Message is identied by a GUID (which is a sequence of bytes). 4

The Reader / Writer and Data Streams provide an interface to send and receive data through sockets.

Searches and Message Routing

Figure 3 shows the classes involved in searches and message routing.

Figure 3: Message routing in JTella

5.1

Incoming messages

Incoming messages are received by the NodeConnections and sent to the Router. The Router outputs a copy of the message (with a decremented TTL) through the other NodeConnections (according to the Gnutella protocol). The 5

Router also stores the GUID of the message with a reference to the NodeConnection that this message came from, in the specic RouteTable for the message type (Ping, Query, or QueryHit). RouteTables encapsulate HashMaps implementation that handle this storage. Pong and Push messages are not stored, but routed back to the Connection that the corresponding Ping (respectively QueryHit) came through. QueryHit messages are both stored and routed back to the originating connection of the corresponding Query.

5.2

Searches

Searches are handled by SearchSession objects, that are created by the createSearchSession() method of the GnutellaConnection. A SearchSession is a runnable thread, and once started, it outputs search messages to all the active NodeConnections, including new NodeConnections that are added during the session. A reference to a listener for query responses is also given to the Router which stores it in the OriginateTable. QueryHit messages will then trigger a notication of this listener. The session ends when the close() method is called on the SearchSession. The SearchSession then unsubscribes the listener from the Router, and no further responses are returned to the listener.

Management of New Connections

Figure 4 shows the classes involved in managing the connections in JTella.

6.1

Bootstrapping

P2P clients need to know at least one existing peer in order to join a network. Lists of known hosts are stored on the web in so-called WebCache les. The class GetHostFromCache uses a le with a list of URLs (congured in GetHostFromCache.java), which are supposed to be the URLs of online web caches, and connects to each WebCache to nd hosts. The class GWebCaches provides a way of storing a hard-coded list of webcache URLs.

6.2

Management of Active Connections

At startup, the GnutellaConnection populates the HostCache this way, then the connections are handled by the OutgoingConnectionManager and the IncomingConnectionManager. The OutGoingConnectionManager attempts to connect to hosts in the HostCache, and when successful adds the new NodeConnections to the GnutellaConnections ConnectionList.

Figure 4: Connection Management in JTella The IncomingConnectionManager listens for new connection attempts from remote hosts, and creates NodeConnection objects from successfully started connections. The NodeConnections are also added to the ConnectionList.

Integration

Integrating the JTella component in a P2P application involves the following aspects: Creating the Gnutella Connection The P2P client needs to create a GnutellaConnection object. Populating the HostCache The HostCache can be populated via online WebCaches, either listed in a le called gwebcache.list or hard-coded into the 7

source GWebCache.java. Alternatively, the P2P client can store a list of hosts by some other means, then access the GnutellaConnections HostCache and insert the hosts. Managing Network searches SearchSession objects are used to handle network searches. To create new SearchSessions, the P2P client must use the createSearchSession() method of the GnutellaConnection. The arguments of the method are the following: query search query querytype the type of the query (get by name / get by hash : see SearchMessage.java) maxResults maximum result set size minSpeed minimum speed for responding servants receiver receiver for search responses (see below) Managing incoming messages In order to receive searches and responses for its own searches, the P2P client must implement the interface MessageReceiver, which consists of the three methods: public void receiveSearch(SearchMessage) public void receiveSearchReply(SearchReplyMessage) public void receivePush(PushMessage) These methods will be invoked when the JTella component receives respectively a search message, a reply to a search that the P2P client has initiated, and a push message. Logs The code has been almost completely adapted to use the logging system Log4J [2]. The appropriate library must be available and a conguration le must create a logger called protocol.com.dan.jtella.

References
[1] Gnutella: The gnutella protocol specication 0.6. http://rfc-gnutella. sourceforge.net (2002). [2] Log4J logging system. http://logging.apache.org/log4j/