Diploma Project
DHT-based Routing and Discovery in JXTA Nicolas Th´eodoloz School of Computer and Communication Sciences Computer Science Departement
Submitted to
Supervisor
Laboratoire de Syst`emes R´epartis
Sameh El-Ansary
Director: Andr´e Schiper Ecole polytechnique f´ed´erale de Lausanne Switzerland
Distributed Systems Laboratory Director: Per Brand Swedish Institute of Computer Science Kista, Sweden
February 2004
Abstract The goal of this project is to make use of the scalable properties of DHT systems in providing an efficient implementation for routing and discovery in the JXTA protocol stack. The contribution of this project is threefold. The first contribution is to provide a detailed description of JXTA, in particular the elements concerning the routing protocols. This part of JXTA has indeed not yet been described in detail neither by the JXTA authors nor by other researchers in any document. The second contribution is to provide generic interfaces allowing to plug any DHT into the JXTA framework and thus improve the JXTA routing. The third contribution is the creation of a common peerto-peer framework allowing to join the efforts of the high-level application developers, the JXTA community and the researchers in structured distributed systems.
Acknowledgments I would like to thank Sameh El-Ansary, my direct supervisor, for his enduring support and guidance. This project benefits greatly from his insights, his suggestions and his deep knowledge in the area concerned by this project. Per Brand, the team leader of the DSL lab at SICS, deserved also thanks for welcoming me in his lab and for his useful suggestions all along the project. Finally, I would like to thank Prof. Andr´e Schiper of the LSR lab at the EPFL for his precious help in finding a lab for a project in mobility and for accepting to take the responsibility of my diploma work. I would like also to thank Prof. Seif Haridi who accepted to supervise this project in Sweden and introduced me to Sameh and Per.
Contents Introduction 1 Peer-to-Peer Systems 1.1 Overview . . . . . . . . . 1.2 Technical Challenges . . . 1.3 Applications . . . . . . . . 1.4 Evolution . . . . . . . . . 1.4.1 First Generation . 1.4.2 Second Generation 1.4.3 Third Generation .
1
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
3 4 4 5 5 5 5 6
2 Distributed Hash Tables 2.1 Pastry . . . . . . . . . . . . . . . . . . . . . . . . 2.1.1 Overview . . . . . . . . . . . . . . . . . . 2.1.2 Pastry Algorithms . . . . . . . . . . . . . 2.2 Related Work: FreePastry . . . . . . . . . . . . . . 2.2.1 FreePastry Project . . . . . . . . . . . . . 2.2.2 Core Elements . . . . . . . . . . . . . . . 2.2.3 Algorithms . . . . . . . . . . . . . . . . . 2.2.4 Network Connections . . . . . . . . . . . . 2.2.5 A Storage Application: Past . . . . . . . . 2.3 Chord . . . . . . . . . . . . . . . . . . . . . . . . 2.3.1 Overview . . . . . . . . . . . . . . . . . . 2.3.2 Chord Space and Key Assignment . . . . . 2.3.3 Algorithms . . . . . . . . . . . . . . . . . 2.4 Related Work: Cooperative File System . . . . . . 2.4.1 A Chord Implementation . . . . . . . . . . 2.4.2 Cooperative File System (CFS) . . . . . . 2.4.3 Replication . . . . . . . . . . . . . . . . . 2.4.4 Caching . . . . . . . . . . . . . . . . . . . 2.4.5 Load-balancing . . . . . . . . . . . . . . . 2.5 Towards a common Architecture . . . . . . . . . . 2.5.1 A common Software Architecture . . . . . 2.5.2 A common API . . . . . . . . . . . . . . . 2.5.3 Related Projects applied to the Architecture
. . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . .
9 10 10 10 13 13 13 14 16 16 19 19 20 20 22 22 22 22 22 23 23 23 24 25
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
i
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
CONTENTS
ii
3 JXTA 3.1 JXTA Project . . . . . . . . . . . . . . . . . . . . 3.2 JXTA Concepts . . . . . . . . . . . . . . . . . . . 3.3 JXTA Services and Protocols . . . . . . . . . . . . 3.4 JXTA Indexing and Routing . . . . . . . . . . . . 3.4.1 JXTA 1.0 . . . . . . . . . . . . . . . . . . 3.4.2 JXTA 2.0 . . . . . . . . . . . . . . . . . . 3.5 Formalization and Algorithms . . . . . . . . . . . 3.5.1 Objective . . . . . . . . . . . . . . . . . . 3.5.2 Notation and Definitions . . . . . . . . . . 3.5.3 Algorithms . . . . . . . . . . . . . . . . . 3.6 Scenarios . . . . . . . . . . . . . . . . . . . . . . 3.6.1 Scenario 1: Indexing . . . . . . . . . . . . 3.6.2 Scenario 2: Joining of Rendez-vous Peers . 3.6.3 Scenario 3: Leaving of Rendez-vous Peers 3.7 JXTA Booting Process . . . . . . . . . . . . . . . 3.7.1 JXTA Configurator . . . . . . . . . . . . . 3.7.2 JXTA Platform Booting . . . . . . . . . . 3.8 Related JXTA Projects . . . . . . . . . . . . . . . 3.8.1 GISP: Global Information Sharing Protocol 3.8.2 JXTA Distributed Indexing . . . . . . . . . 3.8.3 JXTA Content Management System . . . . 3.8.4 Summary of the JXTA Projects studied . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
27 28 28 32 34 34 35 36 36 36 37 40 41 42 43 45 45 45 46 46 49 50 51
4 A DHT plugged into JXTA 4.1 Objective . . . . . . . . . . . . . . . . 4.2 DHT Routing Improvements . . . . . . 4.3 Interfaces . . . . . . . . . . . . . . . . 4.4 Adaptors . . . . . . . . . . . . . . . . . 4.5 The DHT Point of View . . . . . . . . . 4.6 Modifications to the JXTA Distribution 4.7 Implementation . . . . . . . . . . . . . 4.7.1 Overview . . . . . . . . . . . . 4.7.2 Shell Application . . . . . . . . 4.8 Propagation . . . . . . . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
53 54 55 55 56 57 58 59 59 60 61
5 JXTA Personal Point of View 5.1 JXTA Project . . . . . . . . . . 5.2 Documentation . . . . . . . . . 5.3 Routing and Indexing . . . . . . 5.4 Framework . . . . . . . . . . . 5.5 Java Source Code . . . . . . . . 5.6 Distributions . . . . . . . . . . 5.7 Further suggested Improvements
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
63 64 64 64 65 65 65 66
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
Future Work
67
Conclusion
69
Bibliography
71
CONTENTS
iii
A JXTA Use Cases A.1 Discovery Service . . . . A.2 SRDI Service . . . . . . A.3 Resolver Service . . . . A.4 Pipe Service . . . . . . . A.5 Peer Information Service A.6 Rendez-vous Service . . A.7 Endpoint Service . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
75 . 76 . 81 . 83 . 87 . 91 . 94 . 101
B JXTA Shell 105 B.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 B.2 Main Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 C Plugin Java Sources C.1 DHTInterface . . . . . C.2 JXTAInterface . . . . . C.3 JXTAAdaptor . . . . . C.4 DHTAdaptor . . . . . C.5 DHTTemplate . . . . . C.6 DHTPastry . . . . . . C.7 DHTFactory . . . . . . C.8 Message . . . . . . . . C.9 DHTEvent . . . . . . . C.10 NoSuchDHTException
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
111 112 113 114 117 120 121 124 125 125 126
iv
CONTENTS
List of Figures 2.1 2.2 2.3 2.4
Example of a Pastry Node State . . . . . Chord key assignment . . . . . . . . . . . Common Software Architecture . . . . . Common Software Architecture with APIs
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
11 20 23 24
3.1 3.2 3.3 3.4 3.5 3.6
JXTA Edge Peers and Rendez-vous Peers . . . . . . . JXTA Protocols and Services . . . . . . . . . . . . . . JXTA Use Case application: publish an advertisement JXTA Routing and Indexing: Scenario 1 . . . . . . . . JXTA Routing and Indexing: Scenario 2 . . . . . . . . JXTA Routing and Indexing: Scenario 3 . . . . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
29 32 34 41 42 44
4.1 4.2 4.3 4.4 4.5 4.6
Common Software Architecture applied to JXTA . . . . . . Common Software Architecture applied to JXTA with APIs . FreePastry plugged into JXTA . . . . . . . . . . . . . . . . DHT Initialization in the JXTA Rendez-vous Service . . . . Lookup Method in the JXTA Rendez-vous Service . . . . . Implementation Organization . . . . . . . . . . . . . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
54 56 58 59 59 60
v
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
vi
LIST OF FIGURES
Introduction Peer-to-peer computing is a notion used to describe the current trend toward exploiting the full resources available within a network. The resources include disk storage, bandwidth and processing cycles. Information is exchanged between the elements of the network: efficiently locating and transmitting data becomes then an important issue. To construct a large-scale network and provide an efficient routing of messages, structured peer-to-peer overlay networks (also called distributed hash tables (DHTs)) have been studied and evaluated by different groups of researchers. They provide good properties concerning scalability, resilience and routing efficiency. On the other hand, the JXTA project intends to provide a common peer-to-peer platform dealing with the heterogeneity of the physical network and providing abstractions which can be used by applications built on top of the JXTA framework. This framework needs also to route messages in the network. The approach used by JXTA for the routing is however different than a structured peer-to-peer overlay network. This project first analyzes the JXTA routing protocols in comparison with structured peer-to-peer networks and then provides a solution to integrate any structured peer-to-peer network into the JXTA framework through replacing its own routing protocols.
Organization The report starts by presenting in Chapter 1 the peer-to-peer systems outlining their advantages, their evolution and the still open issues. Chapter 2 details structured peerto-peer overlay networks called distributed hash tables (DHTs). Chapter 3 describes and evaluates the JXTA peer-to-peer framework focusing on the routing algorithms. In Chapter 4, interfaces allowing to plug any DHT into JXTA are presented. Chapter 5 discusses JXTA and in particular the Java reference implementation according to our deep study of the source code all along the project. And finally, possible future work is suggested and the project summarized and concluded. Appendix A details with UML Use Cases the interactions between the different layers (called services) in JXTA: this description allowed, among other things, to extract the routing and indexing algorithms and understand how and where they are implemented. Appendix B presents the main commands of the JXTA Shell which is an application allowing to interact with and test the JXTA framework. Appendix C includes the interfaces and classes presented in Chapter 4.
1
2
Chapter 1
Peer-to-Peer Systems
3
CHAPTER 1. PEER-TO-PEER SYSTEMS
4
1.1 Overview Peer-to-peer (P2P) systems try to optimize the use of the resources available in a network of nodes, called peers. Each peer provides computing and storage capacity and interacts with other peers in order to use and supply services. In such a system, it is generally assumed that no peer has a global knowledge of the network: peers are autonomous and self-organizing, according to their local knowledge. Moreover, peers and connections are unreliable: a peer can leave or join the network at any time; a message sent to one element can be either delivered or lost. The following resources must then be exploited in the most efficient way by each peer: Bandwidth : peers on the network need to connect to other peers to use specific services. The problem is that some connections in the network become more and more used, while others remain under-exploited. Peer-to-peer systems should therefore balance the traffic among the available connections. Locating a peer or a service should moreover generate the less traffic as possible in order to keep the network scalable. Computing Resources : if these resources are badly shared, some computers become overloaded, while others keep idle most of the time. Computing must then be load-balanced on the elements of the system. As more people connect to the network, more computing resources are available and can thus be shared by the participants. This property is usually the opposite in a typical client/server model, as a server needs to share its own resources with all the clients connected. Storage : storage capacity of each element of the network provides a huge quantity of memory. Moreover, scalability is guaranteed by the fact that each new peer which joins the network increases the overall storage capacity of the system. This distributed storage must however be managed properly when new peers join or leave the network. According to the previous properties, peer-to-peer systems share the following features: • no single point of failure: when an element leaves the network, the system should continue to work without any interruption and, under some assumptions, still provides the same services. • scalability: as more nodes join the network, bandwidth, computing resources and storage capacity increase, offering a good scalability to the system. • load-balancing results from the fact that each peer is equivalent and can be used for storing elements and providing a service.
1.2 Technical Challenges Scalability and Performance rely on a good distribution of the items stored and the services to the network, as well as efficient routing algorithms. Fault-tolerance is difficult to provide in peer-to-peer systems, as peers and connections are unreliable and as the network topology changes through new joins and
1.3. APPLICATIONS
5
leaves. Replication is often used to improve the fault-tolerance of a system: replication can also be used in peer-to-peer systems to overcome the problem of nodes departures. However, replication adds the problem of consistency of data and does not resolve the unreliable connections issue. Guarantee of finding an item is a good property featured by client/server systems. If an item is available on the server and the server is active, it can be accessed. In peer-to-peer systems, due to the overall unreliability of the peers and the connections and network changes, such a property is more difficult to provide. Without this guarantee, storage of important data (not only music files) remains a problematic issue.
1.3 Applications File Sharing using the storage capacity of the network: KaZaA [10], Overnet [14] Freenet [2], OceanStore [12], . . . Grid Computing using the computing resources of the network: Entropia [1], SETI@home [16], Genome@home [4], . . . Instant Messaging using the distributed network properties: Jabber [7], Onobee [13], ... Group Collaboration Groove [6], Magi [11], . . .
1.4 Evolution The following transitions between the different kinds of peer-to-peer systems were suggested in [24] and are not necessary the common way to classify them. However, they allow to highlight the main motivations of each generation of peer-to-peer systems.
1.4.1 First Generation The first generation of P2P systems focused on the topic of file-sharing, especially music files sharing. Napster was the first application providing such a service using P2P features. Napster used however a centralized directory where clients could export the names of the files that resided locally on their host. The storage of files (mp3 files) remained at the clients. A client, looking for a file, first queried the centralized directory and got back a list of peers storing this file. The client could then download the file directly from a chosen peer of that list according to estimated bandwidth and round trip time. Thus, the storage service is peer-to-peer, but the directory service, using a centralized file location directory constitutes a bottleneck vulnerable to a single failure.
1.4.2 Second Generation The second generation of P2P systems wanted to eliminate the problematic centralized coordination from the first generation. Gnutella and Freenet received a lot of attention when Napster was shut down.
CHAPTER 1. PEER-TO-PEER SYSTEMS
6
Gnutella stores the files as in Napster at the users of the system. However, no centralized localization server is used. To find a file, a flooding approach is used: a search request is forwarded to neighbouring users until it reaches a node where the file is available or exceeds a limited time-to-live. The system is then very robust. However, this approach has also some problems: • flooding search messages to all neighbouring nodes consumes network bandwidth • no central control assures the quality and well-behavior of the participants. Freenet uses an adaptive routing and a caching strategy: each node stores some index information and data. When a request arrives, either the data is in the cache, or the request is forwarded to another node according to a proximity definition until the data is found or a time-to-live is reached. When an answer arrives, the peer caches it (the data and the index information) using specific caching strategies. Both of these systems solve the problem of central coordination. However, they lead to solve other issues such as scalability (flooding leads to a high network traffic) and guarantees of finding an available data in the network. The third generation tries to overcome these problems.
1.4.3 Third Generation Research projects such as Chord [32], CAN [28] and Pastry [30] provide frameworks known as Distributed Hash Tables (DHTs). Each peer in such systems is identified by an hash code of some of its unique attributes (IP address or public key). Nodes are then connected to each other in a defined topology such as a circular space (Chord, Pastry) or a d-dimensional space (CAN). Thanks to these topologies, a lookup process as well as the routing information stored in each peer are in most cases bound to the logarithmic size of the network. Moreover, guarantees of finding data are very high. Pastry: each node maintains a routing table, a neighbourhood set and a leaf set. The routing table is organised in log 2b N rows (b is a configurable parameter, generally 4) representing the pointers to the other nodes sharing a common ID prefix and in 2b − 1 columns representing the first different digit from the local node ID. The leaf set contains the pointers to the nodes that are the closest to the local node ID. The neighbourhood set contains nodes which are closest according to the real network proximity. The routing information stored at each Pastry node is O(log N ) and lookups are resolved in O(log N ) hops. Pastry is described in more details in section 2.1. Chord: assuming a network of size N , each Chord node stores O(log N ) routing information and resolves all lookups via O(log N ) messages. Unique IDs are associated with both data items and nodes, using a consistent hashing. Keys (hash value of data IDs) are assigned to nodes as follows: identifiers are ordered in an ”identifier” circle modulo 2 m where m is the maximal length of the hash value. Key k is assigned to the first node whose identifier is equal or follows k in the identifier space. Chord is described in more details in section 2.3.
1.4. EVOLUTION
7
CAN: CAN (Content Addressable Network) is organized in a virtual d-dimensional coordinate space. Every node owns its individual zone. An object is located by forwarding a request to the neighbour with the closest coordinates to the destination. Each node maintains a routing table containing the coordinates of a part of its neighbours. CAN stores a routing table which has a constant size (O(d) where d represents the dimension of the space), but lookups are less efficient than Chord and Pastry (O(dN 1/d )).
8
CHAPTER 1. PEER-TO-PEER SYSTEMS
Chapter 2
Distributed Hash Tables
9
10
CHAPTER 2. DISTRIBUTED HASH TABLES
2.1 Pastry 2.1.1 Overview Pastry [30] is a completely decentralized, scalable and self-organized P2P overlay network system. Pastry provides efficient algorithms for object location and routing within this network. A node efficiently routes a message to the numerically closest node to a key specified within the message. Pastry tries to minimize the length of this route defined by the number of hops.
2.1.2 Pastry Algorithms Node Identifier Each Pastry node is assigned a 128-bit node identifier (node ID), thanks to a hash code of its unique data such as its IP address or its public key. These node IDs should be uniformly distributed in the space. This node ID indicates its position in the ID space which ranges from 0 to 2 128 − 1. Node State In order to efficiently route messages, each Pastry node stores three tables: a routing table, a leaf set and a neighbourhood set. The routing table (called R) is a two dimensional table. An entry in row i and column j of a node points to a node whose ID shares the same prefix of length i as the local node and whose (i + 1)th digit is j. Thus, i varies from 0 to log 2b N (b is a configuration parameter which balances the size of the routing table and the number of hops to find a data; a digit is composed of b bits; N is the maximum size of the network) and j from 0 to 2 b − 1, which represents all the values a digit can be affected. The leaf set (called L) contains two sets of nodes: l/2 numerically closest smaller node and l/2 numerically larger closest node. The distance definition is based on the IDs. The neighbourhood set (called M) contains the m closest nodes, according to a proximity metric within the real network. Table 2.1 presents an example of the state of a pastry node at a given moment of its existence. Routing Process The Pastry routing algorithm is presented in Algorithm 1. It is executed when a message with key D arrives at a node with node ID A. Notation used: Rli is the entry in the routing table R at row l and column i Li is the i-th closest node ID in the leaf set L; a negative index indicates a smaller node ID than the local node Dl is the value of the l’s digit in the key D
2.1. PASTRY
11
Node ID 10233102 Leaf set SMALLER 10233033 10233021 10233001 10233000
LARGER 10233120 10233122 10233230 10233232
Routing Table 0 1 2 3 4 5 6 7
0 02212102 0 10031203 10200230 10230322 10233032 0
1 1 11301233 10132102 10211302 10231000 1
13021022 02212102
10200230 22301203
2 22301203 12230203 2 10222302 10232121 10233232 10233120 2
3 31203203 13021022 10323302 3 3
Neighbourhood set 11301233 31203203
31301233 33213321
Figure 2.1: State of a pastry node instance with node ID 10233102, b = 2, N = (2b )8 = 65536, l = 8 and m = 8. The shaded cells of the routing table show for each row the corresponding digit of the local node ID. The italic digits present the prefix shared with the local node ID and the bold digit the first digit which differs from the local node ID. shl(A, B) is the length in digits of the prefix shared by A and B When a node receives a message, it first checks to see if the key is within the range of node IDs covered by its leaf set (line 1). If it is the case, the message is forwarded directly to the node whose ID is the closest to the key (line 2). If the key is not covered by the leaf set (line 3), then the routing table is used: the message is forwarded to the node that shares a common prefix with the key which is at least one digit more than the prefix shared by the current node and the key (lines 4, 5 and 6). If this entry does not exist, the message is forwarded to a node that shares a prefix with the key at least as long as the current node and that is numerically closer to the key than the current node (lines 8, 9, 10). This routing procedure converges, because each step forwards the message to a node that either shares a longer prefix with the key than the current node, or shares an as long prefix but is numerically closer to the key than the current node. It can be shown that the expecting number of routing steps is log 2b N , assuming accurate routing tables and no recent node failures. Joining of Nodes When a new node X wants to join the network, it has to initialize its state tables. The knowledge of a nearby Pastry node A, which is already in the system, is assumed. Node X asks node A to route a join message with a key with the value X. Pastry starts to route this join message which finally reaches an existing node Z, whose ID is numerically closest to X.
CHAPTER 2. DISTRIBUTED HASH TABLES
12
Algorithm 1 Pastry routing algorithm 1: if L−|L|/2 ≤ D ≤ L|L|/2 then {D is within the range of our leaf set} 2: forward to Li , s.th. |D − Li | is minimal 3: else {use the routing table} 4: l ← shl(D, A) 5: if RlDl = null then 6: forward to RlDl 7: else {rare case} 8: forward to T ∈ L ∪ R ∪ M , s.th. 9: shl(T, D) ≥ l, 10: |T − D| ≤ |A − D| 11: end if 12: end if
All nodes encountered on the path from A to Z send their state tables to X. X can now initialize its own state tables as following: • The routing table is filled with entries from the state tables received by the peers from A to Z. The i-th row of its routing table is filled with the routing table of the i-th node encountered from the peers A to Z: these peers share at least a prefix of i digits with A. • The leaf set is based on Z’s leaf set: Z and A have the most similar keys in the network, thus Z’s leaf set can be directly used by A’s leaf set. • The neighbourhood set is based on A’s neighbourhood set: it is in fact assumed that A is physically very close to X. Finally, X forwards a copy of its state tables to each of the nodes found in its tables. Those nodes can then update their state tables, according to the new joined node. An optimistic approach can be used to control concurrent node arrivals using timestamps. When a node A sends its state to another node B, it attaches a timestamp with the message. B updates its state and send to A its new state and the timestamp previously received from A. A can then check if a new node has joined this part of the network in the meantime: if the timestamp is no more valid, A informs B that it has to start the process again. This optimistic approach is applicable in this case, if we consider that arrivals of nodes affect only a small number of nodes in the network. Nodes Departures and Failures Nodes may fail or leave without warning. The peers who have an entry in their state tables pointing to them have then to update their local tables: • to repair a failed routing table entry R ld , a node contacts first another entry Rli , i = d of the same row: this entry may have an entry for R ld in its routing table. If such a node is not found, the node can next extend the search to a wider i net using an entry R l−1 . This procedure is highly likely to find an appropriate existing node. • a process periodically checks the availability of the nodes belonging to the leaf set. To replace a failed node, the node with the largest index on the side of the
2.2. RELATED WORK: FREEPASTRY
13
failed node (smaller or larger than the local node ID) is contacted to obtain its leaf set. When the leaf set is received, it is traversed to find a suitable replacement node. This node will exist, because the contacted node’s leaf set partly overlaps the current node’s leaf set. This procedure guarantees the repair of the leaf set, unless l/2 nodes with adjacent node IDs fail simultaneously. • the neighbourhood set is kept up-to-date, also by attempting to contact periodically each node from the set and by requesting the neighbourhood sets of the other members of the set if it is necessary.
2.2 Related Work: FreePastry 2.2.1 FreePastry Project FreePastry [3] is an open-source implementation of Pastry intended to perform further research and development in P2P systems. The distribution source code is written in Java. The description of FreePastry which follows results from the study of the source code (version 1.3) and was not provided by the authors. The names of the FreePastry classes related to each description are thus provided. We assume that the top level rice is explicit (for instance pastry.PastryNode stands for rice.pastry.PastryNode).
2.2.2 Core Elements Pastry peer/node [pastry.PastryNode]: a node with an ID storing and managing a routing table and a leaf set. No neighbourhood set is maintained. Routing table [pastry.routing.RoutingTable]: the routing table stores pointers to other peers according to the corresponding definition in Pastry. Leaf set [pastry.leafset.LeafSet]: the leaf set stores the peers with similar keys with the local node as explained in Pastry. Pastry application [p2p.commonapi.Application]: applications can be installed on top of the Pastry peers network. An application can ask to the underneath Pastry node to get optimal routing information. When a message arrives at a peer, it is transmitted to the related application. The application can then decide whether to deliver the message or to forward it to another Pastry node. Two main applications are included in the FreePastry distribution: PAST [p2p.past.Past] which is a global storage utility described in section 2.2.5. SCRIBE [scribe.Scribe] which is a publish/subscribe system. Pastry endpoint [p2p.commonapi.Endpoint]: an endpoint is the virtual node upon which an application can call methods: an endpoint is obtained by registering an application to a Pastry node. The endpoint has access to the routing table and to the leaf set of the Pastry node. This endpoint offers the following services:
CHAPTER 2. DISTRIBUTED HASH TABLES
14
• sending of a message either directly to a node or using the routing of the Pastry network • reception of messages from the Pastry node and transfer to the application • notification to the application of modifications of the routing table and the leaf set • selection of a list of nodes which can store replicas of an object, according to the local node leaf set Thus, an application has to use this endpoint to communicate with the underneath Pastry node. Security Manager [pastry.security.PastrySecurityManager]: a security manager is associated with each Pastry node and can check the safety of a message and the credentials associated with peers. Message Dispatcher [pastry.messaging.MessageDispatch]: a message dispatcher stores the mapping between messages and receivers; it is used to transmit messages received by the node to the different Pastry components, such as the routing table, the leaf set or application endpoints.
2.2.3 Algorithms Routing Process [pastry.standard.StandardRouter] When a message must be sent and the final destination is not known (for instance for a lookup), an intermediate peer is selected using the Pastry routing algorithm (similar to algorithm 1) according to a key expression. The message is then sent directly to the selected peer which checks in its turn if it is the closest peer to the key. If it is the closest, the message is delivered; otherwise, a new destination peer is selected again using the Pastry routing algorithm. This process is repeated as long as the closest peer is not reached. Message used: Route Message [pastry.routing.RouteMessage] is a generic message routed in the pastry network. This message includes an internal message destined either to a Pastry component (routing table, leaf set) or to a specific application. Join Protocol [pastry.standard.StandardJoinProtocol] When a node wants to join the network, it has first to find a node already member of the network. This part of the protocol is managed by the underneath network transport (section 2.2.4). Assuming that the new node A knows another node B, A sends a message (Initiate Join) to B. The node B creates a new message (Join Request) containing the ID of A, which is routed in the network. Each node encountered from the initial node B to the closest node to A’s ID Z inserts its corresponding routing table row in the message. Node Z then adds its leaf set to the message and the join request is sent back to A. Finally, the node A first initializes its routing table and leaf set and then sends each row
2.2. RELATED WORK: FREEPASTRY
15
of its routing table to the node of the same row which is the closest to A’s ID. Messages used: Initiate Join [pastry.join.InitiateJoin] is the message sent by a peer that wants to enter the Pastry network; it is sent to a peer already member of the network. Join Request [pastry.join.JoinRequest] is the message sent by the node that accepted to take care of the join of a new node. When a node receives this message, it checks if it is the terminal node, which means the one with the closest ID with the new peer. If it is the terminal node, it sends the message back to the initiator, otherwise it routes the message to another peer. Routing Table Maintenance [pastry.standard.StandardRouteSetProtocol] The routing table is maintained at different times: • an internal message (Initiate Route Set Maintenance) is periodically received by the routing table: for each row of the routing table, the routing table manager picks an element and swaps the row with the node it points to (Broadcast Route Row and Request Route Row messages). • when a node enters the network, its new built routing table is sent to a set of peers belonging to the routing table (a part of the join protocol). • when a route message is received by a node, the routing protocol checks if the last node the message went through had an entry in its routing table which was used for the last routing hop (one more digit was resolved). If the previous node did not have a suitable entry, the node sends its own row to the previous node to patch the hole in its routing table. Messages used: Initiate Route Set Maintenance [pastry.routing.InitiateRouteSetMaintenance] to start the process of the maintenance Broadcast Route Row [pastry.routing.BroadcastRouteRow] to send a row to the routing table of another peer Request Route Row [pastry.routing.RequestRouteRow] to request a row from the routing table of another peer Leaf Set Maintenance [pastry.standard.StandardLeafSetProtocol] The leaf set is maintained in a similar way as the routing table: • an internal message to initiate the maintenance is received periodically by the leaf set manager: each member of the leaf set is pinged to know if it is still alive. If the leaf set lost members between two maintenance activities, the leaf sets of the two most distant members of the local leaf set are requested (Request Leaf Set) to send their leaf set (Broadcast Leaf Set). These leaf sets are then used to complete the local leaf set.
CHAPTER 2. DISTRIBUTED HASH TABLES
16
Messages used: Initiate Leaf Set Maintenance [pastry.leafset.InitiateLeafSetMaintenance] to start the process of the maintenance Request Leaf Set [pastry.leafset.RequestLeafSet] to request a leaf set from another peer Broadcast Leaf Set [pastry.leafset.BroadcastLeafSet] to send a leaf set to another peer
2.2.4 Network Connections RMI [pastry.rmi.RMIPastryNode] The joining of a new node involves the search for a node already member of the network. The first node initiates the ring. The second node either knows the address of the first node (and thus the RMI registry) or finds it in the local RMI registry (if the two nodes use the same registry). If the address is not valid or the RMI registry does not contain any node, a new ring is created. This protocol is the same for each new join. The detection of a failed peer during a sending of a message is implemented using detection of RMI exceptions. If a failure occurs, the peer is removed from the routing table and the message delivered again to the local node for re-routing to another node. The method to define the proximity between one local peer and a remote peer involves the sending of an ID request to the remote node and to calculate the delay between the transmission and the reception of a reply to this message. UDP (wire) [pastry.wire.WirePastryNode] For the join process, a new node simply sends a message to a specified address, considered as a bootstrap node. If the peer at this address responds, the new peer can join the network, otherwise, a new network is created. To detect a failure when a message is sent, the protocol uses acknowledgements [pastry.wire.messaging.datagram.AcknowledgementMessage]. If an acknowledgement is not received after a defined period of time, the peer contacted is considered unavailable. It is then removed from the routing table and the message is delivered one more time to the local node to find an alternative route. The proximity between a local peer and a remote peer is calculated by sending a special ping message and by noticing the time necessary to get the message back.
2.2.5 A Storage Application: Past Past is an application which uses the Pastry overlay network to store and look up items. Items are replicated among a selection of peers participating to the Past application. Past offers a service for inserting and looking up items. Past uses these three main components in order to provide its service: Storage Component [persistence.Storage]: items inserted using the Past application are stored in this component.
2.2. RELATED WORK: FREEPASTRY
17
Caching Component [caching.CachingManager]: this cache can store items and thus improve the efficiency of the lookup process. Replica Component [rm.RMImpl]: a replica manager is responsible for keeping invariant the fact that an item is stored in a defined number of nodes (according to a replication factor). Insertion of Contents and Replication When a client A wants to insert a new item in Past, it uses the insertion service of the Past application. The Past application then executes the following steps: 1. The item the client wants to insert is identified by an ID. The PAST application looks for the closest node to this ID using the underneath Pastry network and asks this node to send the references to the peers which are the closest to this ID (the number of peers is defined by a replication factor): 2. The Past application creates a Lookup Handles Message containing a new generated message ID, the ID of the item and the replication factor. 3. The Past application asks its endpoint to route the message. The endpoint creates a Pastry Endpoint Message which includes the Lookup Handles Message and the Past application as handler for this message. Then, the endpoint creates a Route Message which includes the message ID and the Pastry Endpoint Message and transmits this message to the Pastry node. 4. As no destination node is defined, the Pastry node asks the routing protocol to get the closest known node to the item ID. 5. The Route Message is then sent to the selected node by using a specific binding (RMI or Wire). 6. The Route Message goes through the Pastry nodes using the Pastry routing protocol (generally involving multiple hops) until it reaches the closest Pastry node Z to the content ID in the network. 7. This Pastry node Z transmits the Pastry Endpoint Message to the Past endpoint which extracts the Lookup Handles Message from the Pastry Endpoint Message and delivers it to the Past application. 8. The Past application asks the endpoint to get the set of ”replica” peers which will have to store this item and inserts them as a response into the Lookup Handles Message. 9. The Past application asks its endpoint to route the message to the peer A which sent the request. 10. When the source peer A receives the message, it is transmitted to the Past application. The content is then replicated to the list of peers received 11. The Past application sends an Insert Message directly to each peer of the set of peers returned.
CHAPTER 2. DISTRIBUTED HASH TABLES
18
12. When the Past application of one of these peers receives the Insert Message, it stores the content into its local storage; then, it puts the result of the storing (either it succeeded or not) as a response to the Insert Message. This Insert Message is then sent back to the source peer. 13. When the source peer received all responses of the insertions, these responses are transmitted to the client who inserted the content. Messages used Lookup Handles Message [caching.messaging.LookupHandlesMessage] is used to get the set of peers which are the closest to the ID of an item. Pastry Endpoint Message [pastry.commonapi.PastryEndpointMessage] is a message, generally including another one, specifying an application or a Pastry component to which the internal message is destined. Route Message [pastry.routing.RouteMessage] is a generic message which is routed between Pastry nodes. It contains a target ID, a Pastry Endpoint Message and a reference to the optional last node where it went through. Insert Message [p2p.past.messaging.InsertMessage] is a message which includes an item transmitted to a specific Pastry Node. Lookup of Content and Caching When a client wants to look up a content in Past, it uses the lookup service provided by the Past application. The Past application then executes the following steps: • The item requested is identified by an ID. • The Past application creates a Lookup Message specifying for the key the item ID. • The Past application asks the endpoint service to route the Lookup Message. • This message is walked through the peers using the Pastry routing protocol until it reaches one of the peers which stores this item. • When the Past application finds in its storage the content, the content is inserted into the Lookup Message and sent back to the requester peer. Moreover, the content is sent back to the last peer met during the routing using a Cache Message. • When the Lookup Message is received by the Past application on the requester peer, its is transmitted to the client. Messages used Lookup Message [caching.messaging.LookupMessage] is identified by an ID and contains a key. Cache Message [caching.messaging.CacheLookupMessage] is used to send a content to a peer for caching purpose.
2.3. CHORD
19
Replicas Management The replica manager maintains items replicated over a specified number of replicas. If a new node joins the network, the local node can get rid of some keys it is no more responsible for. If a node fails, the local node can become responsible for an extra range of keys: if it is the case, the local node has to fetch keys (RM Request Keys and RM Response Keys). Periodically, the replica manager receives an internal message which initializes the maintenance (RM Maintenance). When it occurs, the replica manager goes through its range of keys and checks if the replica factor is maintained. Fetch of keys can be necessary. A timeout protocol is implemented (RM Timeout): after each timeout, if the keys have not been received, a new message is sent (this process is limited to a defined number of attempts). The detailed procedure to maintain the replication is the following: • definition of the range of keys a peer is responsible The IDs of the peers situated at a distance of r/2 (where r is the replica factor) in both direction of the leaf set define the limits of the range. Indeed, one key situated in this range must be also stored in this local peer, because the local peer belongs to the selection of the r closest peers to this key. • selection of the peers to which a RM Request Keys must be sent The r closest peers to each extremity of the range are selected. These peers may contain keys that the local peer also has to store. • sending of the RM Request Keys To each peer of the previous selection, a RM Request Keys is sent including the range of keys the local peer is currently responsible. • these peers will send back a response which includes the concerned keys (RM Response Keys). Messages used RM Maintenance [rm.messaging.RMMaintenanceMsg] sent periodically to the replica manager for maintaining the replicas. RM Timeout [rm.messaging.RMTimeoutMsg] a message received by the manager notifying a request not fulfilled. RM Request Keys [rm.messaging.RMRequestKeysMsg] to request a set of keys from a remote node. RM Response Keys [rm.messaging.RMResponseKeysMsg] containing a set of keys obtained from a remote node.
2.3 Chord 2.3.1 Overview Chord [32] is a peer-to-peer structured overlay network which is like Pastry decentralized, scalable and self-organizing.
CHAPTER 2. DISTRIBUTED HASH TABLES
20
In this section, the Chord system is reviewed without explaining in detail each algorithm. Only the structure of the system is introduced in order to understand specific implementations using this system.
2.3.2 Chord Space and Key Assignment The nodes’ addresses and keys of items are both hashed to an m-bit identifier. The identifiers are ordered in an identifier circle modulo 2 m . Each identifier in the circle corresponds either to a node address or a key of a data item. A key k is assigned to node n iff k = n or n follows k in the circle. n is called the successor of k. Using the system depicted in figure 2.2, composed of three nodes, namely node 2, 6 and 9, the idea of key assignment is as follows. Keys 10 to 2 are assigned to node 2, keys 3 to 6 to node 6 and keys 7 to 9 to node 9. 15
0
The circle (m = 4) is composed of the nodes 2, 6 and 9. Keys 10 to 2 are assigned to node 2, keys 3 to 6 to node 6 and keys 7 to 9 to node 9.
1 2
14
3
13
4
12 5
11 6
10 9
8
Figure 2.2: Chord key assignment
7
2.3.3 Algorithms Routing Information Each Chord node maintains a routing table with m entries. The i th entry of this table contains the identity of the first node s that succeeds n by at least 2 i−1 on the identifier circle (s = successor(n ⊕2m 2i−1 ), 1 ≤ i ≤ m)1 . The first node of the routing table (i.e. i = 1) is called the successor of n. Referring to figure 2.2, the routing tables of each node of the system are the following: Node 2 6 9
Routing Table [6, 6, 6, 2] [9, 9, 2, 2] [2, 2, 2, 2]
Thus, each node stores routing information about only a small number of other nodes (O(log2 N ) where N is the size of the network). Consequently, a node does not contain enough information to determine completely the successor of an arbitrary key k. Routing Process A node n can resolve completely a query for a key k iff k ∈ [n, successor(n)]: if k = n, then the query is resolved directly by the node n, otherwise the successor of n can resolve it. If k ∈ / [n, successor(n)], then node n forwards the query to the node n , which is the 1 The
notation a ⊕n b is used to denote (a + b) mod n
2.3. CHORD
21
closest preceding node of k according to n’s routing table. For instance, using the system depicted in figure 2.2, if node 2 receives a query for the key 8 (8 ∈ / [2, 6]), the query is forwarded to the node 6 which is the closest preceding node of 8. Key 8 ∈ [6, 9] and the query is resolved by the successor of node 6 which is the node 9. Routing Complexity A query is always forwarded to the half of the distance to the target key. Using this argument, it is proved in [32] that log 2 N hops are sufficient to resolve a given query with a routing table of log 2 N entries, according to a a maximal size of the network of N = 2m . Joining of Nodes Nodes can at any time join or leave the network. Chord has then to maintain the routing table, according to the dynamic modifications of the Chord circle, in order to preserve the bounds to the number of hops necessary for a lookup. To simplify the join and leave mechanisms, each node maintains also a predecessor pointer: a pointer to the immediate predecessor of the node. A node n joining the network performs two tasks: 1. Initialize the routing table (including the successor) and the predecessor. 2. Update the routing tables and the predecessors of existing nodes. It is assumed that node n knows another node n by an external mechanism. The two tasks are then executed: 1. Node n learns its successor s, its predecessor p and routing table by asking n to look them up. The successor s is first found by routing a query containing n as the key. The predecessor p is then the current predecessor p of s. The predecessor of node s is updated and becomes n. The routing table could be filled using a lookup for each entry, but some optimizations are proposed in [32] to reduce the cost of this process. 2. Existing nodes must now update their routing table according to the joining of the node n. A node p has to update the element i of its routing table if this element succeeds n in the circle and n succeeds p by at least 2 i−1 (n is thus a better entry). This joining process maintains the routing tables, the successors and the predecessors of all nodes as the network evolves. However, this maintenance is difficult to execute when concurrent joins occur. A ”stabilization” protocol is thus proposed in [32], which maintains only the successor pointers up-to-date. The joining algorithm now only affects correctly the successor of the new node n. A periodic stabilization protocol is then executed by each node: a node asks its successor to get its predecessor, correcting thus each node successor. Indeed, if we suppose that node n joins the network through n : n learns, using n , that np and ns are respectively its predecessor and successor. Node n s is notified by n and updates its predecessor pointer with n. When n p executes the stabilization algorithm,
22
CHAPTER 2. DISTRIBUTED HASH TABLES
np will ask ns to get its predecessor which is now n. n p will then acquire n as its successor. Thus, all predecessors and successors are again correct. An element i of the routing table of a node n is refreshed periodically by sending a query specifying as key n ⊕ 2m 2i−1 . Thus, the element i is updated with the result of the query (the successor of the key) lazily. Nodes Departures and Failures When a node fails, queries should not be disrupted, which means that the successor pointers should be kept up-to-date. To achieve this property, each Chord node maintains a successor list of its nearest successors in the Chord ring. Thus, when a node leaves the network, the nodes containing this node in their successor list can continue to route correctly a query. They can also complete their own list thanks to the other lists of the other successors: a successor knows nodes which are more distant than the local node.
2.4 Related Work: Cooperative File System 2.4.1 A Chord Implementation The Chord project [17] provides an implementation of the Chord algorithms in C programming language, as well as a simulation environment. No official release is available, but the source code can be downloaded and browsed. This implementation has however not been studied in details in our project.
2.4.2 Cooperative File System (CFS) CFS [21] is a storage system built on top of the Chord implementation. An intermediate layer between CFS and Chord layers, called DHash, is introduced to separate files stored in the system in blocks. CFS interprets then these blocks as files. DHash provides load-balancing, caching and replication of blocks. Splitting files in blocks increases the number of messages required to fetch a file, but improves the load-balancing in comparison to a system storing directly the files such as Past.
2.4.3 Replication A block is replicated by the DHash layer among more than one node, providing a better fault-tolerance. The list of node successors of Chord is used to select the nodes to which a block is replicated.
2.4.4 Caching DHash caches blocks during query processes: when the request arrives at one of the key’s successor or a node which caches a copy, this node can send a copy either to all the nodes encountered in the query process or to a selection of these nodes.
2.5. TOWARDS A COMMON ARCHITECTURE
23
2.4.5 Load-balancing To accommodate heterogeneous node capacities, CFS uses the notion of virtual servers. A local CFS node administrator configures the node with a number of virtual servers which can be dynamically adjusted. Under high load, a node can delete some of its virtual nodes; under low load, a node can create additional virtual servers. The more virtual servers a node manages, the more items it will have to store and the more traffic it will have to support.
2.5 Towards a common Architecture This section describes the common architecture which can be extracted from the study of (1) Pastry/Past [23, 31], (2) Chord/CFS [21] and (3) Tapestry/OceanStore [36]. The paper [22] tries to define a common API for structured peer-to-peer overlays: this API is partially used in this section, too.
2.5.1 A common Software Architecture The figure 2.3 presents the architecture of a software storing items using an underneath structured network. Application
Storage
Routing
Transport
Figure 2.3: Common Software Architecture The architecture includes four main layers: a Transport Layer, a Routing Layer, a Storage Layer and an Application Layer: Transport Layer is responsible for sending messages to and receiving messages from the physical network. Typical transports are based on TCP, UDP or HTTP protocols. Routing Layer is responsible for efficiently route messages to nodes. This layer needs to store and maintain routing information, which are virtual connections to nodes, to improve the routing in terms of number of hops and traffic generated. The overlay network generated by the virtual connections may be structured in such a way that peers and keys are related and that this relation allows: • to store a specific key to a selected peer • to look up a key efficiently
CHAPTER 2. DISTRIBUTED HASH TABLES
24
• to select a set of peers to store replicas of a key • to define the range of keys for which a peer is responsible Storage Layer is responsible for storing items which can be also replicated or cached. This layer is responsible to keep invariant the fact that an item is replicated over a number of peers defined by the replication factor. Application Layer can use the storage layer to store items in the distributed network.
2.5.2 A common API The different layers interact using defined APIs which are depicted in figure 2.4.
Application store(key, obj) unstore(key)
get(key)::Object
Storage route(key, msg, peerAddr)
lookup(key)::Peer replicaSet(key, max)::Peer[] range()::Range
deliver(msg) event(peer, type)
forward(key, msg, peerAddr)
Routing send(peerAddr, msg)
receive(msg)
Transport Figure 2.4: Common Software Architecture with APIs
Interactions between Application and Storage Layers An application on top of the storage layer needs to store and find objects. The application can also ask to remove an object from the storage: this operation cannot however be easily provided by the storage layer and is considered optional. store(key, obj) an application asks the storage layer to store the object obj in relation with the key. get(key)::Object an application looks for an object identified by the key. unstore(key) an application wants to remove an object identified by the key from the storage.
2.5. TOWARDS A COMMON ARCHITECTURE
25
Interactions between Storage and Routing Layers lookup(key)::Peer when the storage layer does not store locally the object related to the key, it has to look up the peer which stores it. Thus, it asks the routing layer to select a peer which either stores the object or knows more about this key than the local peer. A message is then sent (using the route operation) to this selected peer in order to fetch the related object. The route through which the message travels should however satisfy the overlay protocol’s bounds on the number of hops. route(key, msg, peerAddr) forwards the message msg towards the closest node to key. peerAddr is optional and specifies the first hop in the routing of the message. Either key or peerAddr can be null, but not both. To store an object, the following operation can be invoked: route(key, [PUT, object, local peer], null). To get an object identified by a key, route(key, [GET, local peer], null) can be invoked. The response can be sent back to the original peer using route(null, [object], original peer) forward(key, msg, peerAddr) is invoked at each node when the message msg is about to be forwarded to peerAddr (using the send operation). This operation allows the storage layer to stop the forwarding for instance if the object related to key is cached locally. deliver(msg) is invoked on the closest node of the key: the message is transmitted to the storage layer. event(peer, type) notifies the storage layer that peer either joined or left (type of event) the overlay network: the range of keys that the local node is responsible may have changed which may involve the fetch of new keys. The storage layer should react by invoking the operation range. range()::Range provides the range of keys the local node is currently responsible. This range of keys includes all the keys which should be replicated over the local node. replicaSet(key, max)::Peer[] returns a set of nodes of size max (replication factor) on which replicas of the object with key can be replicated. The storage layer can then send directly the object to this selection of peers for providing replication. Interactions between Routing and Transport Layers send(peerAddr, msg) sends the message msg to the peer situated at the physical address peerAddr. receive(msg) is invoked by the transport layer in order to notify the routing layer that the message msg has been received.
2.5.3 Related Projects applied to the Architecture Pastry - Past (FreePastry) Transport Java RMI or UDP Routing Pastry Storage Past
CHAPTER 2. DISTRIBUTED HASH TABLES
26
Chord - DHash - CFS Transport C++ RPC package Routing Chord Storage DHash Application CFS Tapestry - OceanStore Transport TCP or UDP Routing Tapestry Storage and Application OceanStore JXTA JXTA framework, presented in details in the next chapter, can also, as we will see in chapter 4, be represented using this common architecture: Transport TCP, UDP, HTTP Routing Rendez-vous Service Storage SRDI Service Application Applications provided by miscellaneous JXTA Projects
Finally, we can see that we are able to map each project to this general architecture. This observation justifies the interest of joining the efforts of researchers in structured distributed systems, of the JXTA members and of the high-level application developers. The next chapter describes in detail JXTA. Chapter 4 will come back to this observation by providing a way to replace the routing layer of JXTA by any structured network (Pastry, Chord, Tapestry, . . . ).
Chapter 3
JXTA
27
28
CHAPTER 3. JXTA
3.1 JXTA Project JXTA project [15] proposes a specification which aims at creating a virtual network on top of the physical network, providing a common platform for peer-to-peer applications. JXTA project is independent of programming languages, network transport protocols and operating systems. Thus, the JXTA virtual network allows the peers to communicate without managing the choice of network protocols, the problems of firewalls and NATs and changes occurring in the physical network. All these issues are managed by the underneath JXTA framework. The JXTA project proposes reference implementations in different programming languages such as Java, C++, Perl, Python and Smalltalk. However, some of them are more complete according to the specification than others. The Java reference implementation is the most evolved one: in our project we studied the Java stable build 2.1.1 (released on September 2003).
3.2 JXTA Concepts Peers A JXTA peer is any networked device that uses the JXTA virtual network. A peer is uniquely identified by an ID and operates independently and asynchronously from all other peers. Peers can join or leave the network at any time. Peers can provide services and resources to the other peers. Three kinds of peer exist in JXTA: Edge Peers can use services provided by other peers and supply their own services by sending and receiving messages. Edge peers do not participate in the routing of messages: each edge peer is connected to a rendez-vous peer which is responsible for the routing. Edge peers are not considered to be very stable (they can join and leave the network frequently) and no assumption is made about their capacities. Rendez-vous Peers have the same basic functionalities as an edge peer, but participate in addition to the routing of messages. A peer joining the network either decides to become a rendez-vous peer or connects to a rendez-vous peer already present in the network and becomes an edge peer (figure 3.1). A peer can dynamically become an edge peer or a rendez-vous peer during its lifetime. Rendez-vous peers are considered to be more stable than edge peers and provide storage for routing information and indexing, as well as more processing power and bandwidth. Relay Peers maintain information about the routes to reach other peers in NAT environments. A peer behind a firewall which wants to use the JXTA network connects to a relay peer: this relay will allow to transfer the messages from the JXTA network to the peer situated behind a firewall/NAT. A peer can be simultaneously both a rendez-vous peer and a relay peer. In JXTA 2.0, rendez-vous peers and relay peers are sometimes referred as super-peers.
3.2. JXTA CONCEPTS
29
Edge Peer
Rendezvous Peer
Connections
Figure 3.1: JXTA Edge Peers and Rendez-vous Peers
Peer Groups Peers self-organize in peer groups. The collection of peers belonging to a same group agree upon a common set of services. Each peer group is uniquely identified by an ID. A peer can create and publish a new peer group, join an existing peer group, discover peer groups and monitor peer groups. The common motivations for creating peer groups are the following [18]: • to create a secure environment controlling members access • to create a scoping environment allowing the establishment of a local domain of specialization • to create a monitoring environment allowing to monitor a set of peers bounded to a group The JXTA network bootstrapping described in more details in section 3.7 revolves around two special peer groups: World Peer Group is the first element required by the JXTA platform in the bootstrapping process. The World Peer Group defines the basic capacities of the peers, such as the services used and the communication protocols. It includes a set of services which are usually hard-coded in the JXTA implementation. Thus, each JXTA peer intrinsically knows the World Peer Group and can join this peer group, even if it can’t find any other peers on the network. Peers can then interact with other peers using the basic services defined by the World Peer Group. Net Peer Group : the JXTA platform uses then the services of the World Peer Group to discover or generate a Net Peer Group instance. The Net Peer Group can be customized to provide other basic services, to define more specific transports or to start applications. A default Net Peer Group is provided by the JXTA implementation. Using the Net Peer Group, a peer can join another more specific peer group at any time.
30
CHAPTER 3. JXTA
Modules, Services and Applications JXTA modules describe and provide a new behavior destined to peers in the JXTA world. The module abstraction includes the following elements: A Module Class used to advertise the existence of a behavior. It is composed of a name and a description of the behavior it proposes. A Module Specification used to specify the operations provided and describe how to access this module. Each specification includes a reference to its description contained in the Module Class. A Module Implementation is an implementation of a Module Specification. The implementation contains usually a link where the code can be downloaded and the information how to install and launch the module. Modules can be either Service Modules or Application Modules. A service is usually less specific than an application and can be used by many different applications. The separation between these two kinds of modules is however not very strict. Endpoints An endpoint is an abstraction defining an address of a peer on a specific physical network transport. Using endpoints, each peer can be contacted in the JXTA network, either directly or using a multi-hops route with relays. Routes are dynamically updated by the JXTA framework when changes occur in the network. Pipes A pipe is a virtual communication channel connecting endpoints. Applications can use pipes to send messages to the other peers. Pipes are asynchronous and unidirectional. Three types of pipes are provided by JXTA: Point-to-point Pipes connecting exactly two endpoints. The two endpoints are referred to an input pipe for the reception and to an output pipe for the sending of messages. Propagates Pipes connecting one output pipe to multiple input pipes. The output pipe and the input pipes must belong to the same peer group. Secure Unicast Pipes providing a secure communication channel between two endpoints (point-to-point pipe). Messages JXTA peers interact using messages. Messages are sent and routed in the JXTA network. A message is organized in an ordered sequence of named and typed contents called elements (name/value pairs) using an XML representation. Messages can be compacted in a binary form, too.
3.2. JXTA CONCEPTS
31
Advertisements All JXTA resources are described with advertisements (XML documents). The JXTA framework defines the following types of advertisement: AccessPoint Advertisement defines a list of endpoints available for a specific peer. Peer Advertisement describes a peer, specifying its name, its ID and its available endpoints (AccessPoint). PeerGroup Advertisement describes peer groups: name of the group, ID and description. ModuleClass Advertisement describes a module class, including its name, its ID and a description. ModuleSpec Advertisement defines a module specification, providing references to the documentation needed in order to create conforming implementations. It includes its name, its ID, its description and an optional pipe advertisement which can be used to connect to the module. ModuleImpl Advertisement represents one implementation of a given specification. It includes its name, the specification ID to which it refers, a link to the code and implementation parameters. Pipe Advertisement describes a pipe communication channel and specifies the name, the ID and the type of pipe. Rendezvous Advertisement describes a peer that acts as a rendez-vous peer for a given peer group. It includes the peer ID, the peer group ID, a service name and a route to reach this rendez-vous. Route Advertisement used to represent a route to a destination peer in the JXTA network. Routes are represented as a sequence of hops allowing to reach the destination. Transport Advertisement which describes the protocol and network interface associated with an endpoint. JXTA IDs To refer to JXTA resources such as peers, peer groups and pipes, JXTA IDs are used. JXTA IDs are represented as URNs which serve as location-independent resource identifiers. They have the following properties [18]: • unambiguous: they provide a complete reference to the resource • unique: they refer to a single resource • canonical: references to the same resource are encoding to the same JXTA ID Thus, a resource can be located anywhere in the JXTA network and its ID will remain the same. For instance, a peer can connect to the JXTA network from a different access points and will still keep the same identity.
CHAPTER 3. JXTA
32
Credentials A credential is a token used to identify a sender and verify a sender’s right to send a message to a specific peer. Each peer can build its own credential using a specific service proposed by the peer group it belongs to. Thus, credentials provide message authentication and authorization.
3.3 JXTA Services and Protocols A peer can use different services allowing to interact with other peers by exchanging messages according to specific protocols. The different services and protocols specified by JXTA are summarized and represented in figure 3.2 and described in the following paragraphs:
Access Service
Access Service
Membership Service
Membership Service
Peer Discovery Protocol Discovery Service
Discovery Service [Resolver Protocol] Peer Info Protocol Peer Info. Service.
Peer Info. Service [Resolver Protocol] Pipe Binding Protocol
Pipe Service
Pipe Service [Resolver Protocol] Peer Resolver Protocol
Resolver Service
Resolver Service [RendezVous Protocol, Endpoint Protocol] RendezVous Protocol
RendezVous Service
RendezVous Service [Endpoint Protocol] Endpoint Protocol
Endpoint Service
Endpoint Service [TCP, HTTP]
Figure 3.2: JXTA Protocols and Services: the protocol noted above the arrow is the virtual protocol used and the protocol specified under the arrow is the direct underneath protocol(s). The Discovery Service [Peer Discovery Protocol] provides advertising and discovering of resource advertisements, as well as indexing functionalities.
3.3. JXTA SERVICES AND PROTOCOLS
33
The Peer Information Service [Peer Information Protocol] is used for monitoring other peers by learning for instance their capacities, their status or their network traffic. The Pipe Service [Pipe Binding Protocol] establishes the virtual communication channels (pipes) between peers. The Membership Service is used to issue membership credentials and to manage access validation to peer groups. The Access Service is then used to validate requests rights according to the credential of the requester and the policies defined for a specific type of request. These services do not need to transfer information: they can operate independently of other nodes. The Resolver Service [Peer Resolver Protocol] acts as a dispatcher, either toward the services described so far, or toward the RendezVous Service and the Endpoint Service. Services on top of the Resolver Service register themselves as handlers for specific messages related to their protocol. Thus, a message can be directed to the service it is destined. According to the definition of the destination peer(s), either the RendezVous Service (which finally will use the Endpoint Service) or directly the Endpoint Service is used to send a message. The RendezVous Service [RendezVous Protocol] provides two main functionalities in the scope of a peer group: the connection process between edge peers and rendez-vous peers and the routing of messages within a peer group. The connections of edge peers to rendez-vous peers involve the sending of messages according to the RendezVous Protocol resulting in a grant of a lease limited in the time. The messages routing is presented in detail in section 3.5. The Endpoint Service [Endpoint Routing Protocol] encapsulates different network transports, allowing the communication between peers using the physical network. As a peer ID does not contain any location information, the Endpoint Routing Protocol must find routing information (described by advertisements) to communicate to a peer either directly or using relays. Moreover, the Endpoint Service caches routing information and checks the dynamically established connections, as the topology of the physical network may change. Thus, a JXTA message, going through the different services can receive new elements when moving down to the ”stack” of services, according to the related protocols. When a message is received, it goes up to the ”stack”, each service extracting its own protocol elements until the final service to which it is destined is reached. The interactions between the services have been studied in detail during this project. The result of this study is presented in appendix A using UML use cases. For each operation, the full process through the JXTA services is described. We describe here an example of one operation which is the publishing of an advertisement in relation with the use cases presented in appendix. Each expression in italic refers to a use case. The steps are represented in figure 3.3. 1. An application asks the discovery service to publish an advertisement. 2. The discovery service asks the SRDI service to send a SRDI entries message. 3. The SRDI service asks the resolver service to send a SRDI message.
CHAPTER 3. JXTA
34
Application 1
publish an advertisement
Discovery Service
Discovery Service 2
9
SRDI Service
3
SRDI Service
8
Resolver Service
11
Resolver Service
4
10
12
Rendez−vous Service
Rendez−vous Service 7
5
Endpoint Service
6
Endpoint Service
13
Figure 3.3: JXTA Use Case application: publish an advertisement 4. The resolver service asks the rendez-vous service to walk a message. 5. The rendez-vous service asks the endpoint service to send a message. 6. The endpoint service sends the message to another peer using a specific transport. 7. The endpoint service of the other peer receives the message and invokes receive a SRDI resolver message to the resolver service. 8. The resolver service asks the discovery service to process a SRDI resolver message. 9. The discovery service asks the SRDI service to replicate SRDI entries. 10. The SRDI service asks first the rendez-vous service to get the local peer view and then invokes get a replica peer and send a SRDI entries message. 11. The SRDI service asks the resolver service to send a SRDI message. 12. The resolver service asks the endpoint service to send a message. 13. The endpoint service uses a specific transport to send the message to another peer.
3.4 JXTA Indexing and Routing 3.4.1 JXTA 1.0 In JXTA 1.0, as presented in [35], no indexing is used: messages are flooded in the network using multicast when available and propagation between rendez-vous peers. A message is forwarded by one rendez-vous peer to all rendez-vous peers, according to its current knowledge of the network.
3.4. JXTA INDEXING AND ROUTING
35
Time-to-live limitations, loopback detection, as well as caching of advertisements improves the overall performance of the routing protocol. This simple routing process harms however performance and scalability of the system. Thus, a new routing algorithm has been specified and implemented in JXTA 2.0.
3.4.2 JXTA 2.0 JXTA 2.0 reposes the indexing and routing process in the three following components: the Rendez-vous Peer View (RPV), the Shared Resource Distributed Index (SRDI) and the Walker. The papers [33], [34] and [18] describe partially what follows, but the most precise source which has been used to understand the mechanisms is the Java reference implementation (version 2.1.1). We introduce in this section these components. A more precise description of the algorithms will be presented in the next section. The Rendez-vous Peer View (RPV) is an ordered list of rendez-vous peers by their ID. Each rendez-vous peer in the network computes and maintains its own local RPV, according to its personal knowledge of other rendez-vous peers. RPVs on different peers are not strongly consistent. The consistency is improved by exchanging rendezvous peers information between peers, as well as using well-known seeding peers. Moreover, the RPV is updated each time a message is received from or failed to be sent to a rendez-vous peer. Thus, RPVs on different rendez-vous peers eventually converge to a consistent RPV, when changes in the network are not too frequent. The RPV is maintained in the JXTA framework by the RendezVous Service. The Shared Resource Distributed Index (SRDI) is used on one hand on an edge peer to extract indexes from advertisements and push them to the network, and on the other hand on the rendez-vous peers for the lookups. Each type of advertisement defines its specific keys of indexing, for instance its name or its ID. According to these keys, a SRDI daemon periodically pushes these keys related to the edge peer to the distributed index. The process of publishing a key uses a specific function (presented in the next section) which maps a key to a rendez-vous peer: this peer will be asked to store this key that points to the edge peer storing actually the advertisement. Each rendez-vous peer stores its own local index containing the indexes received by other peers (edge peer or rendez-vous peer). More precisely, a rendez-vous peer stores different indexes situated in different services: one in the Discovery Service, one in the Endpoint Service (storing route advertisements indexes) and one in the Pipe Service (storing pipe advertisements indexes). The Walker is a component used for routing when no index information is available locally. In that case, a message is walked to the rendez-vous peers situated in both direction of the RPV, which means from the position of the local peer towards the top of the RPV (toward rendez-vous peers with smaller IDs) and towards the bottom of the RPV (toward rendez-vous peers with greater IDs). This walking process continues until either the key is found, the extremity of the RPV is reached or a defined number of hop counts is reached. The RendezVous Service takes care of this walking mechanism.
CHAPTER 3. JXTA
36
The routing of a lookup message (specifying a key) involves all the components presented previously, according to a preference order: first the SRDI, then the RPV and the mapping and finally the Walker. Indeed, the SRDI provides the most precise indication to find an advertisement (an exact mapping between the key and a peer), the mapping function returns a peer which either can store this index (if the RPV has not changed since its indexing) or is very close to a rendez-vous peer storing this index and thus a good starting point for the Walker. Moreover, each index is assigned a defined time-to-live: a published advertisement must thus be re-indexed periodically. This process improves the consistency of the index, as it provides a correction of no more accurate mappings between keys and responsible peers. Thus, this process is an alternative to an active transfer of index information when rendez-vous peers join or leave the network.
3.5 Formalization and Algorithms 3.5.1 Objective The objective of this section is to provide a semi-formal description attempt of the JXTA components in order to present the routing and indexing algorithms more precisely. Indeed, we need a high-level description of these algorithms in order to compare and be able to replace them with algorithms used in structured overlay networks. This effort to abstract the JXTA algorithms may also make easier the understanding of the routing in JXTA framework for researchers in distributed systems.
3.5.2 Notation and Definitions • P = {P eer1 , P eer2 , P eer3 , . . .} the set of all peers. • R ⊂ P, R = {Rv1 , Rv2 , Rv3 , . . .} the set of rendez-vous peers. • E ⊂ P, E = {Edge1 , Edge2 , Edge3 , . . .} the set of edge peers. • We write E Rvp ⊂ E to refer to the set of edge peers connected to Rv p . • AP eeri = {Adv1P eeri , Adv2P eeri , Adv3P eeri , . . .} the advertisements of resources created by peer P eer i . P eeri • A= A the set of all advertisements in the network. P eeri
• Id(P eeri ) the JXTA ID of the peer P eer i . • Addr(P eeri ) the address of the peer P eer i . • Hash(AdvaP eeri ) the hashing value of an attribute of Adv aP eeri , such as its ID or its name. Typically SHA-1 is used. • STOREP eeri ⊂ A the advertisements stored by peer P eer i . • INDEXRvp ⊂ Hash(AdvaP eeri ) × Addr(P eeri ) the indexes stored by Rv p . • PEERVIEWRvp ⊂ R the sorted list of rendez-vous peers known by Rv p such that pos(Rvq ) < pos(Rvr ) if Id(Rvq ) < Id(Rvr ). PEERVIEW is 0-based.
3.5. FORMALIZATION AND ALGORITHMS
37
• RespP eer(Hash(AdvaP eeri )) returns a Rvq close to Hash(AdvaP eeri ) according to the algorithm 2.
Algorithm 2 RespP eer function used by Rv p RespP eer(Hash(AdvaP eeri )) :: Rvq { digest ← Hash(AdvaP eeri ) sizeHT ← max hash value returned by the Hash function sizeP V ← size(PEERVIEWRvp ) pos ← f loor(digest ∗ sizeP V /sizeHT ) return elementAt(PEERVIEWRvp , pos) } The idea of algorithm 2 is to divide the hash space by the size of the PEERVIEW and assign one segment to each rendez-vous peer, according to the same order defined for the PEERVIEW. Thus, algorithm 2 provides a way to scale the key space to the number of peers currently in the PEERVIEW. Moreover, it provides the following feature: the rendez-vous peers returned by RespP eer function keep close between them (according to the number of peers between them in the PEERVIEW) even when the size of the PEERVIEW changes. Thus, when two mappings of the same key are executed at two different instants, even if the PEERVIEW grew or shrank in the meantime, their distance will remain short. The expectation distance can be calculated and its order is the ratio of the sizes of the PEERVIEW. Note – When we write P eerx , Edgex , Rvx or Advx and x is not bound, this means that we take an arbitrary member of the respective set the element belongs to. – We will use the following ranges of indices: a, b, c, . . . for advertisements i, j, k, . . . for peers p, q, r, . . . for rendez-vous peers u, v, w, . . . for edge peers
3.5.3 Algorithms The following algorithms result from the study of the Java implementation by ”reverseengineering” the source code. The JXTA project does not provide indeed such a precise description of the routing and indexing algorithms in any document published. Joining of an edge peer Edge u through Rvp E Rvp = E Rvp ∪ {Edgeu }
38
CHAPTER 3. JXTA
Joining of a rendez-vous peer Rv p through Rvq PEERVIEWRvp = PEERVIEWRvp ∪ {Rvq } PEERVIEWRvq = PEERVIEWRvq ∪ {Rvp } Creation of an advertisement by a peer P eer i Edge peers, as well as rendez-vous peers can create advertisements for their local entities. – create an advertisement Adv aP eeri – STOREP eeri = STOREP eeri ∪ {AdvaP eeri } Indexing of advertisements Each type of advertisement defines its specific keys of indexing, for instance its name or its Id. According to these keys, a SRDI daemon periodically pushes these keys to the distributed index. Each rendez-vous peer stores its own local INDEX containing the indexes received by other peers. Edge peers do not have any INDEX. Indexes are forwarded to the network as long as a closest rendez-vous peer different from the current peer is computed using the RespP eer function (algorithm 2). This indexing is described in algorithm 3. Algorithm 3 Indexing in JXTA, executed by P eer i Let I ← all new advertisements from STORE P eeri Let K an initial empty set which will contain couples of (key, peer) P eer for all Adva j (i and j can be equal) in I do P eer P ut(K, (Hash(Adva j ), P eeri )) end for if P eeri is an edge peer then send K to the rendez-vous peer to which P eer i is connected else {P eeri is a rendez-vous peer} for all k in K do Rvp ← RespP eer(k.key) if Rvp = P eeri then send to Addr(Rvp ) the index k end if end for end if {At reception of the index k by a rendez-vous peer Rv q } P ut(INDEXRvq , k) Rvr ← RespP eer(k.key) if Rvr = Rvq then send to Addr(Rvr ) the index k end if
3.5. FORMALIZATION AND ALGORITHMS P eerj
Lookup of an advertisement Adva
39
by a peer P eeri
The lookup process involves the use of the STORE, the INDEX and a walking process. If the lookup message reaches the peer storing the advertisement related to the key, the lookup is successful. Thus, the aim of the lookup is to find this peer, using the minimum number of forwardings. The indexing of advertisements to the distributed index and the lookup of an index use the same algorithm 2. However, the computing uses the PEERVIEW which dynamically changes when joins and leaves of rendez-vous peers occur. Thus, the peer selected using the algorithm for the indexing and the one selected for the lookup can be different. In that case, the lookup will be forwarded to a wrong peer. However, the algorithm provides this feature: the peer selected for the lookup will be close to the first peer selected for the indexing. Consequently, if the message is walked to rendez-vous peers following the order defined by the PEERVIEW, the peer storing the indexing information will be reached within a small number of steps. The walking is initialized in both directions of the PEERVIEW, which means from the position of the local peer to the top and to the bottom of the PEERVIEW. This walking process continues until either the key is found, the extremity of the PEERVIEW is reached or a defined number of steps is reached (this last condition has not yet been implemented, but is presented in [34]). Algorithm 4 describes this process of lookup. Algorithm 4 Lookup in JXTA, executed by P eer i , initialized with Query(P eer i, key, 0) P eerj receives Query(src:P eer i, key, hopcount) {If P eeri is an edge peer, it must first send the lookup to the rendez-vous peer to which it is connected. This step is not described here.} {1. Search the key in STORE P eerj } if found: send to P eer i the related AdvaP eerk {if P eerj is an edge peer, the algorithm stops here} {2. Search the key in INDEX P eerj } if found: Incr(hopcount); if hopcount ≤ 2 then forward the query to the peer related to the key else stop {3.a if hopcount = 0 initialize the walking} {Try to find the closest peer} Rvq ← RespP eer(key) if Rvq is not P eerj then Incr(hopcount) if hopcount ≤ 2 then forward the query to Rv q else stop else Incr(hopcount) and walk the message in both directions end if {3.b Continue the walking to the same direction}
CHAPTER 3. JXTA
40
Maintenance of an index Each index is associated with a time-to-live defined at its creation. A local process periodically checks the time-to-live of each index of the local INDEX and removes the expired one (algorithm 5). Thus, an advertisement should be re-indexed. This re-indexing improves the consistency of the index, as it provides a correction of no more accurate mappings between keys and responsible peers. It is an alternative to an active transfer of index information when rendez-vous peers join or leave the network. Algorithm 5 Maintenance of INDEX in JXTA, executed by Rv p Let I ← all the indexes of INDEX RVp for all i in I do if IsExpired(i) then Remove(IN DEXRVp , i) end if end for
Maintenance of the PEERVIEW on peer Rvp The consistency of the PEERVIEWs is improved by exchanging rendez-vous knowledge between peers (algorithm 6), as well as using well-known seeding peers. Moreover, the PEERVIEW is updated each time a message is received from or failed to be sent to a rendez-vous peer. In algorithm 6, two messages are periodically sent by a rendez-vous peer to maintain its PEERVIEW: • a randomly selected rendez-vous peer from its PEERVIEW sent to another randomly selected rendez-vous peer • the local rendez-vous peer sent to the other rendez-vous peers from the PEERVIEW, sequentially at each maintenance activity Algorithm 6 Maintenance of PEERVIEW in JXTA, executed by Rv p Rvq ← Select(PEERVIEWRvp , randomly) Rvr ← Select(PEERVIEWRvp , randomly) send Rvq to Addr(Rvr ) Rvs ← Select(PEERVIEWRvp , sequentially) send Rvp to Addr(Rvs )
3.6 Scenarios In this section, we illustrate the algorithms presented in the previous section according to well-defined scenarios.
3.6. SCENARIOS
41
3.6.1 Scenario 1: Indexing This scenario illustrates the general indexing and lookup processes.
Index Add index
5
1. Store advertisement 9. Get Adv.
35
13 3. Push index 80 2. Push index 80 4. Add index 80
Store 73
8. Forward lookup
10. Send Adv.
5. Lookup 80
22
7. Find Index 80 Index
6. Forward lookup 80
17
50
11. Store Adv.
Store Edge Peer
Rendez−vous Peer
Connection
Message
Figure 3.4: JXTA Routing and Indexing: Scenario 1 In this scenario, we assume that the maximal hash value returned by the Hash function is 100 (size HT ). Scenario 1 is illustrated in figure 3.4. The PEERVIEWs of the different peers are the followings: Id 5 13 17 22 35 50 73
Type Edge Rv Edge Rv Rv Rv Rv
PEERVIEW [13, 22, 35, 73] [13, 22, 35, 73] [13, 22, 35, 50] [35, 50, 73] [13, 22, 50, 73]
1. Edge5 creates advertisement Adv1Edge5 and stores it in STOREEdge5 . 2. The indexing daemon takes this new advertisement Adv1Edge5 and computes the hash value of its Id. We suppose that hash(Adv1Edge5 ) = 80. Edge5 sends (hash(Adv1Edge5 ), Edge5 ) = (80, Edge5 ) to the rendez-vous it is connected to (Rv13 ). 3. Rv13 inserts (80, Edge5 ) in INDEXRv13 and tries to compute a closer peer: RespP eer(80) is Rv73 : f loor(digest∗size(PEERVIEWRv13 )/sizeHT ) = f loor(80∗4/100) = f loor(3.2) = 3
CHAPTER 3. JXTA
42 elementAt(PEERVIEWRv13 , 3) = Rv73 So, (80, Edge5 ) is forwarded to Rv73 .
4. Rv73 inserts (80, Edge5 ) in INDEXRv73 and tries to compute a closer peer: RespP eer(Adv1Edge5 ) is Rv73 . As the closest rendez-vous peer using the RespP eer is not different from Rv73 , the indexing stops. 5. Edge17 looks for the key 80 which is not in its storage. Edge17 sends a lookup message to Rv22 . 6. Rv22 searches in STORERv22 and in INDEXRv22 and finds nothing. Rv22 computes the closest rendez-vous peer: RespP eer(80) is Rv73 . So, Rv22 forwards the query to Rv73 . 7. Rv73 finds nothing in STORERv73 , but finds the index of key 80 in INDEXRv73 . The index points to peer Edge5 . 8. Rv73 forwards the query to Edge5 . 9. Edge5 finds the advertisement in its store STOREEdge5 . 10. Edge5 sends the advertisement Adv1Edge5 to Edge17 (the originator of the request). 11. Edge17 stores the advertisement in STOREEdge17 .
3.6.2 Scenario 2: Joining of Rendez-vous Peers Scenario 2 illustrates the effect of the joining of new rendez-vous peers. This scenario is illustrated in figure 3.5.
5
8
19
21
22
37
39
47
Consistent PEERVIEW of all nodes at time A Hash Table (item 38 in black)
5
8
19 21 22 37 39 40 41 43 46 47
Time A
Consistent PEERVIEW of all nodes at time B
Time B after join of peers 40, 41, 43 and 46 6a. End of peer view
47
40
43
47
40
43
5. Walk Lookup
1. Push Index 38
17
8
41
37
8
41
46
37
46
39
21
17
2. Push Index 38
21
39 4. Forward Lookup
19
5
22
8. Response
19
5
22
3. Lookup 38
23
23
7. Forward Lookup
Edge Peer
Rendezvous Peer
Message
Figure 3.5: JXTA Routing and Indexing: Scenario 2
6b. Find Index
3.6. SCENARIOS
43
Time A 1. Edge17 creates advertisement Adv1Edge17 . The indexing daemon takes this new advertisement Adv1Edge17 and computes the hash value of its Id. We suppose that hash(Adv1Edge17 ) = 38. Edge17 sends (38, Edge17 ) to the rendez-vous it is connected to (Rv8 ). 2. Rv8 inserts (38, Edge17 ) in INDEXRv8 and tries to compute a closer peer: RespP eer(38) is Rv39 . So, (38, Edge17 ) is forwarded to Rv39 . Rv39 inserts (38, Edge17 ) in INDEXRv39 and tries to compute a closer peer: RespP eer(38) is Rv39 as the PEERVIEWs are consistent. The indexing stops.
Time B: rendez-vous peers Rv40 , Rv41 , Rv43 and Rv46 joined the network 3. Edge23 looks for the key 38 which is not in its storage. Edge23 sends a lookup message to Rv19 . 4. Rv19 searches in STORERv19 and in INDEXRv19 and finds nothing. Rv19 computes the closest rendez-vous peer which is Rv43 . So, Rv19 forwards the query to Rv43 . 5. Rv43 finds nothing in STORERv43 as well as in INDEXRv43 . It computes RespP eer(38) which is Rv43 (himself): a walking process must be initialized. Rv43 walks the lookup in the UP direction to Rv46 and DOWN to Rv41 . 6a. In the UP direction, Rv46 has neither the related advertisement, nor an index information. Rv46 continues the walking with Rv47 . As there is nobody more in the UP direction, the walking stops in this direction at Rv47 . 6b. In the DOWN direction, the lookup is forwarded first to Rv41 , then to Rv40 and finally to Rv39 . Rv39 has the index of the key 38 which points to Edge17 . 7. Rv39 forwards the query to Edge17 . Edge17 finds the advertisement in its store STOREEdge17 . 8. Edge17 sends the advertisement Adv1Edge17 to Edge23 (the originator of the request). Edge23 stores the advertisement in STOREEdge23 .
This scenario presents a very bad situation for the algorithm as the Ids of the peers which joined the network are not uniformly distributed in the Id space. However, we can see that the algorithm proposed can be highly affected when new peers join the network even when the PEERVIEWs become consistent.
3.6.3 Scenario 3: Leaving of Rendez-vous Peers We did not find any replication in our study of JXTA source code (version 2.1.1), but [34] presents the idea of replication of indexes. We assume that the replication is executed by the closest rendez-vous peer (algorithm 7). The index is forwarded in both direction of its local PEERVIEW to a defined number of peers (according to a replication factor). Scenario 2 is illustrated in figure 3.6. Time A
CHAPTER 3. JXTA
44
Algorithm 7 Modification of Indexing in JXTA with Replication of Indexes, executed by P eeri ... {At reception of the index k by a rendez-vous peer Rv q } P ut(INDEXRvq , k) Rvr ← RespP eer(k.key) if Rvr = Rvq then send to Addr(Rvr ) the index k else {Rvr is Rvq } send k to neighbours for replication purpose end if
2
8
13
15
17
20
Consistent PEERVIEW of all nodes at time A Hash Table (item 18 in black)
2
8
13
17
Consistent PEERVIEW of all nodes at time B
20
Time A
Time B after leave of peer 15 6. Response
1. Push Index 18
9
19
17
2
2
9
17
19
3b. Index 18
13
2. Push Index 18
20
8
4. Lookup 18
13
15
5. Forward Lookup
20
8
15
3a. Index 18
Figure 3.6: JXTA Routing and Indexing: Scenario 3 1. Edge9 creates advertisement Adv1Edge9 . The indexing daemon takes this new advertisement Adv1Edge9 and computes the hash value of its Id. We suppose that hash(Adv1Edge9 ) = 18. Edge9 sends (18, Edge9 ) to the rendez-vous it is connected to (Rv2 ). 2. Rv2 inserts (18, Edge9 ) in INDEXRv2 and tries to compute a closer peer: RespP eer(18) is Rv15 . Rv15 inserts (18, Edge9 ) in INDEXRv15 and tries to compute a closer peer: RespP eer(18) is Rv15 as the PEERVIEWs are consistent. 3. The index (18, Edge9 ) is replicated to the two neighbours (assuming that the replication factor is 2) of Rv15 in the PEERVIEWRv15 which are Rv13 (3a.) and Rv17 (3b.).
Time B: rendez-vous peer Rv 15 leaves the network 4. Edge19 looks for the key 18 which is not in its storage.
3.7. JXTA BOOTING PROCESS
45
Edge19 sends a lookup message to Rv8 . 5. Rv8 searches in STORERv8 and in INDEXRv8 and finds nothing. Rv8 computes the closest rendez-vous peer: RespP eer(18) is Rv17 . So, Rv8 forwards the query to Rv17 . Rv17 finds the index of key 18 in INDEXRv17 which points to peer Edge9 . 6. Rv17 forwards the query to Edge9 . Edge9 sends the advertisement Adv1Edge9 to Edge19 .
3.7 JXTA Booting Process 3.7.1 JXTA Configurator The JXTA platform is generally configured using the JXTA Configurator GUI tool (the platform can however also be configured by coding the parameters). This configurator generates a configuration file (PlatformConfig) which is stored in a special directory and can be re-used during another session. The configurator allows to define the following properties: The Peer Name The TCP Settings allowing to activate/deactivate the TCP transport, to specify the local TCP address and port, to activate/deactivate multicast and to enable incoming/outcoming connections. The HTTP Settings allowing to activate/deactivate the HTTP transport, to define the HTTP address and port and to enable incoming/outcoming connections. The Rendez-vous and Relays Settings allowing to define the seed addresses of the rendez-vous and the relay peers either by providing directly the addresses or by using a list of addresses downloaded from a remote server defined by a URL. Moreover, it is possible to specify that a peer wants to act as a rendez-vous or as a relay. A Relay Server (address and port) if the peer is behind a firewall Security Settings providing a login/password authentication when the JXTA platform starts.
3.7.2 JXTA Platform Booting During the booting process, the World Peer Group is first created and then the Net Peer Group: • the World Peer Group advertisement defines: – the default services: endpoint service, rendezvous service, resolver service, pipe service, peer information service, discovery service, membership service (Null Membership) and access service (Always Access). – the transports: TCP and HTTP
CHAPTER 3. JXTA
46
– the applications: the Net Peer Group • the JXTA configurator is started (only if the current configuration is empty or not complete). • the services are created and initialized according to the configuration (TCP or HTTP enabled/disabled) and the World Peer Group advertisement. • the transports are included as network transports in the endpoint service. • the default Net Peer Group is created. The services include those defined in the World Peer Group and the proxy service. The transports include now the endpoint router (used to resolve routes towards other nodes), the TLS transport (a secure transport) and the relay transport. A new application is specified: the JXTA shell. • the services are started and the network transports inserted to the endpoint service. • the Net Peer Group is published using the discovery service. • the JXTA shell is started as an application.
3.8 Related JXTA Projects In this section we present projects developed by members of the JXTA community. These projects are close to our project and therefore deserve to be studied. • GISP (Global Information Sharing Protocol) • JXTA DI (Distributed Indexing) • JXTA CMS (Content Management System)
3.8.1 GISP: Global Information Sharing Protocol GISP [26] provides a distributed index system where each peer is responsible for a part of the index. GISP does not use broadcasting: the lookup of a data involves the sending of a query to a selection of peers according to the search keyword. Keywords can be keys as well as XPath expressions. The description which follows presents GISP and its implementation [5]. GISP API GISP provides the following services: Insertion of data : a data is identified by a key. The contain of a data can be either a string or an XML document. A time-to-leave for each data is specified. Query of data : a data can be searched either by specifying its key, or its key and an XPath expression (for an XML document).
3.8. RELATED JXTA PROJECTS
47
GISP Definitions Message : a message is the information that moves between peers. Messages are represented as XML documents defined using XML schemas. PID : an ID assigned to a peer Distance between IDs : defined as A xor B for two IDs A and B Responsible peer of an item : a peer which is one of the closest to the item Binding : a network protocol used as an underlying transport Peer Local Information Each peer stores and maintains a set of local information: Peer Table containing other known peers. Each entry of the Peer Table contains the ID of one peer, its physical address and the number of errors of communication between the local node and this peer. Data List storing items using triplets of (key, value, time-to-live) Reply Table keeping IDs of messages sent which did not timeout or have not yet received a response Bootstrapping A peer needs, in order to use the distributed index, to get an address of another peer present in the network. This bootstrap process relies on the different bindings presented in a following paragraph. Once a peer has a seed address, it sends a message to this address and get back the peer table of this peer: the peer can now initialize its own peer table and start to use the distributed indexing system. Peer Table Maintenance The peer table keeps information on the set of active peers in the network. Each peer information contains an expiration time. An expired peer, as well as a peer no more reachable, is removed from the peer table by a specific process. Each peer sends periodically a message to all the peers in the peer table at least just before the previous information expires. To maintain the table, a process periodically generates lookup messages containing IDs close to the local peer ID. Each response to these messages includes a list of peers close to the remote peer contacted. These peers can thus be inserted in the peer table. Insertion of Items and Replication Each peer has a local database to store items (Data List). When a peer wants to publish an item, it insert the item in its local database. Then, a process (by default every 10 seconds) goes through all the local items and executes the following steps: • the current list of known peers is ordered according to their distance to each item
CHAPTER 3. JXTA
48
• each item is sent to the r (r is the replication factor) closest peers thanks to an insertion message, unless it has already been sent once (each item keeps a list of peers to which it has already been sent). When a peer receives an insertion message, it adds the item into its data list. Each item inserted has an expiration time. A data cannot be deleted: it just expires if it is not refreshed on time. Thus, an item is kept replicated among r peers, even when peers fail (as long as the peer knows at least r peers). Maintenance of Items A process periodically ckecks its data list in order to: • remove expired items • keep the replication of items among the peers Queries When a client wants to search for an item, it looks for it first in its data list and then sends a query message to a defined number of peers which are the closest to the key. When a peer receives a query message, it sends back a result message to the originator of the query. This result contains all the items verifying the optional XPath expression specified in the query. The result also contains a defined number of peers which are the closest to the ID of the query. This information is used for the maintenance of the peer table. Message Routing In a real peer-to-peer network, there are so many peers that one peer cannot store the information of all other peers. Thus, message routing is necessary. However, neither the GISP paper [26], nor the implementation presents a protocol for this routing: the current version of the implementation assumes that each peer is able to store the information of each other peers of the network. The paper proposes a general description of the process of routing with a reduced knowledge of other peers: when a peer receives a message and he knows more appropriate peers, which means there are peers whose hash values are numerically closer to hash value of the message keyword, the peer routes the message to the more appropriate peers. [...] To avoid message looping, a peer includes the list of peers that it has already sent. To provide an efficient routing table, GISP could leverage this work to have a better routing mechanism. GISP extends the Chord routing table [...] Thus, GISP assumes another efficient routing protocol such as Chord. However, this part has not yet been implemented. Bindings JXTA-Endpoint : for the bootstrapping, a peer publishes a JXTA advertisement that contains its informations, in particular its address, using the JXTA discovery service. Messages are transported using the JXTA endpoint service by obtaining a messenger and asking it to send the message.
3.8. RELATED JXTA PROJECTS
49
UDP : for the bootstrapping, a peer should get a seed address using either a commandline parameter, a local file or a central server. GISP Application: Jnushare Jnushare is an information sharing application built on top of GISP. It provides functionalities such as files sharing, messages sharing and bookmarks sharing. Information sharing is based on directories: a file inserted in a directory will be published, in such a way that the other peers will see the file in the same directory. Directories can thus be browsed, after a latency at each new level. Comments • to manage failure of peers, GISP uses multicast of messages. Thus, a peer will generally receive more than one response. This solution is fault-tolerant, as long as not more than the number specified by the replication factor of peers fail simultaneously. A high network traffic is thus generated. A query not resolved simply timeouts. • advertisements from the other peers (such as new peers) are collected using the JXTA discovery service and the use case get a remote advertisement. • the UDP binding is completely independent of JXTA and uses directly sockets and datagrams. • the routing protocol, which is the most interesting part for our project, is not scalable as it is currently implemented. It is moreover independent from the JXTA routing.
3.8.2 JXTA Distributed Indexing The objective of JXTA distributed indexing (DI) project [9] is to implement a fully distributed and robust index service. This index can then be used to search content. JXTA DI uses a distributed hash table to map keys to content: they are dealing with Chord and CAN. State of the Project The current implementation of JXTA DI provides an implementation of Chord and an implementation of CAN. These implementations are however completely independent of JXTA. They intend as future work to integrate Chord and CAN to the JXTA framework. The current underlying transport uses sockets for the connections between the peers. These socket connections are maintained open in a connection pool according to a defined limit of sockets opened simultaneously (using a LRU policy). Overview of the Chord Implementation The routing protocol implements the Chord algorithm.
CHAPTER 3. JXTA
50
The routing table is updated at each reception of a message: the sender is inserted in the routing table if the node is relevant. Another process periodically updates the successors list by sending specific requests containing random keys near the successors. The join protocol first tries to find the successor of the new node, then sends a ”split message” informing the node to split its range of keys. The successor, the predecessor as well as the routing table are updated. Communications are asynchronous using queues of messages. The connection failures are managed using a list of outcoming messages: when a message is correctly sent, it is removed from the list. If an error occurs, a notification containing the node which failed is sent by the process managing this list to the concerned components of the framework. The Chord node removes the node which failed from the routing table, informs its successors of the failure and updates its successor and predecessor. Replication is implemented: keys are replicated among a defined number of peers using the successors’ lists. Caching is not implemented. Overview of the CAN Implementation The CAN implementation is at the same state as the Chord implementation. Connections use directly sockets and no plugin into JXTA is implemented. Comments • Thus, the aim of this project is very similar to our. They have an implementation of a DHT and they want to plug this implementation into JXTA. However, no further information on this subject is available on the web site of the project.
3.8.3 JXTA Content Management System JXTA Content Management System (CMS) [8] allows JXTA applications to share and search content within a peer group. Each shared item is identified by a unique content ID. An item is described using a content advertisement which defines the content ID, the address of the peer (a JXTA endpoint) which shares the content and further metainformation, such as its name, length, MIME type and description. Content Sharing CMS uses the JXTA discovery service to publish the content advertisements. The use case described in appendix A publish an advertisement is used. Thus, the indexing process is managed by the JXTA framework. A content advertisement specifies as indexing keys the content ID, the name of the content and the MIME type of the content.
3.8. RELATED JXTA PROJECTS
51
Content Lookup Process To obtain content advertisements from a remote peer, CMS uses the JXTA discovery service to get remote advertisements (use case get a remote advertisement) by specifying a pair of key and value which specifies the research criteria. Content Fetching Process When the advertisement of a content is discovered, the content can be directly obtained from the peer specified by the endpoint address in the advertisement. CMS first creates a new JXTA message (the type is specific for getting a content). Then, the peer registers the CMS application as a listener to the JXTA endpoint service by specifying as service name CMS-GetRequestrequest ID . Thus, the CMS can receive the response from the JXTA endpoint service. Then, the message is sent asynchronously using the JXTA endpoint service (use cases get a messenger and send a message). When the peer which shares the content receives this message, it creates a response message including the content. This response is then sent back to the requester using again the JXTA endpoint service. JXTA Shell Extensions The JXTA Shell (Appendix B) is extended with new commands allowing to initialize and interact with the CMS application. The extensions are the following: cms used to initialize the CMS application ls used to list local contents rcp used for the content fetching process share used for content sharing unshare used to unshare a content referenced by a content advertisement. The document is no more accessible to any one in the group. Comments • content is described using JXTA advertisements • CMS uses the JXTA indexing to share content using the keys specified in the advertisement • the lookup process uses the JXTA routing algorithms • content transfer is direct between peers and uses the JXTA endpoint service
3.8.4 Summary of the JXTA Projects studied • GISP is not well integrated into the JXTA framework and uses a routing protocol which is not scalable at its current state. • JXTA DI is not integrated at all into the JXTA framework.
52
CHAPTER 3. JXTA • CMS is built on top of the JXTA framework and uses the JXTA indexing and routing algorithms. As these algorithms are not as efficient and scalable as those proposed by structured networks such as Pastry or Chord, we propose in the next chapter to replace these algorithms. With the new routing algorithms, the CMS application is expected to become more efficient, more scalable and more robust, without modifying its implementation.
Chapter 4
A DHT plugged into JXTA
53
CHAPTER 4. A DHT PLUGGED INTO JXTA
54
4.1 Objective The objective of this section is to replace the routing layer of the JXTA framework with any distributed hash table. This modification should involve minor modifications to the JXTA distribution and should be enough general to plug any distributed hash table into the JXTA framework. In Section 2, a common software architecture was presented. As depicted in figure 4.1, the JXTA framework can also be applied to this architecture: Transport The endpoint service manages the sending and the reception of messages. Network transports can be added to the endpoint service: TCP, HTTP and UDP are activated by default. The endpoint service can deal with NAT environments and dynamically updates the routes to reach the peers. Routing Thanks to the Rendez-vous Peer View and the Walker, the rendez-vous service can route messages in the overlay network more efficiently and in a more scalable way than using a flooding approach like in JXTA 1.0. Storage The discovery service, the pipe service and the endpoint service manage each of them an index where advertisements are indexed. Application CMS (presented in Section 3.8.3) is for instance an application which uses the discovery service in order to index and look up content.
Application
JXTA Applications: CMS, ...
Storage
Index in Discovery / Pipe / Endpoint Service
Routing
Rendez−vous Service [Peer View]
Transport
Endpoint Service
Figure 4.1: Common Software Architecture applied to JXTA The aim of the plugin is therefore to keep the application, the storage and the transport layers as they are implemented in the JXTA framework and to replace the routing layer, in particular the peer view with a distributed hash table. In Section 2, the API between the storage and the routing layer and the API between the routing and the transport layer were defined. In order to plug a DHT into the JXTA framework, we need to provide the operations defined by theses APIs. However, the storage layer of the JXTA framework does not provide replication of indexes and no transfer of indexes is executed when nodes join or leave the network. Therefore, the methods range and replicaSet will be defined in the plugin, but will not be linked to the JXTA framework: once the JXTA framework will be updated to take into account these mechanisms, the interaction with the DHT will already be provided.
4.2. DHT ROUTING IMPROVEMENTS
55
4.2 DHT Routing Improvements We summarize in this section the main drawbacks of using the rendez-vous peer view mechanism. The rendez-vous peer view is not scalable. Each rendez-vous peer stores and maintains a list of rendez-vous peers. The management of such a list of rendez-vous peers is not scalable: with N rendez-vous peers, the size of each local view is O(N ). Considering millions of nodes participating to the network, this mechanism cannot be applied. The guarantee of finding a key is low. The main problem is that the rendez-vous peer views are not consistent, which means that some rendez-vous peers are missing in the views. When a message is walked, some peers of the system are thus not reachable and are ignored. This problem is moreover amplified when a request is forwarded by a rendez-vous peer which just joined the network: its peer view is very inconsistent and the first hop will already miss many peers. The Walker is difficult to manage: a message walked in the network can be limited with a hop count. However, if this hop count is too small, guarantee of finding a key is low; if it is too big or not limited, the system is no more scalable. A DHT improves this mechanism as it provides the following properties: Scalability : the size of a routing table is O(log(N )) and each lookup is resolved in O(log(N )) hops. Moreover, a lookup not resolved in O(log(N )) steps is always stopped, independently of its success. High guarantee of finding a key : the routing tables are maintained in such a state that a lookup will never miss a peer. A peer that finished its initialization of its routing table can moreover directly participate to the routing of messages without harming it. The main disadvantages of a DHT in comparison with the rendez-vous peer view mechanism are the following: • indexes have to be transferred between peers. This is the main disadvantage of using a DHT: any DHT at present is based on this mechanism to provide efficient lookups. • the maintenance of the routing tables involves a higher rate of exchange of messages for stabilization purpose. A system such as DKS (distributed k-ary search) [19] solves however this problem by using a technique called correction-on-use which avoids this periodic activity. Moreover, DKS can be tuned to balance the size of the routing table and the lookup length.
4.3 Interfaces In order to provide a clean plugin of any DHT into the JXTA framework, we provide two interfaces: DHTInterface and JXTAInterface. The DHTInterface links the routing layer to the storage layer providing the methods lookup and event. The JXTAInterface links the routing layer to the transport layer providing the methods send and receive.
CHAPTER 4. A DHT PLUGGED INTO JXTA
56
The current system with these interfaces is presented in Figure 4.2. These interfaces are included in the Appendixes C.1 (DHTInterface) and C.2 (JXTAInterface): • The DHTInterface defines the methods lookup and event (converted to a JXTA notification with the method notify), the methods range and replicaSet which will currently not be used by JXTA, and the methods seedPeers and becomeEdgePeer. The last two methods provide: – for seedPeers, a mean to transmit to the DHT the addresses of the seed peers defined thanks to the JXTA configurator during the JXTA initialization. – for becomeEdgePeer, a notification to the DHT that the local node will not participate anymore in the routing and indexing. The DHT can thus notify the other peers before it stops. • The JXTAInterface defines the methods send and receive (receive is in reality a notification received from the endpoint service through the method processIncomingMessage).
Storage lookup
Routing
DHT Interface lookup
route
event
event
deliver
DHT
send
receive
JXTA Interface send
receive
Transport
Figure 4.2: Common Software Architecture applied to JXTA with APIs
4.4 Adaptors To simplify the job of plugging a DHT into JXTA using the interfaces presented in the previous section, adaptors are provided to the DHT to increase its independence from the JXTA framework: JXTAAdaptor (Appendix C.3): the main functionality of the JXTAAdaptor is to simplify the interaction of the DHT with the endpoint service: • when the endpoint service receives a message destined to the DHT, the JXTAAdaptor is notified (the JXTAAdaptor is registered as a listener to the
4.5. THE DHT POINT OF VIEW
57
endpoint service). The JXTAAdaptor converts the JXTA endpoint message to a more generic type of message (Message (Appendix C.8) containing a serializable object). This message is then transmitted to the DHT using a more simple method receive that the DHT must implement. • to send a message, the DHT creates a generic message independent from JXTA: the JXTAAdaptor takes care of converting this message into a JXTA endpoint message and to send the message using the JXTA endpoint service. • during the seeding process initialized by the DHTAdaptor, messages specific for the seeding can be received by the JXTAAdaptor: to simplify the task of the DHT, the JXTAAdaptor checks this kind of messages and invokes the method seedPeer that the DHT must implement. DHTAdaptor (Appendix C.4): as the DHT must use both the JXTAAdaptor and the DHTAdaptor and as multiple inheritance is forbidden in Java, DHTAdaptor extends JXTAAdaptor and the DHT will extend DHTAdaptor. The main activity of the DHTAdaptor is to take care of the notification of events (method event) and the seeding process. The methods lookup, range, replicaSet and becomeEdgePeer can indeed be directly transmitted to the DHT. • the notification of events uses the JXTA notification mechanism provided by the JXTA rendez-vous service: this mechanism was already used by the rendez-vous peer view. • the problem of the seeding process is the following: the seeding addresses provided by the configuration only contain the physical addresses of the peers such as an IP address. We need however to provide to the DHT the IDs of these peers. Thus, these IDs have to be fetched: a specific message is thus sent to these addresses in order to get their IDs. The JXTAAdaptor takes care to reply to these message, to receive the responses and to transmit the IDs to the DHT.
4.5 The DHT Point of View The DHT has now to provide the implementation of the methods lookup, receive, seedPeer, becomeEdgePeer, replicaSet and range. A template of the DHT is presented in Appendix C.5. This template presents the methods that need to be implemented, as well as the methods that are provided to the DHT. An application of this template is presented in Appendix C.6: the DHT used is FreePastry which was described in Chapter 2. Only the initialization of the DHT and the method lookup have been fully implemented. The current implementation of FreePastry should indeed be partially rewritten in order to clearly separate the transport (using Java RMI) from the routing algorithms. However, all the algorithms necessary to implement the methods replicaSet and range are already implemented in the FreePastry distribution. The figure 4.3 presents the current state of the plugin of FreePastry into JXTA. We can notice that FreePastry is still using RMI to communicate with the other nodes in the network. Another step would be to send the messages exchanged by Pastry nodes using the JXTA endpoint protocol.
CHAPTER 4. A DHT PLUGGED INTO JXTA
58
Storage
Storage
Routing
Routing Java RMI
FreePastry
Transport
FreePastry
Endpoint Protocol
Transport
Figure 4.3: FreePastry plugged into JXTA
4.6 Modifications to the JXTA Distribution In order to replace the routing protocol of the JXTA framework, the main modifications brought to the JXTA framework are the following: • instantiate a DHT and the adaptors • redirect the lookup invocation to the DHT • register the DHT as a listener for the related messages to the endpoint service To make easy the plugin of different DHTs we used the factory design pattern. According to a defined type of DHT, the corresponding DHT is instantiated (if the DHT is not available, an exception called NoSuchDHTException (Appendix C.10) is raised). The factory class is included in the Appendix C.7: the only DHT available is currently Pastry.
The rendez-vous service of the JXTA framework is modified as follows:
In the initialization of the rendez-vous service: • a DHT is instantiated using the factory class (lines 6-11). • the platform configuration is used to find the seed peers addresses (lines 13-17). • the seed peers are transmitted to the DHT (to the DHTAdaptor) (line 18). • the DHT is registered as a listener to the endpoint service (lines 25-28). These steps are presented in the code presented in Figure 4.4. The lookup invocation (called getReplicaPeer in JXTA) is redirected to the DHT. A method can thus be used by the storage layer to look up a key. This method, presented in figure 4.6, is provided by the rendez-vous service.
4.7. IMPLEMENTATION
59
Figure 4.4: DHT Initialization in the JXTA Rendez-vous Service public int startApp ( String [ ] arg ) { ... try{ d h t I n t e r f a c e = j x t a d h t . DHTFactory . newDHT( peerGroup , rdvService , endpointService , localPeerId , j x t a d h t . DHTFactory . PASTRY DHT ) ;
}
net . j x t a . impl . rendezvous . conf . StaticRdvConf config = new n e t . j x t a . i m p l . r e n d e z v o u s . c o n f . S t a t i c R d v C o n f ( ) ; config . i n i t i a l i z e ( peerGroup ) ; String [ ] seeds = ( String [ ] ) config . getProperty ( S t a t i c R d v C o n f . BOOTSTRAP ADDRESS PROPERTY ) ; dh t I nt er f a ce . seedPeers ( seeds ) ;
c a t c h ( j x t a d h t . NoSuchDHTException e ){ LOG . warn ( "No such kind of DHT: " + e . getDHTType ( ) , e ) ; } endpoint . addIncomingMessageListener ( dhtInterface , j x t a d h t . J X T A I n t e r f a c e . SVCNAME, j x t a d h t . J X T A I n t e r f a c e . SVCPARAM ) ;
p u b l i c n e t . j x t a . p e e r . P e e r I D g e t R e p l i c a P e e r ( S t r i n g e x p r e s s i o n ){ return d h t I n t e r f a c e . lookup ( expression ) ; }
Figure 4.5: Lookup Method in the JXTA Rendez-vous Service
4.7 Implementation 4.7.1 Overview The main difficulty of the implementation is the integration of the distributions of FreePastry (version 1.3) and JXTA (stable build 2.1.1). The figure 4.6 presents an overview of the different steps involved in the plugin of FreePastry into JXTA. To simplify the tasks of the compilation of the full system, we used Jakarta Ant with different defined tasks. JXTA distribution already used this tool, whilst FreePastry used initially a Makefile. A task (ant jar) executes the following sub-tasks: 1. Compile the FreePastry sources 2. Generate the Java RMI stub and skeleton used by FreePastry (using rmic) 3. Create the FreePastry archive 4. Compile the classes necessary for the plugin (interfaces, adaptors, factory, . . . ) using the FreePastry archive and the JXTA archive (the official distribution) 5. Create the plugin archive 6. Compile the modified JXTA distribution with the integration of the DHT using the plugin archive
CHAPTER 4. A DHT PLUGGED INTO JXTA
60
7. Create the new JXTA archive 8. Replace the JXTA archive used by JXTA Shell with the new JXTA archive and include as a library the FreePastry archive
JXTA 2.1.1
FreePastry 1.3
DHT Plugin Classes
JXTA + DHT
JXTA Shell Figure 4.6: Implementation Organization
4.7.2 Shell Application With the integration of the DHT, the JXTA platform boots correctly and initializes the DHT. A simple scenario can be executed in order to test the implementation. This scenario is the following: 1. Create four instances of the Shell: three rendez-vous peers and an edge peer. Each rendez-vous peer knows another one (except the first one) and the edge peer is connected to one of them. 2. The edge peer creates an advertisement (for instance a pipe advertisement) using the shell command: pipe1 = newpipe -n pipe name 3. The edge peer publishes the pipe advertisement using the shell command: publish -d pipe1 4. By setting the debugging information (JXTA uses Log4J) at the level ”debug” for the discovery service and the SRDI service, we can see that the pipe advertisement is indexed according to its defined keys (the name and the ID): the indexes are forwarded to two rendez-vous peers (they can be however both the same) according to the Pastry routing algorithm. 5. The third rendez-vous can now look for this advertisement using the following command:
4.8. PROPAGATION
61
search -r -aName -vpipe name Using the debugging information, we can see the execution of the following steps: • The discovery service of the third rendez-peer receives a query (with the primary key Adv, the attribute Name and the value pipe name). The SRDI service does not find a related advertisement in its own index, so it asks to the rendez-vous service to look up this key: the FreePastry lookup method is invoked and FreePastry returns the rendez-peer which stores the index of the pipe concerning its name. The query is then forwarded to this rendezvous peer. • This rendez-vous peer processes the query: it looks first in its local storage using the discovery service and finds nothing, then it asks the SRDI service to find this key. The SRDI service finds the key in its index. The query is forwarded to the edge peer, as defined in the index returned by the SRDI service. • The edge peer finds the pipe advertisement in its storage and forwards the advertisement to the third rendez-vous peer. • This rendez-vous of the third peer receives the advertisement and publishes it using the discovery service (we can now see the advertisement using the command search).
4.8 Propagation JXTA implements the propagate pipe abstraction (Section 3.2) with a broadcast service. This service uses the rendez-vous service and the rendez-vous peer view. A message sent to this pipe should be propagated to all the peers which are connected to this pipe. A peer initializes a broadcast by sending two messages: one to the peer which is situated before him in its local peer view and one to the peer situated after him. A peer receiving a propagated message continues to transmit the message to the same direction according to its local peer view as long as the extremity of the peer view is not reached. By replacing the peer view with a DHT, the propagation service must still be available. As presented in [29, 25, 27], the structure of a DHT improves the efficiency of a broadcasted message to a distributed system. Moreover, a broadcast service built on top of a structured overlay network satisfies the following properties: Scalability : a DHT avoids the sending of too many redundant messages (a broadcast requires O(N ) messages for a network of size N ); no node forwards a disproportional amount of network traffic (load-balancing). Robustness : broadcasting using a DHT is resilient to the dynamicity of nodes joining, leaving and failing. Coverage : all the nodes receive the messages broadcasted. Scribe [20] (Pastry), Bayeux [37] (Tapestry) and M-CAN [29] (CAN) already implement multicast on top of their respective underneath structured network.
62
CHAPTER 4. A DHT PLUGGED INTO JXTA
Thus, broadcasting does not constitute an issue in replacing the rendez-vous peer view with a DHT.
Chapter 5
JXTA Personal Point of View
63
64
CHAPTER 5. JXTA PERSONAL POINT OF VIEW
5.1 JXTA Project JXTA project provides a platform allowing to program any P2P applications. This platform makes easy the development of distributed applications as it avoids the building from scratch of a complete infrastructure for instance for discovery and communication. JXTA is thus a very interesting initiative whose aim is to provide a peer-to-peer middleware. JXTA project involves a great and still growing community. This condition is necessary for a common platform to succeed and to be eventually widespread. As peer-topeer applications are distributed among many nodes, each of them have to agree upon common protocols and a common platform: JXTA is the most prominent distribution which can be used to achieve this aim. As the project is open-source, it can benefit from the reviews of people as well from the community as from people from universities and research labs and from individual persons. All these contributors can suggest new improvements and identify bugs. This particularity is essential in order to provide a solution which is close to what people in this realm need.
5.2 Documentation The general drawback of open-source projects is the lack of a detailed and up-to-date documentation. As the JXTA specification and implementation is modified regularly, the few books which have been published so far on JXTA are for the most no more compliant with the current distribution about specific topics. The routing algorithms of JXTA 2.0 presented in this report are for instance described precisely neither in books, nor in the JXTA documentation. We extracted them by reading the source code. Moreover, we noticed also in our project that the documentation is not always compliant with the implementation and no indication of the level of compliance is usually available. For instance, the maintenance of the rendez-vous peer view is described differently in the paper [34] than how it is really implemented in the source code. Replication of indexes is another difference about which nothing is mentioned, too. Another point is the terminology used by the JXTA project which is sometimes confusing. For instance, the service concept is not very clear: sometimes is is nearer to the concept of layer, sometimes to the concept of component and sometimes it is a really service. The endpoint service which is more a transport layer and the rendez-vous service which is used by both edge peers and rendez-vous peers are other examples of not-well chosen terminologies. The JXTA framework is quite complicated and provides a lot of new concepts: to help developer using this framework, the effort of the community should also turns towards a better documentation of their product.
5.3 Routing and Indexing The introduction of a new routing mechanism in JXTA 2.0 was a substantial improvement in comparison to the flooding approach used in JXTA 1.0. This evolution improved the scalability and the efficiency of the system. However, the algorithms remain still unscalable according to real applications involving million of nodes. The rendez-vous peer view keeps O(N ) routing information, whilst a DHT usually stores
5.4. FRAMEWORK
65
only O(log(N )). Moreover, according to preliminary simulations of the JXTA routing algorithms, they behave quite badly when new nodes join the network. Joining and leaving of nodes is however the normal situation in peer-to-peer systems: the framework has thus to deal with them properly. The routing mechanism used by JXTA 2.0 does not rely on a specific structured network, which hampers an efficient and rigid replication of elements. Replication over a defined number of peers cannot be kept accurate by using only the rendez-vous peer view. The peer views are indeed not enough accurate in order to select well-defined peers to replicate an index and to maintain the replication factor of each of them. Finally, research in structured overlay network has reached a point where the algorithms have been proved correct and have been simulated: they can thus be directly applied. JXTA could benefit greatly from this research in improving its routing layer. This step would avoid to the JXTA community to prove the correctness and the efficiency of their own routing protocol.
5.4 Framework With the introduction of the SRDI service, the JXTA framework becomes much more complex and the services less independents. The services can no more be depicted as a stack, as there are to many interactions between them. For instance, the endpoint service relies now on the discovery service to publish route advertisements. It was probably difficult to keep the separations between the services clear, but the components of the framework risk to become more and more interconnected and thus less modifiable.
5.5 Java Source Code We managed to extract the routing and indexing algorithms from the source code, which means that the code is not so badly written. The use of Java, which is welldefined and structured, helped us probably to achieve this task. The main bad point which can be mentioned is the legacy code remaining from the JXTA 1.0 distribution which is no more used. Even if an effort was clearly provided to replace the routing of JXTA 1.0 in a clean way, this effort must be carried on to provide a neat distribution. The source code is on the whole well documented and the packages and classes well organized.
5.6 Distributions The JXTA Web site is very well organized: it is easy to find the sources, the binaries and to download them. Current stable builds, nightly, as well as previous stable builds can be easily downloaded. Issues can be added by any member and browsed using the issues tracking system IssueZilla. The issues corrected are listed at each new stable build. The JXTA source code can be easily recompiled thanks to the powerful tool Ant developed by Jakarta. No particular problem occurs in our project with the compilation of the sources.
66
CHAPTER 5. JXTA PERSONAL POINT OF VIEW
5.7 Further suggested Improvements In order to be widely accepted as a common framework for developing peer-to-peer applications, the JXTA project needs to gain acceptance in research labs in distributed systems. The JXTA technology can help make distributed applications based on peer-to-peer systems grow in the real world. In order to achieve this aim, the effort of the community should also be turned toward a better documentation of the framework. The distributions need to become more stable and address important security issues. The ultimate goal for JXTA would be to become a kind of library which could be used in software development process: this library should be stable, easy to use and reliable.
Future Work In the continuation of the current work, there are issues which are still open. While the plugin of a structured overlay network can improve the efficiency of the routing in JXTA, the JXTA storage layer still needs to be completed with a solution providing on the one hand the transfer of keys when peers join the network and on the other hand replication of indexes over a defined number of nodes. The simulations of the JXTA algorithms could be also carried on with specific scenarios and compared with the other DHTs. The results may provide to the JXTA community the most suitable algorithms to use eventually in the JXTA framework.
67
68
Conclusion The ambition of this project was to analyse the improvement that a DHT could provide to the JXTA framework. After a deep study of the JXTA framework which focused on its indexing and routing algorithms, we managed to provide a means to plug a DHT into JXTA. This plugin is moreover clean enough to use any DHT conforming to the interfaces defined: the main objective of this project is thus fulfilled. Even if the system could not be completely implemented in the scope of the project, the architecture is now well defined and the steps remaining to achieve the final goal which is the developpement of a scalable and efficient peer-to-peer framework are explained and documented in this report. Finally, we provide a high-level description of the organization of storage applications distributed over a peer-to-peer system. This architecture presents the operations that each layer must provide in order to interact with the others, and thus constitutes another contribution of the project. And last but not least, the detailed description of JXTA with on the one hand the UML use cases and on the other hand the formalization of the algorithms presents a new approach to JXTA which differs from the traditional architectural presentations.
69
70
Bibliography [1] Entropia PC Grid Computing, http://www.entropia.com. [2] Freenet, http://freenetproject.org. [3] FreePastry, FreePastry.
http://www.cs.rice.edu/CS/Systems/Pastry/
[4] Genome@home, genome.
http://www.stanford.edu/group/pandegroup/
[5] Global Information Sharing Protocol (GISP) JXTA Project, http://gisp. jxta.org. [6] Groove, http://www.groove.net. [7] Jabber, http://www.jabber.org. [8] JXTA Content Management System (CMS) Project, http://cms.jxta.org. [9] JXTA Distributed Indexing (DI) Project, http://di.jxta.org. [10] KaZaA, http://www.kazaa.com. [11] Magi: Secure Peer-to-Peer Collaboration Solutions, endeavors.com.
http://www.
[12] OceanStore, http://oceanstore.cs.berkeley.edu. [13] Onobee, http://www.ppserver.com. [14] Overnet, http://www.overnet.com. [15] Project JXTA, http://www.jxta.org. [16] SETI@home, http://setiathome.ssl.berkeley.edu. [17] The Chord Project, http://www.pdos.lcs.mit.edu/chord. [18] Project JXTA: Protocol Specification V2.0, February 2003, http://spec. jxta.org. [19] Luc Onana Alima, Sameh El-Ansary, Per Brand, and Seif Haridi, DKS(N, k, f): A Family of Low Communication, Scalable and Fault-Tolerant Infrastructures for P2P Applications, Proc. of CCGRID, 2003. 71
BIBLIOGRAPHY
72
[20] Miguel Castro, Peter Druschel, Anne-Marie Kermarrec, and Antony Rowstron, Scalable Application-level Anycast for Highly Dynamic Groups, Proc. of NGC, 2003. [21] Frank Dabek, Frans Kaashoek, David Karger, Robert Morris, and Ion Stoica, Wide-area cooperative storage with CFS, Proc. of SOSP, 2001. [22] Frank Dabek, Ben Zhao, Peter Druschel, John Kubiatowicz, and Ion Stoica, Towards a Common API for Structured Peer-to-Peer Overlays, Proc. of IPTPS, 2002. [23] Peter Druschel and Antony Rowstron, PAST: A large-scale, persistent peer-topeer storage utility, Proc. of ACM SOSP, October 2001. [24] Sameh El-Ansary, A Framework For The Understanding, Optimization and Design Of Structured Peer-To-Peer Systems, Ph.D. thesis, Swedish Institute of Computer Science (SICS) Kista, Sweden, 2003. [25] Ali Ghodsi, Luc Onana Alima, Sameh El-Ansary, Per Brand, and Seif Haridi, Self-Correcting Broadcast in Distributed Hash Tables, Proc. of PDCS, 2003. [26] Daishi Kato, GISP: Global Information Sharing Protocol — a distributed index for peer-to-peer systems, Peer-to-Peer Computing, 2002. [27] Ji Li, Ben Leong, and Karen Sollins, Implementing Aggregation/Broadcast over Distributed Hash Tables, Tech. report, MIT, 2003. [28] Sylvia Ratnasamy, Paul Francis, Mark Handley, Richard Karp, and Scott Shenker, A scalable Content addressable Network, Proc. of ACM SIGCOMM, 2001. [29] Sylvia Ratnasamy, Mark Handley, Richard Karp, and Scott Shenker, Applicationlevel Multicast using Content-Addressable Networks, Proc. of NGC, 2001. [30] Antony Rowstron and Peter Druschel, Pastry: Scalable, decentralized object location and routing for large-scale peer-to-peer systems, Proc. of IFIP/ACM, 2001. [31]
, Storage management and caching in PAST, a large-scale, persistent peer-to-peer storage utility, Proc. of ACM SOSP, October 2001.
[32] Ion Stoica, Robert Morris, David Karger, M. Frans Kaashoek, and Hari Balakrishnan, Chord: A Scalable Peer-to-peer Lookup Service for Internet Applications, Proc. of Conference on applications, technologies, architectures, and protocols for computer communications, 2001. [33] Bernard Traversat, Mohamed Abdelaziz, and Eric Pouyoul, Project JXTA: A Loosely Consistent DHT Rendezvous Walker, Tech. report, Sun Microsystems, Inc, March 2003. [34] Bernard Traversat, Ahkil Arora, Mohamed Abdelaziz, Mike Duigou, Carl Haywood, Jean-Christophe Hugly, Eric Pouyoul, and Bill Yeager, Project JXTA 2.0 Super-Peer Virtual Network, Tech. report, Sun Microsystems, Inc, May 2003. [35] Brendon J. Wilson, JXTA, New Riders, 2002.
BIBLIOGRAPHY
73
[36] Ben Y. Zhao, Ling Huang, Jeremy Stribling, Seac C. Rhea, Anthony D. Joseph, and John D. Kubiatowicz, Tapestry: A Resilient Global-scale Overlay for Service Deployment, IEEE JOURNAL ON SELECTED AREAS IN COMMUNICATIONS 22 (2003), no. 1. [37] Shelley Q. Zhuang, Ben Y. Zhao, Anthony D. Joseph, and Randy Katz, Bayeux: An Architecture for Scalable and Fault-tolerant Wide-area Data Dissemination, Proc. of NOSSDAV, 2001.
74
BIBLIOGRAPHY
Appendix A
JXTA Use Cases
75
APPENDIX A. JXTA USE CASES
76
A.1 Discovery Service • Publish an advertisement (page 76) • Publish a remote advertisement (page 76) • Get a local advertisement (page 77) • Get a remote advertisement - send a query message (page 77) • Receive a discovery query message (page 78) • Receive a discovery response message (page 79) • Process a SRDI resolver message (indexes)(page 80) • Notify a failure (page 80) • Become a rendez-vous peer (page 80) • Become an edge peer (page 80)
Use Case : Publish an advertisement Context of Use : An edge peer created a new advertisement and wants to publish it. Primary Actor : An edge peer Main Success Scenario : 1. The edge peer created a new advertisement and defines its expiration time (or affects a default value). 2. The discovery service saves the advertisement locally in the advertisements storage. The following steps are periodically executed by an active thread in the SRDI service in parallel with the steps (1-2). 3. A thread in the SRDI service (specific to the discovery service) asks the discovery service to index the new elements from its storage. 4. The discovery service gets from the storage the indexes of the new advertisements added since the last process activation. 5. The discovery service creates a SRDI Entries message containing all these indexes and a time-to-live of 1 (one step to reach the rendez-vous peer to which it is connected). 6. The discovery service asks the SRDI service to send a SRDI entries message (page 81). Use case terminates.
Use Case : Publish a remote advertisement Context of Use : An edge peer created a new advertisement and wants to publish it immediately. Primary Actor : An edge peer Main Success Scenario :
A.1. DISCOVERY SERVICE
1. The edge peer provides the advertisement and its expiration time. 2. The discovery service creates a Discovery Response Message containing the advertisement and the expiration time. 3. The discovery service creates a Resolver Response Message containing the previous created message, the credential of the edge peer, the discovery service as handler name and the special query ID 0. 4. The discovery service uses the resolver service and invokes send a resolver response message (page 85). Use case terminates.
Use Case : Get a local advertisement Context of Use : An peer looks for an advertisement in the storage. Primary Actor : A peer Main Success Scenario : 1. A peer asks the discovery service to get local advertisements specifying the type and an optional attribute/value pair (criteria). 2. The discovery service searches the matching advertisements in the storage. 3. The discovery service transmits the resulting advertisements to the peer. Use case terminates.
Use Case : Get a remote advertisement - Send a query message Context of Use : A peer looks for specific advertisements. Primary Actor : A peer Main Success Scenario : 1. A peer asks the discovery service to get advertisements specifying the type, an optional attribute/value element (criteria), a threshold (specifying the maximum number of advertisements transmitted by a single peer), an optional discovery listener (this listener will be notified when a response is received) and an optional destination peer ID. 2. The discovery service creates a Discovery Query Message specifying the parameters of the query. 3. The discovery service generates a unique ID for this query. 4. The discovery service registers the listener in relation with the query ID. 5. The discovery service creates a Resolver Query Message specifying as handler name the discovery service and adding the credential of the peer, the Discovery Query message and the query ID. 6. The peer is an edge peer. 7. The discovery service uses the resolver service and invokes send a resolver query message (page 84) specifying the eventual destination peer and including the Resolver Query message. Use case terminates. Extensions : 6a. The peer is a rendez-vous peer
77
APPENDIX A. JXTA USE CASES
78
6a.1. The discovery service searches for the key of the query in its own SRDI index. 6a.2. The SRDI index returns at least one response (a set of peers). 6a.3. The discovery service increments the Resolver Query Message hop count. 6a.4. The discovery service asks the SRDI service to forward a query (page 82) to all the peers included in the SRDI response. 6a.2a. The SRDI index finds nothing. 6a.2a.1. The discovery service asks the SRDI service to get a replica peer (page 81) specifying the key of the query as expression. 6a.2a.2. A replica peer is returned. 6a.2a.3. The discovery service increments the Resolver Query Message hop count. 6a.2a.4. The discovery service asks the SRDI service to forward a query (page 82) specifying the replica peer as destination peer. Use case terminates. 6a.2a.2a. No replica is returned. 6a.2a.2a.1. The discovery service used the resolver service and invokes send a resolver query message (page 84) without specifying a destination peer and including the Resolver Query Message. Use case terminates.
Use Case : Receive a discovery query message Context of Use : The resolver service received a message whose handler is the discovery service. Primary Actor : The resolver service Main Success Scenario : 1. The discovery service extracts the Discovery Query Message from the Resolver Query Message. 2. The query does not specify the ”peer advertisement” type or specifies a threshold different from 0. 3. The discovery service looks for an advertisement matching the criteria of the query in the storage. 4. The storage returns a result. 5. The discovery service creates a Discovery Response Message including the advertisements found in the storage. 6. The discovery service creates a Resolver Response Message containing the previous created message, the credential of the edge peer, the discovery service as handler name and the query ID. 7. The discovery service uses the resolver service and invokes send a resolver response message (page 85). Use case terminates. Extensions : 2a. The query specifies the ”peer advertisement” type and a threshold of 0. This is a special case which means that the peer has to provide its own advertisement. 2a.1. The discovery service creates a Discovery Response Message including the local peer advertisement.
A.1. DISCOVERY SERVICE
2a.2. The discovery service creates a Resolver Response Message containing the previous created message, the credential of the edge peer, the discovery service as handler name and the same query ID. 2a.3. The discovery service uses the resolver service and invokes send a resolver response message (page 85). Use case terminates. 4a. The storage does not find anything. 4a.1. The local peer is an edge peer. Use case terminates. 4a.1a. The local peer is a rendez-vous peer. 4a.1a.1. The discovery service searches the keys of the query in its own SRDI index. 4a.1a.2. The SRDI index returns at least one response (a set of peers). 4a.1a.3. The discovery service increments the hop count of the Resolver Query Message. 4a.1a.4. If the hopcount is smaller than 2, the discovery service increments the hopcount and asks the SRDI service to forward the query (page 82) to all the peers included in the SRDI Index response. Use case terminates. 4a.1a.2a. The SRDI index finds nothing. 4a.1a.2a.1. If the hopcount of the Resolver Query Message is 0, the discovery service asks the resolver service to propagate the resolver request (page 85) and the use case terminates. 4a.1a.2a.2. Otherwise, the discovery service asks the SRDI service to get a replica peer (page 81). 4a.1a.2a.3. A replica peer is returned. 4a.1a.2a.4. The discovery service asks the SRDI service to forward a query (page 82) specifying the replica peer as destination peer. Use case terminates. 4a.1a.2a.3a. No replica is returned. 4a.1a.2a.3a.1. The discovery service increments the hop count of the Discovery Query Message and asks the resolver service to propagate the resolver request (page 85). Use case terminates.
Use Case : Receive a discovery response message Context of Use : The resolver service received a Resolver Response Message and the discovery service is the handler. Primary Actor : The resolver service Main Success Scenario : 1. The discovery service extracts the Discovery Response Message from the Resolver Response Message. The step 2 is repeated for each advertisement contained in the Discovery Response Message 2. The discovery service publishes the advertisement (page 76). 3. The eventual listener related to the query ID is notified. Use case terminates.
79
APPENDIX A. JXTA USE CASES
80
Use Case : Process a SRDI resolver message (indexes) (only for rendez-vous peers) Context of Use : The resolver service receives a SRDI Resolver Message and the discovery service is the SRDI handler. Primary Actor : The resolver service Main Success Scenario : 1. The discovery service extracts the SRDI Entries Message from the Resolver SRDI Message. The step 2 is repeated for each entry contained in the SRDI Entries Message 2. The discovery service adds the entry to its SRDI Index. 3. The discovery service asks the SRDI service to replicate SRDI entries (page 82) from the SRDI Entries Message. Use case terminates. Use Case : Notify a failure Context of Use : An endpoint messenger failed to send a message to a destination peer. Primary Actor : The rendez-vous or the resolver service Main Success Scenario : 1. A messenger failed to send a message to a destination peer. 2. The discovery service asks the SRDI service to remove all the entries related to this peer from the SRDI index (page 82). Use case terminates. Use Case : Become a rendez-vous peer Context of Use : An edge peer became a rendez-vous peer using the rendez-vous service. Primary Actor : The rendez-vous service Main Success Scenario : 1. The thread (to push entries to a rendez-vous peer) in the SRDI service is stopped. 2. A new SRDI index is created. 3. The SRDI service is reinitialized. Use Case : Become an edge peer Context of Use : A rendez-vous peer became an edge peer using the rendez-vous service. Primary Actor : The rendez-vous service Main Success Scenario : 1. The SRDI index is removed. 2. The SRDI service is reinitialized. 3. The thread (to push entries to a rendez-vous peer) in the SRDI service is started.
A.2. SRDI SERVICE
A.2
SRDI Service
• Send a SRDI entries message (page 81) • Get a replica peer (page 81) • Forward a query (page 82) • Replicate SRDI entries (page 82) • Remove the entries associated with a peer (page 82)
Use Case : Send a SRDI entries message Context of Use : A service asks its private SRDI service to send a SRDI Entries message. Primary Actor : A service having an internal SRDI service Main Success Scenario : 1. The service transmits the SRDI Entries message to the SRDI service. 2. The SRDI service creates a SRDI Resolver Message specifying as handler name the service and containing the SRDI Entries message. 3. The SRDI service uses the resolver service and invokes send a SRDI message (page 83). Use case terminates.
Use Case : Get a replica peer Context of Use : A service wants to send a query using the properties of the loosely-consistent rendez-vous network. Primary Actor : A service Main Success Scenario : 1. The SRDI service receives an expression. 2. The SRDI service asks the rendez-vous service to get the local peer view (page 95). 3. The SRDI service creates a digest of the expression received using SHA1. 4. The SRDI service gets the replica peer related to the digest using the algorithm 8. 5. The SRDI service returns the replica peer. Use case terminates.
Algorithm 8 Peer View Hashing algorithm 1: digest ← SHA1(expression) 2: sizehashtable ← maximum value of a digest 3: sizepeerV iew ← size(local peer view) 4: pos ← f loor(digest ∗ sizepeerV iew /sizehashtable ) 5: return(localpeerview).elementAt(pos)
81
APPENDIX A. JXTA USE CASES
82
Use Case : Forward a query Context of Use : A Resolver Query Message must be transmitted to a set of peers. Primary Actor : A service Main Success Scenario : 1. The SRDI service receives a Resolver Query Message and a list of destination peers. 2. The Resolver Query Message hop count is less than 3. 3. The SRDI service uses the resolver service to send the resolver query message (page 84) to each destination peers of the list. Use case terminates. Extensions : 2a. The Resolver Query Message hop count is greater or equal than 3. 2a.1. The message is not forwarded. Use case terminates.
Use Case : Replicate SRDI entries Context of Use : A SRDI Entries Message has been received by a service. These entries must be replicated to other rendez-vous peers. Primary Actor : A service Main Success Scenario : 1. The SRDI service asks the rendez-vous service to get the local peer view (page 95). 2. The SRDI Entries Message time-to-live is greater than 0. The steps (3-5) are repeated for each entry contained in the SRDI Entries Message 3. The SRDI service gets a replica peer (page 81) related to this entry. 4. A replica peer is returned and is different from the local peer. 5. A new SRDI Entries Message is created specifying the replica peer and containing the entry (only one SRDI Entries Message is created for each different destination peer) The step 6 is repeated for each SRDI Entries Message generated at step 5. 6. The SRDI Service sends a SRDI entries message (page 81). Use case terminates. Extensions : 2a. The SRDI Entries Message time-to-live is 0. 2a.1. The entries are not replicated. Use case terminates. 4a. No replica peer is found or the replica peer is ourself. 4a.1. Use case continues at step 3 with the next entry.
Use Case : Remove the entries associated with a peer Context of Use : An edge peer failed or disconnected.
A.3. RESOLVER SERVICE
Primary Actor : The rendezvous service Main Success Scenario : 1. The SRDI service removes all entries from the SRDI index associated with this peer ID. Use case terminates.
A.3
Resolver Service
• Send a SRDI message (page 83) • Send a resolver query message (page 84) • Send a resolver response message (page 85) • Propagate a resolver query request (page 85) • Receive a SRDI resolver message (page 86) • Receive a resolver query message (page 86) • Receive a resolver response message (page 87)
Use Case : Send a SRDI message Context of Use : A SRDI message must be propagated to the network. Primary Actor : A SRDI Service Main Success Scenario : 1. A SRDI service asks the resolver service to send a SRDI Resolver Message optionally specifying a destination peer. 2. The resolver service creates an endpoint message. 3. The destination peer is defined. 4. The resolver service creates an endpoint address specifying the handler name (SRDI service) and the destination peer. 5. The resolver service looks for a messenger for this endpoint address in its local list of messengers. 6. A messenger is found. 7. The resolver service asks the messenger to send the message (page 102). 8. The resolver service is notified by the endpoint service when a message fails to be sent. In that case, the handlers are notified of this failure. If the handler is the discovery service, it is notified of this failure (page 80). Extensions : 3a. The destination peer is not defined. 3a.1. The peer is an edge peer. The resolver service asks the rendez-vous service to walk the message (page 97) with a time-to-live of 1 (just the time to reach the rendez-vous) and specifies the SRDI service as handler name. Use case terminates.
83
APPENDIX A. JXTA USE CASES
84
3a.1a. The peer is a rendez-vous peer. The resolver service asks the rendezvous service to walk the message (page 95) and specifies the SRDI service as handler name. Use case terminates. 6a. No messenger is found. 6a.1. The resolver service asks the endpoint service to get a messenger (page 101) for this destination address. 6a.2. Until the messenger is received (asynchronously), the message is kept in a sending queue. 6a.3. When the messenger is received, all the messages waiting in the queue are sent.
Use Case : Send a resolver query message Context of Use : A Resolver Query Message must be sent. Primary Actor : A service Main Success Scenario : 1. A service asks the resolver service to send a Resolver Query Message optionally specifying the destination peer. 2. The resolver service creates a new endpoint message. 3. The destination peer is defined. 4. The resolver service creates an endpoint address specifying the handler name and the destination peer. 5. The resolver service looks for a messenger for this endpoint address in its local list of messengers. 6. A messenger is found. 7. The resolver service asks the messenger to send the message (page 102). 8. The resolver service is notified by the endpoint service when a message fails to be sent. In that case, the handlers are notified of this failure. If the handler is the discovery service, it is notified of this failure (page 80). Extensions : 3a. The destination peer is not defined. 3a.1. The time-to-live is defined as 1 for an edge peer and as the size of the list returned by get the local peer view (page 95) for a rendez-vous peer. 3a.2. The resolver service asks the rendez-vous service to walk the message (page 95) with the time-to-live and the Resolver Query Message handler as handler name. Use case terminates. 6a. No messenger is found. 6a.1. The resolver service asks the endpoint service to get a messenger (page 101) for this destination address. 6a.2. Until the messenger is received (asynchronously), the message is kept in a sending queue. 6a.3. When the messenger is received, all the messages waiting to be sent in the queue are processed. The messenger is inserted in the local messengers list.
A.3. RESOLVER SERVICE
85
Use Case : Send a resolver response message Context of Use : A resolver message must be sent. Primary Actor : A service Main Success Scenario : 1. A service asks the resolver service to send a Resolver Response Message optionally specifying the destination peer. 2. The resolver service creates a new endpoint message. 3. The destination peer is defined. 4. The resolver service creates an endpoint address specifying the handler name and the destination peer. 5. The resolver service looks for a messenger for this endpoint address in its local list of messengers. 6. A messenger is found. 7. The resolver service asks the messenger to send the message (page 102). 8. The resolver service is notified by the endpoint service when a message fails to be sent. In that case, the handlers are notified of this failure. If the handler is the discovery service, it is notified of this failure (page 80). Extensions : 3a. The destination peer is not defined. 3a.1. The resolver service asks the rendez-vous service to walk the message (page 95) with a time-to-live of 1 and the Resolver Response Message handler as handler name. Use case terminates. 6a. No messenger is found. 6a.1. The resolver service asks the endpoint service to get a messenger (page 101) for this destination address. 6a.2. Until the messenger is received (asynchronously), the message is kept in a sending queue. 6a.3. When the messenger is received, all the messages waiting to be sent in the queue are processed. The messenger is inserted in the local messengers list.
Use Case : Propagate a resolver query request Context of Use : The resolver service must propagate a Resolver Query Message. Primary Actor : A service Main Success Scenario : 1. The resolver service is asked to propagate a Resolver Query Message. 2. The hop count of the message is not greater than 3. 3. The resolver service asks the rendez-vous service to get the local peer view (page 95). 4. The time-to-live is defined as the size of the peer view.
APPENDIX A. JXTA USE CASES
86
5. The resolver service asks the rendez-vous service to walk the message (page 95) with the time-to-live and the resolver service as handler name. Use case terminates. Extensions : 2a. The hop count of the message is greater than 3. 2a.1. The message is not propagated. Use case terminates.
Use Case : Receive a SRDI resolver message Context of Use : The resolver service receives a SRDI Resolver Message. Primary Actor : The resolver service Main Success Scenario : 1. The resolver service receives a SRDI Resolver Message. 2. The handler name is extracted from the SRDI Resolver Message. 3. The resolver service looks for this handler in the local map of SRDI handlers. 4. The handler is found. 5. The SRDI Resolver Message is sent to the SRDI handler. 6. The SRDI handler is the discovery service. 7. The discovery service (which is a SRDI handler) processes the SRDI resolver message (page 80). Extensions : 4a. The handler is not found. Use case terminates.
Use Case : Receive a resolver query message Context of Use : The resolver service receives a Resolver Query Message. Primary Actor : The resolver service Main Success Scenario : 1. 2. 3. 4. 5. 6. 7.
The resolver service receives a Resolver Query Message. The handler name is extracted from the Resolver Query Message. The resolver service looks for this handler in the local map of handlers. The handler is found. The Resolver Query Message is sent to the handler. The handler is the discovery service. The discovery service receives a discovery query message (page 78).
Extensions : 4a. The handler is not found. Use case terminates. 6a. The handler is the peer information service. 6a.1. The peer information service receives an information query message (page 92).
A.4. PIPE SERVICE
87
Use Case : Receive a resolver response message Context of Use : The resolver service receives a Resolver Response Message. Primary Actor : The rendez-vous service Main Success Scenario : 1. 2. 3. 4. 5. 6. 7.
The resolver service receives a Resolver Response Message. The handler name is extracted from the Resolver Response Message. The resolver service looks for this handler in the local map of handlers. The handler is found. The Resolver Response Message is sent to the handler. The handler is the discovery service. The discovery service receives a discovery query message (page 78).
Extensions : 4a. The handler is not found. Use case terminates. 6a. The handler is the peer information service. 6a.1. The peer information service receives an information response message (page 93).
A.4
Pipe Service
• Create an input pipe (page 87) • Create an output pipe (page 88) • Maintain pipes cache (page 89) • Receive a pipe binding query message (page 90) • Receive a pipe binding response message (page 90) • Reception of a message for a specific pipe (input pipe) (page 91) • Sending of a message to a specific pipe (output pipe) (page 91)
Use Case : Create an input pipe Context of Use : A peer wants to create an input pipe. Primary Actor : A peer Main Success Scenario : 1. The peer has an advertisement for the pipe. 2. The peer asks the pipe service to create an input pipe, according to the pipe advertisement and providing an optional listener. 3. The pipe service asks the endpoint service to register a listener for that pipe specifying as handler name the pipe service handler name and the pipe ID.
APPENDIX A. JXTA USE CASES
88
4. 5. 6. 7.
The pipe service adds the pipe in its local list of pipes. The listener is specified. The pipe service stores the listener in relation with the input pipe. The pipe service creates a SRDI Entries message containing as entry the new input pipe key and a time-to-live of 1. 8. The pipe service asks the SRDI service to send a SRDI entries message (page 81). Use case terminates.
Extensions : 1a. The peer has no advertisement. 1a.1. The peer creates a pipe advertisement. Use case continues at step 2. 5a. No listener is defined. 5a.1. A queue is created for this input pipe. Use case continues at step 7.
Use Case : Create an output pipe Context of Use : A peer wants to create an output pipe. Primary Actor : A peer Main Success Scenario : 1. The peer has an advertisement for the pipe. 2. The peer asks the pipe service to create an output pipe, according to the pipe advertisement, providing an optional listener and specifying a timeout for the pipe binding process. 3. The pipe service searches the pipe ID in its local pipe ID list (local pipe: input and output on the same peer) 4. The pipe service does not find any pipe in its local list. 5. The pipe service searches the pipe ID in the local cache of pipes (found in a previous looking process). 6. The pipe service does not find any pipe in its pipes cache. 7. The pipe service tries to find a remote pipe. 8. The pipe service creates a Pipe Binding Query Message specifying the pipe ID and the type of pipe. 9. The pipe service generates a unique ID for this query. 10. The pipe service creates a Resolver Query Message specifying as handler name the pipe service and adding the credential of the peer, the Pipe Binding Query Message and the query ID. 11. The pipe service queries the SRDI service to get the peers related to the key of this pipe (get a replica peer (page 81)). 12. No results are provided by the SRDI service. 13. The pipe service uses the resolver service and invokes send a resolver query message (page 84) including the Resolver Query message. Steps 14-15 are repeated as long as the timeout defined in 2 is not reached 14. The pipe service looks for the pipe in the local cache of pipes. If the pipe is found, the destination peer is now found. Use case continues at step 16. 15. The timeout is over. The binding failed. Use case terminates.
A.4. PIPE SERVICE
89
16. The pipe service asks the endpoint service to get a messenger (page 101) (synchronously) for the destination peer. 17. The messenger is stored in relation with the output pipe. Use case terminates. Extensions : 1a. The peer has no advertisement. 1a.1. The peer uses the discovery service to get a local advertisement (page 77) or to get a remote advertisement (page 77). Use case continues at step 2. 4a. The pipe service finds a corresponding input pipe in its local list and consequently a destination peer for the pipe. 4a.1. The pipe service asks the endpoint service to get a messenger (page 101) (synchronously) for the destination peer (in fact the local peer). 4a.2. The messenger (a loopback messenger) is stored in relation with the output pipe. Use case terminates. 6a. The pipe service finds a corresponding input pipe in its cache, and thus a destination peer for the pipe. 6a.1. The pipe service asks the endpoint service to get a messenger (page 101) (synchronously) for the destination peer. 6a.2. The messenger is stored in relation with the output pipe. Use case terminates. 12a. The SRDI index returns at least one response (a set of peers). 12a.1. The pipe service increments the hop count of the Resolver Query Message. 12a.2. The pipe service asks the SRDI service to forward a SRDI query (page 82) to all the peers included in the SRDI response. Use case continues at step 14.
Use Case : Maintain pipes cache Context of Use : Pipe entries have a defined lifetime and must be deleted when they expire. Primary Actor : A pipes cache manager Main Success Scenario : 1. The pipes cache manager periodically (by default every 10 minutes) checks all the pipes in the cache. Steps 2-3 are repeated for each pipe in the cache 2. The lifetime of the pipe is expired. 3. The pipe is removed from the cache. 4. Use case terminates. Extensions : 2a. The lifetime is not expired. Use case continues with the next pipe at step 2.
APPENDIX A. JXTA USE CASES
90
Use Case : Receive a pipe binding query message Context of Use : The pipe service of a peer wants to bind a pipe (find an input pipe) and thus sent a pipe binding request. Primary Actor : The resolver service Main Success Scenario : 1. The pipe service extracts the Pipe Binding Request Message from the Resolver Request Message. 2. The pipe service searches the pipe ID in its local pipe ID list. 3. The pipe service does not find any pipe in its local list. 4. The pipe service searches the pipe ID in the local cache of pipes (found in a previous looking process). 5. The pipe service does not find any pipe in its pipes cache. 6. The local peer is a rendez-vous peer. 7. The pipe service searches for the ID of the pipe (the key) in its own SRDI index. 8. The SRDI index returns at least one response (a set of peers). 9. The pipe service asks the SRDI service to forward a query (page 82) to all the peers included in the SRDI response. Extensions : 3a. The pipe service finds a corresponding input pipe in its local list and consequently an input pipe for the pipe. 3a.1. The pipe service creates a Pipe Binding Response Message containing the information of the input pipe. The pipe service creates a Resolver Response Message containing the previous created message, the credential of the local peer, the pipe service as handler name and the query ID. 3a.2. The pipe service uses the resolver service and invokes send a resolver response message (page 85). Use case terminates. 5a. The pipe service finds a corresponding input pipe in its cache, and thus an input pipe for the pipe. 5a.1. The pipe service creates a Pipe Binding Response Message containing the information of the input pipe. The pipe service creates a Resolver Response Message containing the previous created message, the credential of the local peer, the pipe service as handler name and the query ID. 5a.2. The pipe service uses the resolver service and invokes send a resolver response message (page 85). Use case terminates. 6a. The local peer is an edge peer. 6a.1. The pipe binding fails. Use case terminates. 8a. The SRDI index finds nothing. 8a.1. The pipe service asks the resolver service to propagate the resolver request (page 85) and the use case terminates.
Use Case : Receive a pipe binding response message Context of Use : The pipe service of a peer found the pipe and sent a pipe binding response.
A.5. PEER INFORMATION SERVICE
Primary Actor : The resolver service Main Success Scenario : 1. The pipe service extracts the Pipe Binding Response Message from the Resolver Response Message. 2. The pipe service inserts the pipe ID related to the binding (endpoint address) in the local cache of pipes.
Use Case : Reception of a message for a specific pipe Context of Use : The endpoint service receives a message whose handler is the pipe service and the pipe ID refers to a known input pipe. Primary Actor : The endpoint service Main Success Scenario : 1. A listener is associated with this pipe. 2. An event is generated containing the message. 3. The listener is notified of this event. Extensions : 1a. No listener is related to this pipe ID. 1a.1. The message is put in the queue. A method poll can then get the message from the queue of this input pipe.
Use Case : Sending of a message to a specific pipe Context of Use : A peer wants to send a message using an output pipe. Primary Actor : A peer Main Success Scenario : 1. The peer invokes the method send to the output pipe and includes the message to send. 2. The pipe service looks for the messenger associated with this output pipe. 3. The pipe service asks the messenger to send the message (page 102).
A.5
Peer Information Service
• Add a monitor to a remote peer (page 92) • Remove a monitor from a remote peer (page 92) • Receive an information query message (page 92) • Send information to monitoring listeners (page 93) • Receive an information response message (page 93)
91
APPENDIX A. JXTA USE CASES
92
Use Case : Add a monitor to a remote peer Context of Use : A peer wants to monitor a remote peer. Primary Actor : A peer Main Success Scenario : 1. A peer asks the peer information service to monitor a remote peer, specifying the remote peer ID, the rate of reports sending, a duration of the monitoring and a listener which will receive the reports. 2. The peer information service creates a unique query ID. 3. The peer information service creates a Peer Information Query Message specifying the elements enumerated in step 1 and adding the query ID. 4. The peer information service creates a Resolver Query Message specifying as handler name the peer information service and adding the credential of the peer, the Peer Information Query Message and the query ID. 5. The peer information service uses the resolver service to send the resolver query message (page 84) specifying the remote peer it wants to monitor as destination peer. Use case terminates.
Use Case : Remove a monitor from a remote peer Context of Use : A peer wants to stop monitoring a remote peer. Primary Actor : A peer Main Success Scenario : 1. A peer asks the peer information service to stop monitoring a remote peer, specifying the remote peer ID, the listener which receives actually the reports and a new timeout. 2. The peer information service creates a unique query ID. 3. The peer information service creates a Peer Information Query Message (the type of the Peer Information Query Message is specific for removing). 4. The peer information service creates a Resolver Query Message specifying as handler name the monitoring service and adding the credential of the peer, the Peer Information Query Message and the query ID. 5. The peer information service uses the resolver service to send the resolver query message (page 84) specifying the remote peer it wants to stop monitoring. Use case terminates.
Use Case : Receive an information query message Context of Use : The resolver service receives a message whose handler is the peer information service. Primary Actor : The resolver service Main Success Scenario :
A.5. PEER INFORMATION SERVICE
1. The peer information service extracts the Peer Information Query Message from the Resolver Query Message. 2. The type of Peer Information Query Message is not specific for removing a monitoring. 3. The monitoring is registered in the list of monitoring processes of the monitoring manager. Use case terminates. Extensions : 2a. The type of Peer Information Query Message is specific for removing a monitoring. 2a.1. The monitoring is removed from the list of monitoring processes of the monitoring manager. Use case terminates.
Use Case : Send information to monitoring listeners Context of Use : A monitored peer needs to send periodically information about its state and its connections. Primary Actor : A monitoring manager Main Success Scenario : 1. A monitoring manager generates reports according to the defined rate of reports for each monitoring process. 2. The monitoring manager asks the peer information service to send the report. 3. The peer information service creates a Peer Information Response Message. 4. The peer information service creates a Resolver Response Message specifying as handler name the peer information service and adding the credential of the local peer (the monitored peer), the report and the query ID. 5. The peer information service uses the resolver service to send the resolver response message (page 85) specifying the peer interested in the report as destination peer. Use case terminates.
Use Case : Receive an information response message Context of Use : The resolver service receives a message whose handler is the peer information service. Primary Actor : The resolver service Main Success Scenario : 1. The peer information service extracts the Peer Information Response Message from the Resolver Response Message. 2. The peer information service looks for a listener for this report in its own list of listeners. 3. The peer information service forwards the message to the listener. Use case terminates.
93
APPENDIX A. JXTA USE CASES
94
A.6 Rendez-vous Service • Maintain the rendez-vous peer view (page 94) • Get the local peer view (page 95) • Walk a message (edge peer) (page 97) • Walk a message (rendez-vous peer) (page 95) • Connect to a rendez-vous peer (edge peer) - Send a lease request (page 97) • Disconnect from a rendez-vous peer (edge peer) - Send a cancel lease request (page 98) • Receive a lease request message (rendez-vous peer) (page 98) • Receive a cancel lease message (rendez-vous peer) (page 99) • Receive a granted lease message (edge peer) (page 99) • Maintain the list of connected peers (rendez-vous peer) (page 100) • Become a rendez-vous peer (edge peer) (page 100) • Become an edge peer (rendez-vous peer) (page 100)
Use Case : Maintain the rendez-vous peer view Context of Use : Inside a rendez-vous peer, the rendez-vous peer view is maintained loosely-consistent with the peer views of the other rendez-vous peers. Primary Actor : Peer View main process Strategies : The peer view maintenance uses different strategies to select an element from a list of elements (peers or advertisements): Random strategy (S1) : one element is selected randomly and remains in the list Sequential strategy (S2) : the list is traversed sequentially: each new invocation selects the following element Main Success Scenario : 1. Seed process: as long as the peer view is empty (a peer view does not contain the local peer), the seed process does the following steps: • The rendez-vous service gets the seed rendez-vous addresses (these seed addresses are configured during JXTA initialization) and the advertisement of the local peer is sent to all these rendez-vous peers. The process of sending uses the endpoint service and the messenger mechanism. • The rendez-vous service uses the discovery service and the use case get a local advertisement specifying ”rendez-vous peers” as the criteria. Then, the advertisement of the local peer is sent to all of these rendez-vous peers.
A.6. RENDEZ-VOUS SERVICE • The rendez-vous service asks the endpoint service to multicast the local peer advertisement using a multicast message transport (TCP multicast) if it is activated. • The rendez-vous service sends the local peer advertisement using the wire output pipe specified in the peer group. Steps 2-5 are individually repeatable and can occur in any order 2. Recipient refresh process: periodically (by default every 15 minutes) a rendez-vous advertisement from the peer view is selected using the strategy S1 and a rendez-vous peer is selected from the peer view using also the strategy S1. The selected advertisement is sent to the selected rendez-vous peer: • The rendez-vous service looks for a messenger in its local messenger map for the rendez-vous peer. • A messenger is found. The rendez-vous service asks the messenger to send the message (page 102). • No messenger is found. The rendez-vous service asks the endpoint service to get a messenger (page 101) for this destination address. Until the messenger is received (asynchronously), the message is kept in a sending queue. When the messenger is received, all the messages waiting to be sent in the queue are processed. The messenger is inserted in the local messenger map. • The resolver service is notified by the endpoint service when a message fails to be sent. In that case, the peer view is notified of this failure. 3. Own advertisement process: periodically (by default every 15 minutes), the advertisement of the local rendez-vous peer is sent to a rendez-vous peer selected from the list using the strategy S2. The process of sending is the same as the one described in step 1. 4. Incoming Message: if the originator of the message is a rendez-vous peer. Its advertisement is added to the peer view. 5. Failure notification by the endpoint service: the peer view is updated according to the event. The other rendez-vous peers are notified using the wire output pipe connected to all other peers. If the list becomes empty, the seed process starts again. The use case continues at step 1.
Use Case : Get the local peer view Context of Use : A service needs the current rendez-vous peer view. Primary Actor : A service Main Success Scenario : 1. A service on a rendez-vous peer needs the rendez-vous peer view in a routing process. 2. The rendez-vous service gets the local rendez-vous peer view. 3. The rendez-vous service returns the peer view. Use case terminates.
Use Case : Walk a message (rendez-vous peer)
95
APPENDIX A. JXTA USE CASES
96
Context of Use : A rendez-vous peer has to walk a message. Primary Actor : A service Main Success Scenario : 1. A rendez-vous peer has to walk a message to an optional list of destination peers using a specified handler name. 2. The list is empty. 3. The direction is up or both up and down (if it has not yet been set, both is the default value). 4. The rendez-vous service gets the rendez-vous peer situated after the local peer (up peer) in the peer view. 5. The up peer is not null. 6. The rendez-vous service creates a Limited Range Rendezvous Message. 7. The rendez-vous service specifies the direction up to the Limited Range Rendezvous Message. 8. The rendez-vous service looks for a messenger in its local messenger map for the up peer destination. 9. A messenger is found. 10. The rendez-vous service asks the messenger to send the message (page 102). 11. The direction is down or both up and down. 12. The rendez-vous service gets the rendez-vous peer situated before the local peer (down peer) in the peer view. 13. The down peer is not null. 14. The rendez-vous service creates a Limited Range Rendezvous Message. 15. The rendez-vous service specifies the direction down to the Limited Range Rendezvous Message. 16. The rendez-vous service looks for a messenger in its local messenger map for the down peer destination. 17. A messenger is found. 18. The rendez-vous service asks the messenger to send the message (page 102). Use case terminates. Extensions : 2a. The list contains destination peers. Steps 2a.1. to 2a.3. are repeated for each destination peer of the list 2a.1. The rendez-vous service looks for a messenger in its local messenger map for the destination peer. 2a.2. A messenger is found. 2a.3. The rendez-vous service asks the messenger to send the message (page 102). Use case terminates. 2a.2a. No messenger is found. 2a.2a.1. The resolver service asks the endpoint service to get a messenger (page 101) (synchronously) for the destination peer. 2a.2a.2. If a messenger is returned, the rendez-vous service asks the messenger to send the message (page 102). Otherwise, the peer view is notified of the failure (maintain peer view on page 94) and the destination peer is removed from the peer view. The next destination peer is processed. Use case continues at step 2a.1.
A.6. RENDEZ-VOUS SERVICE
3a. The direction is down. Use case continues at step 11. 5a. The up peer is null. 5a.1. The message is not sent in the up direction. Use case continues at step 11. 9a. No messenger is found. 9a.1. The resolver service asks the endpoint service to get a messenger (page 101) (synchronously) for the up peer. 9a.2. If a messenger is returned, the rendez-vous service asks the messenger to send the message (page 102). Otherwise, the peer view is notified of the failure (maintain peer view on page 94) and the up peer is removed from the peer view. Use case continues at step 11. 11a. The direction is up. Use case terminates. 13a. The down peer is null. 13a.1. The message is not sent down. Use case terminates. 17a. No messenger is found. 17a.1. The resolver service asks the endpoint service to get a messenger (page 101) (synchronously) for the down peer. 17a.2. If a messenger is returned, the rendez-vous service asks the messenger to send the message (page 102). Otherwise, the peer view is notified of the failure (maintain peer view on page 94) and the down peer is removed from the peer view. Use case terminates.
Use Case : Walk a message (edge peer) Context of Use : An edge peer has to walk an endpoint message. Primary Actor : A service Main Success Scenario : 1. An edge peer has to walk a message. 2. The rendez-vous service sends the message to the rendez-vous to which the edge peer is connected: the rendez-vous service asks the endpoint service to get a messenger (page 101) for the rendez-vous peer and then to send the message (page 102) including the endpoint message to send and the rendez-vous service as handler. 3. The rendez-vous service asks the endpoint service to propagate the message to the network: this step is only executed if a multicast endpoint transport (TCP multicast) is available.
Use Case : Connect to a rendez-vous peer Context of Use : An edge peer wants to connect to a rendez-vous peer. Primary Actor : An edge peer Main Success Scenario : 1. The edge peer has the rendez-vous advertisement or the address of the rendez-vous on a specific message transport (TCP, HTTP, . . . ). Thus, the endpoint address of the rendez-vous peer is known. 2. The edge peer asks the rendez-vous service to connect to the rendezvous peer specified by the endpoint address.
97
APPENDIX A. JXTA USE CASES
98
3. The rendez-vous service creates a Lease Request Message containing the advertisement of the edge peer. 4. The rendez-vous service creates an endpoint message specifying the rendez-vous service as handler name and including the Lease Request Message. 5. The rendez-vous service asks the endpoint service to get a messenger (page 101) (synchronously) for the rendez-vous peer endpoint. 6. If a messenger is returned, the rendez-vous service asks the messenger to send the message (page 102). Otherwise, the rendez-vous peer is not reachable. Use case terminates. Extensions : 1a. The edge peer does not have the rendez-vous advertisement. 1a.1. The edge peer uses the discovery service to get a remote advertisement (page 77). 1a.2. The edge peer can now connect to the rendez-vous peer. Use case continues at step 2.
Use Case : Disconnect from a rendez-vous peer Context of Use : An edge peer wants to disconnect from a rendez-vous peer. Primary Actor : An edge peer Main Success Scenario : 1. The edge peer asks the rendez-vous service to disconnect from a rendezvous. 2. The rendez-vous service creates a Lease Cancel Message. 3. The rendez-vous service creates an endpoint message specifying the rendez-vous service as handler name and including the Lease Cancel Message. 4. The rendez-vous service asks the endpoint service to get a messenger (page 101) (synchronously) for the rendez-vous peer. 5. If a messenger is returned, the rendez-vous service asks the messenger to send the message (page 102). Otherwise, the edge peer can either try again after a moment or become unreachable for the rendezvous peer after a period of time. Use case terminates.
Use Case : Receive a lease request message Context of Use : An edge peer sent a Lease Request Message to connect to a rendez-vous peer. Primary Actor : An edge peer Main Success Scenario : 1. The endpoint service received a generic message and the rendez-vous service is the handler. 2. The rendez-vous service extracts the Lease Request Message from the endpoint message.
A.6. RENDEZ-VOUS SERVICE
99
3. The rendez-vous service defines a lease period for this peer (by default 20 minutes). 4. The rendez-vous service asks the discovery service to publish the advertisement (page 76) of the peer. 5. The rendez-vous service creates a Lease Granted Message containing the lease period. 6. The rendez-vous service asks the endpoint service to get a messenger (page 101) (synchronously) for the edge peer. 7. A messenger is returned. 8. The rendez-vous service asks the messenger to send the message (page 102). 9. The edge peer is added to the list of edge peers connected to the rendezvous peer. Use case terminates. Extensions : 7a. No messenger is returned. 7a.1. The message is not sent. Use case terminates.
Use Case : Receive a cancel lease message Context of Use : An edge peer sent a Lease Cancel Message to disconnect from a rendez-vous peer. Primary Actor : An edge peer Main Success Scenario : 1. The endpoint service received an endpoint message and the rendezvous service is the handler. 2. The rendez-vous service extracts the Lease Cancel Message from the endpoint message. 3. The client is removed from the list of edge peers connected to the rendez-vous peer. 4. The rendez-vous service notifies all the srdi services to remove the entries associated with this peer (page 82 in particular for the discovery service). Use case terminates.
Use Case : Receive a granted lease message Context of Use : A rendez-vous peer accepted a connection request and replies to the edge peer. Primary Actor : A rendez-vous peer Main Success Scenario : 1. The endpoint service of the edge peer received an endpoint message and the rendez-vous service is the handler. 2. The rendez-vous service extracts the Lease Granted Message from the generic message. 3. The rendez-vous service asks the discovery service to publish the advertisement (page 76) of the rendez-vous peer. 4. The rendez-vous peer is stored as the connected rendez-vous.
APPENDIX A. JXTA USE CASES
100
Use Case : Maintain the list of connected peers Context of Use : The leases granted to the connected edge peers are limited in time. Primary Actor : A connections manager Main Success Scenario : 1. Periodically, the connections manager (by default every 2 minutes) checks the lease of each connected edge peer. Steps 2-4 are repeated for each edge peer connected to the rendez-vous peer. 2. The lease is no more valid. 3. The edge peer is removed from the list. 4. The rendez-vous service notifies all the SRDI services to remove the entries associated with this peer (page 82 in particular for the discovery service). Use case terminates. Extensions : 2a. The lease is still valid. 2a.1. Use case continues with the next edge peer at step 2.
Use Case : Become a rendez-vous peer Context of Use : An edge peer wants or has to become a rendez-vous peer. Primary Actor : An edge peer Main Success Scenario : 1. The rendez-vous service disconnects from the rendez-vous peer (page 98). 2. The rendez-vous service creates an empty list of clients. 3. The rendez-vous service starts the connections manager. 4. The rendez-vous service creates a peer view and starts the peer view maintenance (page 94). 5. The edge peer is now a rendez-vous peer. 6. The rendez-vous service informs the discovery service that the peer is now a rendez-vous peer (page 80). Use case terminates.
Use Case : Become an edge peer Context of Use : A rendez-vous peer wants to become an edge peer. Primary Actor : A rendez-vous peer Main Success Scenario : Steps 1-4 are repeated for each connected edge peer 1. The rendez-vous service asks the endpoint service to get a messenger (page 101) (synchronously) for the edge peer. 2. A messenger is returned. 3. The rendez-vous service creates a message containing a specific disconnected request element.
A.7. ENDPOINT SERVICE
4. The rendez-vous service asks the messenger to send the message (page 102). 5. The rendez-vous service stops the connections manager. 6. The rendez-vous service stops the peer view maintenance and notifies the other rendez-vous peers using the wire output pipe connected to all other rendez-vous peers. 7. The rendez-vous peer is now an edge peer. 8. The rendez-vous service informs the discovery service that the peer is now an edge peer (page 80). Use case terminates. Extensions : 2a. No messenger is returned. 2a.1. The edge peer will not be informed. Use case continues at step 1 with the next connected edge peer.
A.7
Endpoint Service
• Get a messenger - synchronously or asynchronously (page 101) • Send a message (page 102) • Receive a route query message (page 103) • Receive a route response message (page 104)
Use Case : Get a messenger Context of Use : A service needs a messenger to send a message to a specific endpoint. Primary Actor : A service Main Success Scenario : 1. A service asks the endpoint service to get a messenger for a specified endpoint address (which includes the protocol to use, the service name and the service parameter). 2. The invocation is done asynchronously using a listener. 3. The invocation is inserted in a queue of messenger requests which are processed by a specific process. 4. The messenger request is extracted from the queue by the process. 5. The endpoint service looks for a message transport corresponding to the protocol specified in the endpoint address. 6. A message transport is found. 7. The protocol is jxta://. 8. The message transport will be the endpoint router. 9. The endpoint service returns a virtual messenger which stores the destination endpoint address. Extensions :
101
APPENDIX A. JXTA USE CASES
102
2a. The invocation is done synchronously. 2a.1. The messenger is created immediately. Use case continues at step 5. 6a. No message transport is found. 6a.1. The endpoint service asks the parent endpoint service to find a message transport. If it is found, a cross-group messenger is returned otherwise a failure is sent. 7a. The protocol is tcp:// 7a.1. The message transport will be the TCP Message Transport. Use case continues at step 9. 7b. The protocol is http:// 7b.1. The message transport will be the HTTP Message Transport. Use case continues at step 9. 7c. The protocol is jxtatls:// 7c.1. The message transport will be the TLS Message Transport. Use case continues at step 9. 7d. The protocol is relay:// 7d.1. The message transport will be the Relay Message Transport. Use case continues at step 9.
Use Case : Send a message Context of Use : A service uses a messenger (or a virtual messenger) to send a message. Primary Actor : A service Main Success Scenario : 1. A service asks a messenger to send a message. 2. The messenger asks the endpoint service and more specifically the messenger pool to get a real messenger for the endpoint address. 3. The messenger pool looks for a message transport corresponding to the protocol specified in the endpoint address. 4. The messenger pool asks the message transport to get a messenger for the endpoint address. 5. The message transport is the endpoint router. 6. The endpoint address is not the local peer. 7. The endpoint router creates an endpoint router messenger. 8. The messenger pool asks the messenger to send the query. 9. The messenger asks the endpoint router to find a route to reach the destination peer. 10. The endpoint router asks the discovery service to get a local advertisement (page 77) concerning a route advertisement to the destination peer. 11. No route advertisement is found. 12. The endpoint router creates a Route Query Message specifying the destination address. 13. The endpoint router creates a Resolver Query Message including the Route Query Message, the credential of the local peer, and a new generated query ID. 14. The local peer is a rendez-vous peer.
A.7. ENDPOINT SERVICE
15. The endpoint router searches for a route to reach this destination peer in its own SRDI index. 16. The SRDI index returns at least one response (a set of peers). 17. The endpoint router increments the hop count of the Resolver Query Message. 18. The endpoint router asks the SRDI service to forward the query (page 82) to all the peers included in the SRDI response. 19. The endpoint router waits at most during 15 seconds for the reception of a new route advertisement. 20. The messenger is used to send the message. Use case continues at step 5. Extensions : 5a. The message transport is the TCP Message Transport. 5a.1. The messenger is asked to send the message. Use case terminates. 5b. The message transport is the HTTP Message Transport. 5b.1. The messenger is asked to send the message. Use case terminates. 5c. The message transport is the TLS Message Transport. 5c.1. The messenger is asked to send the message. Use case terminates. 5d. The message transport is the Relay Message Transport. 5d.1. The messenger is asked to send the message. Use case terminates. 6a. The endpoint address is the local peer. 6a.1. A loopback messenger is returned. The loopback messenger is asked to send the message (locally delivered). Use case terminates. 11a. A route advertisement is found. 11a.1. The messenger asks the endpoint service to send on local route, specifying the route. Use case terminates. 14a. The local peer is an edge peer. 14a.1. The edge peer asks the resolver service to send a resolver query message (page 84) specifying the rendez-vous peer to which it is connected as destination peer. Use case terminates. 16a. The SRDI index did not return anything. 16a.1. The endpoint router asks the SRDI service to get a replica peer (page 81) specifying the destination peer as key for the query. 16a.2. A replica peer is returned. 16a.3. The endpoint router asks the SRDI service to forward a query (page 82) specifying the replica peer as destination peer. 16a.2a. No replica is returned. 16a.2a.1. No route is searched.
Use Case : Receive a route query message Context of Use : The resolver service received a Resolver Query Message and the endpoint router is the handler for this message. Primary Actor : The resolver service Main Success Scenario : 1. The endpoint router extracts the Route Query Message from the Resolver Query Message.
103
APPENDIX A. JXTA USE CASES
104
2. The endpoint router extracts the destination peer ID from the Route Query Message. 3. The endpoint router searches a route for this destination peer in its local cache. 4. The endpoint router finds a route. 5. The endpoint router creates a Route Response Message including the route found and the local peer. 6. The endpoint router creates a Resolver Response Message containing the Route Response Message, the credential of the local peer, the endpoint router as handler name and the query ID of the Resolver Query Message received. 7. The endpoint router uses the resolver service and invokes send a resolver response message (page 85). Use case terminates. Extensions : 4a. The endpoint router does not find a route. 4a.1. The Resolver Query Message hop count is smaller than 2. 4a.2. The endpoint router searches for the destination peer ID (key) in its own SRDI index. 4a.3. The SRDI index returns at least one response (a set of peers). 4a.4. The endpoint router increments the hop count of the Resolver Query Message. 4a.5. The endpoint router asks the SRDI service to forward a query (page 82) to all the peers included in the SRDI response. Use case terminates. 4a.1a. The Resolver Query Message hop count is greater or equal than 2. 4a.1a.1. The Resolver Query Message is not forwarded. Use case terminates. 4a.3a. The SRDI index finds nothing. 4a.3a.1. The endpoint router asks the resolver service to propagate the resolver request (page 85) and the use case terminates.
Use Case : Receive a route response message Context of Use : The resolver service received a Resolver Response Message and the endpoint router is the handler for this message. Primary Actor : The resolver service Main Success Scenario : 1. The endpoint router extracts the Route Response Message from the Resolver Response Message. 2. The endpoint router creates a Route Advertisement containing the destination peer, the source peer and the sequence of hops to route a message from the source to the destination. 3. The Route Advertisement is inserted in the local routes cache. 4. The endpoint router asks the discovery service to publish the advertisement (page 76) of the route.
Appendix B
JXTA Shell
105
APPENDIX B. JXTA SHELL
106
B.1 Overview The JXTA Shell is an application which enables users to interact with the JXTA platform through a command-line interpreter. The initial set of commands can be extended with new commands without modifying the shell framework, using a dynamic loading.
B.2 Main Commands The Shell provides environment variables that binds symbolic names to JXTA resources. The main commands of the JXTA Shell (version 2.1.1) are the following: Documents and Advertisements Commands get retrieves a tag body from a message identified by a unique tag name. put inserts a document into the body of a message. A message tag name specifies where the document will be stored in the message. mkadv creates an advertisement from a resource referred by a shell environment variable. info displays information about an advertisement: life time and expiration. This command uses the discovery service to get these information. Publishing, Discovery and Search Commands peers is used to discover other peers within a peer group or at a specified peer location. Running peers command with no options lists only the peers already known by the peer (cached). The -r option is used to send a request to find new peers. peers command stores results in the local cache and creates environment variables referring to them using the following naming: peerX where X is a growing integer number. Options allow to specify a pair of attribute and value to limit the discovery to specific advertisements. Values can use wild cards. This command invokes: • if -r flag is set or a peer location is specified: the discovery service and the use case get a remote advertisement without specifying a discovery listener • otherwise: the discovery service and the use case get a local advertisement. groups is used to discover peer groups by propagation or at a specified peer location. Without an option, groups lists all the peer groups cached by the local peer. The -r option is used to send a propagate request to find new peer groups. groups stores results in the local cache and creates environment variables referring to them using the following naming: groupX where X is a growing integer number. Options allow to specify a pair of attribute and value to limit the discovery to matching advertisements. Values can use wild cards.
B.2. MAIN COMMANDS
107
The process of discovery groups is the same as the process of discovery peers: use cases get a remote advertisement and get a local advertisement of the discovery service are used. search looks for advertisements within a peer group or at a specified peer location. Running search command without any option lists only the advertisements already known by the peer (cached). The -r option is used to send a propagate request to find new advertisements. search stores results in the local cache and creates references to the advertisement(s) with new environment variables, using this default naming: advX where X is a growing integer number. Options allow to specify a pair of attribute and value to limit the discovery to specific advertisements. Values can use wild cards. The process of discovery of other advertisements (no peers or groups advertisements) is the same as the process of discovery peers and groups: use cases get a remote advertisement and get a local advertisement of the discovery service. share publishes an advertisement (not a peer or a group) document in the current peer group. This command uses the discovery service and the use case publish an advertisement. flush flushes an advertisement from the cache. publish publishes an advertisement (a peer, a group or an other advertisement) into local cache. This command uses the discovery service and the use case publish an advertisement. Groups Management Commands newpgrp creates a new peer group advertisement with a random group id and a name. The services proposed by the new peer group are by default the same as the current peer group. This command creates an advertisement and then uses the discovery service and the use case publish an advertisement. login authenticates a peer with the peer group’s membership service. login prompts for a user name and password. If the user name and the password are accepted as being the same as the JXTA platform’s principal user, then a Shell instance is created and the provided arguments are passed to it. login command uses the membership service and its joining process. When the joining is accepted, operations can be executed in this secure environment. join is used to join a peergroup that was created via newpgrp command or using an advertisement that was previously discovered. If no argument is specified, join lists all the existing groups and their status (joined or unjoined). After the join to a peer group, the PG@group name environment variable is updated.
APPENDIX B. JXTA SHELL
108
To join a peer group, a peer can be asked to provide identity information, according to the membership restrictions defined for the peer group. The peer can choose to become a rendezvous for this group. The join command uses the rendezvous service of the group we want to join to invoke become a rendezvous peer or become an edge peer. If an authentication is required, the login command is executed. leave is used to leave a group previously joined via a join or login command. chpgrp is used to modify the default Shell peer group stdgroup environment value. Rendezvous and Relays Management Commands rdv command provides operations allowing to directly interact with the rendez-vous service. A simple indexing service can be used to test the rendez-vous service. This command is modified by the following options: -rpv is used to display the rendezvous peer view. It uses the rendezvous service and the use case get the local peer view -start registers a small indexing application to the rendezvous service by specifying a handler name. When a message is received: • if the index is found, it is forwarded to the originator of the query using the endpoint service and the use cases get a messenger and send a message • otherwise, the rendez-vous service is used with the use case walk a message -stop removes this application from the rendezvous service handlers. -search searches for entries. -add entry adds entry to our own list. -remove entry removes entry from our own list. -list displays all entries from our own list. -test entry tries to find entry in our list. -rdv asks the rendezvous service to become a rendezvous peer. -edge asks the rendezvous service to become an edge peer. rdvstatus shows the rendez-vous peers to which a peer is connected using the rendezvous service. relaystatus displays information about the existing relay connections using the endpoint service and more specifically the relay message transport. Pipes Commands newpipe creates a new pipe advertisement with a random pipe ID and a specified type. mkpipe creates an input pipe or an output pipe from a given pipe advertisement document. This command uses the pipe service and the use cases create an input pipe and create an output pipe.
B.2. MAIN COMMANDS
109
mkmsg creates a message used for sending through a pipe. send sends a message into a pipe. This command uses the pipe service and the use case sending of a message. recv receives a message from an input pipe. A timeout can be given. If no timeout is given, the call will block until a message is received. A timeout of zero corresponds to a non-blocking call. When the pipe service receives a message using the reception of a message use case, the message is bound to an environment variable. Peer Information Commands peerinfo is used to get monitoring information about this peer or remote peers in the same group. This command uses the peer information service and the use case add a monitor to a remote peer to get the remote information. It creates a listener, waits for the response and displays the information received. Transports and Routes Commands route displays information about the routes to reach peers. This command uses the endpoint service to get all message transports and find the endpoint router. The endpoint router can return all known routes. transports displays information about the available message transports in the current peer group. This command uses the endpoint service.
110
APPENDIX B. JXTA SHELL
Appendix C
Plugin Java Sources
111
APPENDIX C. PLUGIN JAVA SOURCES
112
C.1 DHTInterface
package j x t a d h t ; / ∗ ∗ The i n t e r f a c e u s e d by t h e JXTA f r a m e w o r k t o c o m m u n i c a t e w i t h t h e DHT ∗ @author N i c o l a s T h e o d o l o z ∗/ public interface DHTInterface extends JXTAInterface { / ∗ ∗ Used by JXTA t o s e n d a m e s s a g e t o a p e e r r e l a t e d t o an e x p r e s s i o n . ∗ The i n v o c a t i o n o f t h i s method s h o u l d p r o v i d e a p e e r w h i c h i s c l o s e t o ∗ t h e e x p r e s s i o n a c c o r d i n g t o t h e DHT n e t w o r k p r o p e r t i e s . ∗ @param e x p r e s s i o n i s a n y t h i n g we want t o a c c e s s i n t h e n e t w o r k ∗ @return t h e c l o s e s t peer t o t h e e x p r e s s i o n ∗/ p u b l i c n e t . j x t a . p e e r . PeerID lookup ( S t r i n g e x p r e s s i o n ) ; / ∗ ∗ N o t i f y a s t a t e m o d i f i c a t i o n o f a p e e r : add , remove , f a i l . ∗ E l e m e n t s o f t h e JXTA f r a m e w o r k can be n o t i f i e d . ∗ @param e v e n t i s t h e e v e n t c o n t a i n i n g t h e c o n c e r n e d p e e r and t h e t y p e o f e v e n t ∗/ p u b l i c v o i d n o t i f y ( j x t a d h t . DHTEvent e v e n t ) ; / ∗ ∗ Computes t h e r a n g e o f k e y s t h e l o c a l node i s c u r r e n t l y r e s p o n s i b l e ∗ @param min w i l l c o n t a i n t h e l o w e r bound ∗ @param max w i l l c o n t a i n t h e u p p e r bound ∗/ p u b l i c v o i d r a n g e ( I n t e g e r min , I n t e g e r max ) ; / ∗ ∗ R e t u r n s an o r d e r e d a r r a y o f n o d e s on w h i c h r e p l i c a s o f t h e k e y can be s t o r e d . ∗ @param k e y i s t h e e l e m e n t w h i c h n e e d s t o be r e p l i c a t e d ∗ @param max d e f i n e s t h e r e p l i c a t i o n f a c t o r : t h e number o f p e e r s r e t u r n e d ∗ @ r e t u r n t h e p e e r s where t h e k e y m u s t be r e p l i c a t e d ∗/ p u b l i c n e t . j x t a . p e e r . P e e r I D [ ] r e p l i c a S e t ( S t r i n g key , i n t max ) ; / ∗ ∗ JXTA f r a m e w o r k t r a n s m i s s i o n o f s e e d i n g p e e r s a d d r e s s e s . ∗ T h i s method t r i e s t o f e t c h t h e JXTA IDs o f t h e s e p e e r s and ∗ n o t i f y t h e DHT . ∗ @param s e e d P e e r s a r e t h e p h y s i c a l a d d r e s s e s o f t h e p e e r s ∗/ public void seedPeers ( S t r i n g [ ] seedPeers ) ; / ∗ ∗ I n v o k e d when a r e n d e z−v o u s p e e r becomes an e d g e p e e r . ∗ The DHT can s t o p and i n f o r m t h e o t h e r p e e r s . ∗/ p u b l i c void becomeEdgePeer ( ) ; }
C.2. JXTAINTERFACE
C.2
113
JXTAInterface
package j x t a d h t ; / ∗ ∗ The i n t e r f a c e p r o v i d e d t o t h e DHT i n o r d e r t o c o m m u n i c a t e w i t h t h e JXTA f r a m e w o r k ∗ @author N i c o l a s T h e o d o l o z ∗/ public interface JXTAInterface extends net . j x t a . endpoint . EndpointListener { / / u s e d t o r e g i s t e r t h e DHT c o m p o n e n t t o t h e e n d p o i n t s e r v i c e p u b l i c s t a t i c f i n a l S t r i n g SVCNAME = "JXTADHT" ; p u b l i c s t a t i c f i n a l S t r i n g SVCPARAM = "" ; / / s p e c i f y a t a g f o r m e s s a g e s s p e c i f i c t o t h e DHT p u b l i c s t a t i c f i n a l S t r i n g SVCMSGNAME = "JXTADHT" ; / ∗ ∗ P r o c e s s a m e s s a g e r e c e i v e d by t h e JXTA f r a m e w o r k d e s t i n e d t o t h e ∗ @param m e s s a g e i s t h e m e s s a g e r e c e i v e d by JXTA ∗ @param s r c A d d r i s t h e JXTA e n d p o i n t a d d r e s s o f t h e s e n d e r ∗ @param d s t A d d r i s t h e JXTA e n d p o i n t a d d r e s s o f t h e d e s t i n a t i o n ∗/ p u b l i c v o i d p r o c e s s I n c o m i n g M e s s a g e ( n e t . j x t a . e n d p o i n t . Message message net . j x t a . endpoint . EndpointAddress net . j x t a . endpoint . EndpointAddress
DHT .
, srcAddr , dstAddr ) ;
/ ∗ ∗ Send a m e s s a g e u s i n g t h e JXTA E n d p o i n t S e r v i c e . ∗ @param d e s t i s t h e d e s t i n a t i o n p e e r f o r t h e m e s s a g e . ∗ @param msg i s t h e m e s s a g e t o s e n d ∗ @ r e t u r n b o o l e a n i n d i c a t i n g t h e s u c c e s s o f t h e m e s s a g e s e n d i n g o r an I O E x c e p t i o n ∗/ p u b l i c b o o l e a n s e n d ( n e t . j x t a . p e e r . P e e r I D d e s t , j x t a d h t . Message msg ) throws j a v a . i o . I O E x c e p t i o n ; }
APPENDIX C. PLUGIN JAVA SOURCES
114
C.3 JXTAAdaptor package j x t a d h t ; / ∗ ∗ An a d a p t o r b e t w e e n DHT r e q u e s t s and t h e e f f e c t s t o t h e JXTA f r a m e w o r k . ∗ @author N i c o l a s T h e o d o l o z ∗/ p u b l i c a b s t r a c t c l a s s JXTAAdaptor i m p l e m e n t s J X T A I n t e r f a c e { / / A r e f e r e n c e t o t h e Rendez−v o u s S e r v i c e protected net . j x t a . impl . rendezvous . RendezVousServiceImpl rendezvous ; / / A reference to the Endpoint Service protected net . j xt a . endpoint . EndpointService endpoint ; / / The JXTA ID o f t h e l o c a l node p r o t e c t e d n e t . j x t a . p e e r . PeerID localNodeID = n u l l ; / / A s p e c i f i c tag used in messages for the seeding process p r o t e c t e d s t a t i c f i n a l S t r i n g FETCH ADV TAG = "Fetch_Adv" ; / ∗ ∗ C o n s t r u c t t h e a d a p t o r by s p e c i f y i n g some r e f e r e n c e s t o t h e JXTA s e r v i c e s . ∗ @param r e n d e z v o u s i s a r e f e r e n c e t o t h e Rendez−v o u s S e r v i c e ∗ @param e n d p o i n t i s a r e f e r e n c e t o t h e E n d p o i n t S e r v i c e ∗ @param l o c a l N o d e I D i s t h e JXTA ID o f t h e l o c a l p e e r ∗/ p u b l i c JXTAAdaptor ( n e t . j x t a . i m p l . r e n d e z v o u s . R e n d e z V o u s S e r v i c e I m p l r e n d e z v o u s , net . jx t a . endpoint . EndpointService endpoint , n e t . j x t a . p e e r . P e e r I D l o c a l N o d e I D ){ this . rendezvous = rendezvous ; this . endpoint = endpoint ; t h i s . localNodeID = localNodeID ; } /∗∗ ∗ { @ i n h e r i t D o c} ∗/ p u b l i c f i n a l v o i d p r o c e s s I n c o m i n g M e s s a g e ( n e t . j x t a . e n d p o i n t . Message message , n e t . j x t a . e n d p o i n t . EndpointAddre ss srcAddr , n e t . j x t a . e n d p o i n t . E n d p o i n t A d d r e s s d s t A d d r ){ n e t . j x t a . e n d p o i n t . M e s s a g e E l e m e n t me = m e s s a g e . g e t M e s s a g e E l e m e n t ( "jxta" , FETCH ADV TAG ) ; i f ( me ! = n u l l ){ System . o u t . p r i n t l n ( me . t o S t r i n g ( ) ) ; S t r i n g i d = me . t o S t r i n g ( ) ; i f ( i d . e q u a l s ( "" ) ) { / / send our i d back n e t . j x t a . e n d p o i n t . Message msg = new n e t . j x t a . e n d p o i n t . Message ( ) ; S t r i n g l o c a l N o d e I D S t r = l o c a l N o d e I D . getURL ( ) . t o E x t e r n a l F o r m ( ) ; n e t . j x t a . e n d p o i n t . M e s s a g e E l e m e n t msge = new n e t . j x t a . e n d p o i n t . S t r i n g M e s s a g e E l e m e n t ( FETCH ADV TAG , l o c a l N o d e I D S t r , n u l l ) ; msg . a d d M e s s a g e E l e m e n t ( "jxta" , msge ) ; s r c A d d r . s e t S e r v i c e N a m e ( j x t a d h t . J X T A I n t e r f a c e .SVCNAME) ; s r c A d d r . s e t S e r v i c e P a r a m e t e r ( j x t a d h t . J X T A I n t e r f a c e .SVCPARAM ) ; n e t . j x t a . e n d p o i n t . Messenger e n d p o i n t M e s s e n ge r = e n d p o i n t . getMessenger ( srcAddr ) ; t r y{ e n d p o i n t M e s s e n g e r . s e n d M e s s a g e ( msg ) ; } c a t c h ( j a v a . i o . I O E x c e p t i o n e ){}
} else{ n e t . j x t a . p e e r . PeerID peerID = n u l l ; t r y{ j a v a . n e t . URL u r l = new j a v a . n e t . URL( i d ) ; p e e r I D = ( n e t . j x t a . p e e r . P e e r I D ) n e t . j x t a . i d . I D F a c t o r y . fromURL ( u r l ) ; } c a t c h ( j a v a . n e t . MalformedURLExcept io n e ){} c a t c h ( j a v a . n e t . U n k n o w n S e r v i c e E x c e p t i o n e1 ){} seedPeer ( peerID ) ;
C.3. JXTAADAPTOR
}
115
} return ;
j x t a d h t . Message r e a l M s g = n u l l ; try{ n e t . j x t a . e n d p o i n t . M e s s a g e E l e m e n t msgElement = m e s s a g e . g e t M e s s a g e E l e m e n t ( j x t a d h t . J X T A I n t e r f a c e .SVCMSGNAME ) ; j a v a . i o . B y t e A r r a y O u t p u t S t r e a m o s = new j a v a . i o . B y t e A r r a y O u t p u t S t r e a m ( ) ; j a v a . i o . O b j e c t O u t p u t S t r e a m o b j o s = new j a v a . i o . O b j e c t O u t p u t S t r e a m ( o s ) ; msgElement . s e n d T o S t r e a m ( o b j o s ) ; objos . flush ( ) ; os . f l u s h ( ) ; j a v a . i o . I n p u t S t r e a m i s = new j a v a . i o . B y t e A r r a y I n p u t S t r e a m ( o s . t o B y t e A r r a y ( ) ) ; j a v a . i o . O b j e c t I n p u t S t r e a m o b j i s = new j a v a . i o . O b j e c t I n p u t S t r e a m ( i s ) ;
}
r e a l M s g = ( j x t a d h t . Message ) o b j i s . r e a d O b j e c t ( ) ; } c a t c h ( j a v a . i o . I O E x c e p t i o n e ){ } c a t c h ( C l a s s N o t F o u n d E x c e p t i o n c ){ } r e c e i v e ( realMsg ) ;
/ ∗ ∗ R e c e i p t i o n o f a m e s s a g e d e s t i n e d t o t h e DHT . ∗ @param m e s s a g e i s t h e m e s s a g e r e c e i v e d ∗/ p u b l i c a b s t r a c t v o i d r e c e i v e ( j x t a d h t . Message m e s s a g e ) ; / ∗ ∗ N o t i f y t h e DHT o f a s p e c i f i c s e e d p e e r . ∗ @param s e e d P e e r t h e JXTA ID o f t h e s e e d p e e r ∗/ p u b l i c a b s t r a c t void s e e d P e e r ( n e t . j x t a . p e e r . PeerID s e e d P e e r ) ; /∗∗ ∗ { @ i n h e r i t D o c} ∗/ p u b l i c f i n a l b o o l e a n s e n d ( n e t . j x t a . p e e r . P e e r I D d e s t , j x t a d h t . Message msg ) throws j a v a . i o . I O E x c e p t i o n { / / t r u e : m e s s a g e s e n t s u c c e s s f u l l y , b u t n o t n e c e s s a r y r e c e i v e d by t h e d e s t i n a t i o n / / f a l s e : m e s s a g e n o t a c c e p t e d t o be s e n t ( n o t enough l o c a l r e s s o u r c e , . . . ) / / I O E x c e p t i o n : t h e m e s s a g e was n o t s e n t / / C r e a t e an e n d p o i n t m e s s a g e and i n s e r t msg n e t . j x t a . e n d p o i n t . Message e n d p o i n t M e s s a g e = new n e t . j x t a . e n d p o i n t . Message ( ) ; n e t . j x t a . e n d p o i n t . M e s s a g e E l e m e n t msgElement = n u l l ; try{ j a v a . i o . B y t e A r r a y O u t p u t S t r e a m o s = new j a v a . i o . B y t e A r r a y O u t p u t S t r e a m ( ) ; j a v a . i o . O b j e c t O u t p u t S t r e a m o b j o s = new j a v a . i o . O b j e c t O u t p u t S t r e a m ( o s ) ; o b j o s . w r i t e O b j e c t ( msg . g e t M e s s a g e ( ) ) ; objos . flush ( ) ; os . f l u s h ( ) ; j a v a . i o . I n p u t S t r e a m i s = new j a v a . i o . B y t e A r r a y I n p u t S t r e a m ( o s . t o B y t e A r r a y ( ) ) ; msgElement = new n e t . j x t a . e n d p o i n t . I n p u t S t r e a m M e s s a g e E l e m e n t ( j x t a d h t . J X T A I n t e r f a c e .SVCMSGNAME, n e t . j x t a . d o c u m e n t . MimeMediaType . AOS, is , null ); / / credentials } c a t c h ( j a v a . i o . I O E x c e p t i o n e ){ } e n d p o i n t M e s s a g e . r e p l a c e M e s s a g e E l e m e n t ( msgElement ) ; / / C r e a t e an e n d p o i n t a d d r e s s , g e t a m e s s e n g e r f r o m t h e e n d p o i n t s e r v i c e / / and s e n d t h e m e s s a g e net . j x t a . endpoint . EndpointAddress endpointAddress = new n e t . j x t a . e n d p o i n t . E n d p o i n t A d d r e s s ( d e s t , j x t a d h t . J X T A I n t e r f a c e .SVCNAME, j x t a d h t . J X T A I n t e r f a c e . SVCPARAM ) ;
APPENDIX C. PLUGIN JAVA SOURCES
116
n e t . j x t a . e n d p o i n t . Messenger e n d p o i n t M e s s e n g er = endpoint . getMessenger ( endpointAddress ) ; return e n d p o i n t M e s s e n ge r . sendMessage ( endpointMessage ) ; } }
C.4. DHTADAPTOR
C.4
117
DHTAdaptor
package j x t a d h t ; / ∗ ∗ The c l a s s t h a t e a c h DHT m u s t e x t e n d t o be i n t e g r a t e d i n t o t h e JXTA f r a m e w o r k ∗ @author N i c o l a s T h e o d o l o z ∗/ p u b l i c a b s t r a c t c l a s s DHTAdaptor e x t e n d s JXTAAdaptor i m p l e m e n t s D H T I n t e r f a c e { / / The g r o u p t o w h i c h t h e l o c a l node b e l o n g s p r o t e c t e d n e t . j x t a . p e e r g r o u p . PeerGroup group = n u l l ; / ∗ ∗ C o n s t r u c t a g e n e r i c DHT i m p l e m e n t a t i o n p r o v i d i n g t h e n e c e s s a r y i n f o r m a t i o n . ∗ @param p e e r g r o u p i s t h e p e e r g r o u p t o w h i c h t h e l o c a l p e e r b e l o n g s ∗ @param r e n d e z v o u s i s a r e f e r e n c e t o t h e Rendez−v o u s S e r v i c e ∗ @param e n d p o i n t i s a r e f e r e n c e t o t h e E n d p o i n t S e r v i c e ∗ @param l o c a l N o d e I D i s t h e JXTA ID o f t h e l o c a l p e e r ∗/ p u b l i c DHTAdaptor ( n e t . j x t a . p e e r g r o u p . P e e r G r o u p p e e r g r o u p , net . j x t a . impl . rendezvous . RendezVousServiceImpl rendezvous , net . jx ta . endpoint . EndpointService endpoint , n e t . j x t a . p e e r . P e e r I D l o c a l N o d e I D ){ super ( rendezvous , e n d p o i n t , localNodeID ) ; group = p e e r g r o u p ; } /∗∗ ∗ { @ i n h e r i t D o c} ∗/ p u b l i c f i n a l v o i d s e e d P e e r s ( S t r i n g [ ] s e e d P e e r s ){ f o r ( i n t i = 0 ; i < s e e d P e e r s . l e n g t h ; i ++){ net . j x t a . endpoint . EndpointAddress endpointAddress = new n e t . j x t a . e n d p o i n t . E n d p o i n t A d d r e s s ( s e e d P e e r s [ i ] ) ; e n d p o i n t A d d r e s s . s e t S e r v i c e N a m e ( j x t a d h t . J X T A I n t e r f a c e .SVCNAME) ; e n d p o i n t A d d r e s s . s e t S e r v i c e P a r a m e t e r ( j x t a d h t . J X T A I n t e r f a c e .SVCPARAM ) ; n e t . j x t a . e n d p o i n t . Message msg = new n e t . j x t a . e n d p o i n t . Message ( ) ; n e t . j x t a . e n d p o i n t . M e s s a g e E l e m e n t msge = new n e t . j x t a . e n d p o i n t . S t r i n g M e s s a g e E l e m e n t ( FETCH ADV TAG , "" , n u l l ) ; msg . a d d M e s s a g e E l e m e n t ( "jxta" , msge ) ;
}
}
n e t . j x t a . e n d p o i n t . Messenger e n d p o i n t M e s s e n g er = endpoint . getMessenger ( endpointAddress ) ; try{ e n d p o i n t M e s s e n g e r . s e n d M e s s a g e ( msg ) ; } c a t c h ( j a v a . i o . I O E x c e p t i o n e ){}
/ ∗ ∗ Use t h e l o c a l JXTA c o n f i g u r a t i o n t o g e t t h e b o o t s t r a p node and t h e p o r t ∗ o f t h e l o c a l node ∗ @ r e t u r n a s t r u c t u r e c o n t a i n i n g t h e b o o t s t r a p node and t h e l o c a l p o r t ∗/ p r o t e c t e d NodeConnection getNodeConnection ( ) { NodeConnection nodeConnection ; / / S e a r c h t h e IP a d d r e s s o f t h e l o c a l node : i n c l u d e d i n t h e c o n f i g a d v e r t i s e m e n t j a v a . u t i l . A r r a y L i s t a d d r s = new j a v a . u t i l . A r r a y L i s t ( ) ; n e t . j x t a . i m p l . p r o t o c o l . P l a t f o r m C o n f i g confAdv = ( n e t . j x t a . impl . p r o t o c o l . P l a t f o r m C o n f i g ) group . g e t C o n f i g A d v e r t i s e m e n t ( ) ; n e t . j x t a . d o c u m e n t . S t r u c t u r e d D o c u m e n t confDoc = confAdv . g e t S e r v i c e P a r a m ( n e t . j x t a . p e e r g r o u p . P e e r G r o u p . r e n d e z v o u s C l a s s I D ) ; j a v a . u t i l . E n u m e r a t i o n enum = confDoc . g e t C h i l d r e n ( ) ; w h i l e ( enum . h a s M o r e E l e m e n t s ( ) ) { n e t . j x t a . document . TextElement t e = ( n e t . j x t a . d o c u m e n t . T e x t E l e m e n t ) enum . n e x t E l e m e n t ( ) ; i f ( "Addr" . e q u a l s ( t e . getName ( ) ) ) { a d d r s . add ( t e . g e t V a l u e ( ) ) ;
APPENDIX C. PLUGIN JAVA SOURCES
118
}
}
int localport = 0; n e t . j x t a . document . S t r u c t u r e d D o c u m e nt tcpconfDoc = confAdv . g e t S e r v i c e P a r a m ( n e t . j x t a . p e e r g r o u p . P e e r G r o u p . t c p P r o t o C l a s s I D ) ; enum = t c p c o n f D o c . g e t C h i l d r e n ( ) ; i f ( enum . h a s M o r e E l e m e n t s ( ) ) { n e t . j x t a . document . TextElement t e = ( n e t . j x t a . d o c u m e n t . T e x t E l e m e n t ) enum . n e x t E l e m e n t ( ) ; j a v a . u t i l . E n u m e r a t i o n enum2 = t e . g e t C h i l d r e n ( ) ; w h i l e ( enum2 . h a s M o r e E l e m e n t s ( ) ) { n e t . j x t a . document . TextElement t e 2 = ( n e t . j x t a . d o c u m e n t . T e x t E l e m e n t ) enum2 . n e x t E l e m e n t ( ) ; i f ( "Port" . e q u a l s ( t e 2 . getName ( ) ) ) { l o ca l po r t = Integer . par seI nt ( ( String ) te2 . getValue ( ) ) ; } } } java . net . InetSocketAddress bootstrapAddress = null ; / / a d d r e s s form : t c p : / / 1 9 3 . 1 0 . 6 5 . 1 2 9 : 9 7 0 1 i f ( addrs . size ( ) ! = 0 ) { String tcpaddress = ( String ) addrs . get ( 0 ) ; S t r i n g a d d r e s s = t c p a d d r e s s . s u b s t r i n g ( 6 , t c p a d d r e s s . l a s t I n d e x O f ( ’:’ ) ) ; i n t p o r t = I n t e g e r . p a r s e I n t ( t c p a d d r e s s . s u b s t r i n g ( t c p a d d r e s s . l a s t I n d e x O f ( ’:’ ) + 1 , tcpaddress . length ( ) ) ) ; b o o t s t r a p A d d r e s s = new j a v a . n e t . I n e t S o c k e t A d d r e s s ( a d d r e s s , p o r t ) ; }
}
n o d e C o n n e c t i o n = new N o d e C o n n e c t i o n ( l o c a l p o r t , b o o t s t r a p A d d r e s s ) ; return nodeConnection ;
/ ∗ ∗ A s t r u c t u r e c o n t a i n i n g a TCP A d d r e s s and a p o r t number ∗/ p r o t e c t e d c l a s s NodeConnection { public f in al int l o c al p or t ; public f in al java . net . InetSocketAddress bootstrap ;
}
/∗ ∗ I n i t i a l i z e the s t r u c t u r e ∗/ p u b l i c N o d e C o n n e c t i o n ( i n t l o c a l p o r t , j a v a . n e t . I n e t S o c k e t A d d r e s s b o o t s t r a p ){ this . localport = localport ; this . bootstrap = bootstrap ; }
/∗∗ ∗ { @ i n h e r i t D o c} ∗/ p u b l i c f i n a l v o i d n o t i f y ( j x t a d h t . DHTEvent e v e n t ){ rendezvous . generateEvent ( event . getType ( ) , event . getElement ( ) ) ; } /∗∗ ∗ { @ i n h e r i t D o c} ∗/ p u b l i c a b s t r a c t n e t . j x t a . p e e r . PeerID lookup ( S t r i n g e x p r e s s i o n ) ; /∗∗ ∗ { @ i n h e r i t D o c} ∗/ p u b l i c a b s t r a c t n e t . j x t a . p e e r . P e e r I D [ ] r e p l i c a S e t ( S t r i n g key , i n t max ) ; /∗∗ ∗ { @ i n h e r i t D o c} ∗/ p u b l i c a b s t r a c t v o i d r a n g e ( I n t e g e r min , I n t e g e r max ) ; /∗∗ ∗ { @ i n h e r i t D o c} ∗/
C.4. DHTADAPTOR
p u b l i c a b s t r a c t void becomeEdgePeer ( ) ; }
119
APPENDIX C. PLUGIN JAVA SOURCES
120
C.5 DHTTemplate
package j x t a d h t ; p u b l i c c l a s s DHTTemplate e x t e n d s DHTAdaptor{ p u b l i c DHTTemplate ( n e t . j x t a . p e e r g r o u p . P e e r G r o u p p e e r g r o u p , net . j x t a . impl . rendezvous . RendezVousServiceImpl rendezvous , net . jx t a . endpoint . EndpointService endpoint , n e t . j x t a . p e e r . P e e r I D l o c a l N o d e I D ){ super ( peergroup , rendezvous , e n d p o i n t , localNodeID ) ; / / To i m p l e m e n t } / ∗ Methods h e r i t e d t h a t can be u s e d : b o o l e a n s e n d ( n e t . j x t a . p e e r . PeerID d e s t , j x t a d h t . Message msg ) throws java . io . IOException v o i d n o t i f y ( j x t a d h t . DHTEvent e v e n t ) ∗/ p u b l i c n e t . j x t a . p e e r . P e e r I D l o o k u p ( S t r i n g e x p r e s s i o n ){ / / To i m p l e m e n t return null ; } p u b l i c n e t . j x t a . p e e r . P e e r I D [ ] r e p l i c a S e t ( S t r i n g key , i n t max ){ / / To i m p l e m e n t return null ; } p u b l i c v o i d r a n g e ( I n t e g e r min , I n t e g e r max ){ / / To i m p l e m e n t } p u b l i c v o i d r e c e i v e ( j x t a d h t . Message m e s s a g e ){ / / To i m p l e m e n t } p u b l i c v o i d s e e d P e e r ( n e t . j x t a . p e e r . P e e r I D s e e d P e e r ){ / / To i m p l e m e n t } p u b l i c void becomeEdgePeer ( ) { / / To i m p l e m e n t } }
C.6. DHTPASTRY
C.6
121
DHTPastry
package j x t a d h t . p a s t r y ; / ∗ ∗ A DHT u s i n g t h e F r e e P a s t r y d i s t r i b u t i o n ∗ @author N i c o l a s T h e o d o l o z ∗/ p u b l i c c l a s s DHTPastry e x t e n d s j x t a d h t . DHTAdaptor{ private r i ce . pastry . PastryNodeFactory pastryNodeFactory ; p r i v a t e r i c e . p a s t r y . P a s t r y N o d e myNode = n u l l ; p r i v a t e f i n a l i n t ROUTESET SIZE = 1 ; p r i v a t e f i n a l i n t LEAFSET SIZE = 1 6 ; / / The RMI r e g i s t r y p o r t number i s d e f i n e d a s t h e l o c a l node p o r t ID + t h i s v a l u e p r i v a t e f i n a l i n t DIFF PORT LOCAL RMI = 1 0 0 0 ; / ∗ ∗ I n i t i a l i z e t h e F r e e P a s t r y node ∗ @param p e e r g r o u p i s t h e JXTA p e e r g r o u p t o w h i c h t h e l o c a l p e e r b e l o n g s ∗ @param r e n d e z v o u s i s a r e f e r e n c e t o t h e Rendez−v o u s S e r v i c e ∗ @param e n d p o i n t i s a r e f e r e n c e t o t h e E n d p o i n t S e r v i c e ∗ @param l o c a l N o d e I D i s t h e JXTA ID o f t h e l o c a l p e e r ∗/ p u b l i c DHTPastry ( n e t . j x t a . p e e r g r o u p . P e e r G r o u p p e e r g r o u p , net . j x t a . impl . rendezvous . RendezVousServiceImpl rendezvous , net . jx ta . endpoint . EndpointService endpoint , n e t . j x t a . p e e r . P e e r I D l o c a l N o d e I D ){ super ( peergroup , rendezvous , e n d p o i n t , localNodeID ) ; / / Get t h e l o c a l p o r t number and t h e b o o t s t r a p node NodeConnection nodeConnection = getNodeConnection ( ) ; / / I n i t i a l i z e s t h e F r e e P a s t r y nodes f a c t o r y p a s t r y N o d e F a c t o r y = new r i c e . p a s t r y . r m i . R M I P a s t r y N o d e F a c t o r y ( n u l l , n o d e C o n n e c t i o n . l o c a l p o r t + DIFF PORT LOCAL RMI ) ; / / The a d d r e s s o f t h e b o o t s t r a p node java . net . InetSocketAddress bo o t st r a p = nodeConnection . b o o ts t r ap ; / / Change t h e p o r t number , by s p e c i f y i n g t h e RMI r e g i s t r y p o r t if ( bootstrap ! = null ) b o o t s t r a p = new j a v a . n e t . I n e t S o c k e t A d d r e s s ( b o o t s t r a p . getHostName ( ) , bootstrap . getPort () + DIFF PORT LOCAL RMI ) ; r i c e . p a s t r y . r m i . RMINodeHandle b o o t s t r a p R M I = n u l l ; try{ r i c e . p a s t r y . rmi . RMIPastryNodeFactory RMIfact = ( r i c e . p a s t r y . rmi . RMIPastryNodeFactory ) p a s t r y N o d e F a c t o r y ; b o o t s t r a p R M I = ( r i c e . p a s t r y . r m i . RMINodeHandle ) RMIfact . generateNodeHandle ( b o o t s t r a p ) ; } c a t c h ( E x c e p t i o n e ){ / / b o o t s t r a p r e m a i n s n u l l } r i c e . p a s t r y . NodeId n o d e I d = j x t a d h t . p a s t r y . u t i l s . Mapper . p e e r I D 2 N o d e I d ( l o c a l N o d e I D ) ; / / C r e a t e s t h e l o c a l F r e e P a s t r y Node myNode = p a s t r y N o d e F a c t o r y . newNode ( b o o t s t r a p R M I , n o d e I d ) ; } /∗∗ ∗ { @ i n h e r i t D o c} ∗/ p u b l i c n e t . j x t a . p e e r . P e e r I D l o o k u p ( S t r i n g e x p r e s s i o n ){ System . o u t . p r i n t l n ( "Call to DHTPastry::getReplicaPeer with expression: " + expression ) ;
APPENDIX C. PLUGIN JAVA SOURCES
122
r i c e . p a s t r y . I d t a r g e t = new r i c e . p a s t r y . I d ( e x p r e s s i o n . g e t B y t e s ( ) ) ; r i c e . p a s t r y . l e a f s e t . L e a f S e t l e a f S e t = myNode . g e t L e a f S e t ( ) ; r i c e . p a s t r y . r o u t i n g . R o u t i n g T a b l e r o u t e T a b l e = myNode . g e t R o u t i n g T a b l e ( ) ; r i c e . p a s t r y . NodeHandle nextHop = n u l l ; i n t cwSize = l e a f S e t . cwSize ( ) ; i n t ccwSize = l e a f S e t . ccwSize ( ) ; int lsPos = leaf S et . mostSimilar ( t a r g e t ) ; i f ( lsPos == 0) nextHop = myNode . g e t L o c a l H a n d l e ( ) ; e l s e i f ( ( l s P o s >0 && ( l s P o s
