P. 1
Practical JXTA II

Practical JXTA II

4.0

|Views: 15,605|Likes:
Published by Jérôme Verstrynge
This book is an introduction to the JXTA P2P protocol. It is written for software developers and architects willing to understand what P2P is all about, and those looking for code examples explaining how to use JXSE, step-by-step.
This book is an introduction to the JXTA P2P protocol. It is written for software developers and architects willing to understand what P2P is all about, and those looking for code examples explaining how to use JXSE, step-by-step.

More info:

Published by: Jérôme Verstrynge on Jan 25, 2011
Copyright:Traditional Copyright: All rights reserved

Availability:

Read on Scribd mobile: iPhone, iPad and Android.
download as PDF or read online from Scribd
See more
See less

09/06/2015

Sections

Practical JXTA II

Cracking the P2P puzzle

Practical JXTA II
Copyright © 2010 by DawningStreams, Inc. The Netherlands

First edition: July, 2008. Second edition: July, 2010.
All right reserved. No part of this book may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying, recording, or by any information storage and retrieval system, without written permission from the publisher, except for the inclusion of brief quotations in a review. International Standard Book Number: 978-1-4461-3956-1 Limit of Liability/Disclaimer of Warranty: While the publisher and the author have used their best effort in preparing this book, they make no representation or warranties with respect to the accuracy or completeness of the contents of this book. The software code examples, advice, strategies herein are provided “as is” and any expressed or implied warranties, including, but not limited to, the implied warranties or merchantability and fitness for a particular purpose are disclaimed. No warranty may be created or extended by sales representatives or written sales materials. In no event, shall DawningStreams, Inc. be liable for any direct, indirect, incidental, special, exemplary, or consequential damages (including, but not limited to, procurement of substitute goods or services; loss of use, data, or profit; or business interruption) however caused and on any theory of liability, whether in contract, strict liability, or tort (including negligence or otherwise) arising in any way out of the use of the software code examples, advice, strategies, even if advised of the possibility of such damages. You should consult with a professional where appropriate. Trademarks: DawningStreams, Inc. is a registered trademarks of DawningStreams, Inc. in the United States and other countries and may not be be used without permission. All other trademarks are the property of their respective owners. DawningStreams, Inc. is not associated with any products or vendors mentioned in this book. Publisher: Lulu Enterprises, Inc. (www.lulu.com)

-2

Table of Contents
Foreword 11 Why This Book?.............................................................................................................................................................................12 Why A Second Edition?................................................................................................................................................................13 Who Should Read This Book?.....................................................................................................................................................14 Prerequisites..................................................................................................................................................................................15 Introduction 16 Peer to Peer....................................................................................................................................................................................16 A Bad Reputation?.................................................................................................................................................................16 A Quick Historical Review....................................................................................................................................................18 Architectures & Design Principles..............................................................................................................................................20 Client/Server..........................................................................................................................................................................20 Three-tier & Multi-tier ..........................................................................................................................................................21 Clustering & Load Balancing ...............................................................................................................................................21 Service Oriented Architecture & Middleware....................................................................................................................22 Grid Computing.....................................................................................................................................................................23 Cloud Computing..................................................................................................................................................................23 About Needs That Have Shaped IT Solutions....................................................................................................................23 What is P2P?..................................................................................................................................................................................24 ICQ...........................................................................................................................................................................................24 Napster....................................................................................................................................................................................25 Gnutella...................................................................................................................................................................................26 Kazaa.......................................................................................................................................................................................27 BitTorrent................................................................................................................................................................................28 Freenet.....................................................................................................................................................................................28 Pure P2P..................................................................................................................................................................................28 Initial Objectives and Evolution...........................................................................................................................................29 Benefits....................................................................................................................................................................................30 Drawbacks..............................................................................................................................................................................30 So, What Is The Use of P2P?..................................................................................................................................................32 Towards Universality ...........................................................................................................................................................32 JXTA...............................................................................................................................................................................................34 Introduction............................................................................................................................................................................34 The Three Layer Cake............................................................................................................................................................35 The JXTA Project....................................................................................................................................................................36 JXSE Community....................................................................................................................................................................36 C/C++..............................................................................................................................................................................37 JXME.................................................................................................................................................................................37 Documentation, Forum & FAQ............................................................................................................................................37 Understanding JXTA 39 Introduction...................................................................................................................................................................................39 A Tribes-In-Islands Metaphor...............................................................................................................................................39 The Concepts.................................................................................................................................................................................40 Overview.................................................................................................................................................................................40 Peer..........................................................................................................................................................................................41 Peer Group..............................................................................................................................................................................43 Service......................................................................................................................................................................................44 Resources.................................................................................................................................................................................47 Advertisement........................................................................................................................................................................47 Peer Advertisement.........................................................................................................................................................48 Peer Group Advertisement............................................................................................................................................48 Publication.......................................................................................................................................................................48 ID..............................................................................................................................................................................................49

-3

Content....................................................................................................................................................................................50 Codats......................................................................................................................................................................................50 Pipes.........................................................................................................................................................................................50 Module....................................................................................................................................................................................50 The Protocols.................................................................................................................................................................................52 Message...................................................................................................................................................................................53 Endpoint Routing Protocol (ERP)........................................................................................................................................53 Endpoint Service.............................................................................................................................................................53 Endpoint Address...........................................................................................................................................................54 Endpoint Routing Protocol.............................................................................................................................................54 ERP Messages & Advertisements..................................................................................................................................56 Top-Down-Top................................................................................................................................................................57 Rendezvous Protocol (RVP)..................................................................................................................................................58 Message Propagation Protocol.......................................................................................................................................58 PeerView Protocol...........................................................................................................................................................59 Rendezvous Advertisement...........................................................................................................................................60 Rendezvous Lease Protocol............................................................................................................................................61 Peer Connection to Rendezvous ...................................................................................................................................61 Propagation Control........................................................................................................................................................61 Top-Down-Top................................................................................................................................................................63 Pipe Binding Protocol (PBP).................................................................................................................................................63 Pipe Advertisement.........................................................................................................................................................64 Pipe Resolver Message...................................................................................................................................................64 Propagate Pipe Message Header...................................................................................................................................65 Top-Down-Top................................................................................................................................................................65 Peer Resolver Protocol (PRP)................................................................................................................................................65 Resolver Query Message................................................................................................................................................66 Resolver Response Message...........................................................................................................................................66 Shared Resource Distributed Index (SRDI)..................................................................................................................66 Resolver SRDI Message..................................................................................................................................................67 Top-Down-Top................................................................................................................................................................68 Peer Information Protocol (PIP)............................................................................................................................................68 PIP Query Message.........................................................................................................................................................69 PIP Response Message....................................................................................................................................................69 Top-Down-Top................................................................................................................................................................69 Peer Discovery Protocol (PDP).............................................................................................................................................70 Discovery Query Message..............................................................................................................................................70 Discovery Query Response............................................................................................................................................70 Top-Down-Top................................................................................................................................................................71 Access Control...............................................................................................................................................................................71 Membership Service...............................................................................................................................................................72 Access Service.........................................................................................................................................................................72 The Ignition Process......................................................................................................................................................................73 Module....................................................................................................................................................................................73 Service......................................................................................................................................................................................74 Peer Group As A Service – Part I...................................................................................................................................74 Well-known Module Class, Specification and Implementation IDs..........................................................................74 Bootstrapping JXTA........................................................................................................................................................74 Peer Group As A Service – Part II.................................................................................................................................77 Loading Other Services...................................................................................................................................................77 Network Boundaries 79 Reminder........................................................................................................................................................................................79 IP..............................................................................................................................................................................................80 Unicast, Broadcast & Multicast......................................................................................................................................81 IPv4 Versus IPv6..............................................................................................................................................................81 TCP..........................................................................................................................................................................................81 Handshake.......................................................................................................................................................................81 UDP..........................................................................................................................................................................................82 Datagram..........................................................................................................................................................................82

-4

Port...........................................................................................................................................................................................82 Firewalls..................................................................................................................................................................................83 NAT.........................................................................................................................................................................................84 Some Limitations.............................................................................................................................................................86 PAT...................................................................................................................................................................................86 Proxy........................................................................................................................................................................................87 Router......................................................................................................................................................................................87 Multicasting Versus Subnets..........................................................................................................................................87 Natural Network Boundaries...............................................................................................................................................88 Artificial Network Boundaries.............................................................................................................................................89 JXTA Transportation Layer..........................................................................................................................................................89 JXSE Transportation Layer...........................................................................................................................................................90 Overcoming Firewalls............................................................................................................................................................90 Relay Service....................................................................................................................................................................91 Overcoming NATs.................................................................................................................................................................91 Overcoming Proxies...............................................................................................................................................................92 Seeds........................................................................................................................................................................................94 Peer Accessibility..........................................................................................................................................................................95 WAN........................................................................................................................................................................................95 LAN.........................................................................................................................................................................................96 Same Subnet.....................................................................................................................................................................96 Different Subnets.............................................................................................................................................................96 NAT Traversal...............................................................................................................................................................................97 IP Obstacles......................................................................................................................................................................97 Port Prediction.................................................................................................................................................................98 Punching Holes...............................................................................................................................................................98 Hairpin Issue....................................................................................................................................................................98 RFC 5128...........................................................................................................................................................................99 TURN.......................................................................................................................................................................................99 STUN.......................................................................................................................................................................................99 STUNT...................................................................................................................................................................................100 TTL-less Version of STUNT.........................................................................................................................................102 New NAT Classification...............................................................................................................................................102 NUTSS...................................................................................................................................................................................103 P2PNAT.................................................................................................................................................................................103 NATBlaster...........................................................................................................................................................................104 NatTrav.................................................................................................................................................................................104 PWNAT.................................................................................................................................................................................105 ALG........................................................................................................................................................................................106 UPnP......................................................................................................................................................................................107 ICE..........................................................................................................................................................................................107 ICE-TCP..........................................................................................................................................................................108 “Behave” Compliant NAT..................................................................................................................................................108 RFC 5382.........................................................................................................................................................................108 RFC 4787.........................................................................................................................................................................109 Where Does JXSE Stand?.....................................................................................................................................................110 Conclusion...................................................................................................................................................................................111 JXSE Cryptographic Layer 113 Cryptography Reminder............................................................................................................................................................113 Alice, Bob & Eve...................................................................................................................................................................113 Introduction To Secure Communication...........................................................................................................................114 ...And Vicious Circles!..........................................................................................................................................................117 Public Key Infrastructure (PKI)..........................................................................................................................................119 Who Certifies The Root Certificate Authority?..........................................................................................................120 Duties Of A Certificate Authority...............................................................................................................................120 Web Of Trust.........................................................................................................................................................................121 X.509.......................................................................................................................................................................................122 X.500 & Principal..................................................................................................................................................................123 Hash Function.......................................................................................................................................................................123

-5

The Collision Issue........................................................................................................................................................124 Key Sizes ..............................................................................................................................................................................125 Assumptions ........................................................................................................................................................................125 The DRM Illusion..........................................................................................................................................................126 Calling Experts.....................................................................................................................................................................126 Personal Security Environment (PSE).......................................................................................................................................127 Java Cryptography Architecture........................................................................................................................................127 KeyStore................................................................................................................................................................................127 Creation..........................................................................................................................................................................128 Automatic X.509 Certificate & Private Key Creation................................................................................................128 Big Big Big Warning!.....................................................................................................................................................131 Registering Your Own X.509........................................................................................................................................132 PSE Configuration................................................................................................................................................................132 Other Concepts............................................................................................................................................................................134 Secure Socket Layer (SSL)...................................................................................................................................................134 Transport Security Layer (TLS)..........................................................................................................................................134 Virtual Private Network (VPN)..........................................................................................................................................134 JXTA Security Layer....................................................................................................................................................................135 About Cipher Suites.............................................................................................................................................................135 About Encryption of Private Keys......................................................................................................................................135 PSE Configuration Advertisement Encryption..........................................................................................................137 Conclusion............................................................................................................................................................................137 Where Does JXSE 2.6 Stand?........................................................................................................................................138 Architectural Considerations 139 Identity Issues..............................................................................................................................................................................139 IP Addresses As Identities..................................................................................................................................................139 Defining An Identity in JXTA.............................................................................................................................................140 Creation Of Peer IDs & Importation Of IDs From Other Systems..................................................................................141 Peer Group Creation & Identity.........................................................................................................................................141 Configuration Modes..................................................................................................................................................................143 JXTA Peer Types...................................................................................................................................................................143 Minimal Edge Peer........................................................................................................................................................143 Full-Featured Edge Peer...............................................................................................................................................143 Rendezvous Peer...........................................................................................................................................................143 Relay Peer.......................................................................................................................................................................143 JXSE Configuration Modes..................................................................................................................................................144 ADHOC..........................................................................................................................................................................144 EDGE..............................................................................................................................................................................144 RENDEZVOUS..............................................................................................................................................................145 RELAY............................................................................................................................................................................145 PROXY............................................................................................................................................................................146 Peer Type versus Configuration Types..............................................................................................................................146 About Implementation Of Services....................................................................................................................................146 Network Scope............................................................................................................................................................................147 To Be Or Not To Be?.............................................................................................................................................................147 A Relay...........................................................................................................................................................................147 A RendezVous...............................................................................................................................................................148 Number of Seeds...........................................................................................................................................................149 Network Administration............................................................................................................................................................149 Default IP Ports....................................................................................................................................................................149 Default HTTP Port...............................................................................................................................................................149 Default Multicasting Port & IP Address............................................................................................................................150 Implementing Seeds.............................................................................................................................................................150 About Subnets......................................................................................................................................................................150 Cryptography..............................................................................................................................................................................151 Implementing Your Own Cryptography Layer................................................................................................................151 Exportation Limitations................................................................................................................................................151 Access Control Implementation................................................................................................................................................152

-6

Using JXSE 153 Getting Started.............................................................................................................................................................................153 Creating A Project................................................................................................................................................................153 Maven....................................................................................................................................................................................154 Javadoc..................................................................................................................................................................................154 First Connection & Local Configuration...................................................................................................................................154 Example 100 - Starting And Stopping JXTA.....................................................................................................................154 Example 110 – Creating A Local Configuration...............................................................................................................156 Example 120 – Retrieving, Modifying & Saving A Local Configuration.......................................................................157 Miscellaneous.......................................................................................................................................................................159 Understanding ConfigParam.......................................................................................................................................159 Modifying Other Configuration Parameters..............................................................................................................159 Loading A Configuration From A URI.......................................................................................................................159 Automatic Change Of IP Addresses...........................................................................................................................159 Local Configuration Directory Structure....................................................................................................................160 New Configuration Objects & Connecting With OSGi...........................................................................................................160 Example 150 - Configuration Objects.................................................................................................................................160 Example 160 – Connecting with OSGi...............................................................................................................................161 Exploring Connectivity Issues...................................................................................................................................................163 Creating & Using Seeds.......................................................................................................................................................163 About The Default JXTA Seeds...........................................................................................................................................166 Running Multiple Peers On A Single Device....................................................................................................................166 Multiple Peer In The Same JVM..................................................................................................................................166 The Proper Angle To Strike A Match.................................................................................................................................167 Jack, The Rendezvous..........................................................................................................................................................167 Anna, The Edge....................................................................................................................................................................169 Testing Angles Between Jack And Anna...........................................................................................................................171 Angle I - Start Jack, Then Anna, Delete Configuration & Approve Seed................................................................171 Angle II - Start Anna, Then Jack, Delete Configuration & Approve Seed..............................................................172 Angle III - Start Jack, Then Anna, Keep Configuration & Disapprove Seed..........................................................173 Remarks & Warning......................................................................................................................................................173 Aminah, The Other RendezVous.......................................................................................................................................174 Chihiro, The Other Edge.....................................................................................................................................................175 Automatic Reconnection To Other RendezVous..............................................................................................................178 Connectivity Manager.........................................................................................................................................................179 Robert, The Relay.................................................................................................................................................................180 Relay Connectivity...............................................................................................................................................................182 Summary...............................................................................................................................................................................182 Creating Peers And Peer Groups..............................................................................................................................................183 Example 200 – Creating IDs................................................................................................................................................183 Example 210 – Creating A New Peer.................................................................................................................................184 Example 220 – Creating A Customized Peer Group........................................................................................................185 Discovery Operations.................................................................................................................................................................188 Finding Advertisements......................................................................................................................................................188 Example 300 - Retrieving And Flushing Local Advertisements.....................................................................................188 Example 310 – Remote Search For Advertisements.........................................................................................................190 Local And Remote Publication...........................................................................................................................................194 Messages & Advertisements......................................................................................................................................................194 Example 400 – Creating An Empty Message....................................................................................................................194 Example 410 – Add String, Long & Int Elements.............................................................................................................194 Example 420 – Retrieving Message Elements...................................................................................................................195 Example 430 – Add Byte Array Element And Retrieve InputStream.............................................................................196 Example 440 – Adding An Advertisement In A Message...............................................................................................197 Example 500 – Customized Advertisement......................................................................................................................198 Attributes........................................................................................................................................................................201 Methods..........................................................................................................................................................................201 Instantiator.....................................................................................................................................................................202 Example 510 – Registering A Customized Advertisement Instance..............................................................................202 Private Keys, Certificates & KeyStores.....................................................................................................................................203

-7

Example 600 - Exporting & Importing Private Keys And X.509 Certificates.................................................................203 Example 610 – Working With A KeyStore........................................................................................................................205 Example 620 – Custom PSE Peer Group & Joining .........................................................................................................207 Simple Pipe Communication.....................................................................................................................................................210 Chandra, The Rendezvous Listening to Messages...........................................................................................................211 Dimitri, The Edge Sending Messages................................................................................................................................213 Running The Example.........................................................................................................................................................215 Unicast Secure Pipes............................................................................................................................................................217 Bidirectional Pipe Communication...........................................................................................................................................217 Adelaide, The RendezVous At One End...........................................................................................................................217 Quinisela, The Edge At The Other End.............................................................................................................................220 Running The Example.........................................................................................................................................................222 JXTA Socket & Socket Server.....................................................................................................................................................223 Lidong, The Rendezvous And JXTA Socket Server..........................................................................................................223 Ayrton, The Edge And JXTA Socket..................................................................................................................................226 Running The Example.........................................................................................................................................................228 JXTA Multicast Socket................................................................................................................................................................229 Hans, The Rendezvous, A Multicast Participant..............................................................................................................229 Teyacapan, The Edge, Another Multicast Participant......................................................................................................231 Running The Example.........................................................................................................................................................233 Implementing A Customized Service.......................................................................................................................................233 Introduction..........................................................................................................................................................................233 Example 700 – Creating Module IDs..................................................................................................................................233 Example 710 – Astrology Service .......................................................................................................................................234 Static And Non-Static Attributes.................................................................................................................................238 Static Methods...............................................................................................................................................................239 Static Class......................................................................................................................................................................239 Implementation Of Interfaces......................................................................................................................................239 RendezVous Joe, The Astrologer .......................................................................................................................................239 Edge Jill, The Customer ......................................................................................................................................................241 Running The Example.........................................................................................................................................................244 Self-Service Weather Forecasting Method.........................................................................................................................244 Peer Information.........................................................................................................................................................................245 Activation Of The Peer Information Service.....................................................................................................................245 Ping...............................................................................................................................................................................................245 Example 800 – Ping..............................................................................................................................................................246 Example 810 – Pong.............................................................................................................................................................247 Running the Example..........................................................................................................................................................249 Miscellaneous..............................................................................................................................................................................249 Sending A Message With The Endpoint Service..............................................................................................................249 Customized Queries.............................................................................................................................................................249 About Registering Handlers In Services............................................................................................................................250 JXSE Shell.....................................................................................................................................................................................250 About The Future... 251 ...Of P2P........................................................................................................................................................................................251 Perception vs. Facts..............................................................................................................................................................251 About Needs That Have Shaped IT Solutions – Part II.............................................................................................251 Distributed Content.............................................................................................................................................................251 CHURN.................................................................................................................................................................................252 Economical............................................................................................................................................................................252 Costs And Return On Investment...............................................................................................................................252 Potential For Profit........................................................................................................................................................254 ...Of JXTA.....................................................................................................................................................................................255 Technological........................................................................................................................................................................255 Simplification Of Complexity - Universality..............................................................................................................255 New Applications..........................................................................................................................................................255 Accountability & Vendor's Credibility.......................................................................................................................255 Educational...........................................................................................................................................................................256

-8

Documentation, Books And Tutorials.........................................................................................................................256 Code Examples..............................................................................................................................................................257 The Community...................................................................................................................................................................257 The Protocols........................................................................................................................................................................258 JXTA vs. OSGi................................................................................................................................................................258 ...Of JXSE......................................................................................................................................................................................258 Security..................................................................................................................................................................................258 Cache Pollution..............................................................................................................................................................259 Conclusion...................................................................................................................................................................................259 Appendix 261 Protocol Messages Types............................................................................................................................................................261 Advertisement Attributes...........................................................................................................................................................262 Peer Advertisement..............................................................................................................................................................262 Peer Group Advertisement.................................................................................................................................................262 Module Class Advertisement.............................................................................................................................................262 Module Specification Advertisement ................................................................................................................................262 Module Implementation Advertisement ..........................................................................................................................263 Pipe Advertisement.............................................................................................................................................................263 Rendezvous Advertisement................................................................................................................................................264 Route Advertisement...........................................................................................................................................................264 Access Point Advertisement...............................................................................................................................................264 Index.............................................................................................................................................................................................265

-9

- 10

Foreword
Acknowledgments
I thank my friend Jill Schmidig for her support. There are times in life when you need unconditional support from your friends, just because of the challenges of life. I am talking about the kind of support some people believe they will never need (or never have). I was one of these people. I am grateful to have had her during those days when life hit hard on me, my friends and my family. She was always there to listen and to talk when I needed to. I also thank all those who have helped me answering questions and to clarify issues about JXTA on the JXTA forum. I also thank all those who have participated to the development of JXTA and the Open Source community in general.

About the Author
Jérôme Verstrynge is a graduate in computer science from the Université Libre de Bruxelles (Belgium). He also obtained a Master in Human Resource Management from that same institution and a Master of Business Administration in marketing from the Rotterdam School of Management (The Netherlands). Since he finished his MBA, he has started his own company in Amsterdam (The Netherlands) with a friend, in the New-York Metropolitan Area (New Jersey, USA). They are working on their own P2P related project. Jérôme Verstrynge has joined the community of JXTA software developers in 2008. He participates to the JXTA forum using the AdamMan71 pseudonym. He can be reached by email at adamman71@dev.java.net.

Foreword Foreword - 11

Why This Book?
The name of the book is inspired from another book called Practical Cryptography by Niels Ferguson and Bruce Schneier. Practical Cryptography aimed at discussing cryptography implementation at an engineer's level, rather than at a mathematical level, which is often abstract and conceptual. It discussed “how to apply the cryptographic functions in a real-world setting” citing real software implementation issues. Sun Microsystems introduced JXTA in 2001. JXTA is a set of protocol specifications for implementing peer-to-peer applications. Like cryptography, JXTA is very abstract and conceptual in its definition. It does not get involved with implementation issues (or very little). Although several books written about JXTA at the beginning of the Millennium included discussions on its implementation in the Java programming language, its evolution and the evolution of its implementation has made these books progressively obsolete. The author started investigating JXTA in early 2006 and faced many issues trying to understand this technology. The Java implementation was undergoing a major overhaul as it was migrated to version 1.5 of the Java platform. The available documentation became obsolete as new code was delivered by the open source community. The available software guides were becoming obsolete. This made learning JXTA very tedious. Then, the latest available version of JXTA was 2.5. Although the corresponding version of the programmer's guide constituted an improvement over the previous versions, it did not explain how JXTA concepts operated in details. Moreover, it did not describe the technical issues those who had implemented JXTA had to solve to enable smooth communication over computer networks. Understanding these issues is essential when designing, implementing and configuring software applications based on JXTA. The first version of this book was aiming at shedding more light as to how JXTA operates behind the scenes, both from a conceptual and a practical point-of-view. In addition, it provided a reminder covering network concepts and basic cryptographic issues. That book was about bringing the core concepts of the JXTA puzzle together, in order to crack it and to make JXTA a practical technology to use.
1

1

Practical Cryptography, by Niels Ferguson and Bruce Schneier, published at Wiley Publishing, Inc. in 2003.

Foreword Why This Book? - 12

Why A Second Edition?
In spring 2009, the author decided to take the lead to release version 2.6 of JXTA/JXSE. This was an opportunity to clean-up an increasing technical debt in the code, to refactor it, and to solve several bugs left in the 2.5 release. Together with several developers from the community, new features have also been made available:
• • • • • • • •

In-memory implementation of SRDI Database implementation of the cache manager Improvement of threads and resource consumption with a task manager New TCP layer implementation Introduction of the OSGi framework Configuration objects Mavenization of the project New connectivity methods

Many people were happy to see a new and updated book about the JXTA technology come out in 2008, but some remained frustrated that more information about what is happening under the hood was not available. This information has never been documented and released until recently. It is now available in the Programmer's Guide v2.6. This second edition is about updating the first edition with novelties delivered in the JXTA/JXSE 2.6 release. It also includes some of the 'under the hood ' information delivered in the Programmer's Guide v2.6. Code examples have been improved and rewritten where necessary. The purpose of Practical JXTA remains to be a complete introductory book to P2P in general and to the JXTA/JXSE technology. It gives pointers to those who want to explore it and its implementation deeper.
2

2

See http://jxse.kenai.com/Developers/Developers.html

Foreword Why A Second Edition? - 13

Who Should Read This Book?
This book is intended for:

JXTA early adopters – If you are one of those who adopted JXTA since its inception, this book will help keep you up-to-date with the recent evolution of the JXTA implementation. Contrary to many books published earlier, this book contains code examples using the most recent features of JXSE, including those delivered as part of release 2.6.

Functional analysts and software architects – This book covers all the JXTA concepts (including their usage), that a functional analyst or a software architect needs to understand, in order to design JXTA-based P2P applications. The official JXTA specification document contains several abstract terms referencing each other, together with a lot of technical language, making it hard to understand by everyone. This book is solving this entanglement by using many metaphors from the real world.

Software developers – This book will explain altogether the basic concepts of JXTA and how to use JXSE, the Java implementation of JXTA, to develop your own P2P applications. It contains several basic code examples explaining how to use JXTA, step-by-step. These were designed to be as didactic as possible, that is, without optimization, to facilitate the learning. You will be able to take inspiration from these building blocks for your own software implementations.

System and network administrators – The JXTA technology is abstract in its concepts, but it relies heavily on network transportation. Many transportation protocols can be implemented with JXTA, although TCP/IP and HTTP are the most common. Nearly all implementations of JXTA require mechanisms to overcome firewalls, NATs and proxies boundaries. This book explains how administrators can improve the overall performance of JXTA-based applications using an adequate configuration of their systems, and without compromising security policies.

Managers and decision makers – If you are a manager or a decision maker, you may have heard about peer-to-peer technologies. You may even have used them for chatting, phoning over the Internet, or on your mobile phone and hand-held devices, and would like to know more about them. This book explains the origin of P2P and demystifies the undeserved negative publicity it received at the beginning of the decade. It describes the benefits of P2P, how to take advantage of it. Security and control access issues to copyright

Foreword Who Should Read This Book? - 14

protected documents are also discussed here. This book does not explain how to implement JXTA. However, it can be used as a base to understand JXTA. Developers willing to implement the JXTA protocols will have to refer to the official specification documentation available online at https://jxta-spec.dev.java.net/ for technical details.

Prerequisites
This book assumes that software developers know about the Java programming language and concepts such as URI (Uniform Resource Identifiers), URL (Uniform Resource Locater) and URN (Uniform Resource Name). They should master the event firing and even listening mechanism. Functional analysts and software architects need to know about XML, TCP/IP and HTTP, in general. System and network administrators should be aware of how TCP/IP, firewalls, NATs, proxies, routers and other types of network transportation systems operate in general. Managers and decision makers do not need to know more than general IT concepts. The code examples provided in this book are relying on version 2.6 of JXSE, which requires JDK 1.5 (or a higher version).

Foreword Prerequisites - 15

Introduction
This chapter introduces peer-to-peer and JXTA in general. We will describe the motivations that led to the emergence of the peer-to-peer philosophy by revisiting parts of the IT history since the 1960's. We will compare it with other major IT design philosophies; describe its specificities, potential benefits and drawbacks. We will also explain why a universal set of protocols became necessary to implement open peer-topeer functionalities in software applications, thus leading to the creation of JXTA.

Peer to Peer
Peer-to-Peer (or P2P for short) is defined as a concept allowing direct communication between individual computers by some, and as a set of networking design principles by others. The actual definition of what P2P is varies according to authors; but most agree that a peer-to-peer system traditionally rejects the client/server model and the underlying hierarchy it imposes between computers operating on a network. Most of us heard about P2P for the first time when we used a file exchange application such as Napster, Kazaa or Gnutella, an instant messaging application such as ICQ or Yahoo! Messenger, or when we started “phoning” over the Internet with Skype. Others discovered P2P with Groove (now Microsoft Groove), a software application developed by Groove Networks in the 1990's.

A Bad Reputation?
In his July 15, 2007 cryptogram newsletter , Bruce Schneier, a renowned cryptography and security specialist, discussed the role of the correspondent inference theory on the human perception of terrorist group motivations. This theory, proposed by Edward E. Jones and Keith Davis, suggests that people are analyzing the consequences of other people's behavior and actions to guess their motivation, regardless of external or situational factors. Bruce Schneider provided the example of someone violently hitting someone else. Most would assume that this person would be inherently violent, until one tells them that he or she is role playing for a movie and that the camera can be seen in the distance. Information about the context is not taken into account and a false conclusion is drawn. Several television shows use this technique to trap guests and celebrities by hiding contextual information.
3

3

http://www.schneier.com/crypto-gram-0707.html

Introduction Peer to Peer - 16

Since the year 2000, P2P technologies have boomed in a high number of file sharing and chatting applications. Unfortunately, some P2P applications have often been associated with illegal file transfers, copyright infringements on music and films, and all sorts of other illegal or unsafe activities. Those using P2P technologies have been accused of participating in a movement damaging the economy. On the other side of the fence, others claimed that some companies, especially in the media industry, were abusing their dominating position and inadvertently created the context for these new Internet technologies to appear. They claimed these P2P technologies were good, since they allow us to buy songs and exchange movies online, to listen and view them at any time, improving the customer's overall experience. They claimed that all of this should be accepted as part of the natural evolution of economies. Can we really blame P2P technologies for bad behavior, illegal activities and exposure to security breaches? The first P2P application dates back to 1979 and many have been created since. The public started using P2P in the late 1990's as the Internet became more and more available to a wide audience. These applications were not initially designed by intention to perform any sort of illegal activity. Although we can observe a correlation between the increasing number of P2P application users and some copyright infringement activities since the beginning of the Millennium, we cannot infer that these applications are the cause. The absence of access control to resources is not intrinsic to P2P applications. One needs to make a clear difference between access control to resources and P2P software design principles. They are not incompatible and can be implemented together harmoniously. Several P2P applications have been called unsafe. The main argument being that since all sorts of files, including applications, were being exchanged, the risk of virus propagation was increased. Interestingly enough, email applications have never been called unsafe, although emails contribute to the propagation of viruses. Email content, not the application itself, has been blamed. Different perceptions have created different explanations for a unique cause requiring a unique solution: anti-virus software applications. So, is the bad reputation attributed by some to P2P applications fair? Some developers have exploited key features of P2P applications and added anonymity to facilitate anonymous transactions. Some were claiming a right for privacy alibi, while de facto, their applications were about sharing copyright protected content, such as audio files and movies. Consider similar controversy:

Introduction Peer to Peer - 17

should we blame knives and ban them because they have been used by some criminals? Or should we focus on the criminals? Would the elimination of knives prevent criminals from committing crimes? Aren't knives useful in other situations? P2P, itself, is not to blame for illegal activities and does not deserve the bad reputation. P2P design principles have been instrumentalized by some to enable many activities, including illegal activities, but these should not be rejected as a whole. We will see that it is possible to take advantage of all the benefits of P2P design principles without suffering from the abuse of careless or malintentioned individuals, through the use of access control and cryptography, for example.

A Quick Historical Review
More than 40-years ago, the first mainframe computers appeared, allowing remote users to share their usage via a client/server model. These mainframes were expensive items. Users (clients) would access the mainframe (server) with terminal computers performing very basic operations: establishing a connection with the central server, collecting key strokes from users,
ADM-3A terminal

sending them to the mainframe for processing and waiting for feedback, that is, characters to display on the screen. That's it! The communication model between the client and the server was very primitive and the client terminal was completely useless when not connected to the mainframe server. These individual devices were very different from today's personal computers which are capable of much more sophisticated operations. As time went by, mainframes became more powerful and less expensive to acquire. Eventually the need for these computers to exchange information between themselves arose. The first connection was established in 1969 via the ancestor of the Internet, the ARPANET. This type of communication was very different from the passive client/server model described above. Both parties where acting individually, requesting, providing and processing information on their own. In the absence of a connection, each party was still capable of operating on its own. This was not the case with terminal computers. Technically speaking, we can consider this as the first P2P connection between two computers. In 1983, ARPANET evolved into what is now called TCP/IP, a set of protocols to exchange information between remote computers over the Internet. Meanwhile, starting from the end of the 70's, computers became available to individual consumers: the personal computer was born. Some were equipped with the capacity to connect to mainframes or to other computers via telephones and modems. In technical terms, P2P connections could be established between peers. But this is still far from today's definition and the gener-

Introduction Peer to Peer - 18

al understanding of P2P systems and applications. The World Wide Web was introduced in the early 1990's and the usage of TCP/IP increased. More users connected to the Internet and for longer periods of time. Yet, users were still accessing web pages or databases located on a central server and sending their email via mail servers. This way of interacting between computers closely resembles to the 1960's client/server model. To some extent, having to connect to central servers and waiting for responses was nothing different than behaving like terminal computers of the 60's. PC's are left with a lot of underutilized power and resources. One thing leading to another, some developers imagined the possibility of designing P2P-like applications operating directly from PC to PCs instead of going through central servers. This was facilitated by the fact that every PC was capable of establishing connections to other PC's via the Internet. Were these new applications the first P2P applications? Not really. In 1979, Usenet, an Internet application allowing users to post messages, was created. Its true novelty was that it did not rely on a single server, but on a changing set of loosely connected servers. Users could post messages on a server and servers could exchange these messages between themselves in order to make them available to other users. There was no central server or central authority. Decentralization and distributed communication were born. The downside of this is these concepts were only available to servers, but not yet to end users. So, what is P2P precisely? Is the 'absence of central authority or central servers' required to claim that an application or a system is P2P? In that case, Napster, one the most popular early P2P applications would be disqualified for using a central server for indexing shared files. Does 'two peers exchanging files and communicating directly' say enough to claim that we are dealing with a P2P application? Some P2P applications are now used to process data on a large set of computers. This is more than just exchanging files and communicating; peers are providing services to each other. Should this be taken into account in the definition of P2P? P2P covers many facets, as we will see. First, we will explore different types of IT architectures and design principles to refine our definition and understanding of what P2P is all about..

Introduction Peer to Peer - 19

Architectures & Design Principles
Client/Server
The client/server model was the first type of architecture created by the IT industry. It solved a very basic problem related to the nature of early computers: they were very expensive and valuable, since they could perform many operations in a short period of time. This made them a scarce resource desired by many. Since it was not practical to have all potential users work in the room containing the computer, nor to use the same keyboard, terminal computers were created. These centralized computer systems offered several advantages: easy access control, optimized consumption of a resource, and single localization of data and software applications. As computers became increasingly successful, more users required their services. Since a server can only accommodate so many users before experiencing performance degradation, new servers were acquired. Data required to provide services to all users was synchronized between several servers. This increased the maintenance and operational efforts required to mitigate potential inconsistencies. The comfort of single computer systems was gone: software and data was not located on a unique system anymore. This increased the maintenance and operational effort. The need to exchange or to synchronize data between systems on a regular basis became omnipresent. Network communications mechanisms were developed. Information was now able to flow between systems, in quantity.

Database applications were developed to gather, organize and centralize various types of system
information. They represented a great means to protect access to sensitive and confidential information by avoiding dispersion. They reinforced the need for centralized systems. The first software applications using databases were developed; the code was separated from the data source. Several software applications could access the same database in a queue model where

queries were processed sequentially. Remote access mechanisms between software applications
and databases were developed. Software applications could be run on one computer while the database was accessed on another computer. This data exchange between computers led to yet another issue: how to make sure it was not acIntroduction Architectures & Design Principles - 20

cessed by third parties when transmitted between two systems? That is when modern crypto-

graphy emerged as a new science in the 1970's.

Three-tier & Multi-tier
A database system and the software containing the business

logic accessing this database are two different software applications. Software applications have a life of their own: they evolve, new functionalities are being developed and bugs are being corrected. When a new version of an application or a patch is available, it has to be installed on all systems running that application. Keeping such applications in a central location to install upgrades and new versions is far easier than performing the same operation on distant systems. The 2-tier architecture of client/server models became 3-tiers: the data-tier (centralized), the application-tier (most often centralized) and the presentation-tier for end users (decentralized). In order to avoid having to install any software on a user's PC, four-tier architectures, making usage of web/application servers have also been developed. Users can use their application from anywhere in the world via their browsers as long as an Internet connection is available. Software application systems running on several systems are called multi-tier applications, whether they use two, three or more tiers. The division of software applications, in tiers, is a logical division. There is nothing preventing users from running several tiers on one physical machine, although most often, this may result in bad performance issues.

Clustering & Load Balancing
Companies and institutions have increasingly used more and more multi-tier software applications. As expected, increased usage meant increased issues as web servers and application servers received more and more requests from users. Network congestion rendered some systems unavailable or resulted in unacceptable delays responding to user queries. This is comparable to hoards of holiday shoppers in one store or to cars lining a highway at rush hour. Introduction Architectures & Design Principles - 21

The more complex a system becomes, the more prone it is to the single point of failure problem, that is, a situation where one failing server or component of a software application compromises the whole system. The obvious solution was to create redundant servers, either to make sure that one was ready to replace a failing one, or simply to share the workload between them. Two other concepts appeared, server clustering and

load balancing. Server clustering is the idea that a set
of servers, usually located very closely to each other on the network, would work together and be perceived as one unique computer from the outside. In some configuration, each server (master) has one more backups (slaves) and which are kept synchronized with the master. If a master server fails, one of its backup takes over and automatically becomes the new master providing services. Load balancing is about distributing user requests among several servers to make sure services are provided within a reasonable amount of time. This includes detecting a down server and redirecting the traffic away to an operational one.

Service Oriented Architecture & Middleware
Service Oriented Architecture (or SOA for short) aims at defining not only services (usually business processes), but also the IT infrastructure required to operate these processes. The primary concept is that services should not be implemented for a unique software application, but that they should be made available to a broad audience. Applications or other services can invoke them remotely when needed. Databases are an example of shared services for data manipulation and storage. A device providing temperature and humidity in a location is another example of service. Making different software applications or systems work together, old and new, from same or different companies, whether or not they have been developed with SOA, is not automatic. This integration is often performed with middleware: some glue to make the blocks stick together and to operate as smoothly as possible. Middleware helps software components or services, operating on

Introduction Architectures & Design Principles - 22

different systems, with different communication languages work together, regardless of the hardware. It can be implemented as an interface between a database and a web server, or between a finance application developed by one vendor and payroll application developed by another vendor. The shape and structure of middleware is heavily dependent on the blocks it tries to connect. SOA and Middleware are complementary concepts.

Grid Computing
The grid computing concept has risen from the world of distributed computing, that is, the idea of solving problems or storing data on several computers connected together via a network, rather than one computer or super computer containing multiple processors. The set of computers and clusters of computers performing distributed computing are each considered as a resource or node on the grid. Grid computing can be less expensive to perform than centralized computing, since the acquisition of several commodity computers can be much cheaper than the acquisition of a super computer.

Cloud Computing
Cloud computing is the latest emerging concept attempting to name architectural trends it the IT
industry. Just like the Web 2.0 acronym was englobing several technologies and concept in the early 2000, cloud computing englobes SOA while hiding technical details of any underlying IT architecture. Anything consumable on the Internet (service, date, video, applications...) is made available to anyone on the Internet, on demand. It claims to be a step further from the client server model.

About Needs That Have Shaped IT Solutions
By revisiting some IT history and concepts, we can identify some of the core needs that have shaped the development of solutions in the IT industry. Of course, these were not the only forces which had an influence: wars, the economy, marketing, dominating positions – to name a few – also had a great influence:

Remote access to a resource – Early on, engineers had to develop a way to give access a
computer resource from a distant location. The terminal-mainframe model is an example. This included controlling access to these resources. Later, it was not only users who had a need to access these resources, but computer resources themselves. This required a mechanism to locate those resources. Introduction Architectures & Design Principles - 23

Concurrent access to a resource – Engineers had to provide a means for many users to
access computer power and resources available in scarce quantity, thus time sharing was implemented. Each user would be given slices of time to run their application on the unique resource: the processor.

Exchange of information between resources – Engineers had to develop a mechanism allowing the exchange of information between different computer resources located 'far' from each other. This included protecting it from third parties during transportation.

Collection, centralization and organization of information from resources – Following the
dispersion of information and its increasing collection, engineers had to develop systems capable of organizing, storing and processing this data.

Replication of resources – Since a single resource could not always supply for the requests from users, engineers had to find ways to replicate it to satisfy the demand.

Until recently, these needs have been satisfied with client/server-like methodologies and solutions. Today, the power of an average PC is significantly greater than the power of server computers available in the 1960's and 1970's. Everyone has enough equipment and computer power to operate independently from central servers. One can conceptually start from individual resources and have them organize themselves using a collective approach (from the bottom up), rather than organizing them around a central authority (top-down approach). This is precisely the starting point of peer-to-peer computing; a set of individuals working together as opposed to authorities organizing and controlling a society of computers.

What is P2P?
The general idea behind P2P is that computer devices belonging to users should act both as client and server on the network and that they should connect directly to each other, that is, without the need of a central server, to exchange information or services. A P2P software application is one enabling such operations between several computer devices connected to each other via a network.

ICQ
ICQ (pronounced “I seek you”) was one of the first P2P-like applications made available to a wide
4 http://www.icq.com/
4

Introduction What is P2P? - 24

audience. It allowed users to exchange instant messages and to be notified when they were online. It inspired Microsoft, AOL and Yahoo! to create their own version of instant messaging called respectively MSN, Internet AOL Messenger and Yahoo! Messenger. These were not compatible since they were not using a common communication protocol. This has changed since. Purists do not consider ICQ as a pure P2P application, since it is using a central server to identify users appearing on the network and to notify other connected users of their presence. Once the notification is sent, users communicate directly. Therefore it is a combination of client/server and P2P design principles. As we will see further, the localization of a user on the Internet is not obvious. We are nomads in nature and many of us take our computer to work, to an Internet café, on a business trip and back home. On our way, we connect to the Internet from several locations. Even if we keep our PC home, our address on the Internet may change each time we connect to it. ICQ solved the location issue by having users first connect to its well-known central server to give their Internet address (i.e., location), which was then forwarded to other users already connected to ICQ.

Napster
Three years after ICQ, Napster appeared on the Internet in 1999 and provided users with the possibility to exchange MP3 audio files. Users uploaded their file list on a central server. Then, they sent their queries for specific files to that server, which replied with a list of IP addresses (i.e., Internet locations) of users having those files. At last, they established a connection with these users to download files. Of course, there was a risk of obtaining obsolete IP addresses since users would connect from different locations or would be assigned new IP addresses each time they connect to the Internet. This application achieved something that the traditional client/server model never achieved. It was tapping on the local hard drive space of users to store its content instead of centralizing all files in a unique location, creating an unprecedented way of storing data on remote locations. Moreover, it was significantly reducing the traditional network congestion of the client/server model by limiting communications to file lists and requests. Napster would never have succeeded if it had tried to
5 Napster was shutdown in July 2002, but the brand is still used on http://free.napster.com/
5

Introduction What is P2P? - 25

store all exchange files on a central server. The server and the network would never have been able to support all transactions.

Gnutella
Gnutella appeared in March 2000. Like Napster, it was a file exchange application. However, it differed significantly from Napster in its way of establishing contact with other peers and querying for files. Instead of contacting a central server, the Gnutella application would try to connect to a predefined set of nodes to obtain a list of IP addresses of other nodes. It would then try to connect to these nodes to obtain more IP addresses until a sufficient set of successful connection was reached. Unsuccessful addresses were automatically discarded. This type of bootstrapping method made the application decentralized and independent of the current node network topography. Nodes could join and quit the network from anywhere without hampering the systems' capacity to establish connections with other nodes as long as seed nodes were available. Once the contact was established, each node could send file queries to the pool of connected nodes. They would forward these to the nodes they knew, which would forward these to nodes they knew, etc... etc... provoking a cascading effect. When a node possessed the researched file, it would notify the original node sending the query, so that a file transfer could be started between them. Each query would contain a positive number called time to live (TTL) which was decreased each time the query was forwarded to another node. When TTL
6 http://www.gnutella.com/
6

Introduction What is P2P? - 26

reached 0, the query was not forwarded anymore. The list of visited nodes was kept in each copy of the propagated query to avoid loops. Unfortunately, it did not prevent nodes from receiving the same query twice, through different paths. The increasing number of users resulted into an incredible amount of useless traffic between nodes. The consequence was that the network congestion around servers was now propagated around all users. The architecture of Gnutella presented a benefit over the architecture of Napster. The latter could easily be attacked or stopped since it was relying on a central server. With Gnutella, attacking or stopping a node was inefficient, since other nodes could take over and compensate for the missing node.

Kazaa
Kazaa appeared in March 2000 and introduced a new concept: super nodes. Instead of having each node maintaining its own list of shared files to share locally, they were uploaded to super nodes at regular intervals. User's queries were sent to super nodes. Then, these nodes would reply with the list of nodes offering the searched file. Queries were not propagated in all directions anymore. The user could then establish a connection with the remote node containing the requested file and start the transfer. This method induces significantly less network traffic than Gnutella-like applications. Super nodes are automatically chosen by the system according to their capacity (storage, bandwidth, etc...). In this model, some individuals in the community are being given more responsibilities to organize the life of the community.
7

7

http://www.kazaa.com/

Introduction What is P2P? - 27

BitTorrent
BitTorrent appeared in July 2001. It introduced a new way of exchanging files on a P2P network. Instead of focusing on a single peer for the transfer of large files, the query peer would obtain parts of it from different peers simultaneously, creating a torrent of data. This method allows faster download time compared to traditional P2P transfer methods. If you were unlucky and downloaded a file from a peer having a low bandwidth connection, you had no other option than to wait or to cancel the connection and try with another peer, hoping for a better connection. With this new method, even a set of low bandwidth peers can generate rapid transfer times.
8

Freenet
Freenet appeared in 1999 (at least conceptually). The objective of this P2P application was to let its user publish and exchange decentralized information in pure anonymity using cryptography and special routing functions between nodes, making it hard to trace peers querying for information. Other applications such as Napster, Gnutella and Kazaa do not provide anonymity. Users know who they are downloading data from and they also know where users queries are coming from, making it relatively easy to trace them.
9

Pure P2P
A P2P network is often defined as pure when the following criteria are met:
• • •

Flat hierarchy in roles and responsibilities between nodes No central authority managing the network No central authority indicating how two nodes should connect

In that respect, ICQ and Napster do not qualify as pure P2P networks. Gnutella is getting closer, although some of the bootstrapping nodes were initially hard-coded. Other techniques are now available to fetch initial seed nodes, such as reading a file from a specific location on the network. Its content would indicate where to locate active seed nodes.
8 9 http://www.bittorrent.com/ http://freenetproject.org/

Introduction What is P2P? - 28

Pure P2P networks are impractical since not organizing the traffic between peers using efficient methods results in a poor performance of the system overall. Some peers need to have more responsibilities than others to manage the network and to help new peers to find other peers.

Initial Objectives and Evolution
At the beginning of the millennium, the initial objectives of P2P were multiple. They started with chatting, then with file sharing and escaping central server computers in general. However, these early objectives obscured another goal of P2P application: distributed computing. One of the most successful examples is the SETI@home project . Internet users can download a free program that would use the idle time of their computer to analyze radio telescope data. When finished, the results are sent back to a central server and new data is downloaded for analysis. Although this application is not P2P in its design, it illustrates how many computers can solve a large divisible problem. A real-life example of divisible problems is mowing the lawn. One person can do it alone or several can simultaneously do it by taking care of a part of the yard. There are some indivisible problems, such as checking one's account balance when withdrawing money. You need to centralize all account transactions in one location in order to compute the balance and make sure there is money available when performing the withdrawal. However checking many balance accounts is a divisible problem: the account checking can be spread over a set of computers. Each account can be verified simultaneously. In general, indivisible problems are better served in a client/server model and divisible problems in a P2P model. One will notice that, excluding semantics, grid computing and a P2P network of computers performing distributed computing is virtually the same thing. Both systems have to satisfy the same core needs to locate resources, request services, access, exchange and collect information remotely. A surprising evolution of P2P is Skype, the application allowing us to phone for free with our computer anywhere around the world. This ground breaking technology has had a tremendous impact on the telecoms industry. Today, some are trying to develop P2P television, but they are facing issues with network bandwidth availability. To summarize it, P2P is the last extremity of a continuum starting from the mainframe-terminal concept and going forward to the client-server, multi-tier, SOA and cloud computing concepts. As much as a single mainframe is impractical to use by many, as set of pure P2P devices are impractical to operate globally. So far, all successful operational systems and architectures have been
10 http://setiathome.berkeley.edu/
10

Introduction What is P2P? - 29

implemented somewhere between those two extremities.

Benefits
The common benefits associated with P2P applications are:

Tapping into resources at the edge of the Internet – Instead of relying on a central server
to perform many operations, P2P attempts to maximize the utilization of resources of client PCs (memory, processing power and storage capacities) instead.

Reduced network traffic – If more work is performed at the edge of the Internet or if resources are distributed between nodes, then there will be less traffic and network congestion around servers. However, we have seen that if the search mechanism for resources across peers is not well implemented, it can generate a lot of useless traffic.

Cost savings – If work can be done by peers, then there is no need to buy a server to do
it. Therefore, one can save money in material and maintenance.

Faster information delivery – We have seen that high volumes of data can be generated
by downloading data parts from multiple peers simultaneously. This is more efficient than acquiring a bigger bandwidth between two entities where only one end is transmitting data.

Scalability – If you need extra processing power for a P2P application, you just need to
add extra nodes which is easier than installing another server. This can be useful for divisible problems .

Self-organization – Nodes arrive and depart at frequent intervals in P2P systems. Despite
this chaotic activity, P2P systems can re-organize themselves automatically.

Network fault tolerance – If one peer goes down the network is still alive, another one can
take over. If a server is down that is not (always) true.

Pervasiveness – This is the capacity to reconnect with peers and services that have
changed location on the Internet. It allows users to behave like nomads on the Internet.

Drawbacks
The common drawbacks associated with P2P applications are:

Non-deterministic services – Since peers connect and disconnect to the network more often than servers, there is a higher risk of resource or service unavailability. However, if the

Introduction What is P2P? - 30

resources and services are duplicated on another peer, this problem can be mitigated. If two peers request the same service or resources on a P2P network, they may obtain it from different peers via different routes, with different bandwidths, resulting in different service quality.

Content ownership infringement – Early P2P allowed fast distribution of any content, including copyright protected content. However, some control on who-exchanges-what-withwhom can be implemented now within P2P applications, limiting the massive illegal propagation of resources. Sharing content or resource is a matter of trust. There is nothing that can prevent someone with bad intentions from distributing protected content with permissive applications.

Absence of central control – The fact that P2P applications allow the exchange of direct
information from one peer to another means that improper content can be transferred too, such as child pornography or terrorist documents. The flip side of this argument is that a complete central server-like type of control would still not prevent users from exchanging this kind of information. They would simply do it by other means. There is a fundamental conceptual flaw with the idea that control needs to be central. Control is about trust. Whom do you trust? Why? And what privileges do you grant to that person or entity? When one receives a driving license, one does not need to show it to the administration each time one drives its car. A policeman can verify it at anytime, anywhere. Control is very often distributed in our societies. This is also true in client/server model where multiple web servers can verify cryptographic keys and messages generated by servers they do not need to contact. The very idea that one has to control a device to control its interactions, in combination with the fact that early P2P applications had no controlling features, led to the belief that P2P was intrinsically unsafe. If many devices can perform controlling operations alone in a client/server model, why could not they in a P2P model?

Some have mentioned that profitability is a drawback of P2P systems, since transactions are not performed via a central authority, and therefore cannot be registered and billed. However, there is nothing preventing one from selling licenses of limited duration to access content on a P2P network.

Introduction What is P2P? - 31

So, What Is The Use of P2P?
Traditionally, P2P is introduced in opposition to the client/server model. The qualities of P2P systems are described by comparing them to those of the client/server model. But is this enough to establish an identity? Is a hammer better than a wrench? Do we define hammers by comparing them to wrenches? No, we tend to describe hammers by what you can do with them. A hammer is more or less useful than a wrench depending on the situation and the task that has to be achieved. If computers were bricks, P2P would be an excellent mortar! In addition to the benefits we described earlier, many readers will have identified P2P as a natural way to implement middleware solutions and service-offering architectures. Implementing clusters of computers is something natural for P2P systems, since they inherently need to organize themselves to operate efficiently. Performing distributing computing with load balancing is possible with P2P. Redundancy can also easily be implemented in P2P systems. The monitoring of other peers is something common. P2P has the potential to support, enhance and transform many methodologies and techniques traditionally used in the IT industry to develop systems and software. It can easily welcome the existence of powerful servers on the network and let other peers behave like clients, utilizing the server for indivisible problems. However, P2P will never be good at replacing multi-tier applications and will most probably never replace the World Wide Web technology, since the latter requires fixed servers to fetch web pages. Using P2P would not bring any added value to the current implementation of the World Wide Web.

Towards Universality
In order to implement P2P universally, one needs to establish a common communication language between peers, regardless of the technology they are using. One also needs to organize their transactions. This can be achieved with protocols. In a broad sense, a protocol is a set of rules explaining how an activity or a transaction should happen. Every society and culture has its own rules and ways of organizing itself. Signs, gestures and comments do not always have the same meaning from one culture to the other. The birth of a diplomatic protocol is driven by the necessity to establish a communication channel between at least two different societies or cultures. The immediate effect is the creation of a new set of meanings between the two parties: 'if you do this in that context, it will mean that'. This new set of meaning may not be compatible with all the rules of one culture or its habits. However, if the Introduction What is P2P? - 32

benefit of understanding each other is higher than the cost of adopting this new set of rules, the protocol will be adopted and utilized. What about IT? Just like diplomacy helps countries, cultures and nations to communicate and to understand each other, we have seen that the IT industry gradually required 'something' to help its multiple systems and computers communicate together. Many networking protocols and sets of protocols were created to solve this problem. A natural selection has happened resulting in the selection of TCP/IP (Transmission Control Protocol / Internet Protocol). In fact, it is not a unique protocol, but a suite of communication protocols allowing computers and devices to communicate over what is now called the Internet. One may wonder that since there is a protocol allowing computers to communicate directly between themselves over the Internet, why should we need a universal P2P protocol at all? In theory, we could rely only on TCP/IP to create a universal P2P application, or at least, a means of P2P communication between systems using different technologies. That is what we already do, to some extent. If I know the IP address of my correspondent, TCP/IP will establish a connection with that correspondent for me. If we know the link to a website, www.sun.com, our PC can find the corresponding IP address via a technology called DNS (Domain Name System) and TCP/IP will establish a connection to it. So, what's the big deal? The big deal is that: a) There is no such thing as one IP address per user on the Internet today. When you switch on your PC or connect to the Internet, you are very often assigned a dynamic IP address which will remain valid for the duration of your connection. If you move to a wireless network, you will connect to the Internet via a different IP address. We can't rely on identifying a peer by its IP address, only. Some will say that version 6 of the Internet protocol should provide a sufficient number of addresses. This is true, but that is not the only problem to solve as we will explain later. b) In order to locate a peer, we could use the DNS mechanism to resolve the IP address of a computer from its name. Each peer could be assigned a unique name and we could use DNS to retrieve its IP address. Each time a peer would connect to the Internet, it would send its IP address to a central server – à la ICQ – to the attention of other peers. But, using DNS servers to locate peers on a P2P network implies using central servers, which is against the P2P philosophy. Moreover, who would maintain these servers? c) Relying on TCP/IP means that one would be tied with a specific technology to implement Introduction What is P2P? - 33

a universal P2P solution. Some protocols within TCP/IP are directly related to hardware technologies. What if TCP/IP were completely replaced with a new technology or with new types of hardware from which new communication protocols would be derived in the future? Your P2P application would become instantaneously obsolete. You would have to rewrite (at least) the transportation layer of your code. d) TCP/IP enables communication between computers, but does not guarantee that what is being communicated will necessarily be understood by the other party. A common language to exchange information and organize transactions between peers is still necessary. Therefore, defining a P2P protocol independent of any platform implementation is a necessity to achieve universal objectives. This is where JXTA comes into play.

JXTA
Introduction
JXTA, pronounced 'juxta', comes from the word juxtapose. JXTA reflects the operations by which peers establish temporary associations to form a P2P network; they juxtapose themselves to each other. JXTA is not a software design philosophy and it is not a software application. It is a set of protocols that software developers can implement using their own technology to establish P2P connections with other peers using identical technologies or different implementations of JXTA. For example, a group of developers can implement JXTA in Visual Basic under Windows XP. Another group could do the same in C++ under Linux and a third group could implement the JXTA layer on a hand-held device in Java. They would all be able to find each other on the Internet and to start exchanging any kind of information or services between them, despite the use of different underlying technologies. The JXTA protocols are designed to be independent of transport protocols and make few assumptions about network transportation mechanisms between computers and electronic devices. In other words, JXTA does not take the responsibility of explaining how messages should physically be exchanged between peers or from a technical point-of-view. Introduction JXTA - 34

JXTA imposes a common structured language to issue and exchange messages between peers: XML (Extensible Markup Language). Although this language is readable by human beings, which is a benefit, its verbosity has often been pointed as a weakness regarding application performance. XML documents are usually bigger than traditional binary data documents containing the same amount of information. This issue can be me mitigated by the use of data compression within XML documents. Contrary to binary data documents whose data can have any structure, the structure of XML documents must comply with well-known standard rules. There is no need to code specific structure rules in your application, like for binary documents. The generic XML rules are good enough to read and manipulate any XML documents, even if they have been created by a software application developed in a different programming language than yours. This is a huge benefit, since less code is required to manipulate and exchange data openly between peers. The cascading effect is that your software application is less complex, contains less code and requires less testing; therefore, it is less prone to bugs. The fact that JXTA defines its protocols independently from any other technologies and that it has chosen a neutral technology to communicate messages between peers implementing its protocols guarantees its universality. Of course, its implementation on specific platforms and the choice of a network transportation layer between peers creates specific technical issues which have to be solved by each implementation of JXTA locally. This preserves its universality.

The Three Layer Cake
Conceptually, JXTA is made of three logical layers: 1. Platform – This layer is the base of JXTA and contains the implementation of the minimal and essential functionalities required to perform P2P networking. Ideally, JXTA-enabled peers will implement all JXTA functionalities, although they are not required to. This layer is also known as the core layer. Applications Services Platform
Three Layer Cake

2. Services – This layer contains additional services that are not absolutely necessary for a P2P system to operate, but which might be useful. For example: file sharing, PKI infrastructures, distributed files systems, etc... These services are not part of the set of services defined by JXTA. 3. Applications – P2P applications are built on top of the service layer. However, if I develop

Introduction JXTA - 35

a file sharing application and let other JXTA based applications make requests to my application, the other applications will perceive me as a service. Therefore, the border between a service and an application depends on one's perspective. As JXTA and the IT industry are evolving, the application layer concept is becoming somehow meaningless. One should focus on the platform and the service layers. JXTA is not an operating system and (most probably) will never become one.

The JXTA Project
The JXTA project was started by Sun Microsystems, Inc. in 2001 and is “re11

sponsible for the formal specification and documentation of the JXTA Protocols”. It is maintained by a group of
people which anyone can join. The official website was accessible from https://jxta-spec.dev.java.net/. It is now officially moving to http://jxta.kenai.com. There you can download the latest version of the official document describing the JXTA protocol in HTML or PDF format. Other information such about the board of directors, governance and the mailing lists can be found.

JXSE Community
JXSE is the implementation of the JXTA protocols in the Java programming language. The JXSE acronym is more and more used to distinguish the protocols from their implementation in Java. Until recently, the source code and the downloads where available from: https://jxta-jxse.dev.java.net/.

11

http://www.sun.com/

Introduction JXTA - 36

However, the site is officially moving to http://jxse.kenai.com/. The source code, the javadoc, the .jar files, the dependencies and the tutorial code examples can be downloaded from there.

C/C++
Two web pages for the implementation of JXTA in C/C++ are available from: https://jxta-c.dev.java.net/ and http://wiki.java.net/bin/view/Jxta/JxtaC. The C/C++ implementation of JXTA can be downloaded from http://download.java.net/jxta/jxtac/2.5.2/ and the API documentation is available from: http://rdv.jxtahosts.net/jxta/api-doc/jxta-c/. However, this project has not been active recently.

JXME
JXME, an implementation of JXTA for Java ME (Micro Edition) is available from: https://jxta-jxme.dev.java.net/. As a reminder, Java ME is a reduced version of the Java platform facilitating the development of software applications for small devices, such as cell phones and PDAs. JXME is delivered in API (Application Programming Interface) bundles called: configuration, profiles and optional packages. A configuration bundle provides the virtual machine features and a set of libraries that must be available as part of a specific implementation of the Java ME environment. It is a building block. A profile bundle is another building block providing a set of API for a specific category of devices. The combination of both enables the implementation of Java ME for a specific category of devices. This implementation can contain additional optional packages. JXME should operate on devices using an implementation of Java ME based on the Connected Limited Device Configuration (CLDC) - Mobile Information Device Profile 2.0 (MIDP) combination. It should also operate on Connected Device Configuration (CDC), which is a fully compliant implementation of the Java virtual machine optimized for small devices. Unfortunately, this project has not received much attention recently.

Documentation, Forum & FAQ
The JXTA / JXSE Programmers Guide are available from the Tutorial link on the JXSE website. Introduction JXTA - 37

Guides in preparation are available from the De-

velopers link.
The forum is still available from http://forums.java.net/jive/forum.jspa?forumID:50. Anyone is free to register and to ask any questions related to the implementations of JXTA by starting conversation threads. Technical issues can also be submitted. The future of the forum is unclear as the projects are moving to Kenai. For more information, one should register to the mailing lists still operating from the Java.net (as of the publication of this book) . One can also access the following web page for frequently asked questions over JXTA: http://wiki.java.net/bin/view/Jxta/JxtaFAQ. http://kenai.com/projects/jxse/pages/FAQ. This will progressively be replaced by:
12

12

See https://jxta.dev.java.net/servlets/ProjectMailingListList.

Introduction JXTA - 38

Understanding JXTA
This chapter presents the JXTA concepts and how they work together. Since most of its content is conceptual, several metaphors are used to facilitate the understanding. We will first introduce each concept individually and progressively explain how these operate with each other. We will also focus on some JXTA implementation challenges, but we will not explain how these have been overcome from a technical point-of-view. This is mostly a functional chapter.

Introduction
A Tribes-In-Islands Metaphor
One good way to help create meaning in a world that is unknown to us is to use metaphors. Let's imagine several hundred tribes, each living on their own island (or set of islands), in the middle of an unknown ocean. Each tribe has a king or a queen and a unique distinctive sign (a flag, an animal or a symbol) that helps to distinguish itself from other tribes. Some islands are in close proximity, others are distant. Each tribe grows its own type of crops. Some fish, others raise some type of livestock. Some have developed special skills like working iron, drawing maps or curing diseases. Some tribes growing the same kind of crops want to organize themselves in groups to create markets. In the real world, the king or queen of a tribe is a human being and an island is an electronic device capable of running an implementation of the JXTA protocols, that is, a JXTA peer. All tribes are willing to travel from island to island to exchange products or services they do not produce themselves to satisfy their needs. This is the concept of communication between JXTA peers. They all have boats to navigate over the ocean. Some tribes have mastered the ability to fly from island to island, but your tribe does not master this technique. Each tribe speaks its own language (or eventually shares one in common with others), but all have agreed on a minimal dialect that helps them communicate with any other tribe, regardless of their language. This is XML, the language selected by JXTA . The king or queen of each tribe is able to write down notes on dried leaves, using the minimal dialect, in order to communicate with other kings and queens. You are the ruler of a tribe and you have recently heard about two new services offered by other
13 Newcomers to JXTA are often scared by the fact that data transfer with XML documents is always more voluminous than with binary documents. The JXTA specification document defines two binary message formats to solve this issue.
13

Understanding JXTA Introduction - 39

tribes: astrology predictions and a self-service weather forecasting method. If you provide your birth date and your birth location to the tribe's astrologer, he or she will predict your future. The weather forecast method has been written in your language (i.e., not the minimal dialect which is too basic anyway) and you are interested in acquiring it to perform it as a service yourself for other tribes in the area. In other words, you are (for example) interested in loading the weather forecast service written in Java on your device running JXSE.

The Concepts
Overview
The JXTA specifications define several abstract concepts referencing each other. We will cover these one by one in the coming pages, but do not panic if you do not grasp the complete meaning of each concept right from the start. It will become more and more clear as you read further down this chapter and explore the code examples provided later in this book.

Don't forget that JXTA specifications are abstract. They need to be implemented using a specific programming language and/or platform to become operational. This book focuses on JXSE, the Java programming language implementation of JXTA. In order to understand JXTA, we also need to explain how and why its concepts have been selected and implemented this or that way in JXSE. Otherwise, we take the risk of losing the reader in abstractions. We will frequently switch from JXTA to JXSE and vice-versa to facilitate the description of JXTA. Of course, JXSE is not the only way to implement JXTA. Don't forget that there are many ways to

Understanding JXTA The Concepts - 40

comply with JXTA specifications. The methods and techniques chosen by those who have implemented JXSE are not necessarily the same methods and techniques others would use in different implementations of JXTA. The figure provides a general overview of JXTA concepts and the relationship between them. The basic principle that one should keep in mind is that, conceptually, nearly everything is a resource in JXTA. Peers are resources, resources are located on peers and peer groups, and resources are accessing or consuming local resources or resources located on other peers. The resource concept is the Ouroboros of JXTA. The two main exceptions are advertisements which represent resources and IDs which identify resources.

Peer
For JXTA, a peer is “any networked device (sensor, phone, PDA, PC, server, supercomputer,

etc.) that implements the core JXTA protocols ”. In our metaphor, a peer is the king or queen of a
tribe, which we shall sometimes refer to as the ruler. For the time being, we will consider that a human will use one and only one electronic device at once. Hence, we do not make a difference between a peer and a human being using a device running JXTA. Technically speaking, the tribes are actually running the JXTA protocols. An island and its tribe is a networked device running a software application implementing the JXTA protocols. A tribe is not a peergroup in our metaphor. Some tribes are nomadic in nature and travel from island to island with their ruler. We can use several computers (one at home, one at work, etc...). Our PCs can sometimes be used by other members of our family or by our colleagues. Thus, the island is temporarily invaded by other tribes. So, what is the difference between a peer and human being using its device? Fact is that with JXSE, you can save different configuration files on the same computer (one per user for example). It is even possible to run several instances of P2P applications simultaneously on the same device. This is comparable to having several tribes occupying a big island. Technically speaking, a peer is a tribe and its leader with its configuration files. These could eventually be located on a memory stick, meaning that a tribe can run JXTA-enabled software applications from many devices (i.e., islands). JXTA requires that:

“A peer should not make any assumption about the runtime environment (island shape or size) or programming language (tribe language) of other peers”.

Understanding JXTA The Concepts - 41

“A peer should not make any assumption about the capabilities or complexity of the net-

work of peers supporting the JXTA protocols ”. There are small and big islands, close or
distant, easily reachable or not, with big and small tribes, providing little or many products or services.

“A peer wishing to interact with other peers through JXTA should implement the protocols

it decides to implement fully, not partially” . Kings and queens should play the game of exchanges according to the rules.

“A peer should cache advertisements and forward messages for other peers, although

this type of participation is optional”. Being good to the community helps.
A peer can take different responsibilities within a JXTA network. It can be a simple peer, connecting from time to time to the network and performing exchanges with other peers. It can also be a

rendezvous peer, that is, a tribe facilitating the research of other tribes and of services provided by
other tribes. Another type of responsibility is being a relay peer. Sometimes, tribes are located on remote islands or surrounded by unbridgeable coral reefs (firewalls, NAT, router, proxies...). Contrary to rendezvous peers, the relay peer concept is not covered by the JXTA specification document. It is a necessary by-product of the implementation of JXTA in Java over TCP/IP. We will describe this later. JXTA peers are not obliged to implement all JXTA protocols to participate on a JXTA network, but they are required to implement at least some of the core protocols described in the JXTA Core

Specification together with corresponding concepts to make them operational. In other words,
kings and queens must (at least) participate in the process of finding routes from one tribe island to another. Metaphorically: These minimal responsibilities consist in i) letting boats from other tribes moor on your island to deliver messages, ii) helping tribes find a route to their destination if such information is available, and iii) preparing your own dried leaves and ink in order to write messages to the attention of other tribes.

Understanding JXTA The Concepts - 42

Consider that a ruler is not obliged to answer all requests from other tribes. He is free to do what he wants with the messages he receives (deleting, answering or storing them for the future), whenever he wants. Let's imagine that Panama was a huge island covering all the Americas from Alaska to the bottom of Argentina and that its famous canal was not built yet. The shortest trading route from Cuba to Hawaii would be to navigate to the narrowest strip of land in “big” Panama, unload goods, cross the land strip, reload the goods on another boat and navigate to Hawaii. In JXTA, the ruler of 'big' Panama does not have the obligation to facilitate the exchange of goods from Cuba to Hawaii through the land strip, although it would be welcome. However, it should indicate the routes it knows to reach Hawaii if Cubans ask them. Currently, peers are characterized by an ID, called PeerID. There is currently no user concept in JXTA and JXSE. This ID is part of the configuration parameters of the application running the JXTA protocols. This can be confusing because a human being can be running multiple instances of the application on one or many devices, using one or many peer IDs, which can cause strange behaviors. This issue was not anticipated in the initial design of JXTA.

Peer Group
A peer group is a set of tribes having some common interests who have decided to organize themselves as a group. In JXTA, there are two fundamental peer groups called world peer group and the net peer group. They both have unique IDs known by all applications implementing JXTA. Typically, a peer always connects to the JXTA network via at least one peer group by establishing connections with other members of this peer group. The key fact to remember is that a peer can belong to many peergroups at once while being connected to the JXTA network. That is, it can operate many different transactions with many different peers belonging to many different peergroups at once. The world peer group must implement at least the minimum services required to establish connections with other JXTA peers. By default in JXSE, the world peer group implements all the services

Understanding JXTA The Concepts - 43

defined as part of the JXTA specification document, although it is not required to do so. This is related to the fact that a peer may (but does not have the obligation) to implement all JXTA protocols. Peer groups are created according to a hierarchical structure where a child has one and only one parent. For example, the

beef merchants peer group is a child of the cattle raisers peer group, which is a child
of goods merchants peer group, which is a child of the net peer group. By default, the parent of the net peer group is the world peer group, although this is not an absolute requirement. Typically, a JXSE peer will not connect to JXTA through the world peer group, but rather via the net peer group, which inherits of the services made available from its parent, the world peer group. All additional peer groups created by peers should use the net peer group or any sub-peer group of the net peer group as the parent, although it is also technically possible – but not recommended – to use the world peer group as a parent in JXSE.
The last thing to remember is that peer groups are considered as a type of module in the JXTA paradigm.

Metaphorically: The world peer group could be (more or less) compared to Gaia, the Greek goddess personifying earth, or any other religious deity that has created the world, and the net peer group could be compared to humanity, that is, the world population. Humanity uses resources of the world to perform its activities.

Service
The JXTA protocols are implemented with the help of services and modules. These are the basic entities representing 'things' a JXTA peer must know how to 'do' to operate on the JXTA network. Services and modules are constituents of the glue that makes the JXTA network stick together. The other constituents are standard messages defined in JXTA. At first, the distinction between modules and services in JXTA is not obvious. The relationship between both concepts is not explicitly described in the protocol specifications. However, a module is defined as “an abstraction used to represent any piece of code used to implement a behavi-

or in the JXTA world”.

Understanding JXTA The Concepts - 44

On the other side, there are many services described in the JXTA protocols specification document. These 'behavior' specifications can be considered as functionality specifications. Hence, the implicit link between modules and services is that each service is ultimately implemented as a module. Services can be immediately loaded and available on the local peer, or can be accessed remotely using a pipe or another proxy module. Eventually, an authentication module can be used to check communication with the service. The code can also be fetched from a remote location and loaded later. The publication of a service advertisement should contain all necessary information explaining how to use it or to invoke it. The JXTA specification 2.0 mention two types of services:

Peer Services, where individual instances run on each peer. If a peer goes down, the individual service goes down too. Each instance of the service should publish its own advertisement.

Peer Group Services are published within peer group advertisements. Instances of these services run on each peer participating to the peer group. Typically, these services may communicate with each other.

Moreover, a JXTA-enabled service is defined as a service published using a Module Specification Advertisement . Warning: All these types and sub-types of services, together with their publication processes, can be confusing. For example, the difference between a peer service and a JXTA-enabled service is unclear. This will most probably be clarified in future versions of the JXTA protocols. For the time being, one should remember that, in practice, peers are modules creating peergroup modules and that services (which are modules too) are attached to peergroups. A peer communicates and operates with other peers using the services attached to the peer groups it has created. Customized or additional services can be loaded on peergroups created by the peer too. JXTA defines core and standard services, these implement the protocols that we will describe later:

14

Access Service – This is the service verifying the credentials and information of a ruler
making a request to access a resource from a tribe or a peer group, in order to find out if he or she has access to what is requested.

14

We will cover module specification advertisements later.

Understanding JXTA The Concepts - 45

Discovery Service – This is the service allowing tribes to search for other tribes or peer
groups within a peer group. Technically speaking, they will search for the advertisements representing them. The discovery service can also help searching for other types of resources, such as routes to islands or trading routes between tribes. Warning: Newcomers to JXTA often believe that discovery means finding out whether a peer is connected online. Consequently, they implement complex strategies in JXSE involving expiration of advertisements to check whether peers (i.e. devices) are connecting or disconnecting to the Internet. They republish advertisements at regular interval as a

'proof' that a peer is alive. Soon, they get frustrated because this technique does not work
for reasons that will become clear later. In the JXTA paradigm, discovery means discovery of advertisements describing resources (such as peers, peergroups, services, etc...) within a given peergroup. It is NOT the instance of these resources themselves. It is like confusing a Class and an object instance of this class in the Java programming language.

Endpoint Service – This service is responsible for transmitting a message from one peer
to another peer.

Membership Service – This is the service used to allow or reject a new request for membership in a peer group. It can be as simple as always approving a new member or more complex, like using a voting procedure. A tribe willing to join a group must first find one of its members and request to join the group. Warning: Many newcomers to JXTA, and more specifically to the JXSE technology, are often disappointed by the currently available implementations of the membership service. Their expectations are high and not met. This situation will surely improve in the future releases of JXSE as there is a growing demand in the community.

Peer Info Service – This service helps peers find about the status of other peers in a peer
group.

Pipe Service – This service creates trading routes between one or many tribes (not islands) belonging to the same peer group.

Rendezvous Service – This service is operated by peers acting as rendezvous to facilitate
the efficient forwarding of queries to peers belonging to the peer group.

Resolver Service – This service is used to address queries made by a tribe leader to anUnderstanding JXTA The Concepts - 46

other tribe leader and to collect responses. Some services implement core specifications that all JXTA implementations should deliver. Other services are considered standard and should preferably be implemented, but this is not mandatory. Remaining services are not mandatory.

Service/Functionalities Endpoint Service Resolver Service Discovery Service Peer Information Service Pipe Service Rendezvous Service

Requirement Core Core Standard Standard Standard Standard

Resources
There are five basic types of resources in JXTA: peer groups, peers, pipes (i.e. trading routes between tribes), contents and services. A resource is something conceptual that is uniquely identified with an ID in messages and advertisements exchanged between peers. It is the most abstract concept in JXTA. Resources are represented by usually one, but sometimes up to three advertisements in JXTA.

Advertisement
In JXTA, an advertisement is what represents and describes a resource using the minimal common dialect understood by all tribes (XML). It may also contain configuration information about a resource. In our metaphor, advertisements are written down on the dried leaves prepared by each tribe and exchanged among them. Typically, your tribe, like any other tribe, will notify its existence to other peers with an advertisement. This is also true for peer groups and all other JXTA resources. There are several types of advertisements, for example: peer advertisements, peer group advertisements, rendezvous advertisements, etc... Conceptually, it is not uncommon to confuse advertisements representing a resource with the resource itself. We often talk about discovering resources, but as mentioned earlier, what we really mean is discovering advertisements representing these resources. Accessing those resources is a completely different operation.

Understanding JXTA The Concepts - 47

Warning: It is key to remember that if an advertisement describing a resource is found, it does not necessarily mean that an instance of that resource is 'up and running' on the JXTA network.

Peer Advertisement
A peer advertisement contains at least a peer ID and the ID of the peer group it belongs to. Eventually it can contain a name, a description of the peer, an endpoint address (i.e., the location of the island you are currently occupying) and attributes such as being a rendezvous for a peer group. Warning: Earlier, we said that peers could participate to many groups simultaneously Since each group has its own peergroup ID, this means that multiple peer advertisements exist for given peer. This is can be confusing if one assumes that a peer should be represented by one advertisement only. Fact is, each peer advertisement should be published in its corresponding peergroup. A peer advertisement is an advertisement in a group. Metaphorically: Peer advertisements are similar to passports and driving licenses. They both contain a picture representing you, but are not physically you. You may have both a passport and a driving license which both represent you in different communities. A credit card is another example.

Peer Group Advertisement
A peer group advertisement contains at least the ID of the peer group and eventually a name and a description of the peer group. Typically, it designates a set made of peers who have agreed to operate a common set of services for the community they constitute. The list of IDs of these services is also part of the advertisement.

Publication
Advertisement publication is a common operation in JXTA. It may consist of sending copies of an advertisement to one or many members of your peer group. This is called remote publication. Publication can also be performed locally, meaning that other tribes will have to come to your island to find out about the advertisements describing what you have to offer. Typically, a peer will locally cache its advertisements and those received or fetched from other peers for future use, improving general responsiveness of the JXTA network by avoiding unnecessary queries. An advertisement is always published with a limited duration. When it has expired, the advertisement should be considered as obsolete.

Understanding JXTA The Concepts - 48

The publication of a peer group advertisement is always performed in the peer group itself and the parent peer group of that peer group. This enables parent-child relationships. Metaphorically: A tribe leader may keep the dried leaves describing other tribes, group of tribes and resources they have to offer in a small box. After some time, some dried leaves will be too rotten or too damaged to be read and new ones should be fetched from remote tribes. A leader can also decide to burn all his dried leaves if he or she wants. Warnings: A tribe leader should never forget that in the process of searching for other tribe advertisements, for example, his people may get lost at sea, say, because of a storm. It does not mean that the queried tribe (or resource) description does not exist. On the other side, it is not because one has a copy of a tribe advertisement (or resource advertisement), that the tribe (or service) still exists (or is available). Volcanoes do erupt and tsunamis do happen. Some tribes truly disappear forever while copies of their advertisements still exist in other tribe's box of dried leaves. This is not to be confused with tribes who are in hiding in a mountain cave for some period of time (i.e., a device is disconnected from the network). Just because you can't reach them does not mean they are gone forever. Conversely, new tribes may appear. Yet, you will not know about them unless you specifically search for new tribes or they get in contact with you. Your box of dried leaves is a temporary representation of the reality, but not the reality itself. The validity of the information contained in your box degrades with time. At last, a leader should not make any assumption about the time its people will need to fetch messages and advertisement from other tribes. They may travel long distances before coming back with results. This leads to another issue: what if a tribe has disappeared completely? You cannot ascertain with a situation whether your peers are lost at sea or still searching. The solution is to set a time limit and assume that a tribe has probably disappeared if you cannot get an answer from them.

ID
In JXTA, an identifier (ID for short) is a unique reference to a resource. Different resources have different IDs. Different types of resources have different type of IDs. For more details, the reader should read the JXTA specification document. Metaphorically: IDs are the distinctive sign of each tribe or peer groups, for example.

Understanding JXTA The Concepts - 49

Content
A content is something 'material' (like a text file, a PDF file, an image or some binary code) as opposed to services which do not have physical properties. However, the implementation of a service is something material. Metaphorically: This could be the cargo carried by boats across the ocean between tribes (bananas, chickens, precious wood, etc...) or the weather forecasting method written down on a dried leaf.

Codats
Each content is published with a unique ID. The combination of a content and an ID is called a

Codat. It belongs to a peer group. If the same content has to be published in two different peer
groups, two codats are required. You can also create two codats for the same content in the same peer group.

Pipes
Pipes are means for peers to exchange messages. Messages can be propagated from one peer to one or many peers. If there is only one destination, a pipe is called a point-to-point pipe. If there are many destinations, they are called propagate pipes. JXTA also defines a secure unicast pipe to exchange information in a secured and confidential way between two peers. To send data from one peer to another, a peer packages the data to be transmitted into a message and sends the message using the output end of a pipe. On the opposite end, a peer receives a message from its input side and extracts the transmitted data. Metaphorically: Pipes are trading routes between tribes and their ruler, not islands. Tribes can relocate to new islands (i.e., change of IP address or devices). A message forwarded via an established trade route should reach the proper tribe, no matter its location. Don't forget about rulers using memory sticks, their messages should be forwarded to the proper island (i.e., the device where the memory stick is used).

Module
A module in JXTA is a set of functionalities that a peer can use, offer or obtain from another peer. It is an abstraction for services and applications in the three layer cake model . A module can be initialized, started and stopped. In JXTA, an application is a module that can be loaded and ex15 See page 35.
15

Understanding JXTA The Concepts - 50

ecuted on a device. It may eventually implement the JXTA protocols as services. However, remember that the application concept in the 3 layer cake is becoming obsolete. There are 3 type of advertisements associated with modules:

Module Class Advertisement – This advertisement simply declares the existence of a
class of modules, but does not provide any information about their implementation or how to use them. It contains a Module Class ID, the name of the class of modules and its description. A typical example is the peer group concept.

Module Specification Advertisement – This advertisement provides some interfacing characteristics of a module . This advertisement contains a unique Module Specification ID, a name, the name of the module creator, a URI to a specification documentation, a specification version number, a specification description and parameters (usually IDs of other module specification) for the specification. Typical examples are: the world peer group, the net peer group, a customized peer group... Each can offer a different set of services. It can contain also contain a pipe advertisement to communicate with other instances of modules of this specification, or the module specification ID of a proxy module which can be used to communicate with other instances of modules of this specification. Lastly, it can also contain the module specification ID of an authentication module which may be required to communicate with other instances of modules of this specification. Remark: This is not very easy to understand at first. In our metaphor, we mentioned an astrology service. Typically, its module specification advertisement would contain at least the following mandatory information: ID=34 and version=1.0 . We could include the Module Specification ID of an authentication module to make sure that those requesting astrology services have the right to do so. We should also include a pipe advertisement that peers willing to use the astrology service should use to get in contact with an astrologer. We could also use another method to communicate with the peer running the astrology service. We could specify the module specification ID of a proxy module and have the as17 16

16 17

Conceptually, this is more or less corresponding to the interface or abstract class API concept in the Java programming language. Functionalities are described but those objects still need to be implemented in order to be instantiated. This would be the functional version of the module, not the implementation version.

Understanding JXTA The Concepts - 51

trology client peer search for an implementation of that proxy module, which he/she could run on his/her device. This peer would load that module on its device and use it to communicate with the astrologer located on another island.

Module Implementation Advertisement – This advertisement provides information about a
concrete implementation of a module specification. It contains a Module Specification ID (i.e., the one of the corresponding Module Specification Advertisement), some compatibility information, the code of the module implementation or some information about the module implementation code, a URI to the package containing the code of the module implementation, the name of the entity providing the module implementation and some parameters for the module implementation. If we consider the self-service weather forecasting method again, we know that if we want to run it on our device, we need to find a version written in a language that our tribe will understand. If this is Java, we will be looking for a .jar file. Although the content of this file could be included in the module implementation advertisement, we should preferably load it using the URI specified in the advertisement. In Java, this is typically performed with the loadClass() method. Once loaded on the peer, the weather forecasting method can now be used by the peer and can be offered as a service for other peers of the group.

If you did not get it all at once, don't worry. Just remember that: i. ii. Modules are piece of code loaded one way or another on devices. There are different ways to establish communication with or between modules.

iii. Contrary to other types of JXTA resources, modules are described with three types of advertisements instead of one. One type identifies the module class (i.e. category) in general, one describes the functional version of the module and one describes how to retrieve an implementation of the function version in a specific programming language.

The Protocols
JXTA defines 6 protocols. The core protocols are the Peer Resolver Protocol (PRP) and the Endpoint Routing Protocol (ERP). The standard protocols are the Peer Discovery Protocol (PDP), the Peer Information Protocol (PIP), the Pipe Binding Protocol (PBP) and the Rendezvous Protocol (RVP). Higher protocols use lower protocols to delegate work. Some lower protocols can some-

Understanding JXTA The Protocols - 52

times call higher protocols. Every JXTA peer must implement at least the Endpoint Routing Protocol and the Message Propagating Protocol, which is a subprotocol of the Peer Resolver Protocol, in order to participate to a JXTA network. We will describe each JXTA protocol using a bottom-up approach and after describing the role of messages in JXTA.

Message
Messages are documents exchanged between JXTA peers. JXTA defines different type of messages using a Matryoshka doll approach. The Matryoshka doll is a Russian is a set of dolls in decreasing size and nested inside each other. They are opened recursively to find a smaller one within the first, an even smaller one inside the next, etc. As messages are created by top protocols and go down to the bottom of the JXTA protocol stack, they can be wrapped within other messages, which can be wrapped up in other messages, etc... Some message elements can be added along the way. When the bottom protocols forward received messages to upper protocols, these messages are stripped from their layers to extract the core. We will briefly describe each type of JXTA message used by protocols. For more details, the reader should read the JXTA specification document. Metaphorically: A message is a dried leaf where kings and queens write the information they want to communicate to other tribes using the common languages of tribes.

Endpoint Routing Protocol (ERP)
Endpoint Service
Before we describe the endpoint routing protocol, we need to describe the endpoint service. This service is responsible for transmitting messages from one peer to another using the network transportation protocols upon which a JXTA implementation is operating (i.e., TCP, multicasting or HTTP for JXSE). It is not responsible for finding a route between two peers. This is the responsibility of the endpoint routing protocol that we will describe later.

Understanding JXTA The Protocols - 53

Metaphorically: an endpoint is the JXTA concept for identifying the location of the island a tribe occupies. It is the source and destination of any message. Any messages managed by the endpoint service should have a source and a destination endpoint address.

Endpoint Address
An endpoint address indicates how and where a message should be sent to a peer by providing information specific to the transportation layer used by the JXTA implementation. It is made of four parts (protocol, address, serviceName, serviceParam), but only the two first parts are mandatory. For example: tcp://10.42.218.15:9701/PipeService/urn:jxta:uuidE558B6E34E2B40958B3487E2342466013293A926FEA6485282A7D52DA855F58 604 In this example, the transportation protocol is TCP, but it could also be HTTP or any other protocol supported by the JXTA implementation. The destination is an IP address with a port number. The message is for the pipe service and the value of the transmitted parameter is a pipe ID. A peer can publish several endpoint addresses for different network interfaces (TCP/IP, HTTP). A peer knows a direct route to another peer if it knows one of its endpoint addresses and if it can use the corresponding network protocol successfully it to reach it without using intermediary peers. Such intermediary peers are also called hops. Metaphorically: an endpoint address is the location of an island on a map, with eventually the name and address of an individual to which a message is sent.

Endpoint Routing Protocol
The Endpoint Routing Protocol is the fundamental JXTA protocol on which all other JXTA protocols directly or indirectly rely to perform their operations. This protocol allows JXTA peers to send messages to other JXTA peers, even when no direct routes to those destination peers is known by the sending peer. This protocol lies between the transportation layer used by JXTA implementations and the other JXTA protocols. It is primarily used to find out about the current status of the network topology (i.e., location of islands and tribes in the ocean).
18

18

There are many technical reasons why direct routes cannot always be established between peers (NATs, Firewalls...). We will cover this later.

Understanding JXTA The Protocols - 54

When a message has to be sent from peer A to peer B, peer A takes a look in its cache for a known route from peer A to peer B. If such a route is known, the message is sent across that route using the endpoint service. Else, peer A sends a route resolver query to members of its peer group. Every peer receiving this query should (but is not obliged to) send back the routes to peer B they know. Routes responses will contain one or several path routes to peer B, specified by a semi-ordered list of peer IDs (i.e., hops). Peer A can then use one of these routes to send its message to peer B. Let's imagine that peer A receives a route to peer B across many peers. If it knows a shorter route to one of the intermediary peers to reach B, it can optimize it before sending its message. If any intermediary peer can optimize the route further while the message is on its way, it may do so too. If peer A can directly access peer B from the information it received, it does so directly. No intermediary peer is called. This is the ultimate optimization. If a peer does not have a route to another peer and does not get a response by sending a route resolver query, it gives up and notifies the caller of the service. An optimization consists in checking for direct connections to peers belonging to the route peer list within a route message query response, starting with the last hop. In our figure, the last peer is B, but we don't have a direct connection to it. The next-to-last peer is Z and we have a direct connection to it, so we can erase any peers above it in the list, that is, peer X and Y. Our route is now shorter. If we go over the list in the right order again, we get peer A > peer Z > peer B. Peer A will send its message to peer Z, while indicating that the recipient is peer B. Typically, intermediary peers are relay peers. Remark: Unfortunately, JXSE 2.5 and 2.6 only checks the first hop of a route if it cannot reach the destination directly and does not try the others . This will most probably change in future releases, since long routes are sometimes necessary. Metaphorically: You want to notify your existence to the tribe providing the self-service weather forecasting method. You know who they are (ID), but you don't know how to reach their island (peer). Therefore, you write a request for navigation routes to that island on a dried leaf and ask
19 The underlying assumption is that it potentially takes only one peer with a public address (i.e., hop) to connect any peers with private addresses. We will cover this topic deeper later.
19

Understanding JXTA The Protocols - 55

your people to navigate to other known tribes for answers. If these tribes have this information and are willing to give it, your people brings it back on dried leaves. These can be series of small maps. You may compare the information received with other information you already have and decide to create an optimized map to the forecaster tribe island. Your people are now ready to notify your existence to this tribe. If they can reach the destination island directly, they will do so. Else, if the distances are too long or the destination island is part of a group of islands surrounded by coral reefs, they will need to navigate through several islands to reach it. On their way, your people will show the map used to reach the destination island to tribes encountered on intermediary islands. These tribes may decide to optimize this map more to the benefit of you and your people. Some tribes are nomadic in nature. Although you may already have routes to reach them, you know that these will become invalid in the future and you will need to find new ones to reach them again from time to time.

ERP Messages & Advertisements
The endpoint routing protocol uses several messages and message elements:

Route Query Message – This is the type of message peers send to obtain information
about routes to other peers. It contains the ID of the destination peer and the route advertisement of the peer requesting the route. The latter is required to send a reply to the query.

Route Response Message – This is the response sent by those receiving route query
messages. It contains the route advertisement to the destination peer mentioned in the query, together with the route advertisement of the peer who has sent the query.

Route Advertisement – It contains the ID of the target peer, its endpoint address and a list
of access point advertisements to reach that peer.

Access Point Advertisement – This advertisement provides a list of endpoint addresses
for a peer ID, sorted in the preferred order of usage. They explain how to reach peers when trying to establish a route to destination peers.

NACK Message – This optional message is typically sent by peers receiving a message to
route to another peer for which they don't have a route. It tells sending peers that the selected route to destination is invalid.

Understanding JXTA The Protocols - 56

Top-Down-Top
In JXSE, the endpoint service implementation offers a method called addIncomingMessageListener(...) to let anyone register a listener for specific messages reaching the current peer. A service name and eventually a service parameter are provided when calling the method. Each time a message reaches the peer, the endpoint service will search first for a listener having the proper service name and service parameter. If no such listener can be found, a listener with the proper name and a null service parameter will be searched. If none can be found, the message will be discarded. Remark: the JXSE 2.6 implementation of the endpoint service offers additional methods (including some which were not available in 2.5) :

20

Messenger getMessengerImmediate(EnpointAddress...) - This method can be used to retrieve a Messenger object to send a message to a remote peer. If no messenger is available to the target peer, one is created and resolved asynchronously. The resolution may or may not fail. If successful, this peer will use the messenger to send the message. Warning: It is not because a message is sent successfully from a peer that it necessarily reaches the target peer. There is always small probability of getting lost when traveling across multiple hops.

Messenger getMessenger(EnpointAddress...) - This method is blocking and only returns resolved messengers (or null if none if the endpoint address cannot be resolved). It can also be used to send messages to target peers.

boolean

isReachable(EnpointAddress...,

tryToConnect) – This is the

ping() method of JXTA/JXSE.

If the 'try to connect' boolean is not set, the method will indicate whether this peer has already managed to reach the target peer and still has an operational messenger to it.

If the 'try to connect' boolean is set, and if no operational messenger to the target peer is available, the method will try create one. If it resolves successfully, the method will return true. Otherwise, it will return false.

boolean isConnectedToRelayPeer() - This method indicates whether this peer has

20

We will not cover all methods offered by the EndpointService, but only those that software engineers might use in their own applications.

Understanding JXTA The Protocols - 57

managed to connect to a relay peer .

21

Collection<PeerID> getConnectedRelayPeers() - This method return the set of relay peer IDs to which this peer is connected to. Typically, in JXSE 2.6., a peer is only connected to one relay at once.

EndpointRoutingTransport getEndpointRouter() - The methods gives access to the endpoint routing transport (which is responsible for the routing of messages) via a method called getRouteController(). The route controller is the active manager of routes to remote peers. It uses the local cache of fetch routes from remotes peers. Some of its methods are:

Collection<RouteAdvertisement> getAllRoutes() - The method gives access to all actively used routes to reach remote peers.

Collection<RouteAdvertisement>

getRoutes(PeerID) – This method

provides all routes actively used to reach a specific peer.

RouteAdvertisement getLocalPeerRoute() - This method return a route to this peer.

Typically, route controller methods should only be used to trace connectivity issues between peers.

Rendezvous Protocol (RVP)
The rendezvous protocol (RVP) builds on top of the endpoint routing protocol and is implemented as the rendezvous service. It contains of three sub-protocols: the message propagation protocol, the peerview protocol and the rendezvous lease protocol. Only the message propagation protocol is mandatory in JXTA, the others are optional. Typically, in JXSE, it allows propagation of messages over network transportation layers that do not support multicasting or to peers located too far to be reached by traditional TCP/IP broadcasting.

Message Propagation Protocol
This is the only mandatory protocol of RVP. It helps simple peers propagating individual messages to other peers within a peer group. In our first example, Mary is connected to Arthur who behaves as a rendezvous for the peer group. She asks him to help her send a message to Filip by providing its peer ID. Arthur, with the help of Hillary, transmits the message to Filip.
21 We have not covered relay peers yet. For now, these are peers facilitating communication between hardly reachable peers.

Understanding JXTA The Protocols - 58

Technically

speaking,

Mary is lucky that Arthur knows about Hillary, who knows about Filip. Mary and Arthur may have known about each other either because they are located on the same LAN, just like Hillary and Filip are on the same LAN. Arthur may know about Hillary and vice-versa, because they both have a permanent public IP address which they rely on to communicate with each other. We could rely on the endpoint routing protocol to find a route between peers each time we are missing one or each time we need to send a message, but this is not very efficient. This can be improved with the peerview protocol and the Rendezvous Lease protocol which we will describe further. If these two protocols are implemented, then message propagation as described in JXTA defines two other behaviors: the connection to a rendezvous peer and the propagation control which we will describe later.

PeerView Protocol
This optional protocol helps rendezvous peers of a peer group organize themselves, by maintaining a distributed list of active peers within a peer group. This list is called a peerview. A peerview operates at the peer group level. Its content is distributed among the rendezvous peers of the peer group. The set of active rendezvous of a peer group is called a rendezvous peerview. It is made of the peerview peers flagged as rendezvous in the peer group. In our example, the members of the rendezvous peerview are Lilia, Mark, John, Arthur and Hillary. The members of the peerview are the member of the rendezvous peerview plus Mary, Julia, Ethan, Mohamed, Filip, Sanchez and Yoko. Each rendezvous peer of a group is responsible for maintaining its local portion of the peerview and exchanges peerview messages with other members of the peerview to learn about the existence of other rendezvous in the group. These messages can be probe or response messages containing rendezvous advertisements. Probe messages are used to find out about other peers in Understanding JXTA The Protocols - 59

the peer view. An edge probe is performed when a peer not belonging to a peerview wants to learn about members of a peer view. The response will contain rendezvous advertisement from which the rendezvous service name identifying the peer group peerview can be retrieved. A participant probe is a message sent from a peerview member to another peerview member. There are four types of responses to probes: i. ii.

Participant Response containing the rendezvous advertisement of the responding peer Participant Referral Response containing the rendezvous advertisement of another peer
belonging to the peerview

iii. Shutdown Notification indicating that a peer is shutting down and that it will not be available anymore iv. Failure Notification indicates that a peer has failed and is no longer available Metaphorically: This is the mechanism that tribes belonging to an astrology group would use to keep a list of active members, for example.

Rendezvous Advertisement
Every peer acting as a rendezvous for a peer group publishes a rendezvous advertisement containing at least the peer group ID, the peer ID, the rendezvous service name identifying the peer Understanding JXTA The Protocols - 60

view and eventually the name of the peer and a route advertisement to it.

Rendezvous Lease Protocol
The rendezvous lease protocol is an optional protocol allowing non-rendezvous peers of a peer group to receive messages propagated within a peer group. The subscribing peer requests a

lease from a rendezvous via a Lease Request Message containing its peer advertisement. A rendezvous peer grants the lease via a Lease Granted Message containing the duration of the lease, the ID of the rendezvous peer granting the lease and eventually its peer advertisement. A lease is canceled with a Lease Cancel Message containing the peer advertisement of the peer canceling the lease.

Peer Connection to Rendezvous
A peer can connect to a rendezvous via a lease and therefore obtain messages propagated within a peer group. The connection is established with the help of the Endpoint Routing Protocol. The service name and service parameter used in the endpoint address in the lease messages are respectively JxtaPropagate and the peer group ID, for example: tcp://10.42.218.15:9701/JxtaPropagate/urn:jxta:uuidE2E76334369C484E8986AC6A6EE02F3E02 In order to receive propagated messages, a peer implementing the Rendezvous protocol will have to register as listener of incoming messages in the endpoint protocol.

Propagation Control
A rendezvous peer should propagate the messages it receives from its leases to non-rendezvous peers, unless:

Loop – The message has already been processed by the rendezvous peer. This can be
detected because a list of visited peers is maintained in propagated message. Each time the message reaches a new peer, the peer ID is being added to the list.

TTL – The time to live of the message is decreased by one each time it reaches a peer. If it becomes 0, then message is not propagated anymore.

Duplicate – A message can reach the same peer twice via different paths. If a peer has
already received a message, it will discard it.

The Rendezvous Propagation Protocol is also responsible for providing: Understanding JXTA The Protocols - 61

The source of a propagated message – In our earlier example, Filip will know that the
message he receives came from Mary.

The list of peers who already have received the propagated message while it is being
transmitted – When Mary sends her message to rendezvous peers, it could
22

eventually

reach back Arthur by the Mary > Arthur > Hillary > Mark > Arthur path if the propagation method was inefficient. Arthur will be part of the list of peers who already have received the message. It won't be propagated further, since Arthur already propagated it in an earlier step.
• •

The listener name – That is, the service that will handle the propagation of messages. The remaining time to live of the propagated message – It is decreased each time it
passes through a peer and when it reaches zero, the message is not propagated anymore.

Remark: A developer should never have to deal with the rendezvous plumbing. It should never access the corresponding service to establish connections with rendezvous peers in JXSE. New mechanisms to establish such contacts have been made available in new classes called the NetworkManager and the Networkconfigurator via seeds. It is key to remember that a peer may participate to multiple peer groups and act as a rendezvous in some of them and not in others. The JXSE 2.6 implementation of the rendezvous service offers methods which can be useful for software engineers:

startRendezVous(),

stopRendezVous()

&

isRendezVous() - These three

methods can be used to manually initiate a rendezvous behavior of a peer within the corresponding peer group or to stop that behavior. One can also find out whether the rendezvous behavior is enabled.

setAutoStart(boolean auto, long period) - This method can be used to periodically change the rendezvous behavior of this peer within a peergroup according to the number of available rendezvous and edge peers requesting leasing. If there are not enough rendezvous, the peer automatically becomes a rendezvous. If there are too many rendezvous, it can demote itself to a simple edge peer.


22

List<PeerID> getLocalRendezVousView() - If this peer acts as an edge in its

This would happen if the forwarding method was to forward the message 'à la Gnutella' to all known peers without taking into account the list of peers who already have received the message before proceeding.

Understanding JXTA The Protocols - 62

group, this method returns the rendezvous peer ID it is connected to (if any). If it acts as a rendezvous, it returns the set of other rendezvous peers it knows about. This list is not necessarily the whole peerview.

List<PeerID> getLocalEdgeView() - If this peer acts as an edge in its group, this method returns an empty list. If it acts as a rendezvous, it returns the set of edge peers who have a lease with the rendezvous peer.

boolean isConnectedToRendezVous() - If this peer acts as an edge in its group, this method returns true if it has a lease with a rendezvous and false otherwise. If it acts as a rendezvous, it returns true if it know about other rendezvous in the rendezvous peerview, false otherwise.

Top-Down-Top
Typically, the rendezvous protocol will not send its messages itself, but invoke the endpoint routing service. When a peer acts as a rendezvous in a peer group, the rendezvous service will register proper listeners in the endpoint routing service to make sure rendezvous related messages are collected properly.

Pipe Binding Protocol (PBP)
In JXTA, pipes connect a sending endpoint to one or several other receiving endpoints. The sending end of the pipe is called the output and the receiving end is called the input. JXTA defines uni-

directional asynchronous unicast pipes. Unidirectional means that the data is moving only from the
output end to the input end. Asynchronous means that the sending endpoint can send data at any time and that receiving point can read it at any time. Unicast means that the communication is limited only from point-to-point. Such pipes are called JxtaUnicast pipes. JXTA also defines secured pipes using TLS 1.0 (Transport Layer Security). Such pipes are called JxtaUnicastSecure pipes. There are also diffusion pipes for one-to-many peer communication called JxtaPropagate pipes. The data sent by the sending endpoint is received by each receiving endpoints.

Understanding JXTA The Protocols - 63

The Pipe Binding Protocol is responsible for establishing pipe connections between endpoints, but is not responsible for the data transfer between these endpoints. It relies on the endpoint protocol for initial data exchanges to establish the pipe connection and for transporting data between endpoints over the pipe connection. The endpoint protocol take cares of crossing natural and artificial network boundaries, which can imply transferring data through several peers before it reaches the destination endpoint. Metaphorically: You have decided to establish a trade route between your tribe and one or several other tribes to exchange goods (chicken, bananas, wood, etc...). You have asked your people to find out whether other tribes are ready to do trade with you. They travel over the ocean and come back with responses.

Pipe Advertisement
A pipe advertisement contains a unique ID for the pipe, its type (JxtaUnicast, JxtaUnicastSecure or JxtaPropagate) and eventually a name and a description.

Pipe Resolver Message
After publishing a pipe advertisement for a pipe, regardless of its type, we need to find out which peer is listening to the pipe (input end) before an output end can be created. The same type of message (i.e., pipe resolver message) is used to query for those peers and to obtain responses from them. A pipe resolver message contains a message type (query or answer), the pipe ID, the type of the pipe, a peer ID, a found boolean and a peer advertisement. If the message type is query and a peer ID is specified, then the message is targeted for the specified peer only, other peers should not answer it. Else, the message should be propagated to any peer of the peer group. The found boolean indicates whether the specified pipe was found on the specified peer when replying. If the message type is answer, the peer field will contain a list of peers known to have resolved the input end of the pipe. The peer advertisement is one of the peers which resolved the input end of the pipe. This peer may appear in the peer field list, but not necessarily. Understanding JXTA The Protocols - 64

Pipe resolver messages are used to establish a pipe connection between peers, not to send messages over pipes themselves. This operation is performed by the endpoint routing protocol.

Propagate Pipe Message Header
Every message sent via a JxtaPropagate pipe (i.e., sent to many peers) includes an extra message element called a propagate pipe message header. This element contains the ID of the peer issuing the message, the Pipe ID, a message ID to avoid duplication when propagating it, a TTL that each peer should decrement before attempting to forward it and the list of already visited peers.

Top-Down-Top
Just like the rendezvous protocol, the pipe service will not send its messages itself, but invoke the endpoint routing service. It will register several listeners by setting the service name to 'PipeService' and set the service parameter to the pipe ID. With this configuration, each piped message will reach its destination properly, no matter if there is one or many destination peers. This protocol also uses the resolver protocol to send and receive queries. Remark: The JXSE 2.6 implementation of the pipe service offers methods which can be useful for software engineers:

InputPipe createInputPipe(PipeAdvertisement, PipeMsgListener) – This method is the first step in establishing a pipe communication between peers. Messages are received on the listeners.

createOutputPipe(PipeAdvertisement, OutputPipeListener) – This method starts the resolution process with a input pipe create on a remote peer. If such is found, the output pipe listener is notified.

Peer Resolver Protocol (PRP)
The Peer Resolver Protocol (PRP) is the protocol used to send a generic query to one or several peers via a resolver query message, and to receive one or many responses to that query via re-

solver query responses. The query and the response are strings of characters whose interpretation is not defined by JXTA. Queries and responses are sent to handlers which may or may not be registered on peers via the resolver service. Each handler has a unique name and there may be one and only one handler registered on a peer for a given handler name. It is another way of saying that there should be one and only one mailbox on an island for a given destination address. Understanding JXTA The Protocols - 65

Earlier, we mentioned that an endpoint addresses could contain the name of a service and a parameter to that service. We provided an example containing a PipeService and a JXTA ID. Typically, the peer located at the specified IP address should have registered a handler called 'PipeService' in order to get the message sent to this address. In other words, there should be a mailbox having the proper name of the recipient, or the message will not be delivered. Metaphorically: You want to know if other tribes are selling bananas. You send your people on a query to find out. Each tribe has its own set of delegates to answer specific questions. Those having a supply query delegate provide an answer to your question. Others tribes ignore it. Your people bring back the answers they collected and transmit it to your delegate responsible for managing answers to supply questions.

Resolver Query Message
A resolver query message (or query message for short) contains the credentials of the sender, a service/handler's name, the peer ID of the query issuer, the query ID, the number of peers through which the query has 'traveled' and the query itself expressed as a string.

Resolver Response Message
A resolver response message (or response message for short) contains the credentials of the respondent, the name of the handler to handle the response, the peer ID of the response issuer, the query ID and the responses to the query. The number of responses can be 0 to many, and these might be copies of each other.

Shared Resource Distributed Index (SRDI)
JXTA defines an optional shared resource distribution index concept operating between rendezvous peers in JXSE. SRDI aims at minimizing unnecessary traffic on the JXTA network. The inten-

Understanding JXTA The Protocols - 66

tion is to avoid forwarding peer queries in all directions and to focus on peers more likely to answer these. In JXSE, each edge peer publishing advertisements in their local cache maintain an index containing the keys of these advertisement and synchronize the content of this index from time to time to its rendezvous via the SRDI service. The rendezvous peers propagates copies to other rendezvous peers of their peer group called replicas. Therefore, when rendezvous have some information about advertisements, they use it to avoid propagating queries in all directions. Else, they propagate queries to other rendezvous. It is key to remember that each advertisement has a set of indexable fields. This is the information contained in SRDI and exchanged between rendezvous peers, not the whole advertisement itself.

Resolver SRDI Message
In order to keep the SRDI up-to-date between peers implementing it, JXTA uses resolver SRDI messages. These are made of a handler name, the credential of the sender and a payload (that is, a string to be interpreted by the handler). Remark: If developers want to create a customized service to handle their own set of customized queries, they will typically register their own QueryHandler in the resolver service (not the endpoint service) and give it a specific name. In order to send a query or a response, they will invoke the sendQuery(...) and sendResponse(...) methods from that same service using ResolverQueryMsg and ResolverResponseMsg objects which contain the name of the target query handler. Each time a resolver query or response or message reaches a peer, it is transmitted to the corresponding handler, if such exists. The JXSE 2.6 implementation of the resolver service offers methods which can be useful for software engineers:

QueryHandler registerHandler(name, handler) – This method allows the registration of a unique query handler using the handler's name.

QueryHandler unregisterHandler(name) – This method removes any registered query handler using its name.

Understanding JXTA The Protocols - 67

void sendQuery(destPeer, query) – This method sends a query to a destination peer.

void sendResponse(destPeer, response) – This method sends a query response to a destination peer.

In

order

to

create

query

messages, and

one

can

use

the

static

ResolverQueryMsg

newResolverQueryMsg()

ResolverResponseMsg

newResolverResponseMsg()

methods from each class. One can also use the ResolverResponseMsg makeResponse() method on any received query message to prepare a response.

Top-Down-Top
Just like previous protocols, the peer resolver protocol will not send its messages itself, but invoke the endpoint routing service. It will also register its own handler for SRDI messages when it is activated (that is, if a peer acts as rendezvous in JXSE).

Peer Information Protocol (PIP)
The Peer Information Protocol is an optional JXTA protocol allowing peers to obtain information about other peers on the JXTA network. It operates with query and response messages and operates on top of the peer resolver protocol. The JXTA specification document does not provide more details about how it should be implemented, but we will describe its implementation in JXSE . The peer info service can be used to retrieve status information about the current peer or remote peers. This is performed with monitor reports containing service metrics. Such a service is 'anything metric' measured on a peer by a service monitor. One can implement cumulative service metrics, like the number of messages received by a peer for example. Each service monitor is identified by a module class ID and can monitor anything. This 'service' terminology can be misleading because of the JXTA service concept. For example, a service metric could be the temperature of a room. JXSE also implements monitor filters containing a list of service monitor filters. This can be useful if you do not want to obtain all the metrics which can be obtained from a peer. If you are only inter ested in the temperature of a room metric, you can create a monitor filter containing a service monitor filter for that specific metric. The next step is to register a monitor listener in the peer info service. A reporting rate and a monit23 Unfortunately, this service has not been used and tested widely in JXSE. Existing documentation is limited. In release 2.5, the PIP (or metric) code could be generated from the main Ant script. It is now fully integrated in 2.6 and activated via static booleans.
23

Understanding JXTA The Protocols - 68

or filter can be specified to only obtain relevant data at a regular interval. Later, the monitor listener can be invoked in three ways by the peer information service: i) to notify that the reporting has been canceled (the reason can be retrieved from the corresponding event), or ii) the request for monitoring failed (and the reason can also be retrieved from the corresponding event), or iii) a monitoring report has been received and can be retrieved from the corresponding event. One can obtain the monitoring capacities of a local or remote peer from the peer information service. This information is grouped in an object containing the list of module class ID corresponding to the service monitors available on the target peer. If the target peer is a remote peer, a specific

peer monitor info listener must be specified together with a timeout. This listener can be invoked in
two ways: either i) the information is returned in time by the target peer and can be retrieved from the event, or ii) the information is not returned in time.

PIP Query Message
A Pip Query Message contains ID of the peer making the request, the ID of the target peer being queried, and a request. The request is an optional field whose interpretation in not defined by JXTA. Typically, it contains a peer information query expressed as a string.

PIP Response Message
A Pip Query Message contains at least the ID of the peer who has made a request and the ID of the target peer being queried. Unless the information is unavailable or could open a security breach, this message should contain the up time of the peer expressed in milliseconds and the

time stamp at which this message was generated. This time stamp represents the number of milliseconds since January 1 , 1970 at 00:00:00 GMT. The message can also contain a response to the query. Again, the interpretation of this response is left to the peer. It can also contain information about the traffic, such as the time of the last incoming message, the time of the last incoming message, information describing the incoming and/or outgoing traffic from various endpoint addresses, together with the number of bytes received/sent by the named address endpoint.
st

Top-Down-Top
Typically, a peer information service will create its own queries and send them via the peer resolver service. It will also register its own query listeners in that same service. Understanding JXTA The Protocols - 69

Peer Discovery Protocol (PDP)
The Peer Discovery Protocol is the highest level protocol in JXTA. It is used to find advertisements of other peers, rendezvous and any kind of resource that has a published advertisement (a pipe, a module, etc...). Ideally, it should be called resource description discovery protocol. This protocol operates at a group level, meaning that discovery queries are performed within a group. This protocol uses two messages: the Discovery Query Message and the Discovery Response messages.

Discovery Query Message
Contains at least the type of searched advertisements, a threshold indicating the maximum number of messages a given peer should return and eventually the advertisement of the query sender and some search parameters. This type of message may also contain a pair of attribute and value items. The value provided for this pair of items will be used to search for advertisements having an attribute called attribute and for which, the corresponding value is value. Typically, a peer advertisement contains a field called Name. If you are searching for advertisement of peers having a name starting with 'J', you will typically set the following in your discovery query message: attribute = 'Name' and value = 'J*'. Wild cards are allowed. This feature can be very useful if you define your own advertisements having their own specific attributes. A list of attributes per advertisement types is provided in the Appendix.

Discovery Query Response
Contains the advertisement types, the number of responses in the message, the advertisement of the respondent, the expiration in milliseconds and the responses + expiration expressed in milliseconds. If the attribute and value of a pair of items was present in the discovery query message, they will be present in the response too. The JXSE 2.6 implementation of the discovery service offers methods which can be useful for software engineers:

getRemoteAdvertisements(...) – These methods enable the retrieval of advertisements published on remote peers.

getLocalAdvertisements(...) – This method allows the retrieval of advertisements published on this peer.

Understanding JXTA The Protocols - 70

• • •

publish(...) – This method publishes advertisements on this peer. remotePublish(...) – These methods publish advertisements on remote peers. flushAdvertisements(...) – These methods delete advertisements on this peer.

Top-Down-Top
The discovery service uses the peer resolver protocol to send its queries and receive answers. Typically, a user expecting answers from his discovery queries should register a discovery listener for each of his queries, but he or she could also register a general discovery listener.

Access Control

The above figure is the initial implementation design of access control in JXSE . The general principles are the following: 1. The user retrieves the membership service of the peer group object instance. 2. It applies with authentication credentials, which provides an authenticator.
24 This image is extracted from the net.jxta.membership.doc-files package of the release 2.5 jxta.jar.

24

Understanding JXTA Access Control - 71

3. Authentication transactions are performed with this authenticator (via a screen, by providing a password, etc...). 4. When the authenticator is ready to join, the user returns it to the membership service using the join(...) method and if successful, a credential for the identity is returned. It operates at a group level. 5. Later, this credential can be used with the access service to check access on privileged operations via the doAccessCheck(...) method. Privilege operations are created from the access service using the

newPrivilegedOperation(...) method.

Membership Service
The membership service is a required JXTA service which must be implemented at the peer group level. In its simplest form, it is used to request access to a peer group. Eventually, access can always be granted. Each peergroup has a membership service. By default, the World Peer Group and the Net Peer Group have a none membership service, that is, everyone is admitted. There is a corresponding always access service. By default, new peer groups are created with the Personal Secure Environment (PSE) service and the corresponding PSE access service. We will describe this specific membership service later, in the cryptographic section of this book.

Access Service
The Access service is used to validate requests made by one peer to another. The peer receiving the request provides the requesting peer credentials and information about the request being made to the Access Service to determine if the access is permitted. Not all actions within the peer group need to be checked with the Access Service. Only those actions that are restricted to a subset of member peers must be checked. Like other JXTA services, the access service is implemented as an interface in JXSE. One should retrieve the access service implemented by a peer group and then check whether a privileged operation can be performed with the doAccessCheck(...) method. This method takes in two parameters: the privilege operation and the credentials of the peer requesting the operation. Four values can be returned: DISALLOWED, PERMITTED, PERMITTED_EXPIRED and UNDETERMINED. The PERMITTED_EXPIRED value indicates that the operation would be permitted if the creden-

Understanding JXTA Access Control - 72

tials were not expired.

The Ignition Process
How does a JXTA network get started? How does a peer get started? JXSE uses one of the most interesting features of the Java programming language: its capacity to load pieces of code at run time, that is, while an application is running. Later, that same application can start running these loaded pieces of code. Remember that JXTA operates with modules and that these modules are to be 'loaded' on peers. I guess one can safely bet that many readers are starting to get the whole picture. Understanding the ignition process of JXTA in JXSE in details requires some knowledge of the Java programming language. However, the non-savvy reader will still understand most what is being said in the next pages. We will first review some features of modules and services in JXSE, before describing the ignition process of JXTA.

Module
In JXSE a module can be initialized, started and stopped. It is implemented as a Java interface. When a module is initialized, a PeerGroup object, together with an ID and a module implementation advertisement are passed as parameters. JXSE supports the co-depending start of modules. In other words, if module A needs to wait for module B to be started and module B needs to wait until A is started before finishing it starting process, this can be achieved with JXSE. When a module is started, an array of string arguments can be passed as a parameter. Calling the startApp() method returns a value which can be one of the following:

START_AGAIN_PROGRESS – This value indicates that the startApp() method of a module needs to be called again later in order to finish its starting procedure. This module may have already performed parts of its starting procedure.

START_AGAIN_STALLED – This value has the same meaning as START_AGAIN_PROGRESS, but it gives the caller of the startApp() method an indication that the module has stopped somewhere in its starting procedure. It should be called again later.

START_DISABLED – This value indicates that the starting procedure of this module has been disabled or that the module cannot start for some reason. Understanding JXTA The Ignition Process - 73

START_OK – This value indicates that the module has started successfully and that it can be considered as operational. The start method should not be called again.

This is an important feature because if a high-level service using lower-level services is started before these low-level services are started, it has a mean to notify the caller of its startApp() method that it is waiting for other modules/services to be started before finishing its own start procedure.

Service
In JXSE, a service is a type of module and is also implemented as an interface. In addition to the methods provided by the module interface, one can obtain the module implementation advertisement of this service by calling the getImplAdvertisement() method.

Peer Group As A Service – Part I
JXSE has developed a Java PeerGroup interface, which is a type of service, to attach other JXTA services. If you think about it, it means that JXSE considers peer groups as services. JXTA services are attached at a peer group level, and not at a peer level. Such services can be retrieved with some of the following methods, for example: getDiscoveryService(), getEndpointService() and getPeerInfoService().

Well-known Module Class, Specification and Implementation IDs
JXSE has defined several well-known module classes, module specification and module implementation IDs. These are available as static fields in the Java PeerGroup interface. They all share the same prefix: urn:jxta:uuid-DeadBeefDeafBabaFeedBabe. For example, the wellknown module class id for the standard implementation of the pipe service (i.e., the pipeClassID) is: urn:jxta:uuid-DEADBEEFDEAFBABAFEEDBABE0000000405. JXSE references these when starting JXTA.

Bootstrapping JXTA
One way of starting the JXTA network in JXSE is to use the startNetwork() method of the NetworkManager class. This method returns an instance of the Net Peer Group from which we can access the default implementation of JXTA services. This is what is happening when calling that method:

Understanding JXTA The Ignition Process - 74

1. If the net peer group has already been created, it is returned. 2. Else, a new instance of the NetPeerGroupFactory object is created. During this process, a new instance of the WorldPeerGroupFactory is created. This call triggers the creation of the world peer group PeerGroup Java object instance using its module implementation advertisement. This advertisements contains references to modules and services which should be running at the world peer group level. 3. The next step is to 'load' the services that the world peer group object will provide. Technically speaking, this is equivalent to 'loading' the implementation of each of these modules, which are, in fact, pieces of code delivered as part of the current implementation of JXTA (i.e., the jxta.jar file since we are using JXSE). In another implementation, the code or .jar file could be retrieved from a URI. Some links need to be established between well-known module implementation IDs and the Java byte code corresponding to the implementation of these modules. Some module implementation advertisements have to be created to be passed as parameters when instantiating corresponding module objects in JXSE. 4. How is this resolved? As soon as the Java class called StdPeerGroup is referred to for the first time (and this happens when the startNetwork() method is invoked for the first time), its static initialization is performed. This operation includes the loading of information located in the META-INF.services/net.jxta.platform.Module file delivered as part of the JXSE implementation. This file contains all the necessary information to resolve the set of module implementation IDs with the name of the Java classes implementing that module in the jxta.jar file. Remember that a module/service is an interface in Java and that we need a Java class implementing that interface to run the code that will operate this module/service .
25

25

Those savvy with OSGi will complain about the limitations of this method, for example, when there are multiple versions of a module, or when there are dependencies between modules. JXSE is ill-equipped to handle such complex situations. This has triggered the progressive introduction of OSGi in release 2.6.

Understanding JXTA The Ignition Process - 75

5. The object implementing the World Peer Group is the Platform object. It extends the StdPeerGroup object, which extends the PeerGroup interface. During initialization, the Platform object loads every modules and services defined in its implementation advertisement with the help of a JxtaLoader, and starts them. This includes the creation of physical transportation module objects (i.e., TCP, HTTP, multicasting...). 6. Once finished, the PeerGroup object instance of the world peer group is now ready to be used and methods can be used to invoke the default implementation of JXTA services in JXSE. This instance is used as a parent for the creation of an instance of the net peer group PeerGroup object (technically speaking, the type of this object is ShadowPeerGroup). It will automatically inherit of the service implementations 'loaded' as part of the creation of the world peer group (for example, the transportation module) or creates its

Understanding JXTA The Ignition Process - 76

own peergroup level service instances as necessary. This new net peer group instance is returned by the startNetwork() method. The code corresponding to module/service implementations is now 'loaded' and linked with their module implementation IDs.

Peer Group As A Service – Part II
Typically, when the JXTA network is started in JXSE, the user specifies its peer ID (or a new one is automatically created). This ID is taken into account when creating the initial world peer group and net peer group PeerGroup objects. Since a peer group is a module in JXSE, its ID is transmitted to the corresponding peer group module when it is initialized. Now that the user has access to the JXTA network via the net peer group, it can start to search for other resources on the network with the discovery service for example. In a way, this peer has become a 'resource' of the net peer group during the bootstrapping process and it can now be accessed by other peers. The system is bootstrapped. If the user wants to connect to other peer groups (or create them), he or she will create additional PeerGroup objects using one of the newGroup(...) methods from the net peer group object. These groups will automatically benefit from the default implementation of JXTA services available from the world peer group via the net peer group. Remark: If you did not get it all, just remember the most important thing: in JXSE, a peer gets initial access to the JXTA network via an instance of the world peer group and of the net peer group, who offer default services to operate on the JXTA network.

Loading Other Services
Once a peer is connected to the JXTA network via a peer group, it can load other peer level or peer group level services with the one of the loadModule(...) methods from its peer group Java object.

Understanding JXTA The Ignition Process - 77

- 78

Network Boundaries
This chapter covers the network communication technical issues one has to overcome when implementing JXTA. It contains a reminder about IT network concepts and explains how artificial and natural network boundaries can be crossed using specific techniques. These issues must be well understood by developers, architects and network administrators to develop efficient P2P systems based on JXTA. This chapter will provide the context to help them set-up JXSE properly and troubleshoot common implementation issues.

Reminder
Historically, the Internet was not initially developed with the intention of supporting hundreds of millions of users. As the community grew, several problems arose and sophisticated solutions were implemented to solve them. This has resulted in a complex plumbing that only experts understand in details. Today, many software developers don't know exactly what is happening inside this plumbing. They know how to connect to taps and sinks to send and receive data, but most often, they can't explain precisely how the plumbing operates. This is normal, since the plumbers are offering a couple of services they can call to perform their operations. The developer delegates the duty of transporting information over the network to these transportation services. The world would be great if the Internet plumbing was simple and universal, but it is not. It was not initially designed with universality in mind, but it became more and more universal as more and more people used it. International organizations defined standards to normalize the utilization and development of solutions. Every implementation of JXTA must be performed by selecting a network transportation layer. Otherwise, messages cannot be exchanged between peers. This causes a natural friction between the high level concepts of JXTA and the down-to-earth issues of Internet plumbing. Some middle solutions must be implemented as part of every JXTA implementations to meet both ends. The consequence is that developers have to configure their application properly to make sure it will operate according to the universal objectives of JXTA. We will start by providing a reminder about Internet concepts before explaining how the plumbing can limit the universal ambition of JXTA. We will then explain how these issues are solved in Network Boundaries Reminder - 79

JXSE.

IP
The Internet Protocol (or IP) is a protocol technology making the link between the hardware aspect of networks (cables, network cards...) and software running on computers via a network

transport layer. Each time a computer connects to the Internet, it is using a fixed IP address or it is
assigned one automatically.

Computers are usually connected together in rings (or segments) called LAN (local area networks) and then rings are connected to each other to form the Internet. To make things more complicated, those rings can be divided in subnets, that is, subsets of computers. This is a logical distinction, not a physical one. One of the main functions of IP is routing. When transmitting data, IP attempts to make the best effort to deliver packets of data from a sending computer to a destination computer. However, some packets can be lost, arrive out of order or even duplicated because of technical or traffic issues. These can be solved with TCP, which we will discuss later. When a data packet is sent to a destination host located on the same subnet as the sender, the routing is called direct. Else, if the host is located on another physical network or on another subnet of the same physical network, it needs to transit through at least one, but usually many, IP gateways (also called routers) to reach its destination. This is called indirect routing. This way of organizing networks provides network administrators with some flexibility to organize their networks both from a physical point-of-view and from a logical point-of-view. However, there is an important limitation, they cannot create a subnet with computers belonging to different physical networks.

Network Boundaries Reminder - 80

Unicast, Broadcast & Multicast
In IP, a data packet can be sent to one or many recipients. If the IP address of the destination is unique, the transfer is called unicast. If a data packet is send to many recipients, it is called broad-

casting. Sending a packet to all members of a subnet is called multicasting. This is performed with
reserved IP addresses (from 224.0.0.0 to 239.255.255.255).

IPv4 Versus IPv6
There are different versions of IP. The IP addresses of IPv4 are represented by 32 bits unsigned values. Therefore it allows a maximum of 4 294 967 296 IP addresses. The IP addresses of IPv6 are represented by 128 bits unsigned values, allowing a maximum of ≈ 3.40 1038 IP addresses. The number of IPv4 addresses is not enough for all computers and devices today. However, most of our material still relies on IPv4 today. Subnetting physical networks was one way to solve this issue, but other techniques, which we will describe later, have been developed to work around this issue.

TCP
IP does not operate only by itself. It is either combined with UDP (which we will discuss next) or the Transmission Control Protocol (TCP). The latter provides a reliable way to exchange streams of data expressed in bytes between computers. It operates by establishing a logical connection between the two computers. The data packets transmitted between the sending computer and the destination computer are delivered in order and only once. If necessary, packets lost at the IP level are requested by the source again to ensure proper service.

Handshake
In order to establish a TCP communication, devices start with a 3-way handshake: 1. Device A sends a synchronization packet (SYN) to device B. 2. Device B receives SYN and replies with a synchronization acknowledgment packet (SYNACK). 3. Device A receives SYN-ACK and replies with an acknowledgment packet (ACK). 4. Device B receive ACK.

Network Boundaries Reminder - 81

The TCP communication is established. Each communicated packet contains information about the created connection.

UDP
The User Datagram Protocol (or UDP) is another transportation protocol operating on IP. It provides a faster, but insecure way to transfer messages between two computers by using datagrams. Contrary to TCP, UDP is a connection-less mean to exchange data between devices. As long as a device starts listening for UDP communication, it can potentially receive communication from any other device on the Internet. There is no need for a handshake-like protocol.

Datagram
A datagram is the name of a message containing data sent over UDP. It is an independent unit of information. It can reach its destination out of order. It can also be duplicated or may never reach its destination.

Port
A port is a number ranging between 0 to 65535 in the header of data packets sent over the TCP and UDP. It can be compared to specific terminal numbers assigned to planes to load or unload passengers in airports. It helps several software applications performing direct communications over a single IP communication line by addressing their data directly to another software application listening to the corresponding port. In JXTA, the corresponding mechanism is the service name and service parameter in endpoint addresses.

For example, port 80 is used for HTTP, the World Wide Web protocol. This is the port your web browser uses to request and obtain the content of web pages from a web server. The data packets exchanged over the Internet for HTTP are stamped with port number = 80 and

Network Boundaries Reminder - 82

are transferred automatically to your web browser and your web server application, who are both listening to port 80. There is an important fact to keep in mind regarding ports: maximum one application can listen to a given port on a given PC. If a second application tries to listen to that port, it will receive an error message. The port must be freed before it can start listen to it. Eventually, an application can behave as a proxy listening to one port for other applications. It will manage the distribution of incoming messages to proxy-ed applications. The IANA (Internet Assigned Numbers Authority) maintains a list of port numbers which is organized in 3 categories: well-known ports (0-1023), registered ports (1024-49151) and dynamic/private ports (49152-65535). Software applications are expected to comply with the IANA port list, that is, they will listen and communicate with the proper port corresponding to their activity. However, this is not mandatory and cannot be enforced. Some malicious applications often try to pass illicit data via free ports. Some don't hesitate to hijack well-known ports to allow external parties to try to take control of your PC. In order to prevent this, a solution, called firewalls, has been introduced.
26

Firewalls
A firewall is a device aimed at protecting a PC from external attacks. It can also be implemented to protect a LAN from attacks coming from the Internet. Firewalls filter the data packets moving in and out of the area or the PC they are protecting by enabling or disabling some ports. They are comparable to guards at city gates in ancient times. If a data packet tries to pass through a disabled or blocked port, it is discarded. Some readers may already have received some messages from their computer when an application was trying to communicate via a blocked port. They most probably did not know what to do and enabled it without fully understanding the consequences. Of course, everyone knows the story of the Trojan horse which the Achaeans used to infiltrate Troy. The city guards though it to be a gift and let it in, not knowing that it contained Achaean warriors inside. At night, these warriors killed the city guards and opened the city doors to let other warriors come in to take over the city. That is exactly what some malicious piece of software tries to do on your PC. Some are called viruses, others spyware. They are all looking for a way in. This is why we called them Trojan horse viruses. Firewalls provide access control over ports and therefore, to improper communication via un26 http://www.iana.org/assignments/port-numbers

Network Boundaries Reminder - 83

desired channels. Since only one application can listen to a given port at a given time, the first one who gets it keeps it. If non-harmful applications get hold of their ports before others when you boot your PC, this can prevent harmful applications from getting control of these ports. If you tell your firewall to disable all ports on your PC and ask to get a message each time an application tries to get hold of a port, you will know who is doing what on your PC. You may decide then to provide port access to the requesting application. Malicious applications will become visible when they try to communicate on the Internet. Unfortunately, if you have let a malicious application take control of a port, firewalls will be powerless against Trojan attacks, since they will comply with your order of letting that application use the port. This is why anti-virus applications and spyware removers have been created. Users don't always know whether they are dealing with a dangerous or even infected application. This is another issue. Some non-harmful applications can be infected by harmful application, but fortunately, that often leaves a trace in the code or in the behavior. Anti-virus and anti-spyware applications have lists of suspicious applications and known viruses. They scan your PC and its application from time to time, together with data being transmitted in and out of your PC for illegal or suspicious activities. They are complementary protections to firewalls. In practice, one cannot block all ports of a computer to prevent attacks from the outside, since a PC alone is not very useful. Otherwise, we would not need firewalls at all, since no Internet connection would have to be established. The value of a PC increases when connecting to other computers. Operating JXTA on TCP/IP (or UDP) requires listening to (at least) one port for incoming messages and to send messages to specific ports on the destination peer listening to that port. Unfortunately, these ports can sometime be blocked by firewalls either on the sending peer or the destination peer of both. The firewall can also be located somewhere on the network between them. JXSE has a solution to this problem: relay peers. We will discuss this later. Metaphorically: One can compare ports to the skin protecting our body from infections and to our nose filtering the air coming in. However, these protections do not prevent some viruses or bacteria from getting into our lungs. Fortunately, our immune system takes care of these. We cannot live without oxygen in the air, we need to let it in one way or the other. There no Internet connection from PCs without ports.

NAT
Network Address Translation (or NAT) is a mechanism providing a solution to the shortage of IPv4 Network Boundaries Reminder - 84

addresses. Instead of assigning a unique IP address to every computer in the world, which is impossible since there are not enough, we introduce a distinction between internal IP addresses and

external IP addresses.
A set of internal addresses is used for a local network area (LAN). They are only valid for a given LAN. However, two distinct LANs could use the same set of internal addresses. The computers of one LAN cannot connect directly to the computers of the other LAN by referring to the same set of addresses. A set of external addresses is a set of unique IP addresses which could be assigned to any computers on the Internet (i.e., some of the 4 294 967 296 available, minus reserved addresses). Since the computers on the LAN do not need to connect to the Internet permanently (most often), they do not need to have a fixed IP address and can be assigned one of the internal addresses. When they need to connect to the Internet, they can borrow one of the external addresses temporarily. This is precisely what a NAT is accomplishing for them. NATs are physical devices isolating a physical network from the Internet. They keep a pool of external IP addresses for the computers on the LAN which are using internal addresses. Each time one of these LAN computers accesses the Internet, the NAT will match its internal IP address with a free external IP address from its pool and make sure that answers received from the selected external IP address are returned back to the right computer on the LAN. The local IP address of the LAN PC is substituted with one of the external addresses by the NAT in the data packets leaving the LAN to the Internet. These are copied back by the NAT in the data packets coming back to the computer on the LAN. Some NATs are capable of operating with one external IP address only. Since they are controlling all the incoming and outgoing data, they can play on the fact that they can reassign port numbers from the sender in outgoing messages to create unique IP addresses – port combinations (multiplexing). When a response comes back, they will read the destination IP Address – port combination from the data packet and search for the corresponding PC destination on the LAN in their list of combinations. They'll update the data packet with proper destination information (demultiplexing) and drop it on the LAN. The proper destination PC will get it.

Network Boundaries Reminder - 85

NATs also have their own internal IP address on the LAN, which is different than their external pool address(es). They are accessed with different IP addresses on the LAN and on the WAN.

Some Limitations
NAT can only translate addresses from data packets holding their destination and source IP addresses in a header. Some applications and protocols include IP addresses in the data part of data packets, which is hardly detectable by NATs. If such applications include their LAN IP address, it will not be useful to applications located outside of the NAT. These are not static addresses and one cannot rely on these to identify a computer or to try to access it from outside the NAT. NATs break the end-to-end principle that was valid until we started lacking IPv4 addresses. They compromise Internet protocols relying on the fact that IP addresses will not be translated in data packets. Some other protocols work fine when, either the sending computer or the destination computer, but not both, is located behind at NAT. Otherwise they fail. Additional mechanisms become necessary to solve these issues. There is a good side to NATs (in addition to solving the lack of IP addresses issues); direct attacks on specific computers located on a LAN become hard to achieve, since their IP address is unknown from the outside. NAT can cause some trouble to JXTA applications operating on IT, but these can be relatively easily solved as we will see further.

PAT
PAT is an acronym for NAT port translation or port address translation. It is the process by which a NAT may translate a private IP address port number into another public address port number.

Network Boundaries Reminder - 86

Proxy

A proxy server aims at forwarding Internet-like requests from its clients to other computers on the Internet. They can be used to manage HTTP requests for example. Instead of sending their requests directly to the Internet, PCs located on a network isolated by a proxy server will need to send their requests to that proxy and will receive corresponding answers from it too. Proxy servers are most often used to perform controlling activities similar to those of firewalls. In JXSE, if a peer needs to communicate on the Internet through a proxy, this has to be configured properly (we will cover this later).

Router
Routers are responsible for finding out whether data packets should be transferred from one subnet to another or not, or whether they should be sent to the outside on Internet or not. They can find this information from the IP addresses themselves; some ranges are reserved and have a special meaning regarding the destination of data packets. By default, JXSE uses the 224.0.1.85 IP address for multicasting. Routers will not forward data packets using this address to the Internet. These data packets will remain inside the part of the LAN isolated by the router. Very often, routers also act as NATs and firewalls for the LAN they are isolating.

Multicasting Versus Subnets
Multicasting of data packets from computers located in different subnets of the same LAN may or may not be enabled by the routers organizing these subnets.

Network Boundaries Reminder - 87

Natural Network Boundaries
Natural Network Boundaries (NNB) are those rising from physical devices and differences between network transportation protocols. Your PC, together with its network card, its network cable and its communication protocols can only communicate with to the set of PCs who can exchange information with these same means. There is a natural boundary to the set of PCs it can reach considering its networking capacities. Many PCs are now equipped with wireless communication facilities. It extends their capacity to communicate with other PC's without using network cables. Not all destination PCs can exchange information that way. They need special material and software to do so. The natural network boundary of wireless enabled PCs is larger than those who do not have wireless communication facilities, since they can potentially communicate with more computers than the latter. However, a PC connected to the Internet with a network card and a network cable can communicate with a wireless PC connected to Internet through a wireless connection if there is a third PC on the network equipped with adequate material and software to act as bridge between the cabled network and the wireless network. This is transparent for the user. Now, imagine that in the future, a new type of network communication layer called FutureNet is created to replace TCP/IP. Let's assume that it is not compatible with TCP/IP. Some computers will be able to operate on both networks, if they have the adequate material and software, while others won't. Computers operating only on FutureNet or only on TCP/IP will need to find a bridge computer to communicate between both transportation layers. Why are we mentioning all this? Because every implementation of JXTA must select a network transportation layer. In JXSE, peers can only reach peers accessible with TCP/IP or HTTP. If an implementation of JXTA does not support TCP/IP of HTTP, the peers of both implementations will not be able to communicate with each other, even though they will have implemented the JXTA protocols properly. They will not be able to cross the natural network boundary between them. As a consequence, if JXTA were implemented in the future using only the FutureNet transportation layer, computers using that implementation would not be able to communicate with peers us-

Network Boundaries Reminder - 88

ing JXSE, since it operates only over TCP/IP and HTTP. The problem would be solved once a peer becomes capable of operating over both networks with a JXTA implementation capable of using both network transportation layers. This is how the natural network boundary would be crossed. Of course, there is a very high probability that if a new network communication layer called FutureNet is created in the future, existing JXTA implementations will be adapted to operate on that network transportation layer too. Therefore bridge peers will not be necessary for peers using that updated implementation. This is a very theoretical discussion, but it illustrates an important point: no matter how universal JXTA tries to be, the surface of its universality is constrained by the selected network transportation layers for its implementations. In addition, it is not because a network technology is available on one's PC that a JXTA implementation can automatically use it to connect to other JXTA peers, some adaptations may be required. Metaphorically: Do you remember the tribes capable of navigating and the tribes capable of flying? If some tribes can only be reached by flying, those only capable of navigating will need the help of those capable of flying to send them messages or cargo. Regarding our argument, there is a very low probability that all tribes capable of flying would all be incapable of navigating too. This demonstrates the need of having islands where boats can moor and flying devices can take off and land to connect with all tribes on all islands.

Artificial Network Boundaries
Artificial Network Boundaries (ANB) are devices controlling and organizing the natural flow of data between networks, for example: routers, NATs, Firewalls and Proxies. Artificial network boundaries usually restrain the surface of natural network boundaries.

JXTA Transportation Layer
JXTA knows three concepts for transportation: endpoints, pipes and messages. Two peers are endpoints communicating messages, often over a pipe. JXTA specifications do not make any requests or put any constraints on the implementation of these concepts and the protocols that use them. Technically speaking, JXTA could be implemented on TCP, on UDP, on HTTP or any other transportation protocols. It does not matter as long as the specifications are met. The only limitation is

Network Boundaries JXTA Transportation Layer - 89

that applications implementing JXTA should not make any assumption about the time it takes to communicate data from one peer to another or assume that transmitted data will necessarily reach its destination. That's it! Metaphorically: The transportation layer is the sea and the tribes capable of flying are using FutureNet.

JXSE Transportation Layer
The network transportation layers selected by JXSE are TCP/IP and HTTP. Three types of potential boundaries need to be crossed: proxies, firewalls and NATs. As we will see, both TCP/IP and HTTP are required to overcome the limitations imposed by these artificial network boundaries.

Overcoming Firewalls
By default, JXSE uses port range 9701 to 9799 for TCP/IP communication. If a peer wants to communicate with another peer beyond the LAN, it will use its IP address and port to send its messages sliced in data packets. Unfortunately, if the LAN on which the peer is located is isolated by a firewall blocking ports 9701 to 9799, the message will never reach its destination. In this case, JXSE will switch to another protocol: HTTP. It will first try to establish a connection with known relay peers using HTTP via port 9901. Relay peers are special peers capable of receiving and answering HTTP requests from other peers inaccessible because of firewalls. One should not forget that when users send HTTP requests from their browsers, these requests can contain some data to the web server's attention. For example, when you type your login and your password on a web page, they are transmitted as parameters to the web server in the corresponding HTTP request. The web server sends back an answer; most often an HTML page to be displayed by the web browser of the user. A HTTP request is always followed by an answer. JXTA uses HTTP requests to pass its XML document as parameters in HTTP request. The relay peer receiving these responds with another XML document in the HTML response to the initial peer. This other document can come from third-party peers that the relay peer has contacted on behalf of the firewalled peer. This mechanism implies that JXSE peer contain an HTTP engine which is activated when peers behaves as relays. Currently, JXSE uses the Jetty HTTP server. It is in the process of being replaced by the Netty HTTP engine requiring much less resources to operate. Unfortunately, the HTTP fetching mechanisms only works one way. Non-relay peers need to

Network Boundaries JXSE Transportation Layer - 90

probe relay peers from time to time to retrieve messages from other peers. A relay peer cannot initiate HTTP requests to non-relay peers. The consequence is that relayed communications will always be slower than non-relayed ones. It is tempting to increase the frequency of probes, but this comes at the expense of relay peers' responsiveness. At last, if all default JXSE ports (9701 to 9799, and 9901) are blocked by a firewall, a peer trying to connect to other peers located beyond a firewalled LAN will not be able to communicate with these no matter what. It will only be able to communicate with other peers located on the same LAN. Some issues will also rise if applications start listening to all JXSE ports, before a JXSE peer has a chance to listen to them as well.

Relay Service
The relay service is not defined as part of the JXTA specification, yet it has been created as part of JXSE to help overcoming artificial network boundaries. This service is responsible for managing HTTP communication between any peer and relay peers. It is activated when a peer behaves as a relay. Remark: In the previous edition of this book, it was said that 'This service is responsible for man-

aging HTTP communication between any peer and relay peers'. This is not exactly true, because
the JXSE relay service can operate with TCP too (or any other transport). This misconception – common in the JXTA community – comes from a comment in the 2.5 Programmer's guide: 'If you are located behind a firewall or NAT, you must use HTTP and specify a

relay node'.
Fact is, you only need to use HTTP communication with a relay peer when: 1. Corporate firewalls only allow HTTP communication. 2. Using small devices only offering an HTTP API not operated on TCP itself. If private IP address translation is the only connectivity issue, TCP can be used with relay peers.

Overcoming NATs
In IPv4, NATs create an issue for JXSE, because the IP address of a peer located behind NATs is often unknown to peers located outside of the NAT. IPv4 addresses on a LAN are frequently assigned dynamically when a computer is booting. These are called dynamic IP addresses and are private to the LAN. Some peers behind a NAT also have fixed (or static) public IP addresses that they keep even after rebooting. Network Boundaries JXSE Transportation Layer - 91

Assuming that a NAT is properly configured to forward all IP packets corresponding to a static IPv4 address of a peer located on the LAN, that peer will always be visible on the net by all JXTA peers knowing a route containing an endpoint address created with that IPv4 static address. This type of peer will not be impacted by the NAT. However, the situation is different for LAN peers having dynamic IP addresses. Those IP addresses cannot be used directly on the Internet and need to be translated into external IP addresses by the NAT. As a consequence, such peers remain inaccessible from remote peers located on the WAN (i.e., the Internet area not isolated by the NAT), until either a) a remote peer manages to obtain an virtual route to an inaccessible peer via a relay peer visible to the remote peer and to which the inaccessible peer is connected, or b) the inaccessible peer establishes a connection to the remote peer spontaneously. Peers capable of using IPv6 addresses are not impacted by NATs, since there is no need to compensate for a lack of IP addresses in IPv6. They can easily establish direct IP connections with other peers capable of using IPv6 addresses. Such peers will publish route advertisements contain endpoint addresses created with IPv6 addresses. These advertisements may also contain IPv4 addresses to (potentially) allow external peers to make IPv4 connections with them (if they are not blocked by artificial network boundaries). Apparently, JXSE does not necessarily privilege IPv6 over Ipv4. Later, we will discuss NAT traversal issues and potential solutions to increase connectivity between peers.

Overcoming Proxies
Proxy servers are the easiest boundaries to overcome (when they can be). If your users have to access the Internet via a web proxy, you will need to pass the proxy parameters in the command line when starting your JXSE-enabled application. Here is an example:
> java -Dhttp.proxyHost=theproxy.atmycompany.com Dhttp.proxyPort=8080 ...

For proxies requiring authentication, additional parameters should be added in the command line:
> java -Djxta.proxy.user=myusr -Djxta.proxy.password=mypwd ..

One can also explore the possibility to set those parameters at runtime with the following code before starting the JXTA network for example: Network Boundaries JXSE Transportation Layer - 92

... System.getProperties().put(proxySet,true); System.getProperties().put(proxyPort,8080); System.getProperties().put(proxyHost,theproxy.atmycompany.com); ...

Remark: If a proxy is blocking the transmission of TCP/IP and HTTP data on the default ports selected by the JXSE implementation (9701 to 9799 for TCP/IP and port 9901 for HTTP), communication between peers will be impossible. If the communication is blocked only on default TCP/IP ports, a peer will be able to reach other peer if and only if it can establish contact with a relay peer on the WAN.

Network Boundaries JXSE Transportation Layer - 93

Seeds

If you develop your own JXTA-enabled application based on JXSE, your must take into account the fact that peers running your application may not always be able to connect to other peers using that same application easily. Even if they are not hampered by artificial network boundaries, how can a peer located in Namibia and connected to JXTA via the net peer group know about another peer also connected to JXTA via the net peer group in Canada? It is not because they are both connected to JXTA using the same peer group that they necessarily know how to contact each other by using one of the network protocols of the JXTA implementation. How would they get to know about each other's route advertisement? By which means?

Network Boundaries JXSE Transportation Layer - 94

If we push this argument a little further, we can easily imagine that pockets of peers (all connected to JXTA via the net peer group) could organize themselves in different countries, having their own rendezvous peers to connect isolated pocket members, but those pockets of peers would still not be connected together. This lack of connectivity can be solved by the means of well-known rendezvous seeds, that is, a set of well-known peers not made inaccessible by artificial network boundaries. Some pocket peers (for example, local rendezvous peers) would use these seeds to notify their presence and be added to the peerview of the seed rendezvous. Automatically, connections would be established with other rendezvous of other pockets, since JXTA automatically propagates peerview updates between connected rendezvous of a peer group. This provokes a cascading effect allowing everyone to (potentially) know about everyone else. The concept of seeds also applies to relay peers to help peers made inaccessible by NATs or firewalls establishing connections with other peers. Of course these relay seeds should not be inaccessible because of artificial network boundaries themselves.

Peer Accessibility
In JXTA, there is no such thing as a blind peer not capable of finding other peers on the JXTA network. There are only inaccessible peers and distant peers (that is, not accessible by LAN multicasting only). Don't forget that peers can also be off-line, that is, not connected to the network for a period of time.

WAN
The following tables will help you understand what you should expect from JXSE according from the WAN. You should perform an analysis with both tables and combine the mentioned restrictions to find out how accessible your peer is.
Behind a Yes TCP traffic Yes firewall enabled No HTTP traffic and ports enabled and open ports open No Accessible from anywhere through TCP Yes Accessible if HTTP contact established with a relay accessible from the WAN No Inaccessible from the WAN Accessible from anywhere through TCP

Network Boundaries Peer Accessibility - 95

Behind a NAT

Yes Peer using IPv4 address

Yes

Using a private address

Yes Accessible from the WAN if contact established with a relay accessible on the WAN No Accessible from anywhere if NAT configured properly to let data packets stamped with static IP address pass without translation Accessible from anywhere if IPv6 is operational between communicating peers. Accessible from anywhere

No No

LAN
Same Subnet
The natural way for peers located on the same subnet (and therefore in the same LAN) is to use multicasting on a shared multicasting IP address and port. Typically, these peers do not need a rendezvous peer to discover each other, unless the port used for multicasting is blocked on the peers themselves, or multicasting is disabled on the LAN or the peers themselves. If multicasting is disabled, one peer will need to act as a rendezvous for the other peers. Assuming that all peers are connecting to JXTA using the same peer group, the rendezvous should be set as a seed for the other peers. Discovery queries for peer advertisements should be sent by each peer to get to know about other peers on the subnet/LAN. If multicasting is enabled on a subnet, queries sent by a peer will be automatically sent to other peers on the subnet via the multicasting address. In this case, rendezvous peers are not needed to forward queries to peers on the subnet/LAN. However, rendezvous are necessary to forward queries to peers located outside the subnet/LAN.

Different Subnets
We have already mentioned that the capacity of peers located on different subnets to communicate depends on the setting of the router organizing these subnets. Typically, the rules regulating the visibility of peers between subnets of a same LAN are the same as those located on the WAN in respect to firewalls when these are set between subnets. However, NATs do not affect traffic between subnets. We have also mentioned earlier that multicasting between subnets of a same LAN may or may not be enabled. Therefore, one may or may not need a rendezvous seed to establish connections between peers located between different subnets and to forward queries between them.

Network Boundaries Peer Accessibility - 96

NAT Traversal
Before we start discussing the various techniques available to establish communication between peers located behind NAT with a private address, we need to introduce some vocabulary and some key concepts. We will start by reminding all the obstacles an IP packet has to overcome to reach a destination peer.

IP Obstacles

When a IP packet (UDP or TCP) leaves a user's PC or device, it passes through several obstacles: 1. It may be blocked by a firewall installed on the local PC or device. 2. It may be blocked a LAN firewall (usually implemented inside a router). 3. It may be blocked a LAN NAT (often part of a router) if the destination address is not routable. 4. It may be blocked by any additional corporate routers or proxy servers filtering traffic. 5. It may by blocked by an Internet Service Provider router (though this is rare). 6. It travel through many hops on the Internet and may be blocked (though this is rare too). 7. It may blocked by the destination's outmost router. 8. Etc... when navigating to the destination user PC or device. Multiple IP address translations can happen at each encountered router/NAT. Further in this chapter, we will describe situations where only one NAT is involved, but one should keep in mind that multiple layers of NATs are common when communicating on the Internet.

Network Boundaries NAT Traversal - 97

Port Prediction
Port prediction refers to guessing the port mapping operation performed by a NAT when translating a private IP address to a public IP address. If one can predict NAT mappings when local peers establish connections to the WAN, there is a possibility to connect two NAT-ed peers if they can predict each other's NAT translation mechanism by sending proper communication to the predicted port.

Punching Holes
If port prediction can be performed successfully on a NAT, then a hidden peer knowing that another peer wants to communicate with it can punch a hole in its NAT (i.e., create a mapping) by initiating a dummy outbound communication. If the mapping is predictable, the other hidden peer can then initiate a communication to that anticipated mapping. It will be forwarded to the initial peer by the NAT, since it holds a mapping. Punching holes is a fundamental mechanism by which NAT traversal can be performed on Ipv4.

Hairpin Issue
The hairpin situation is characterized by two peers located behind the same NAT. Let's imagine that B has created an outbound communication and that peer A knows about this translation. Under normal circumstances, peer A can always communicate with peer B using its local IP address, but what if is uses the translated address of peer B? This is called a hairpin situation and it is not always handled properly by NATs. Typically, NATs should forward the traffic to peer B, even though it does not come from the WAN. Such situations are common when establishing communication with NAT-ed peers. It can also happen when multiple levels of NATs are involved.

Network Boundaries NAT Traversal - 98

RFC 5128
In March 2008, an informational memo called RFC 5128 was created to the attention of the Internet community. It summarizes the state of P2P communication across NATs and proposes a common terminology regarding NAT mapping strategies and endpoint filtering. We will cover this later.
27

TURN
The current technique used by JXSE to establish connection with peers located behind NATs is equivalent to Traversal Using Relay NAT (TURN). A relay with a public address accepts and forwards traffic from and to peers located behind NATs with private IP addresses. It can be used for both TCP and UDP traffic. The benefit of this technique is that it allows communication from any peer to any peer on the Internet, regardless of the presence of any (traversable) NATs. The drawback is that is creates bottlenecks and many relays are required to sustain high communication between peers.

STUN
STUN stands for Simple Traversal of User Datagram Protocol (UDP) through Network Address Translators. This protocol is about establishing direct UDP connection for peers located behind NATs. The first version of the protocol defined in RFC 3489 went like this: 1. Each peer connects to two STUN servers (i.e. with a public address) to learn about the translation of their local address into a public address. This information is available to the STUN server located on the WAN when receiving the UDP packets. 2. By analyzing the values returned by the STUN servers, one can classifying the NAT behaviors as following:
28

27 28

See http://tools.ietf.org/html/rfc5128. See http://www.ietf.org/rfc.html for more details.

Network Boundaries NAT Traversal - 99

Full Cone – Once a NAT mapping is established towards a remote WAN IP address, return traffic from any IP address is accepted by the NAT. In other words, it does not matter whether returning/incoming traffic comes from the NAT mapped IP address and port or not, it is accepted and forwarded back to the hidden peer. 23.55.128.99:4445 ⇆ XXX.XXX.XXX.XXX:YYYY

Restricted Cone – Once a NAT mapping is established towards a remote WAN IP address, only traffic coming back from the translated address is accepted, regardless of the port: 23.55.128.99:4445 ⇆ 23.55.128.99:YYYY

Restricted Cone – Once a NAT mapping is established towards a remote WAN IP,
only traffic coming back from the translated address:port combination is accepted: 23.55.128.99:4445 ⇆ 23.55.128.99:4445

Symmetric – Contrary to the above behaviors where a given LAN peer's local IP address is always translated to the same public dress, symmetric NATs always create a new public address:port communication for all outbound communication.

3. Each behavior can then be transmitted to the other peer which can establish direct UDP communication, except in the presence of symmetric NATs. In the presence of restricted cone NATs, spoofing of sender's address would be necessary. Unfortunately, this classification turned out to be too simple and is now abandoned It does not cover for all situations properly. RFC 3489 has been replaced by RFC 5389 in October 2008. The scope has been reduced to detecting public mapping of a hidden peer/device and eventual connectivity between peers. The NAT classification has been dropped and the newly proposed standard does not claim to be a NAT traversal solution anymore.

STUNT
STUNT stands for Simple Traversal of UDP through NATs and TCP too. This concept was intro-

Network Boundaries NAT Traversal - 100

duced in an article called: Characterization and Measurement of TCP Traversal through NATs

and Firewalls, by Saikat Guha and professor Paul Francis .
The first version (called STUNT #1) of this method includes spoofing in the 3-way handshake as following: 1. Two peers A and B behind different NATs are connected to a STUNT server. 2. They both initiate a dummy TCP connection by setting a low TTL
30

29

in the first TCP packet

(i.e., SYN). This punches a hole in respective NATs, but a notification of TTL failure is returned to each sending peer. 3. Yet, the mapping in each NAT remains valid and the returned TTL failure packet contains low level information about the dummy TCP connection. Both peers transmit this information to the STUNT server, which fabricates 'TCP connection accepted' packets for each peers and sends them back. 4. Both NATs believe that the responses come from the target peers and forward the packet received from the STUNT server to their local peers. 5. NAT traversal has been established. There are two main issues with this method. Firstly, it is hard to find the proper low TTL values, since there may be multiple levels of NATs between a given NAT-ed peer and the STUNT server. Holes must be punched until the last NAT before reaching the STUNT server. Secondly, one must have enough privilege to fiddle IP packets, which is not always possible under every operating system or in every programming language. The second version (called STUNT #2) of this method goes like this: 1. Only peer A initiates a dummy TCP connection by setting a low TTL. A hole is punched in NAT A.

29 30

See http://conferences.sigcomm.org/imc/2005/papers/imc05efiles/guha/guha.pdf. TTL stands for time to live. It sets a limit to the number of hops (i.e., intermediary devices) a packet can go through to reach its destination. At each hop, the TTL is decreased by 1. When it reaches 0, the packet is discarded and a notification is sent back to the sender.

Network Boundaries NAT Traversal - 101

2. It collects the TTL failure response from the returned packet and sends to the STUNT server who transmits the information to peer B via a central peer. 3. Peer B sends a TCP connection request to peer A using the information provided by the STUNT server. It punches a hole in its NAT. 4. NAT A accepts this incoming request (since a hole has already been punched) and sends a positive response to peer B. 5. The TCP communication is established, NAT traversal has been performed. The benefit of this method over STUNT #1 is that no packet spoofing is required.

TTL-less Version of STUNT
Using port prediction, TTL-less versions of STUNT #1 and #2 can be implemented too. The packets are sent to the predicted ports after holes are punched.

New NAT Classification
The work of Saikat Guha and professor Paul Francis led to the creation of new grids describing NAT behaviors. The first one relates to NAT mapping when outbound communication is initiated:
NAT Mapping Independent Description The mapping is independent from the target/outbound IP address and port. For a given local address:port combination, the mapping will always be the same. For a given local address:port and target address:port combination, the mapping will remain the same if this combination is re-used. The mapping for new combinations results in an increase of the mapped port by 1. Each new outbound communication creates a new mapping (no re-use of existing mapping) and the mapped port is increased by 1. For a given local address:port, the mapping will remain the same if the target port is the same. In other words, the mapping only depends on the local outbound address:port and target port. For a given local address:port, the mapping will remain the same if the target port is the same. In other words, the mapping only depends on the local outbound address:port and target port. Each new outbound communication creates a new mapping with an unpredictable port mapping.

Address and Port1

Connection1

Port1

Address1

ConnectionR

Network Boundaries NAT Traversal - 102

Remark: the port increase is set to δ = 1 in the above table, but some NATs are known to have δ = 2. The second grid relates to the treatment of incoming communication:
Endpoint Filtering Address and Port Address Port Independent Description Incoming communication must match the mapped address and port. Incoming communication must match mapped address. Incoming communication must match mapped port. All incoming communication from anywhere is accepted as long as a mapping is available.

These classifications have been summarized in RFC 5128. Remark: By testing 16 lab NATs and 93 homes NATs, Saikat Guha and professor Paul Francis found out that only 0.5% behaving like ConnectionR (or symmetric NATs). This is important, because it is impossible to punch predictable holes with these NATs.

NUTSS
NUTSS
31

is a network architecture also developed by Saikat Guha and professor Paul Francis at

Cornell University. It stands for: “NAT that effectively extends the IP address space, URIs that re-

store end-to-end stable addressing, Tunnels that allow protocols like IPsec and mobile IP to run through NATs, SIP that routes messages with URIs, end-to-end, and lets hosts signal their intentions to each other and to middle boxes in real time, and lastly STUNT that tells how to establish direct IP connectivity through NATs ”.
The project code has been made public in 2007 and is not maintained anymore.

P2PNAT
P2PNAT
32

is a technique proposed in 2005 by Bryan Ford from the Massachusetts Institute of

Technology, Pyda Srisuresh from Caymas Systems, Inc. and Dan Kegel. It aims at creating TCP communication between NAT-ed peers. The idea is to have a central peer to which two NAT-ed peers are connected with a TCP connection. When they want to communicate with each other, they
31 32 See http://nutss.gforge.cis.cornell.edu/. See http://www.brynosaurus.com/pub/net/p2pnat/.

Network Boundaries NAT Traversal - 103

first fetch the other's translated address with the help of the server peer. Then, they both initiate a TCP connection to the other peer using the same port they were using to connect to the central peer and wait until the TCP connection is established successfully. This method relies (amongst others) on the fact that NATs will accept an incoming TCP communication request on the port used to sent an outbound TCP communication request to the target peer, before the outgoing request has been notifies as accepted by the target peer. This sequence of TCP events is not necessarily accepted by all NATs.

NATBlaster
The NATBlaster technique was proposed by Andrew Biggadike, Daniel Ferullo, Geoffrey Wilson, Adrian Perrig from the Carnegie Mellon University in 2005. It is very similar to the STUNT #1 method and goes like this: 1. Two peers A and B behind different NATs are connected to a central peer. 2. They both initiate a dummy TCP connection by setting a low TTL in the first TCP packet (i.e., SYN). This punches a hole in respective NATs, but a notification of TTL failure is returned to each sending peer. 3. The collected information is transmitted to each others' peer via the central peer. 4. Both peer send a 'TCP connection request accepted' response to the other peer. 5. NAT traversal is been established. This method bears the same issues as STUNT #1, but does not require packet spoofing. However, it uses TCP event sequences which are not always accepted by all NATs.
33

NatTrav
NatTrav is a STUN like method proposed in 2005 by Professor Jeffrey L. Eppinger from the Carnegie Mellon University to establish direct TCP connections between peers located behind NATs.
33 TTL stands for time to live. It sets a limit to the number of hops (i.e., intermediary devices) a packet can go through to reach its destination. At each hop, the TTL is decreased by 1. When it reaches 0, the packet is discarded and a notification is sent back to the sender if target has not been reached.

Network Boundaries NAT Traversal - 104

It involves a public broker peer helping hidden peers to establish a connection. Each peers maintain some kind of UDP lease connection with the broker peer. When a peer wants to communicate with the other, it notifies the broker, which notifies the target peer. The establishment of direct communication process is started. This method tacitly relies on the fact that for a given outgoing local address:port combination, the NAT will always use the same mapping, though this is not explicitly stated.

PWNAT
PWNAT , pronounced poe-nat, is an ingenious technique developed by Samy Kamkar to punch holes in NATs for NAT traversal. Unfortunately, it relies on a NAT configuration that most companies and network administrator disable for security reasons. In general, all incoming and outgoing IP packets are filtered by NAT according to allowed and existing mappings, but there is an exception. ICMP, the Internet Control Message Protocol, is part to of IP stack. It can be used to trace routes to remote device via echo requests messages (type 8). This is used by the ping instruction for example. Contrary to other types of communication, Type 8 ICMP packet are not mapped. In fact, they cannot be mapped, because their purpose is to provoke an echo from all devices between this device and the targeted device. Since these are unknown, their IP address is also unknown. Hence, not mapping can be established. NAT work around this situation by analyzing the content of the returned ICMP packets (type 0, echo response). Here is how pwnat works: 1. Let's imagine a source peer A on LAN A with local IP address 192.168.0.34 hidden by a NAT A having 248.18.22.44. 2. Let's imagine a target peer B on LAN B with local IP address 192.168.0.45, knowing the public IP address of NAT A. 3. Both peer agree that communication between should happen on a pre-agreed port, for example: 2222. 4. When started, peer A starts sending ICMP echo packets to a dummy public address, for
34 See http://samy.pl/pwnat/.
34

public

address

Network Boundaries NAT Traversal - 105

example 3.3.3.3, on port 7 (the echo port). This message has a pre-agreed (hard-coded) identifier, sequence number and content known by peer B too. 5. NAT A translates 192.168.0.34:7 to, let's say 248.18.22.44:7 and the echo is sent to 3.3.3.3:7. Peer A never gets a response from 3.3.3.3 and does not expect any. 6. Let's imagine peer B want to communicate with Peer A, it creates dummy echo reply (type 0 ICMP message) using the pre-agreed identifier, sequence number and content. 7. Peer B knows about the 248.18.22.44 public address. It sends its packet to 248.18.22.44:7. 8. NAT B translates peer B's local address 192.168.0.45:7 to, let's say 87.88.89.90:7, and sends it to 248.18.22.44:7. 9. In the mean time, Peer B also starts sending UDP packet to peer A on the pre-agreed port: 248.18.22.44:2222. A hole is punched in the target peer for 2222. 10. NAT A receives the echo reply from peer B and does not check that the reply does not come from 3.3.3.3. Peer B faked its identity as a step device (hop) between Peer A and 3.3.3.3. 11. NAT A forwards this echo response to peer A after analyzing its content. 12. Peer A knows a) the translated address 87.88.89.90 of peer B, and that b) peer B wants to communicate with it. 13. Peer A starts to fire UDP packets to 87.88.89.90:2222 and punches a hole for port 2222. 14. Peer A starts to receive communication from Peer B on 2222 and so does Peer B from Peer A. 15. NAT traversal is accomplished. This technique relies on port preservation between NATs, which is not always guaranteed. Moreover, corporations often close such ICMP echo communication.

ALG
ALG are application layer gateways. These can be installed on PCs, NATs or firewalls. Such applications have been implemented to solve NAT traversal issues and installed on NATs to filter and analyze traffic. Unfortunately, these solutions are not universal, because they would require installation on all Network Boundaries NAT Traversal - 106

devices. Sometimes, IP address information is 'hidden' in the IP packet's content/payload or are encrypted. ALGs are not always able to handle such situations. Global updating and maintenance of ALGs is not a simple operation. One of the biggest problems with ALGs when it comes to NAT traversal is that they create an open for man-in-the-middle attacks. Traffic can potentially be diverted inappropriately.

UPnP
Regarding NAT traversal, Universal Plug-and-Play is a technique by which devices can communicate with router and tell them to forward external port traffic to a specific internal host on the LAN. The routers must support that technology to operate. Unfortunately, this technique is not safe and can be used by hackers to perform many attacks. For example, a malicious application could let undesired traffic come in through the router.

ICE
ICE stands for Interactive Connection Establishment. It is an Internet standardization proposal for

Network Address Translator (NAT) traversal for Offer/Answer Protocols. It relies on STUN and
TURN. The first draft was submitted in 2003, and a very recent version of the proposal has been released in April 2010 (RFC 5245). The motivation for ICE comes from Session Initiation Protocol (SIP), a method used by voice of IP (VoIP) communications. As described by Jonathan Rosenberg in the IETF journal issues. A standard was needed. We will briefly introduce the main steps of an ICE session creation: 1. Gathering – A peer starts to collect IP addresses and ports for possible communication. These are called candidates. The NAT translation of these addresses is obtained by contacting a STUN server. The result is called server-reflexive candidates. 2. Prioritizing – The candidates are assigned a priority according to a preference policy. 3. Offering – The candidates are sent to the remote peer. 4. Answer – The remote peers acknowledges the communication request and sends back its own candidates.
35 36 See http://tools.ietf.org/html/rfc5245. See http://www.isoc.org/tools/blogs/ietfjournal/?p=117.
36 35

in 2007, NAT

traversal was an issue then. Several solutions were implemented, but often came with their own

Network Boundaries NAT Traversal - 107

5. Checking – Each peer constructs candidate pairs with their candidates and remotes candidates. Each pair is prioritized and tried successively. 6. Completing – Once a connection is established successfully, peers confirm the selected candidate pair and start communicating. The ICE standard proposal has been through many evolutions. At the beginning, it was explicitly referring to SIP. Now, it does not anymore: “SIP can use ICE”. The latest standard proposal explicitly refers to UDP, whereas in earlier versions, this was not the case.

ICE-TCP
ICE-TCP or TCP candidates with ICE is a standard draft created in October 2009. It aims at “ ex37

tending ICE to TCP-based media, including the ability to offer a mix of TCP and UDP-based candidates for a single stream”. This document contains the key concepts of NUTSS.

“Behave” Compliant NAT
Solving the NAT traversal problem is not only a software related issue. Some best practices for NAT configuration and design have been defined in RFC 5382 and RFC 4787 for TCP and UDP communication respectively. The consequence is that individuals & companies may need to invest in new compliant material to smoothly operate P2P applications if old material cannot be configured properly or break possibilities of performing NAT traversal.

RFC 5382
For TCP, the best practice recommendations include the following. A NAT should:
• •

Have an 'Endpoint-Independent Mapping' behavior. Have an 'Endpoint-Independent Filtering' behavior, or an 'address dependent filtering' if a more rigorous behavior is required.

• •

Be capable of handling TCP simultaneous-open connections. Not answer an unsolicited inbound TCP request (SYN packet) for at least 6 seconds. If a corresponding outbound TCP request is received in the mean time, the original SYN packet must silently be dropped, else a 'port unreachable' error may be sent.

37

See http://tools.ietf.org/html/draft-ietf-mmusic-ice-tcp-08.

Network Boundaries NAT Traversal - 108

Not abandon an idle connection session before 2 hours and 4 minutes. For DDCP minutes.

38

con-

nections, the value of the "transitory connection idle-timeout" MUST NOT be less than 4

• • • •

Disable all ALGs impacting TCP. Not use port overloading (i.e., assigning a new port for each outbound connection). Support/manage hair-pinning situations properly. Translate ICMP Destination Unreachable (Type 3) messages if it translates TCP addresses.

Not terminate NAT mapping or TCP connections upon receipt of any sort of ICMP messages (otherwise it would open many opportunities to disturb established communications).

RFC 4787
For UDP, the best practice recommendations include the following. A NAT should:
• •

Have an 'Endpoint-Independent Mapping' behavior. Have an 'IP address pooling' behavior of 'Paired', that is, a device with a private IP address should always be translated with the same public IP address. This is relevant for NATs capable of exposing multiple public IP addresses (i.e., address pooling). If the mapping is random, it is called 'Arbitrary'.

• • • •

Not implement 'Port overloading' for port assignments during translations. Keep house source ports in the 0-1023 range into the same range for translation. Keep house source ports in the 1024-65535 range into the same range for translation. Implement 'port parity preservation', that is, an even port should be translated into an even port, and an odd port should be translated into an odd port. This a recommendation, not an obligation.

Not expire UDP mappings in less than two minutes, unless the port is in the 0-1023 range. A delay of 5 minutes is recommended. Have a 'NAT outbound refresh behavior' of true. That is, if an UPD datagram is sent from a NAT-ed device to the WAN, it should reset any idle timeout monitor to zero. A 'NAT inbound refresh behavior' is optional.


38

Make sure that configurable external IP interface do not conflict with internal IP addresses

Datagram Congestion Control Protocol: It is a protocol guaranteeing the delivery of datagrams, but not necessarily in order.

Network Boundaries NAT Traversal - 109

or make sure translation happens smoothly.

Have an 'Endpoint-Independent Filtering' behavior, or an 'address dependent filtering' if a more rigorous behavior is required. This may be a configurable option on the NAT.

• • • • • • •

Support/manage hair-pinning situations properly. Disable all ALGs impacting UDP. This may be a configurable option on the NAT. Have a deterministic behavior and not change translation or filtering behavior over time. Not terminate NAT mapping upon receipt of any sort of ICMP messages. Not filter ICMP messages based on their source IP address. Support ICMP destination unreachable messages (recommendation). If a packet received on an internal address with the 'don't fragment' flag set to 1, an ICMP message "Fragmentation needed and DF set" should be sent to the host. If the flag is set to 0, the NAT must fragment the packet and send the fragments in order.

Should be able to receive in-order and out-of-order fragments (a 'Receive Fragments Out of Order' behavior).

Where Does JXSE Stand?
JXSE is currently relying on a TURN-like solution to overcome NAT issues. However, this is not very efficient on a large scale. The community has shown some interests in implementing NAT traversal solutions to increase connectivity between peers. Several factors should also be taken into account. As of release 2.6, JXSE uses TCP, multicasting and HTTP for communication. UDP is not used. Hence, if a pure TCP NAT traversal solution can be implemented, it should have the priority. This eliminates the latest ICE standard proposal and shifts focus on ICE-TCP. Any solution requiring specific privileges on peer devices should be discarded, as this parameter cannot be controlled by the application. Short TTL based solutions are hazardous and not always implementable under every environment. The selected solution should work with as many NATs behaviors as possible. The research performed by Saikat Guha and professor Paul Francis indicates that STUNT #2 without low-TTL would be the preferred solution, as it is the most robust to establish TCP connection between NAT-ed peers. The community will decide.

Network Boundaries NAT Traversal - 110

Conclusion
Obviously, since the booming of P2P around year 2000, no definitive standard has emerged to solve all NAT traversal issues. Existing research shows that it is a complex problem to solve. Multiple solutions exist, but have not been integrated fully. Evidently, the final standard for NAT traversal, if ever accepted by Internet community, will have to: a) Work both for TCP and UDP communication. b) Make usage of port prediction from time to time to cover for all types of NAT behaviors. c) Punch holes in NATs from time to time. d) Work without requiring special user privileges on the device or to access to NATs directly. e) Implement a fall-back solution for NATs filtering/refusing valid cases of TCP event sequences. f) Implement a fall-back solution if direct traversal communication cannot be established.

g) Have to offer the possibility of authenticating exchanged messages to avoid man-in-themiddle attacks while establishing NAT traversal. If a global NAT traversal standard is made available and implemented in JXSE, one may wonder if the JXTA protocols will remain useful when it comes to connectivity. Solving NAT traversal issues is tacitly assuming that a device has access to the WAN. But that it not always the case, either because the device is not equipped for that, or because access is not granted on its part of the network. Communication may need to go through multiple peers before reaching destination. One can imagine situations where communication might be necessary between such 'hard-toreach' peers. If they implement the JXTA protocols, and cannot traverse their NATs or are too isolated, they could still forward their message to another 'local' JXTA peer who has access to the WAN. This peer would act as a JXTA proxy. Hence, the endpoint routing protocol of JXTA remain a valid fall back solution to unsolvable NAT traversal issues of a given peer.

Network Boundaries Conclusion - 111

- 112

JXSE Cryptographic Layer
Before we cover architectural considerations in JXTA, like how to develop and configure your P2P system, we will first cover the cryptographic layer of JXSE. This chapter includes a reminder about the main concepts of cryptography. We will focus on public key infrastructures. If readers are not interested in cryptography at this stage, they can skip this chapter and read it later.

Cryptography Reminder
Cryptography is a powerful tool that can help in mitigating (and sometimes eliminating) the inherent access control and confidentiality issues faced by all software applications when they communicate and exchange data from remote locations. The following paragraphs remind us about common cryptography concepts and issues every software developer and architect needs to keep in mind when designing a software application containing cryptography features. Even the seasoned cryptographer's work is not exempt of weaknesses and flaws; this book cannot foresee every known attack on cryptographic systems. Therefore, we strongly recommend less-experienced programmers have their work reviewed by experts when implementing it with JXTA.

Alice, Bob & Eve
Alice, Bob and Eve
39

are three famous characters in cryp-

tography. They are the basic elements of a paradigm describing the issues and objectives of cryptography. The scenario is the following: Alice and Bob want to communicate and exchange information confidentially, but Eve tries to interfere with the communication. The objective of cryptography is to provide Alice and Bob with a system that allows them to communicate confidentially from remote locations while remaining protected from Eve's bad intentions. More specifically, security is established between two users, computers or communicating entities over the Internet when:
39 Eve stands for eavesdropping. Cryptography uses many other names, such as Mallory for malicious attacker. For the sake of simplicity we have kept only one name to identify an individual willing to disrupt the peaceful and private communication between Alice and Bob using any possible means.

JXSE Cryptographic Layer Cryptography Reminder - 113

✔ ✔

Alice can establish a communication channel with Bob Alice can make sure the party at the other side of the channel is Bob (and not Eve faking his identity)

✔ ✔

Alice can exchange information over this channel without revealing its content to Eve Alice can make sure that a message transmitted over the channel to Bob has not been tampered or replayed by Eve

When the above is established perfectly, the anxiety of undesirable and uncontrollable disclosures is perfectly eliminated and the level of trust between Alice and Bob is maximum, allowing lively exchanges. Any pair of nodes on a P2P network can be considered as Alice and Bob.

Introduction To Secure Communication
Confidentiality between Alice and Bob can be achieved by the mean of a public key system. Cryptographic systems relying on these infrastructures often use two types of keys: asymmetric keys for public exchanges and symmetric keys for private exchanges. This global system can be split into two subsystems. The most common asymmetric key system (or public key system) used in cryptography is RSA. It has been designed to help distant parties initiate a secured connection, verify each other's identity and certify the origin of exchanged data. Unfortunately, the algorithms used by this system are not very efficient at encrypting large quantities of data. Another practical and faster solution was required, which led to the creation of symmetric key systems (or private key systems). The most common one is Rijndael. It has been selected by the National Institute of Standards and Technology (NIST ) in 2001 as the advanced encryption standard (AES) to be used by the U.S. Government. To put it simply, after Alice and Bob have verified their identity with the public key system, they create a private key between themselves. Next, they use that private key to encrypt and to exchange large quantities of data with the private key system which is more efficient. Let's look at the procedure in more details (for the sake of simplicity, we will not include the usage of a private key system at this stage): 1. Alice and Bob both create their RSA asymmetric key, which is made of two parts, a public part and a private part. The public part of an RSA key is often called the public key. The
40 http://www.nist.gov/
40

JXSE Cryptographic Layer Cryptography Reminder - 114

private part of the RSA key is often called the private key, but it should not be confused with the symmetric key that will be created later with the private key system. This is a common misunderstanding of novices in cryptography. RSA keys pairs have an interesting property, if you encrypt a message with the public key part, it can only be decrypted with the corresponding private key part. It is virtually impossible to decrypt an encrypted message without knowing the private key part. This is the main value of RSA keys. 2. Alice and Bob both publish the public part of their respective RSA key to a central authority they both trust. This authority is called a certificate authority. This authority is responsible for certifying the public keys of its customers. They deliver certificates establishing a link between an identity (Alice, Bob...) and a public key. Third parties can later verify the validity of these certificates to make sure these are not fakes. 3. Alice fetches Bob's public key from the certificate authority and Bob does the same with Alice's public key. They both verify the certificates against fakes. Now, Alice can use Bob's public key part to encrypt a message and send it to him. Only Bob has the corresponding private key part to decode it. However, since Bob's public key is also available to Eve who can fetch it from the certificate authority, she could also encrypt a message and send it to Bob. Therefore, Bob needs a mechanism to make sure the author of the received message is Alice and not Eve. 4. Authentication is achieved by having Alice encrypt a secret message that only Bob and her know (i.e., an authentication code) with Bob's public key and joins it to the encrypted message sent to Bob. This is something Eve cannot craft herself, since she does not have access to Alice and Bob's secret. Moreover, she cannot get access to the secret when the authentication code is being transmitted, since she does not have access to Bob's private key. When the message and authentication code arrives, Bob can verify that it is Alice who has sent him the received message by decrypting the authentication code with his private key and make sure it contains their secret.

JXSE Cryptographic Layer Cryptography Reminder - 115

But there is a major flaw in this way of communication: Eve can substitute the encrypted message sent by Alice to Bob with her own encrypted message using Alice's public key and keep the authentication code created by Alice. She has the possibility to pollute the communication to Bob and he will not be able to detect this. The solution to this problem is to have an authentication code based, not only on a secret shared by Alice and Bob, but also on the message itself. This is what we call a message

authentication code (or MAC for short). Computing a MAC is not a simple operation. It
cannot be performed by any algorithm. A good hash function
41

is required, that is, a

function guaranteeing that finding the original message and secret used to compute the MAC is virtually impossible to achieve knowing the MAC only. It is a one-way function. Creating good hash functions is a fundamental and complex problem that has been studied in depth by cryptographers for a long time. It is imperative to use well-known and well studied hash functions in cryptographic applications. 5. The new procedure to send a secret message is now i) to have Alice encrypt her message with Bob's public RSA key, and ii) to compute a MAC using the secret she shares with Bob and the message itself. When Bob receives the communication from Alice, he first decrypts the message with his private RSA key and then computes the MAC of the message using the secret he shares with Alice. Then, if the computed MAC does not match the MAC received from Alice, the message is not authenticated and Bob should discard it. He has no guarantee that it comes from Alice. Eve is not in a position to create a credible MAC, because she does not know the secret Alice and Bob share and she does not have access to the original message. Since the hash function used to create the MAC cannot be reversed easily, she will not be able to figure out the secret and the message used to create the MAC. If she substitutes the encrypted message with her own pollution message encrypted with Bob's public key, she will still be missing their secret to create a credible MAC. Bob will notice the discrepancy between the received MAC and the MAC he will compute himself and know that someone has been fiddling with the communication. There is still an issue we need to solve: how do we get Alice and Bob to share a common secret?
41 For example, the SHA functions: http://en.wikipedia.org/wiki/SHA_hash_functions

JXSE Cryptographic Layer Cryptography Reminder - 116

What type of secret should they share? The place of their first encounter or their favorite meal is probably not very hard to guess by Eve! It should be something quite impossible to guess. This issue can be solved by using the Diffie-Hellman protocol. Without entering into details, this protocol allows Alice and Bob to create a secret code from their remote locations using their RSA keys. Even if Eve has access to the content of all transactions between Alice and Bob during the execution of the Diffie-Hellman protocol, she will not be able to guess the secret code that is being created. This protocol allows Alice and Bob to create secrets at will from remote locations. There is another benefit to creating secrets with Diffie-Hellman. The secret can be used as a symmetric key between Bob and Alice to encrypt bigger messages with faster algorithms (such AES for example). In this situation, Eve will not be able to create polluted messages anymore, since a) they won't be using the public key of Bob to encrypt messages anymore and b) Eve will not have access to the secret created by Alice and Bob. The secret key created between Alice and Bob will be valid only between them. This is why we call it symmetric as opposed to RSA keys which can be used to establish secured communications between any given pair of peers (i.e., asymmetric communications).

...And Vicious Circles!
Many readers are probably wondering how we can prevent Eve from achieving her evil objectives when i) Bob and Alice register their public RSA keys at the certificate authority or ii) when they both retrieve the other's key from that same authority? She could fake the identity of the certificate authority and have Alice and Bob believe that they are talking to that certificate authority by deviating the transactions with this authority. One can be tempted to say: It's simple, establish a secure communication with the certificate authority and Eve won't be able to achieve her objectives !!! Another reader will answer: Yes, but you would need to obtain the public certificate of that authority first! What if Eve fiddles that communication too? This is an Ouroboros situation !!! Moreover, Eve could create her own RSA key pair claiming she is Bob or Alice and register it at a certificate authority. Or better, Eve might be running the certificate authority service herself !!! There are several issues to be solved here. There is a simple but impractical solution to tackle Eve's plans. Instead of using a certificate authority, Bob and Alice could meet face-to-face to exchange their public RSA key in the absence of

JXSE Cryptographic Layer Cryptography Reminder - 117

Eve. This is OK when Alice and Bob live in the same neighborhood, but what if they have hundreds of friends and colleagues all around the world? This method would be impractical. In order to make sure that Eve is not creating a fake certificate pretending that she is Bob or Alice, the certificate authority has to verify her identity. This could be done with a driver's license or a passport, but we can't exclude the possibility that Eve is faking these too. Regardless of the fact that this solution would be impractical too, this is another case of Ouroboros. Can we trust the authority certifying Eve's-pretending-to-be-Alice's identity? Let's imagine that Eve manages to obtain a fake certificate and pretends she is Alice with Bob. Bob will not be able to detect it, until after some time: a) he notices that the communication with Alice is bizarre... Why doesn't Alice remember the place of our first meeting in our conversations? or b) he gets to meet Alice face-to-face and talks about a discussion they apparently had on the net the day before... A discussion Alice won't remember of course! Eve is busted !!! Alice and Bob will need a mechanism to denounce and invalidate the false certificate used by Eve. This is a service that certificate authorities should offer. Now, Eve could also try to break the system by pretending to be Alice and claiming (falsely of course) that someone else called Eve has in fact registered a fake Alice certificate. She would use her fake identity papers to pretend she is the real Alice and ask the certificate authority to invalidate the current Alice certificate and replace it with a new one. Alice who was Alice is now Eve playing Alice for other peers on the network. In fact, this technique may have been the technique she used in first place to fake her identity with Bob. Do you think this is crazy? Cryptography is a complex matter !!! This problem can be mitigated by notifying the 'former' Alice that her certificate has been revoked, unless Eve controls that communication channel, too. The 'former' Alice would then contact the certificate authority and say that she never made a request to invalidate her certificate. The certificate authority could perform more verifications and since they would most probably have kept a copy of Eve-pretending-to-be-Alice' identity papers, they would come to a conclusion that these are invalid. They would notify other authorities that someone is trying to fake Alice's identity with these false identity papers. In these attacks, we are assuming that Eve is very powerful and that she can control things that she most probably would never be able to control in reality (at least, without being detected sooner or later). However, we have to keep these scenarios in mind to minimize the capacity of potential hackers to crack security systems. In reality, certificate authorities cannot ask for identity papers each time someone wants to register JXSE Cryptographic Layer Cryptography Reminder - 118

a certificate; it is impractical over the Internet. They often register an email address, a real mail address, a phone number and the IP address of the peer making the request for certification instead. They ask for a confirmation by sending an email to the registered address and request users to click on a web page link contained in the email to confirm their registration. It is another opportunity to register IP addresses. In case of problem, the certificate authorities can always use that information to track down the user who has registered that information. If they can't find that person or if the corresponding person does not match with the registered information, the certificate authority will know that there is something suspicious going on... This discussion illustrates some of the problems cryptography has to solve. It also demonstrates that if many people want to start communicating securely from distant locations, there is no other practical option than to put some initial trust in the cryptographic system and to accept that there will always be a risk that people with bad intentions will try to exploit cracks and fake identities or corrupt communications. This is like poker, if you want to play, you have to pay the ante !!! The fundamental issue is that you have to trust 'things' that are representing people or entities without always having a possibility to double-check with 100% certainty that those using these 'things' are the real people or entities themselves. That is one type of loophole Eve is trying to find and to exploit. Such loopholes cannot be avoided since the whole world population is not living on the same street. Moreover, it will never be interested in living in the same street for the benefit of tackling Eve by having only face-to-face conversations with other peers. It will always prefer to trade a bit of risk for the comfort of remote and quite secure communications. There is no need to become paranoid about cryptography systems just by reading the above paragraphs. We trust the post office not to open or to fiddle with the letters we send to our beloved ones (or others), even though these items are highly unprotected. We have been using our phones and mobile phones for years without thinking that someone might listen to our conversations. How many secrets did we reveal that way? Today, many of us are using chatting applications which are sometimes not protected at all. We transmit sensitive documents by email even though we don't really know how much protection they have. Before stressing on the cracks of cryptography systems, most of us should first stress on the way we deal with confidential and sensitive information using traditional means of communications. We will now cover some of the concepts we have mentioned earlier in more details.

Public Key Infrastructure (PKI)
A public key infrastructure is a means by which public keys of users are bound with their identities JXSE Cryptographic Layer Cryptography Reminder - 119

with the help of a certificate authority. As we mentioned it earlier, a user willing to publish his or her public key to other users starts by requesting a certificate authority to certify its public key by providing its identity and receives a certificate in return. This certificate can then be distributed to other peers who can verify and validate its content themselves (we will explain how later). A well-known standard for those certificates is X.509 which is used as part of JXSE.

Who Certifies The Root Certificate Authority?
A PKI creates chains of certificates by certifying other authorities and users, but there is always (at least) one root certificate authority to start with. The question is who will certify that authority? The answer is nobody. Root certificate authorities certify themselves and publish their own certificate. These are often big institutions relying on their established credibility to get the trust of their customers. This type of credibility requires a level of trust which is similar to that we put in banks when they keep our money or centrals banks when they print bank notes. Central banks are the root institutions delivering credits to other banks. Their objective is to facilitate economical transactions between individuals or entities in an economy by providing certified bank notes.

Duties Of A Certificate Authority
Every certificate authority should provide a document explaining in detail how it issues and manages certificates. It should also describe all other associated services it may provide in relationship to certificate management. This document is called a Certificate Practice Statement (CPS). Certificate authorities not only should implement a mechanism to verify the identity of users requesting certifications, but also a means to get access to that user in reality. They should also maintain a Certificate Revocation List (CRL), that is, a list of all certificates issued by the certificate authority which should not be considered as valid anymore. Let's imagine that someone has managed to steal the private key of a user or that this private key

JXSE Cryptographic Layer Cryptography Reminder - 120

has been compromised by other means, the corresponding public key on the user's certificate should not be used anymore. However, many copies of that certificate can still be owned by many users. These users should check the CRL from time to time to make sure that the certificate of other peers they own has not been revoked.

Web Of Trust
The web of trust is an alternative to the central authority model. Instead of calling a central authority to establish trust relationships via certificate, one establishes trust relationships via the people they trust. If Alice trusts Bob, and Bob trusts Carol, can Alice trust Carol? Most probably yes. How is this performed with certificates? Bob certifies Carol's certificate. Since Alice can make sure that Bob – and no one else – has certified Carol's certificate, Alice can trust Carol's certificate. Likewise, Carol will do the same with Alice's certificate via Bob. This model will look very appealing to defenders of pure P2P systems. Every peer can create a community of peers they trust. Everyone generates their own certificates and have these certified by the people they trust. Unfortunately, it only works with small communities. Once several thousands or millions of users get involved, very long chains of certifications are created. Each will be as strong as the weakest link. If Eve manages to get in some of these chains (which is not very hard with this type of trust model), she can compromise large parts of the system. In addition, a peer can be certified by different chains of peers, which is redundant. Moreover, this model does not explain how to perform efficient certificate revocation. It turns out that authentication of peers and their public keys is best performed by central authorities as opposed to a model where everyone certifies each other. Most of us can be trusted not to cheat, but there will always be a small percentage of people with bad intentions. They can do a lot of damage in the web of trust model. In order to have a practical and secure P2P system, you are better off using a couple of central authority peers. The trade-off is that you have to put your trust in these authorities, rather than in your close friends, but you will benefit from a higher overall level of security.

JXSE Cryptographic Layer Cryptography Reminder - 121

X.509
X.509 is a standard for the definition of certificates which appeared in 1988. Since then, three versions of this standard have been made available. The following table describes version 3 of the X.509 certificate structure. Some fields are mandatory and others are optional:

X.509 version 3 structure version serialNumber signature issuer validity subject subjectPublicKeyInfo issuerUniqueID subjectUniqueID extensions signatureAlgorithm signature

Description X.509 version 1, 2 or 3 Unique identifier of the certificate Signature algorithm that should be used to certify this certificate Identity of the certificate authority issuing the certificate Validity period of the certificate Identity of the user to certify Public key of the user Optional - Certificate authority unique ID Optional - User unique ID Optional – Additional information Signature algorithm used by the certificate authority Signature of the certificate itself

Hashed field Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes No No

Typically, a user will send its identity (subject field), eventually its ID (subjectUniqueID field) and a request to use a specific signature algorithm to the certificate authority (signature field) to the certificate authority. The certificate authority will fill the remaining fields to be hashed and will hash them with a proper hashing function. The result value will then be encrypted (i.e. signed) with the private RSA key of the certificate authority to create the signature of the certificate. At last, the certificate authority fills the signatureAlgorithm field to specify which algorithm has been used and send the certificate back to the user . Later, the user can distribute his certificate (let's call it A) to other users. They can check that certificate A is genuine by retrieving the certificate of the certificate authority (let's call it B) whose name is mentioned on A. This certificate should be retrieved from the certificate authority itself. Certificate B contains the public key of the central authority. Our verifying users compute the hash value of the to-be-hashed fields in certificate A using the method specified in the signatureAl42 We have not included identity verification in this procedure for the sake of clarity and simplicity, but it should be included in real implementation of certificate authorities.
42

JXSE Cryptographic Layer Cryptography Reminder - 122

gorithm field. They also verify the content of the signature field with the public key of the certificate authority available from certificate B. This operation returns a value which can be compared to the hash value of A. If these match, then certificate A can be considered as valid. A check on the validity period of certificate A and a verification on the certificate authority CRL should be performed too to make sure the certificate has not become obsolete. Now, I can also check the validity of certificate B with the certificate of the central authority mentioned on that certificate. I can repeat that operation until I reach to the root certificate authority. This is how the links in the chain are connected to each other to form a chain of trust.

X.500 & Principal
A principal is something representing an entity which can be a peer, an individual, a corporation, etc... X.500 is a standard for directory services, that is, a system of software applications collecting, organizing, storing and providing information about network resources and users. This information is typically used by network system administrators. JXSE uses the Java X500Principal object to describe certificate authority peers when implementing cryptography. When a certificate authority peer signs a certificates, its name is expressed using a format defined as part of the X.500 standard. The identity, or more specifically, the prin-

cipal of the certified peer is also expressed using one of these standard formats.

Hash Function
Several hash functions have been developed by cryptographers. Crafting such function requires a lot of mathematics and statistics. It is a complicated task and one should rely on well-known and studied functions rather than trying to fiddle one's own algorithm (which will be cracked quickly by hackers...). Examples of hash function are: SHA1, MD5, RIPEMD and Tiger. SHA1 is a hash function returning a result of 160 bits long, MD5 returns a result of 128 bits long. The size of the return value is very important when implementing a cryptographic system, because of the collision issue which we will describe next. The number of possible input values of good hash functions is always incredibly greater than the set of possible output values, meaning that many input values will generate the same output. One of the most interesting properties of good hash functions is that they tend to return values which are uniformly distributed in the set of possible returned values. In other words, it is very hard to guess the input value (or the set of input values) of a hash function by knowing its output only.

JXSE Cryptographic Layer Cryptography Reminder - 123

The Collision Issue
The collision issue is often described with the birthday paradox. Let's imagine an empty room where one would let random people come in one by one. Each time someone comes in, we check whether that person shares the same birthday as anyone else already in the room, regardless of the year of birth. The question is: after letting how many people will the probability to have at least two people share the same birthday be over 50%? There are 365 days per year (except for leap years). Surprisingly, this threshold is reached after only 23 people. Most people would think more. The mathematics of the birthday paradox will tell you that if the number of possible output values for a hash function is 2 for example, the 50% probability of encountering a collision (i.e., two input values producing the same output value) will occur after more or less 2 paradox, 365 = 2
8.51... n/2 n

attempts. In the birthday

and 2

8.51.../2

≈ 19.104... This is close to the real number: 23. When n increases

the relative error between the real value and the estimation of the threshold tends to 0. But what is the problem with the collision issue? Well, it can be used to fake identities! Here is how to proceed: 1. I request a certificate authority to sign my certificate A. 2. The authority checks my identity and signs my certificate, since I am who I claim I am. 3. I can compute the hash value of the to-be-hashed fields of my certificate. Let's call this value hash(A). 4. Let's imagine that I want to fake the identity of a rich person (for example, Donald Trump), to send fake orders to his bank. I create a dummy certificate B with the same values as in certificate A, except for the fields identifying the user. I substitute these values with those corresponding to my victim. 5. Then, I select random values for the public key and compute the hash value of my crafted certificate B, until the result hash(B) equals hash(A). If MD5 is the hashing function, the birthday paradox theory says it should happen with a probability above 50% after 2 ≈ 10 attempts. This can reasonably be attempted with a set of powerful computers. Unfortunately, some weaknesses have been found with MD5 (and many other hashing functions). Cryptographers have managed to create collisions with a lower threshold, and therefore, to lower the number of attempts required to reach our objectives in reality. But let's ignore this for now. 6. I don't need to ask the certificate authority to sign certificate B, because I know that the reJXSE Cryptographic Layer Cryptography Reminder - 124
64 19

turned signature value will be identical to the one of certificate A, since hash(A) = hash(B). The certificate authority would sign the certificate with the same hash value, even though the content of the fields are different. Different inputs are resulting in the same output value. Therefore, I just need to copy the signature of certificate A on certificate B. 7. I can now use certificate B to send bank orders to Donald Trump's bank. The bank will get the public key of the certificate authority to check the signature on certificate B (which this authority has never signed) and will find out that it matches with hash(B). Therefore, the bank will consider that I am Donald Trump and proceed with the order without ever detecting my true identity: Eve. Do you like this trick? Why do you think hackers try to steal credit card information on the Internet? Would you have found this one by yourself? Do you think you can beat all the scientists that have dedicated hours of research and hard work, years after years, to identify those dirty tricks and produce robust solutions? If your answer is yes, then the NSA will have a job for you... Otherwise, trust the hard work that has been done by cryptographers and experts in the past. Ask for their advice. What you need to remember about hash functions is that the size of their output, expressed as a power of 2, should preferably be equal to (or greater than) 160 (but preferably 256) to escape the collision issue. There is not enough processing power to crack collisions in a space of 2 for now or in the near future, since a collision would only probably happen after 10
38 256 43

values

attempts

when using a brute force attack (i.e., trying random combinations until a collision is obtained).

Key Sizes
The size of a symmetric key is a different concept than the size of asymmetric key pairs. The minimum acceptable size of a symmetric key today is 128 bits, although 192 or 256 bits are recommended for more sensitive data. The size of an asymmetric key is in the 1024+ range. As of the publication of this book, 2048 bits long asymmetric keys are believed to be valid until 2030, but 4096 bits are more recommended.

Assumptions
One should keep in mind that the strength of the RSA public key system is relying on the fact that a number made up of the product of two very large prime numbers cannot be decomposed into its original factors easily. There is no known fast algorithm to achieve this operation, but it does not
43 National Security Agency

JXSE Cryptographic Layer Cryptography Reminder - 125

mean that none will be found in the future. It also does not mean that we won't be able to prove that such algorithms don't exist either. If such an algorithm is found, then the suggested size for corresponding RSA keys will fall immediately and all cryptographic systems relying on RSA will collapse instantaneously. If we can prove that no such algorithm exists, it will mean that we will have a nearly perfect method to hide secrets for as long as we want. The same line of thought can also be applied to other algorithms used in cryptography. We do not know of any easy way to crack these, but we do not have proof that there is no way to crack them easily. Banks, International Institutions and the military trust many of these algorithms to protect their data and their communications. Do you think you can trust them too?

The DRM Illusion
There is one venue that many believe to be a 'holy grail' when it comes to protect content on remote devices: Digital Rights Management (DRM). The intention is the following: Alice owns a secret recording of the Beatles and wants to share it with many people, but does not want them to copy it. She implements an application checking whether Bobs are allowed to listen to the record and preventing them from copying it. Both this application and the encrypted record are located on Bobs' devices. The safe and the key are in the hands of the same individual. No matter how much protection you put on your recording, at some stage, listeners are always granted some access to it. If Eve plays a Bob, she will always have the possibility of stripping all protection and access the content of the recording. At best, DRM systems – and any system where individuals both have access to the safe and the key – can only help keeping honest people honest, but not dishonest people honest. If you need to perform an operation involving a secret (i.e., key), perform it on a device that is under your full control and that no Bobs can physically access. Don't store your secrets on a device that is not fully under your control, they will sooner or later be compromised.

Calling Experts
We have briefly described some cryptography concepts which can be implemented in P2P systems. However, there are many practical issues and ways of attacking cryptographic systems that have not been covered in this book. We will repeat ourselves, but cryptography is a very complex science. Arrogance, creativity and lack of experience are good indicators of people you should avoid in this domain. Humility, patience and experience are what you are looking for. Use code libraries developed by experts; do not try to do it yourself if you are not an expert. Your adversaries JXSE Cryptographic Layer Cryptography Reminder - 126

know about the typical flaws novices make and can exploit weaknesses in unimaginable ways. Do not assume they won't find your cracks. They will. If you include a cryptography system in your application, whether or not it is P2P, it is highly recommended to call cryptography experts to review your design documents and to review the technical implementation of your cryptographic system (i.e., the code and sometimes the hardware). It is better to be safe than sorry. Keep a list of potential weaknesses of your system and monitor these one way or the other. At last, never believe that security systems will ever protect you perfectly. They won't. They will provide degrees of security. These should match the value of what you have to protect. Don't expect more, don't expect less.

Personal Security Environment (PSE)
The personal security environment is a specific implementation of the JXTA membership service using a public key infrastructure. It is the default membership service implemented in JXSE, except for the NetPeerGroup and the WorldPeerGroup which have a 'grant-access-to-all' membership service. Every instance of the PSE Membership Service requires a keystore, that is, a place where certificates and private keys can be stored safely.

Java Cryptography Architecture
Before we get into more details, the PSE relies on functionalities implemented as part of the Java Cryptography Architecture. This includes the creation of X.509 certificates and keystores for example. Developers will also find useful functionalities to create Certificate Revocation Lists. Readers should get familiar with these API (Application Programming Interfaces) if they are not savvy with Java cryptographic functionalities. Some documentation is available from: http://java.sun.com/j2se/1.4.2/docs/guide/security/CryptoSpec.html.

KeyStore
JXSE implements three sorts of keystores via the KeyStoreManager interface: the CMKeyStoreManager located in the local peer cache directory, the FileKeyStoreManager where the user specifies File location when creating the keystore object and the URIKeyStoreManager where the location is provided with a URI. When creating such objects, a keystore type can be specified. It can be any type accepted by the standard KeyStore Java class. If no type is specified (null), the default JKS type implemented by Sun Microsystems will be used. JXSE Cryptographic Layer Personal Security Environment (PSE) - 127

Creation
The following code describes how to create a simple File keystore:
... // Preparing data String MyKeyStoreFileName String MyKeyStoreLocation String MyKeyStorePassword String MyKeyStoreProvider
44

= = = =

"MyKeyStoreFile"; "." + File.separator + "MyKeyStoreLocation"; "My Key Store Password"; "Me Myself And I";

File MyKeyStoreDirectory = new File(MyKeyStoreLocation); File MyKeyStoreFile = new File(MyKeyStoreLocation + File.separator + MyKeyStoreFileName); // Deleting any existing key store and content NetworkManager.RecursiveDelete(MyKeyStoreDirectory); MyKeyStoreDirectory.mkdirs(); // Creating the key store FileKeyStoreManager MyFileKeyStoreManager = new FileKeyStoreManager( (String)null, MyKeyStoreProvider, MyKeyStoreFile); MyFileKeyStoreManager.createKeyStore(MyKeyStorePassword.toCharArray()); // Checking initialization if (MyFileKeyStoreManager.isInitialized()) { System.out.println("Keystore initialized successfully"); } else { System.out.println("Keystore NOT initialized successfully"); } ...

Before creating the keystore, the directory that will contain the resulting file is emptied from its content and the directory structure is (re)created if necessary. Then, we create a default keystore and set its password. Next, we make sure it has been initialized properly. We should obtain the following:
Keystore initialized successfully

This operation is a one time operation that all peers wishing to use the PSE membership environment should perform. The keystore will be used next when setting the network configuration.

Automatic X.509 Certificate & Private Key Creation
Before starting the JXTA network, one should set some parameters in the NetworkConfigurator object that will be used to configure the PSE membership service. After creating a keystore,
44 The complete code examples are available in the appendix.

JXSE Cryptographic Layer Personal Security Environment (PSE) - 128

one should set the keystore location with the setKeyStoreLocation(URI keyStoreLocation) method. If a peer does not have a X.509 certificate and private key pair and wishes to create one itself, it can do so with the following code:
... // Erasing any existing configuration Tools.DeleteConfigurationInDefaultHome(); // Creation of the network manager NetworkManager MyNetworkManager = new NetworkManager( NetworkManager.ConfigMode.EDGE, "My Network Manager instance name"); // Retrieving the network configurator NetworkConfigurator MyNetworkConfigurator = MyNetworkManager.getConfigurator(); // Setting the key store location MyNetworkConfigurator.setKeyStoreLocation(MyKeyStoreFile.toURI()); // Setting the name to be used for the X500 principal String ThePrincipal = "Me, Myself & I"; MyNetworkConfigurator.setPrincipal(ThePrincipal); // Setting a password for encrypting the private key that will be // created as part of the X.509 automatic certificate creation String SecretKeyPassword = "My Secret Key Password"; MyNetworkConfigurator.setPassword(SecretKeyPassword); // Saving the configuration, which will trigger the X.509 certificate creation MyNetworkConfigurator.save(); // Trying to retrieve the X.509 certificate from the configurator X509Certificate MyX509Certificate = MyNetworkConfigurator.getCertificate(); if (MyX509Certificate==null) { System.out.println("Cannot retrieve X509 certificate from NetworkConfigurator"); } ...

The above code begins by deleting any existing configuration. After creating the NetworkManager, we retrieve the NetworkConfigurator and set the principal for the X500 structure, together with the password that should be used to encrypt the private part of the public key that will be created as part of the X.509 certificate creation. Saving the current configuration triggers the creation of a X.509 certificate, since all existing configuration has been deleted. If we try to retrieve the result from the NetworkConfigurator, it will be unsuccessful:
Cannot retrieve X509 certificate from NetworkConfigurator

Why? Because the NetworkConfigurator does not reload what it has just saved. However, we can JXSE Cryptographic Layer Personal Security Environment (PSE) - 129

retrieve our automatically created X.509 certificate via the PSE configuration advertisement as following:
... // Retrieving the configuration parameters ConfigParams MyConfigParams = MyNetworkConfigurator.getPlatformConfig(); // Retrieving the PSE configuration advertisement PSEConfigAdv MyPSEConfigAdv = (PSEConfigAdv) MyConfigParams.getSvcConfigAdvertisement(PeerGroup.membershipClassID); // Retrieving the X.509 certificate MyX509Certificate = MyPSEConfigAdv.getCertificate(); System.out.println(MyX509Certificate.toString()); ...

We get something like this:
[ [ Version: V3 Subject: OU=3B9641C7512BE17295F3, CN="Me, Myself & I-CA", O=www.jxta.org Signature Algorithm: SHA1withRSA, OID = 1.2.840.113549.1.1.5 Key: Sun RSA public key, 1024 bits modulus: 1149142515334121103270713157246112976747... public exponent: 65537 Validity: [From: Wed Apr 30 19:54:30 CEST 2008, To: Mon Apr 30 19:54:30 CEST 2018] Issuer: OU=3B9641C7512BE17295F3, CN="Me, Myself & I-CA", O=www.jxta.org SerialNumber: [ 01] ] Algorithm: [SHA1withRSA] Signature: 0000: 6B E2 28 4C 9A C2 22 0010: B5 B6 6F 70 01 BF 80 0020: F8 AB B4 2D 61 B7 84 0030: 8A 6C 3C C2 46 7F F4 0040: C0 7A A5 6D 67 CE C2 0050: FF 00 3B 7B 52 1E E4 0060: 0D 11 EC 4D D5 1B AA 0070: 06 D8 84 DD DA 01 A6 ]

DD 5B AD D8 05 A5 DA F2

C6 23 CB AC A6 DB 69 CD

E5 06 3F C0 D5 57 43 50

06 4D D6 94 86 3E 97 66

22 46 1A AD 93 7C 65 44

D2 A8 3D FF E6 C7 85 CC

5C 90 DD E0 EA 45 3E AE

3F 0F 90 F2 14 A8 A3 6F

04 4A 45 9B 76 BF B2 1C

k.(L.."....".\?. ..op...[#.MF...J ...-a....?..=..E .l<.F........... .z.mg..........v ..;.R....W>..E.. ...M....iC.e.>.. .........PfD..o.

If we do not erase the newly created (and saved) configuration the next time we retrieve the NetworkConfigurator, the X.509 certificate will be available directly from the MyNetworkConfigurator.getCertificate() method. One will not need to retrieve it from the PSE configuration advertisement anymore. Regarding the private key, it can be retrieved from the NetworkConfigurator assuming that the password used to encrypt it in the keystore has been set properly.

JXSE Cryptographic Layer Personal Security Environment (PSE) - 130

In the code examples we provide later, we will describe a third method to retrieve keys and certificates from keystores using the PSE configuration object of the PSE membership service.

Big Big Big Warning!
The newly created certificate is based on a public RSA key pair of 1024 bits, which is not a lot. As of the publication of this book, the largest RSA key pair which has been cracked is 768 bits long . Cryptographers consider that data encrypted with keys of 1024 bits should be not be considered safe after 2015. Yet, the default duration of the certificate is set to 10 years. You do the math...! Moreover, the hashing method is SHA1, which return results of 160 bits longs. Unfortunately, some researchers have managed to create SHA1 collisions within 2 theoretical 2
80 63
45

attempts , instead of the

46

limit. This is a little too close for comfort. You would still need a lot of computer
47

power to create collisions, but it is not unreasonable to think that such power can be made available in the near future by coupling networks of computers . There is another issue you need to take into account: the password and method used to encrypt the secret key corresponding to the X.509 certificate. The number of different characters we use for our passwords is roughly 45 (a-z, 0-9, special characters...). Since we often use passwords of 6 to 8 characters long, the total number of combinations is more or less 45 ≈ 2 . Again, this is not a lot. A network of powerful computers could try to generate all password combinations and find which one you used to encrypt your secret key. And this is an optimistic view, since we assume that all characters will be used with equal probabilities. This is not the case in reality; our passwords usually contain more letters than numbers and more numbers than special characters. In their Practical Cryptography book, Neil Ferguson and Bruce Schneier indicate that the amount entropy per character in English text is in the neighborhood of 1.5-2 bits. Since most of us use passwords of 6 to 8 characters, we generate an entropy of 16 bits in average. This is much, much lower than the 244 limit. Besides, our passwords often contain words from the dictionary, names, birth dates, etc... Some claim that there is up 1 million words (2 ) available in English. This is a small amount of combinations to try in order to crack a password (even if you combine them with numbers and special characters). This type of attack is called a dictionary attack. There is technique called salting (or salt-and-stretching) to reduce password weaknesses. Instead
45 46 47 http://en.wikipedia.org/wiki/RSA_numbers# RSA-768 http://en.wikipedia.org/wiki/SHA1 Don't even think about JXTA to do this!!!
20 8 44

JXSE Cryptographic Layer Personal Security Environment (PSE) - 131

of using a password as is, we can use hash functions several times on it with a set of random bits to produce a new hashed password. The idea is to have the number of hashing iterations compensates for the lack of password entropy. We will come back later on security issues of JXTA and JXSE.

Registering Your Own X.509
If you create your own X.509 by other means or obtain it from third certificate authorities, you can register these in the NetworkConfigurator with the setCertificate(X509Certificate cert) method. You can also register your certificate chains with the setCertificate(X509Certificate[] certificateChain) methods. Do not forget to save your configuration.

PSE Configuration
When using the PSE membership service, some initial configuration may have to be performed via the PSEConfig object after the keystore has been created. This object can be retrieved from the PSEMembershipService itself:
... // Creation of the network manager NetworkManager MyNetworkManager = new NetworkManager( NetworkManager.ConfigMode.EDGE, "My Network Manager instance name"); // Starting JXTA and retrieving the net peer group PeerGroup TheNetPeerGroup = MyNetworkManager.startNetwork(); // Retrieving the membership service PSEMembershipService ThePSEMembershipService = (PSEMembershipService) TheNetPeerGroup.getMembershipService(); // Retrieving the configuration object PSEConfig ThePSEConfig = ThePSEMembershipService.getPSEConfig(); ...

We can check whether the PSE configuration has been initialized and set an initial keystore password if such has not been set. This password should not be confused with the password used to encrypt secret keys when automatically creating X.509 certificates.
... if (ThePSEConfig.isInitialized()) { System.out.println("PSE is initialized");

JXSE Cryptographic Layer Personal Security Environment (PSE) - 132

// Retrieving login password String LoginPass = JOptionPane.showInputDialog(null, "Enter keystore password"); ThePSEConfig.setKeyStorePassword(LoginPass.toCharArray()); } else { System.out.println("PSE is NOT initialized"); // Retrieving initial password String InitPass = JoptionPane.showInputDialog(null, "Enter initial keystore password:"); ThePSEConfig.setKeyStorePassword(InitPass.toCharArray()); // Initializing PSE configuration ThePSEConfig.initialize(); } ...

Later, if that code is run again, one will detect that the PSE configuration has been initialized and the corresponding password will be retrieved from the user. It is not mandatory to use a password with a keystore. There is a possibility to set a protection for each entry with a specific password with the following methods:

void setKey(ID id, Certificate[] certchain, PrivateKey key, char[] key_password) – This PSEConfig method creates (or replaces) an entry for the specified ID (usually a user or peer ID) to set a certificate chain and a private key. If the key_password parameter is not null, it will be used to protect that entry.

PrivateKey getKey(ID id, char[] key_password) – This other PSEConfig method can be used to retrieve a PrivateKey corresponding to a specific ID. If a password has been used to protect the entry, it will have to be specified again, else the key_password can be left null. Typically, if you had your X.509 certificate created automatically, this is where you should use the password you specified to encrypt the private key that has been created automatically too.

The same password protection principle applies to several other PSEConfig methods. This second level of protection comes on top of the keystore password. One can check whether the password provided for an entry is valid with the validPasswr(ID id, char[] store_password, char[] key_password) method which returns a boolean. Several other practical methods are available from the PSEConfig objects to manage keys and certificates. The reader should check the javadoc for more information.

JXSE Cryptographic Layer Personal Security Environment (PSE) - 133

Other Concepts
Secure Socket Layer (SSL)
The Secure Socket Layer was invented to provide secured communications between two entities over the World Wide Web. It was originally implemented for HTTP connections. The idea was to have only one party (the web server) authenticated. The user would check its certificate from the corresponding certificate authority. SSL operates at two levels: the SSL Handshake protocol and the SSL Record Protocol. After checking the server's certificate, the first protocol is responsible for creating a symmetric key between the two parties. The second protocol is responsible for exchanging information in a secure way using the created symmetric key. Several versions of SSL have been implemented; the latest being version 3. Earlier versions of SSL have been disabled in many web browsers, because they contain several weaknesses.

Transport Security Layer (TLS)
Transport security layer is the follow-up of SSL. It is very similar to SSL, but is intended for a broader set of applications (not only web browsing). Typically, two applications or entities can use it to establish secure communications using one of many types of algorithms. There is not real difference between SSL 3.0 and TLS 1.0. Today, TLS 1.1 and 1.2 are available. Both SSL and TLS are standardized in IETF documents.
48

Virtual Private Network (VPN)
Virtual Private Networks offer the idea of extending your local company network to the whole of the Internet via secured communications. In other words, instead of having your local network protected only by routers, proxies and other artificial network boundaries, your users can connect to your company from any remote location. Since their identity can be established during the creation of the secured communication channel and since other parties cannot interfere with such connections, these users and their PCs can be considered as a safe part of the company's network, although they are not physically located within the company.

48

Internet Engineering Task Force: http://www.ietf.org/

JXSE Cryptographic Layer Other Concepts - 134

JXTA Security Layer
JXTA implements TLS version 1.0 for transportation of messages between peer endpoints on the JXTA network. This model is a clear-message-over-encrypted-communication-channels rather than an encrypted-message-over-clear-communication-channels model. JXSE guarantees that if a message between two peers has to be transmitted via a relay peer or via other peers, these will not have access to the content of the message.

About Cipher Suites
Experts in cryptography will tick at the fact that there are weaknesses in the methods used by TLS 1.0 to establish secured communications. These methods are called cipher suites . The official specification of TLS 1.0 authorizes the usage of specific cipher suits methods to establish secured connections. Unfortunately, some of these suites use weak algorithms. The current implementation of JXTA has peers automatically selecting/negotiating the cipher suite themselves according to their capacity and order of cipher suite preference. This is coming from the Java implementation of TLS connections itself. This could be exploited by hackers to force the usage of a weak cipher algorithm. This attack venue is not very easy to exploit, but those having means can certainly use it. The main issue is that there is no way to configure any JXTA TLS communication parameters as of version 2.5 of JXSE. One cannot force the usage of safe cipher suites only. Ideally, one should be able to use some of the TLS 1.1 or 1.2 cipher suites too and block all the unsafe ones. Those willing to modify the JXSE code to solve this issue themselves should take a look at class TlsConn in package net.jxta.impl.endpoint.tls in the TlsConn(TlsTransport tp, EndpointAddress destAddr, boolean client) constructor. The setEnabledCipherSuite(String[] suites) method can be called on the ssls object after the call to ssls.setEnabledProtocols(new String[]{"TLSv1"}) to restrain the usage to specific cipher suites. Other protocols can be selected too, but with the risk of not being 100% compatible with those who do not use these.
49

About Encryption of Private Keys
Java offers two types of keystores: JKS and PKCS#12. JXSE offers the possibility to create keystores via the PSEKeyStoreManagerFactory object, but their type is automatically set to JKS. This how the PSEConfig object will create keystores when its initialize() method is called.
49 The list of authorized cipher suites for TLS can be found in Appendix A.5 of the TLS specification document available on http://www.ietf.org/rfc/rfc2246.txt.

JXSE Cryptographic Layer JXTA Security Layer - 135

PKCS#12 is a standard describing a syntax to define personal information exchange. The Java keystore object contains two versions of the same method to store private keys:

void

setKeyEntry(String

alias,

byte[]

key,

Certificate[]

chain) – This method should called for private keys which have already been previously protected (i.e., encrypted) by other means.

void setKeyEntry(String alias, Key key, char[] password, Certificate[] chain) – This method can be called for private keys which have not been protected by external means.

But what do we know about the algorithm used by JKS keystores to encrypt private keys which have not been protected by other means? Apparently, not much information is available on the Internet. If we take a look at the PSEConfig object, which can be used to configure the PSE membership service delivered by JXSE, it contains a method to set private keys in the user's keystore:
... public void setKey(ID id, Certificate[] certchain, PrivateKey key, char[] key_password) throws KeyStoreException, IOException { String alias = id.toString(); synchronized (keystore_manager) { KeyStore store = keystore_manager.loadKeyStore(keystore_password); // Remove any existing entry. store.deleteEntry(alias); store.setKeyEntry(alias, key, key_password, certchain); keystore_manager.saveKeyStore(store, keystore_password); } } ...

The bad news is that this method calls the second version of the setKeyEntry() method of the keystore, that is, for keys which have not been protected beforehand. The user may think that its private keys will be protected safely in the keystore, but nothing is less sure. The workaround is simple, one can retrieve the keystore from the PSEConfig object by calling one of the getKeyStore() methods and call the proper version of the setKeyEntry() method after having encrypted/protected its private key properly. The reader may wonder why the encryption of private keys is an issue, since these are never ex-

JXSE Cryptographic Layer JXTA Security Layer - 136

changed during JXTA communications. There is a risk if someone gets access to the keystore file of a user on its PC. This can happen if a PC is stolen for example.

PSE Configuration Advertisement Encryption
If one sets a private key and an encryption password in the NetworkConfigurator, and later calls the save() method, a PSE configuration advertisement will be created and saved as part of the local configuration. This advertisement will contain an encrypted version of the private key. The encryption method is salting the password 500 times with MD5 and then encrypting the private key with DES and the result of the hashing. Some cryptographers will complain about MD5 and the number iterations, but this is still much better that the unknown algorithm in Java keystores. If someone steals a user's PC, his encrypted private key will be accessible to the thief. If the encryption password used to protect it is weak, then brute force attack will allow the thief to have access to it in a reasonable amount of time if he/she has access to sufficient computer power. This issue can be mitigated by encrypting one's PC hard disk. It makes the access to the encrypted private key much harder, especially when a strong password has been used to encrypt the hard disk.

Conclusion
Discussing the weaknesses of an encryption system or of its usage always comes with a dilemma: who should be informed of this? Will hackers try to exploit those weaknesses? The fact is that hackers willing to attack JXTA/JXSE-enabled applications would easily spot the weaknesses mentioned here. The information provided in this book may look very technical to those who have little or no expertise in cryptography, but it is not to those with more experience, including hackers. The author strongly believes that in this context, it is much more preferable to inform readers than not, especially if some indication for solutions can be provided. The acute reader will notice that some of the issues raised here are not related to the implementation of cryptography in JXTA itself, but to the usage of cryptography in general. The development of JXTA and JXSE is an ongoing process. A project to better integrate JXSE with JAAS (Java Authentication and Authorization Service) has been created. Contributions are welcome.

JXSE Cryptographic Layer JXTA Security Layer - 137

Where Does JXSE 2.6 Stand?
Although JXSE code contains an embryo of secured communications, there are still some fundamental issues to be solved. For example: published advertisements are not signed, and therefore cannot be authenticated. It is unfortunately an open venue to pollute local caches with remote publication for example. Some code has been implemented by a member of the community to solve these issues. However, although patches exist, they have not been included as part of 2.6 because of a lack of resources and priority was given to other 'urgent' issues.

JXSE Cryptographic Layer JXTA Security Layer - 138

Architectural Considerations
This chapter discusses JXTA and implementation of software applications using JXSE from an architectural point-of-view. We will cover the general issues and questions software designers should be aware of. This includes the configuration of peers, the definition of a peer's identity and other factors.

Identity Issues
IP Addresses As Identities
Earlier, we mentioned that using IP addresses to identify peers or JXTA was not going to be a good solution, even when using IPv6. Although IPv6 is providing more IP addresses than the humanity will (most probably) ever need, we cannot rely safely on the fact that one could assign a unique IP address per peer and that this IP address could be used to identify any peer. The problem is that if you assign a unique IP address to each physical device, for example, by hard coding it in the network card or within the processor of a computer, there is still a possibility that your computer needs some repair requiring you to change your network card or your processor. Either one would need to reset the IP address on its device or one would need to notify everyone that he or she has changed of IP address (i.e., identifier). If one can change its IP address on his/her device, he/she would therefore be able to fake its identity, since its IP address is his/her identity on the network. Another problem is that people change computers. Sometimes, they have many computers, too. Two different computers cannot have the same IP address (except when they belong to different subnets ), otherwise, the Internet would not be able determine which one should receive a data packet. Therefore, if I had two computers, I would have two identities on the Internet. That is not really what we are looking for. Moreover, many people can connect to the Internet via the same computer. If a unique IP address is used on that computer, then who is really connected to the Internet? We would need several IP addresses for the same computer to establish different identities. When using IPv4, there is also the problem of dynamically assigned IP addresses. If one's IP address changes each time one connects to the Internet, we cannot rely on its IPv4 address to es50 This is like two cities having a street with the same name. The postman does not get confused about the destination street, since the name of the city differentiates them.
50

Architectural Considerations Identity Issues - 139

tablish one's identity. The fact is that we need to conceptually decouple the concept of location on the Internet and the concept of user identity. Users can use one or many computer devices and devices can be used by one or many users. We should also keep in mind that a computer or a device does not necessarily always have the same IP address according to its physical location when connecting to the Internet. Contrary to houses, computers are mobile, like laptops. There are 3 factors to take into account: the user, the computer and the location of the connection on the Internet. It is tempting to believe that since we need to identify peers in a unique way on the Internet and that since IPv6 offers a sufficient number of IP address to accomplish this task, we should use these to identify users. But, IP addresses are used to identify physical locations where to deliver data, not users. Moreover IPv6 addresses can be changed for a given device.

Defining An Identity in JXTA
In JXTA, the concept of peer is a little bit blurring, since a peer is defined as 'any networked

device implementing the JXTA protocols '. However, we use peer IDs to identify peers on the network. To be correct, we should say that users are using a peer to connect on the JXTA network. In JXSE, there is a clear decoupling between the identity of a peer (i.e., a physical device implementing the JXTA protocols) and its address on the network. This allows the peer to connect from different locations on the Internet. The peer ID is fixed, but the IP address can change. One should not forget that a peer must provide its peer ID to connect to the JXTA network via a peer group. Now, there is a temptation to make a one-to-one relationship between a peer ID and a user, as if a user would always possess only one physical device running JXTA protocols. That is not a good idea. If we connect two devices having the same peer ID on a JXTA network, the behavior of the system will be unpredictable. The identity of a peer in JXTA should not be confused with the identity of a user. A peer ID is defining a peer, not a user and not a computer device. In JXSE, a memory stick containing a JXTA-enabled application could be used by several users on several computer devices. Now, there is nothing preventing each of these users to connect to the JXTA network using their own peer ID when they use the memory stick. If two memory sticks A and B were available, a user connecting sometimes with A and sometimes with B would not be starting with the same JXTA status in terms of known advertisements, for example.

Architectural Considerations Identity Issues - 140

Metaphorically: There is a risk of identity confusion in our metaphor, because: 1. Islands are physical locations on the ocean. 2. It is the tribe's people who are running the 'jxta protocols'. Since we tend to identify ourselves with the tribes, rather than with their rulers, and since each tribe has its distinctive sign (flag, tattoo, etc...), we tend to believe that it is our tribe's distinctive sign that defines us, but no: users are rulers and rulers are users. Our tribe's people is the software that is running the JXTA protocols; they can do that on many islands. We could be the ruler of a tribe having another distinctive sign. Now, contrary to reality, islands are immobile. Our computer devices are not. This is a limitation of the metaphor. Yet, tribes' people still navigate between islands.

Creation Of Peer IDs & Importation Of IDs From Other Systems
A peer ID can be are created with two static methods of the IDFactory object:

newPeerID(PeerGroupID groupID) – This method will create a new random Peer ID using the ID of the peer group used to connect to the JXTA network.

newPeerID(PeerGroupID groupID, byte[] seed) – This method can be used to import IDs from other systems by converting them into byte arrays. If your IDs represent users, don't forget that you are tacitly assuming that there is a one-to-one relationship between peers and IDs when providing them as seeds.

Every ID in JXTA has a format. A peer ID is made, amongst other things, of two hexadecimal strings of 32 characters: one for the peer group and one for the peer itself. This gives us 32 = 2
24 16 80

≈ 10 combinations for the peer ID part only. Peer IDs are generated with a statistically uniform distribution among possible combinations. If you are too worried about possible collisions from our discussion about the birthday paradox, you can eventually split your population in peer groups.

Peer Group Creation & Identity
Just like peers, peer groups have their own JXTA IDs too. The identity of a peer group is easier to define than for peers. We already know that there are two default peer groups having default IDs: the world peer group and the net peer group. The question software architects and designers will have in mind is when to create a new group?

Architectural Considerations Identity Issues - 141

There are several factors influencing the answer to that question:

Inclusion – Sometimes, people need 'something' to get connected to each other. Peer groups can be used to create social semaphores that will help those sharing a common interest gathering together.

Seclusion – Sometimes, groups of individuals want to isolate themselves from the rest of the world to discuss specific issues. Instead of including everyone, they select the people they want to let in. This can be implemented by the means of credentials and membership services.

Access Control – Some peers may be offering services of value or possess valuable content. Owners do not necessarily want to share and distribute this content. Access control can be implemented to solve this issue.

Membership Control – From the protocol specifications, the net peer group and the world peer group should accept all requests for peergroup membership . If membership control is required, one should create a new group with the PSE membership service (for example).
51

Capacity – Some peers may be capable of offering services that other peers can't, because they have more capacity (software, memory, processors, etc...) than others. One may want to create a group to identify them and let people connect to that group to find out which peer is available to perform those resource consuming services.

Monitoring – Let's imagine that a meteorological institute installs a set of small devices operating on JXTA to measure the temperature or the humidity of a given area. One will be interested in creating a peer group to monitor those devices and collect information from them.

Architects and designers will need to find the right balance to create peer groups. The more peer groups are created, the more rendezvous will be needed for those groups to operate properly. Do not forget that messages are only propagated within a peer group. The consequence is that, ultimately, the more peer groups are created (i.e., very high specialization), the less peers connected to these groups will be able to connect with other peers in other groups. Since peer groups are organized according to a parent-child hierarchy, peers looking randomly for other peers would need to travel through that hierarchy and to connect to many groups
51 This requirement was not properly implemented in the 2.5 release. This has been solved in 2.6.

Architectural Considerations Identity Issues - 142

before finding someone 'interesting'. This is an extreme scenario, but it describes the limit to multiple group creation.

Configuration Modes
JXTA defines four kind of peers
52

and JXSE offers five basic configuration modes which can be

combined together to create more sophisticated configurations.

JXTA Peer Types
Minimal Edge Peer
Typically, these peers send and receive messages, but they do not keep copies of advertisements or route messages. The consequence is that other peers cannot count on them to provide support when looking for resources or routes to reach other peers. This can be perceived as a selfish attitude, but is justified when dealing with devices having low capacities (sensors, mobile phones, etc...). Minimal edge peers can be considered as pure consumers of JXTA networks.

Full-Featured Edge Peer
Like minimal edge peers, full-featured edge peers can send and receive messages. Contrary to these, they cache advertisements and participate to the discovery process initiated by other peers by answering to their queries when they can. However, full-featured edge peers do not forward these queries to other peers. Full-featured edge peer make a greater contribution to the JXTA network then minimal edge peers, since they help other peers finding or getting access to resources on the network.

Rendezvous Peer
Rendezvous peers are similar to full-featured edge peers, but they take more responsibility in organizing the JXTA network. Among other things, they keep a map of all connected peers in a peer group and they help forwarding messages and queries within a peer group. Such a peer is considered as an infrastructure peer.

Relay Peer
Relay peers were formally known as route peers earlier in JXTA.. Their purpose is to help peers
52 These types are not defined in the JXTA specification document, but in the developer's guide version 2.5, which is a little ambiguous.

Architectural Considerations Configuration Modes - 143

hidden by some features of the network transportation layer connect with other peers and viceversa. These are also considered as infrastructure peers.

JXSE Configuration Modes
JXSE defines configuration modes via the NetworkManager.ConfigMode.

ADHOC
Ad hoc is the most minimal JXSE configuration a peer can use.

These peers do not connect to infrastructure peers (like RELAY or RENDEZVOUS) to benefit from their services.

If they receive a query or any other kind of infrastructure-related request, they automatically propagate it on their LAN if they cannot answer it, but do not get involved in more sophisticated operations. They perform strict minimum duties. Such infrastructure communications are received by ADHOC when a RENDEZVOUS or EDGE peers are also located on the WAN and propagates information via multicasting.

They only use multicasting on the LAN to communicate with other peers. Hence, they cannot directly be reached by peers on the WAN.

They can automatically become EDGE or RENDEZVOUS if proper configuration is set and specific conditions are met. If this happens they never return to an ADHOC status (unless the application is started again).

EDGE
Edge is the most frequent JXSE configuration used by devices to connect to the JXTA network:

These peers automatically try to connect and to remain connected to one and only one rendezvous peer.

If a connection with their rendezvous is lost, if their rendezvous goes down or if a rendezvous does not accept a lease request, they will try to establish a connection with the next rendezvous they know about until success. It is an infinite cycle.

Edge peers can communicate using multicasting, TCP and HTTP when enabled through configuration. Hence, they can directly communicate with adhoc on the LAN if multicasting

Architectural Considerations Configuration Modes - 144

is enabled.

Edge peers with private IP addresses need to be connected to a relay peer to be reachable from the WAN. Like with rendezvous peers, they attempt to connect to relay peers and do their best to remain connected, or shift to the next relay.

When an edge wants to perform an operation involving infrastructure activity it does so via its connected rendezvous. Some infrastructure related query and information can sometimes be propagated on the LAN via multicasting if enabled.

If properly configured, an Edge can become a rendezvous when there are not enough rendezvous available for example. It can also switch back into an edge if there are few edges connected to it.

RENDEZVOUS
Rendezvous peers are edge peers implementing and offering the services of JXTA rendezvous peers for their peer group.

Rendezvous can communicate using multicasting, TCP and HTTP. Typically, they should always enable at least TCP, else they will barely be able to perform their duties.

Typically, rendezvous peers should operate with a public address, which makes them (potentially) reachable from anywhere on the WAN.

A rendezvous with a private address is redundant when multicasting is enabled by all peers on the LAN. It only makes sense if only TCP is enabled and if the local rendezvous is connected to other rendezvous.

Rendezvous can demote themselves into edge peers when configured so and when few edge peers are connected to them. They can also become rendezvous again if there are not enough rendezvous available.

Rendezvous accept lease requests from edge peers and use these to propagate infrastructure related messages and messages propagated through the peergroup to edge peers.

RELAY
In JXSE, relay peers are edge peers providing means for peers having a private address on a LAN to be reachable from the WAN.

Architectural Considerations Configuration Modes - 145

Relay peers are typically enabled with a public IP address. Edge peers with a private address have to be able to connect to them. A relay with a private address is useless.

Edge peers connect to relay peers. When a remote peers wants to connect to NAT-ed peers, the process of finding a route will indicate that they should go through the relay peer.

PROXY
In early implementations of JXTA, there used to be proxy-needing peers who would connect to proxy peers to access the JXTA network. These proxy-needing peers were implemented for small devices with limited capacities. Since, JXME peers have been developed and do not need to connect to JXTA via proxy peers. The proxy code has been deprecated in JXSE 2.6 and will be removed in a future version.

Peer Type versus Configuration Types
The following table establishes the relationship between the JXSE configuration mode of a peer and its type in JXTA.
Is a ADHOC EDGE RENDEZVOUS RELAY Minimal Edge Peer Can be No No No Fully-featured Edge Peer No Yes Yes Yes Rendezvous Peer No No Yes Could be too Relay Peer No No Could be too Yes

About Implementation Of Services...
Confusion can rise between the services available in JXSE peers and their role in the JXTA network. Some may believe that (for example) if a JXSE peer uses an edge configuration, rendezvous or relay services will not be available from these peers. Yet, when one performs a test, one will notice that these services can be retrieved from the PeerGroup object used to connect to the JXTA network. The fact is that JXSE developers decided to make the implementation of all JXTA services available to all peers connecting to the JXTA network via the net peer group and the world peer group. However, those services are not necessarily activated. As a consequence, all connections to new peer groups made by calling the newGroup(...) method of PeerGroup objects will automatically benefit from the implementation of these services as long as these are mentioned in the modArchitectural Considerations Configuration Modes - 146

ule implementation advertisement. Developers who want to implement their own versions of JXTA services will have to implement corresponding interfaces and either create a new object implementing the PeerGroup interface or inherit from the existing class implementing the PeerGroup interface. In each case, the method returning the service from the PeerGroup object should return the new one implemented by developers.

Network Scope
When implementing an application based on JXTA, one must decide the scope of the JXTA network one wants to reach. This question may seem silly at first, since JXTA is defining a universal set of protocols for P2P transactions, but it is not when considering implementation issues. In theory, JXTA offers the possibility to connect to all JXTA-enabled peers, but in practice, we have already seen that technical issues prevent this from happening smoothly and automatically. Each implementation of JXTA requires a network transportation layer, which determines the set of JXTA-enabled peers which can be reached from a technical point-of-view. If you are using JXSE, you will be able to reach peers connected via TCP/IP (and HTTP). If you want to reach peers via another transportation layer, you will need another implementation of JXTA. You also need take into account the technical capacities of each device that will run your JXTA-enabled applications. Are they capable of running java byte code or not? Do you need to compile a C/C++ version on a specific platform? Do you need to implement JXTA in a new programming language?

To Be Or Not To Be?
In order to operate efficiently, JXTA also needs a set of super peers, that is, a set of peers having more responsibilities, capacities and duties than others in order to organize and to operate the JXTA network efficiently.

A Relay
The necessity for relay peers in JXSE comes from the need to overcome artificial network boundaries. The factors to be considered are the following:
• •

Will you peers be assigned private Ipv4 addresses? Will your peers be connecting from/to the WAN to peers located behind a NAT? Architectural Considerations Network Scope - 147

Is only HTTP allowed outbound to the WAN on your network?

If the answer to any of these questions is yes, you will need to implement some relay peers with public IP addresses. These relays should be set as seeds for user peers running your JXTA-enabled application. User peers should not be acting as relays themselves, but should rely on the set of relay peers you will implement when deploying your application. You can control the maximum number of simultaneous connections to your relay peers via the setRelayMaxClient(...) method of the network configurator.

A RendezVous
RendezVous are facilitating the propagation of messages and queries between peers in a peer group whose members are not all reachable by multicasting. The necessity for rendezvous peer is mostly driven by the number of peer groups your JXTA-enabled application will use. There should be enough rendezvous for each peer group. But what is enough? There are three dimensions to this issue: a) Some seed peers should be setup to enable general connectivity of peers within peer groups, and b) some edge peers may decide to become rendezvous themselves for the peer groups they are connected to and c) every rendezvous can be accept a limited amount of connections from edge and rendezvous peers. The RendezVousService of peer groups contains a couple of useful methods:

setAutoStart(boolean auto, long period) – This method can be used to have user peer switching between becoming rendezvous peers or not. They will reconsider their roles after an interval of period milliseconds have expired.

IsConnectedToRendezvous(...) – Indicates whether a peer is connected to at least one rendezvous.

IsRendezvous(...) – Indicates whether a peer is acting as a rendezvous.

You can control the maximum number of simultaneous connections to your rendezvous peers via the setRendezvousMaxClient(...) method of the network configurator. One should remember that each rendezvous maintains its list of known rendezvous in a peer group. These rendezvous peers regularly send random lists of their known rendezvous peers to a set of known rendezvous peers. Non-responding peers are removed from the lists. This helps keeping the network connected.

Architectural Considerations Network Scope - 148

Moreover, a peer can be connected to several peer groups simultaneously. Therefore, it can act as a rendezvous for some or all of these peer groups.

Number of Seeds
Edge peers try to maintain one and only one connection with a rendezvous. However, a rendezvous cannot support an infinite number of peers. Even if many rendezvous are set, the number of peers trying to connect to these can still be an issue. Moreover, rendezvous peers also need to establish initial connections with other rendezvous seeds. If the same set of seed rendezvous is used for edge and rendezvous peers, the risk of running out of lease connection will rise even more. A solution is to create a set of rendezvous seeds for edges and a set of rendezvous seeds for rendezvous. If necessary multiple layers of seeds can be set. A seed belonging to a layer would only try to use seeds of an above layer.

Network Administration
There is a lot network administrators can do to guarantee the performance and connectivity of JXSE-enabled applications.

Default IP Ports
The default IP ports used by JXSE are in the 9701 to 9799 range. If a user runs one JXSE-enabled application, he/she will use one port. If several JXSE-enabled applications run on his/her computer (or device), several IP ports in the range above will be used. In this case, they are selected randomly. Network managers should do their best to configure their network firewalls in order to enable communication over these ports. However, if there is a conflict, JXSE-enabled applications can be configured to use other port ranges via the NetworkConfigurator object. This would have to be discussed with the application developers.

Default HTTP Port
In order to establish communication with peers located behind NATs or with peers hidden behind firewalls (because the default JXSE IP ports are not enabled), JXSE-enabled peers will try to establish HTTP connections via port 9901 to relay peers. It is important to let peers communicate via that port on firewalls too, because if they cannot connect via the standard IP port and IP ports, there will only be able to establish connections with other peers via multicasting on the LAN. This Architectural Considerations Network Administration - 149

would be a very strong limitation. Using the default HTTP port is also necessary to let peer from the WAN initiate connections with peers located on the LAN via relay peers. Again, if the default value for this port creates a conflict, JXSE-enabled peers can be configured with another value.

Default Multicasting Port & IP Address
JXSE-enabled peers naturally try to establish connections with other peers using the 224.0.1.85 multicast address. They listen on port 1234 to do so. If firewalls are implemented on the user devices themselves, this port should be enabled to establish multicasting connections. Those values can be reconfigured in case of conflict.

Implementing Seeds
In order to operate a network of JXSE-enabled peers, rendezvous and relay seeds are required. These facilitate the connectivity of JXSE-enabled peers over the Internet. In order to operate properly, such seeds must have a static IP address and should be visible from anywhere on the Internet. When implementing such seed devices, network managers need to make sure that NATs are configured to let data packets reach and leave these seeds directly (i.e., without translation). Network Managers may be tempted to question the need of seeds since they control their networks. They should keep in mind that users belonging to their own organization may need to establish connect from outside their network, and that from these other locations, remote routers, firewalls and NAT may not be configured optimally for JXSE-enabled peers. These will often need to access known seeds of their organization to establish connections with other peers of their organization.

About Subnets
If network managers have divided their networks into subnets, they need to make sure that all their routers are configured properly to allow peers located on one subnet to connect to peers located on another subnet using their local IP address. They should do also their best to enable multicasting between these to facilitate connectivity. Otherwise, rendezvous peers will be necessary to perform infrastructure activity between peers located on different subnets.

Architectural Considerations Network Administration - 150

Cryptography
Two main strategies are available regarding using cryptography over JXTA. One can rely on the TLS communication layer implemented within JXSE between peers, or one can implement its own cryptography layer over other JXTA items.

Implementing Your Own Cryptography Layer
Implementing a customized cryptographic layer using a PKI based on RSA key pairs requires choosing a proper hash function and a proper a cipher algorithm for private messages exchanged between peers. As of the publication of this book, only a few number of hash functions have not already been cracked with collisions. This includes the SHA-256/224 and SHA-512/384 functions. Others, like famous MD5 and SHA-0 have been cracked with collisions and cannot be considered as safe anymore. The author recommends using the SHA series of hash functions since they have benefited of a lot of attention from experts. For the cipher algorithm, the author recommends using the AES (Advanced Encryption Standard) or one of the finalists of the competition that led to the selection of the AES: Serpent, Twofish, RC6 and MARS. We recommend using Counter (CTR) or Cipher-Block Chaining (CBC) for the block cipher mode. A good version of the Diffie-Hellman protocol will have to be implemented too to create private keys between peers. Remark: Implementing your own cryptography layer is not an easy task. Your job should be reviewed by experts.

Exportation Limitations
There is another issue you need to take care of: exportation limitations. Several countries have limitations on exportation of products containing cryptographic features. The stronger the algorithm and the bigger the RSA key, the more you may need an exportation license for your product. Authorities are more permissive with mass-market software applications than, say 10 years ago, yet restrictions still exist. Check with lawyers for the latest export license requirements and obligations.

Architectural Considerations Cryptography - 151

Access Control Implementation
We have seen earlier that the default implementations of the membership service and of the access service in JXSE are very permissive. Software architects will need to design their own access control system to protect the access to their JXTA resources, when necessary. This implies developing a Java class implementing the AccessService interface. Some may not be satisfied with the default PSE Membership Service implementation and may want to re-implement it too. In both case, one will need to modify the content of the net.jxta.platform.Module file in the META-INF.services package of the JXSE reference implementation source code to make sure these are loaded by the default peer group implementation.
# The list of Built-in Module Implementation Classes included with this distribution. # Used by PeerGroup Implementation. urn:jxta:uuid-deadbeefdeafbabafeedbabe000000020106 urn:jxta:uuid-deadbeefdeafbabafeedbabe000000030106 urn:jxta:uuid-deadbeefdeafbabafeedbabe000000040106 urn:jxta:uuid-deadbeefdeafbabafeedbabe000000050106 urn:jxta:uuid-deadbeefdeafbabafeedbabe000000050206 urn:jxta:uuid-deadbeefdeafbabafeedbabe000000050306 urn:jxta:uuid-deadbeefdeafbabafeedbabe000000060106 urn:jxta:uuid-deadbeefdeafbabafeedbabe000000070106 urn:jxta:uuid-deadbeefdeafbabafeedbabe000000080106 urn:jxta:uuid-deadbeefdeafbabafeedbabe000000090106 urn:jxta:uuid-deadbeefdeafbabafeedbabe0000000A0106 urn:jxta:uuid-deadbeefdeafbabafeedbabe0000000B0106 urn:jxta:uuid-deadbeefdeafbabafeedbabe0000000D0106 urn:jxta:uuid-deadbeefdeafbabafeedbabe0000000E0106 urn:jxta:uuid-deadbeefdeafbabafeedbabe0000000F0106 urn:jxta:uuid-deadbeefdeafbabafeedbabe000000100106 urn:jxta:uuid-deadbeefdeafbabafeedbabe000000100206 net.jxta.impl.resolver.ResolverServiceImpl... net.jxta.impl.discovery.DiscoveryServiceImpl... net.jxta.impl.pipe.PipeServiceImpl Reference... net.jxta.impl.membership.none... net.jxta.impl.membership.passwd.. net.jxta.impl.membership.pse.. net.jxta.impl.rendezvous.. net.jxta.impl.peer.PeerInfoServiceImpl... net.jxta.impl.endpoint.EndpointServiceImpl... net.jxta.impl.endpoint.tcp.TcpTransport... net.jxta.impl.endpoint.servlethttp... net.jxta.impl.endpoint.router.EndpointRouter... net.jxta.impl.endpoint.tls.TlsTransport... net.jxta.impl.proxy.ProxyService... net.jxta.impl.endpoint.relay.RelayTransport... net.jxta.impl.access.always... net.jxta.impl.access.simpleACL...

The software developers will need to specify the name of the class containing their own access control implementation classes at the proper lines in the above file. Remark: Access control can be implemented for other purpose than peer group membership. It could be used to control access to resources or services.

Architectural Considerations Access Control Implementation - 152

Using JXSE
This chapter explains how to use JXSE in your applications. It works step-by-step, starting with the basic concepts to facilitate the learning process and then builds on top of these to reach the most complex concepts. A concept that is being explained at one level, will not be re-explained at a subsequent level. Developers will be able to use these building blocks to integrate them in their own applications, according to their needs.

Getting Started
All the code examples included in this book have been implemented using JXSE version 2.6. These are available from www.practicaljxta.com.

Creating A Project
We use NetBeans 6.8 to describe our code examples . The following procedure explains how to create an initial project using the JXTA libraries: i) Create a Java application project from the File > New Project menu. Check the Use Dedic53

ated Folder for Storing Libraries flag and set
the Library folder to '.\lib'. ii) Download the jxse-2.6.jar and lib-dependencies-2.6.zip libraries from http://jxse.kenai.com/Downloads/Downloads.html. /lib directory of your project. iii) Add the followings .jar in the libraries section: jxse-2.6.jar, bcprov-jdk15-145.jar, derby-10.5.1.1.jar, felix.jar, h21.2.127.jar, javax.servlet.jar, org.mortbay.jar.jetty.jar, 3.1.5.GA.jar.
53 See http://netbeans.org/downloads/index.html for download.

Put

the

jxse-2.6.jar and unzip the dependencies in the

netty-

Using JXSE Getting Started - 153

You are now ready to implement the code examples.

Maven
JXSE 2.6 will soon be available from Maven via Sonatype . Check for the latest information on http://jxse.kenai.com.
54

Javadoc
You can download the javadoc (jxse-2.6.-javadoc.zip) and add it to NetBeans by: 1. Selecting Tools > Java Platform. 2. Selecting the Javadoc tab. 3. Click Add Zip/Folder and select the downloaded zip file.

First Connection & Local Configuration
Example 100 - Starting And Stopping JXTA
The following code example describes the simplest way to start the JXTA network:
... public class _100_Starting_And_Stopping_JXTA_Example { public static final String Name = "Example 100"; public static void main(String[] args) { try { // Creation of the network manager NetworkManager MyNetworkManager = new NetworkManager( NetworkManager.ConfigMode.EDGE, Name); // Starting JXTA Tools.PopInformationMessage(Name, "Starting JXTA network"); PeerGroup ConnectedVia = MyNetworkManager.startNetwork(); // Diplaying peer group information Tools.PopInformationMessage(Name, "Connected via Peer Group: " + ConnectedVia.getPeerGroupName()); // Stopping JXTA Tools.PopInformationMessage(Name, "Stopping JXTA network"); MyNetworkManager.stopNetwork(); } catch (IOException Ex) { // Raised when access to local file and directories caused an error Tools.PopErrorMessage(Name, Ex.toString()); } catch (PeerGroupException Ex) { // Raised when the net peer group could not be created 54 http://nexus.sonatype.org/oss-repository-hosting.html

Using JXSE First Connection & Local Configuration - 154

Tools.PopErrorMessage(Name, Ex.toString()); } } } ...

Example 100 – Starting and stopping JXTA

1. The first step is to create the network manager by specifying a configuration mode and an instance name. We have selected the EDGE mode. This version of the constructor will, by default, create a /.jxta directory in the current working directory ($CWD) to store a local configuration. This may trigger an IOException if the local directory cannot be accessed. If you do not want the network manager to create a local configuration by default, you can use its setConfigPersistent(false) method to prevent this. 2. Secondly, we start the JXTA network by invoking the startNetwork() method from the network manager we have just created. We will exist as a new peer on the network with a

new peer ID, but we will not necessarily be able to connect to other peers, unless other
peers can be reached on the LAN with IP multicasting. By default, the network manager uses the net peer group as the reference group to start JXTA. It may throw a PeerGroupException if this group fails to initialize. 3. At last, we stop the JXTA network by invoking the stopNetwork() method from the network manager. The example calls the static PopInformationMessage(...) method from the Tools object. This object has been created as part of the code examples contained in this chapter to offer basic functionalities necessary to run these code examples. Metaphorically: You are a random tribe which appeared on an island. You have elected a new ruler who created his box of dried leaves. There is a very high probability that no one has noticed your arrival, since you have not made contact with other tribes. Right after you appeared, you have almost immediately decided to hide in a big cave in the mountains after storing your box of dried leaves in its default location for later usage. If you used the setConfigPersistent(false) method, you are an ephemeral new tribe who has elected a new ruler. You have created a temporary box of dried leaves. However, you have

Using JXSE First Connection & Local Configuration - 155

decided to disappear soon after you arrived on the island. The tribe has been dismantled together with the box of dried leaves. There is a high probability that no one has noticed your tribe's existence at all.

Example 110 – Creating A Local Configuration
The following code example describes a simple way to create a local configuration for JXTA and to save it:
... public class _110_Creating_A_Local_Configuration_Example { public static final String Name = "Example 110"; public static void main(String[] args) { try { // Preparing the configuration storage location String LocalPath = "." + System.getProperty("file.separator") + "MyPath"; File ConfigurationFile = new File(LocalPath); // Removing any existing configuration Tools.PopInformationMessage(Name, "Removing any existing local configuration"); NetworkManager.RecursiveDelete(ConfigurationFile); // Creation of the network manager NetworkManager MyNetworkManager = new NetworkManager(NetworkManager.ConfigMode.EDGE, Name, ConfigurationFile.toURI()); // Setting the peer name Tools.PopInformationMessage(Name, "Setting the peer name"); NetworkConfigurator MyNetworkConfigurator = MyNetworkManager.getConfigurator(); MyNetworkConfigurator.setName(Name, "My peer name"); // Saving configuration Tools.PopInformationMessage(Name, "Saving the local configuration in:\n\n" + ConfigurationFile.getCanonicalPath()); MyNetworkConfigurator.save(); } catch (IOException Ex) { // Raised when access to local file and directories caused an error Tools.PopErrorMessage(Name, Ex.toString()); } } } ...

Example 110 - Creating a local configuration

1. We prepare a directory location for our local configuration. The above example points at a directory called “MyPath” created in the current working directory. 2. Next, we use another constructor for the network manager and specify the location of the

Using JXSE First Connection & Local Configuration - 156

local configuration. If no configuration file can be found at that location, the network manager will create a new file called PlatformConfig. 3. We then retrieve the network configurator from the network manager. 4. We set the peer instance name in the network configurator. 5. We save our configuration. The directory where the local configuration has been saved will contain a file called PlatformConfig. If we check its content, it will contain the name of our peer and the peer ID created automatically:
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE jxta:CP> <jxta:CP type="jxta:PlatformConfig" xmlns:jxta="http://jxta.org"> <PID> urn:jxta:uuid59616261646162614E504720503250337644372E0A464012AFE3EF0726DD904003 </PID> <Name> My peer name </Name> <Desc> Created by NetworkManager </Desc> ... </jxta:CP>

Metaphorically: You have decided to create a special box of dried leaves with special decoration and put your name on it. You have also created a specific storage location for that box on your island.

Example 120 – Retrieving, Modifying & Saving A Local Configuration
The following code example describes a simple way to retrieve a local configuration, to modify it and to save it.
... public class _120_Retrieving_Modifying_And_Saving_An_Existing_Configuration_Example { public static final String Name = "Example 120"; public static void main(String[] args) { try { // Preparing the configuration storage location String LocalPath = "." + System.getProperty("file.separator") + "MyPath"; File ConfigurationFile = new File(LocalPath); // Creation of the network manager

Using JXSE First Connection & Local Configuration - 157

NetworkManager MyNetworkManager = new NetworkManager( NetworkManager.ConfigMode.EDGE, Name, ConfigurationFile.toURI()); // Checking for configuration existence NetworkConfigurator MyNetworkConfigurator = MyNetworkManager.getConfigurator(); if (MyNetworkConfigurator.exists()) { // Found existing configuration Tools.PopInformationMessage(Name, "Found existing configuration"); } else { // No configuration found Tools.PopInformationMessage(Name, "No configuration found at:\n\n" + ConfigurationFile.getCanonicalPath()); } // Modifying new name String NewName = "My new name @ " + System.currentTimeMillis(); Tools.PopInformationMessage(Name, "Setting new name to: " + NewName); MyNetworkConfigurator.setName(NewName); // Saving modifications Tools.PopInformationMessage(Name, "Saving configuration at:\n\n" + ConfigurationFile.getCanonicalPath()); MyNetworkConfigurator.save(); } catch (IOException Ex) { // Raised when access to local file and directories caused an error Tools.PopErrorMessage(Name, Ex.toString()); } } } ...

Example 120 – Retrieving, modifying and saving a local configuration

1. First, we prepare the network manager by specifying the location of our local configuration. Then, we retrieve the network configurator. 2. Next, we check whether a local configuration exists at the specified location and display a message. 3. We modify the name of the peer, and save the local configuration. Metaphorically: You and your tribe were hiding in a big cave in the mountain and you decided to come out and to retrieve your box of dried leaves. If you can find it again, you will redo some of its decoration and change the name of it, else you automatically create a new one and set your new name. At last, you store back the box of dried leaves to its location.

Using JXSE First Connection & Local Configuration - 158

Miscellaneous
Understanding ConfigParam
ConfigParam is an advertisement containing a set of configuration parameters for a peer. It is saved within the PlatformConfig file in the local configuration directory. If you open one with a text editor, you will notice that it contains several advertisements describing all aspects of the desired behavior of a peer. Technically speaking, the ConfigParam object, which contains the configuration of a peer, is passed to the net peer group, which is then passed to the world peer group when the startNetwork() method is called for the first time in the NetworkManager. Some readers will complain that they would like to be able to provide a ConfigParam object for each instance of PeerGroup objects they may create by invoking the newGroup() method from those same PeerGroup objects. This is not possible for now, although a solution is being studied for a future version of JXSE.

Modifying Other Configuration Parameters
The NetworkConfigurator object contains many methods to modify the default configuration of JXSE peers (IP addresses, port ranges, multicast port, peer ID, etc...). Developers should use these methods before starting the JXTA network. If a peer has already started the JXTA network and needs to modify its configuration, it should first stop the JXTA network, perform configuration modifications and restart the network.

Loading A Configuration From A URI
Some developers will want to load the configuration of a peer from a remote location. This can be done with the load(URI uri) method of the NetworkConfigurator object. This can be very useful for devices with low capacities.

Automatic Change Of IP Addresses
Some platforms support the automatic modification of IP addresses of devices on-the-fly. Unfortunately, there is no way to detect such events automatically in Java for now. If this should happen while the JXTA network has been started, this can cause unpredictable behavior. The JXTA network should be restarted.

Using JXSE First Connection & Local Configuration - 159

A workaround to this situation is to check the local host address from time to time with the static method InetAddress.getLocalHost() and restart the JXTA network when necessary. The NetworkManager offer a methods to check whether the JXTA network has been started.

Local Configuration Directory Structure
Typically, the local configuration directory structure of a peer contains a /cm directory. This directory will contain other directories whose names correspond to peer group IDs. These directories will contain two types of files: *.idx (index files) and *.tbl (table files). The later contain miscellaneous types of entries, such as advertisement published by the peer or obtained from other peers. The index files contain information about the content of table files.

New Configuration Objects & Connecting With OSGi
Release 2.6 comes with a new way of connecting to the JXTA network and of creating, using and saving configurations.

Example 150 - Configuration Objects
The following code example describes how to create, save and load configuration objects:
... public static final String Name = "Example 150"; public static void main(String[] args) { try { // Creating a default configuration object JxsePeerConfiguration MyConfig = new JxsePeerConfiguration(); JxseHttpTransportConfiguration MyHttpConfig = MyConfig.getHttpTransportConfiguration(); JxseTcpTransportConfiguration MyTcpConfig = MyConfig.getTcpTransportConfiguration(); // Setting some configuration information MyConfig.setPeerInstanceName("Config Object Test"); MyHttpConfig.setHttpIncoming(true); MyTcpConfig.setTcpIncoming(true); // DON'T FORGET TO SET BACK THE TRANSPORT CONFIGURATION MyConfig.setHttpTransportConfiguration(MyHttpConfig); MyConfig.setTcpTransportConfiguration(MyTcpConfig); // Saving the configuration ByteArrayOutputStream BAOS = new ByteArrayOutputStream(); MyConfig.storeToXML(BAOS, "My saving"); System.out.println(BAOS.toString()); // Reading the configuration ByteArrayInputStream BAIS = new ByteArrayInputStream(BAOS.toByteArray()); JxsePeerConfiguration MyReadConfig = new JxsePeerConfiguration(); MyReadConfig.loadFromXML(BAIS); // Checking Tools.PopInformationMessage(Name, "The configuration name is: " + MyReadConfig.getPeerInstanceName());

Using JXSE New Configuration Objects & Connecting With OSGi - 160

JxseHttpTransportConfiguration MyReadHttpConfig = MyReadConfig.getHttpTransportConfiguration(); JxseTcpTransportConfiguration MyReadTcpConfig = MyReadConfig.getTcpTransportConfiguration(); Tools.PopInformationMessage(Name, "HTTP Incoming is: " + Boolean.valueOf(MyReadHttpConfig.getHttpIncoming())); Tools.PopInformationMessage(Name, "TCP Incoming is: " + Boolean.valueOf(MyReadTcpConfig.getTcpIncoming())); } catch (IOException ex) { // Unexpected error Tools.PopErrorMessage(Name, ex.toString()); } } ...

Example 150 – Creating, saving & loading JXSE configuration

1. We start by creating a JXSE configuration object. These contain sub-objects to configure transport layers. 2. In this example, we retrieve a copy the TCP and HTTP configuration objects and set some values. We then set them back in the JXSE configuration object. 3. Next, we save the configuration into a byte array, but one would use a real file in a real application. 4. Then, we load that configuration again in a new JXSE configuration object. 5. We display the configured values.

Example 160 – Connecting with OSGi
The following code example describes how to start the JXTA network using the OSGi framework:
... public static final String Name = "Example 160"; // The NetworkManager service instance private static JxseOSGiNetworkManagerService TheNMS; // The OSGi service tracker for the NetworkManager Service private static ServiceTracker ST; public static void main(String[] args) { try { // Starting the OSGi framework (Felix) JxseOSGiFramework.INSTANCE.start(); // Retrieving the NetworkManager service ST = JxseOSGiFramework.getServiceTracker(JxseOSGiNetworkManagerService.class); // Starting to track the service

Using JXSE New Configuration Objects & Connecting With OSGi - 161

ST.open(); // Retrieving the NetworkManager service for at most 5 seconds TheNMS = (JxseOSGiNetworkManagerService) ST.waitForService(5000); if (TheNMS==null) { Tools.PopErrorMessage(Name, "Could not retrieve the NetworkManager " + "service within 5 seconds"); System.exit(-1); } // Creating a peer configuration JxsePeerConfiguration MyConfig = new JxsePeerConfiguration(); MyConfig.setConnectionMode(ConnectionMode.ADHOC); MyConfig.setPeerID(IDFactory.newPeerID(PeerGroupID.worldPeerGroupID)); MyConfig.setPeerInstanceName("Poupoudipou"); // Setting the configuration in the NetworkManager OSGi service TheNMS.setPeerConfiguration(MyConfig); // Retrieving a configured network manager NetworkManager MyNM = TheNMS.getConfiguredNetworkManager(); // Starting and stopping the network MyNM.startNetwork(); MyNM.stopNetwork(); // Stopping the service tracking ST.close(); TheNMS = null; // Stopping the OSGI framework JxseOSGiFramework.INSTANCE.stop(); // Waiting for stop for maximum 20 seconds FrameworkEvent FE = JxseOSGiFramework.INSTANCE.waitForStop(20000); // Checking whether we stopped properly if ( FE.getType() != FrameworkEvent.STOPPED ) { Tools.PopErrorMessage(Name, "OSGi framework failed to stop after 20 seconds, event type: " + FE.getType() ); } } catch (PeerGroupException ex) { Tools.PopErrorMessage(Name, ex.toString()); } catch (JxtaConfigurationException ex) { Tools.PopErrorMessage(Name, ex.toString()); } catch (InterruptedException ex) { Tools.PopErrorMessage(Name, ex.toString()); } catch (BundleException ex) { Tools.PopErrorMessage(Name, ex.toString()); } catch (IOException ex) { Tools.PopErrorMessage(Name, ex.toString()); } catch (Exception ex) { Tools.PopErrorMessage(Name, ex.toString()); } } ...

Example 160 – Starting the JXTA Network with OSGi

Using JXSE New Configuration Objects & Connecting With OSGi - 162

1. We begin by starting the OSGi framework . 2. Next, we retrieve the OSGi NetworkManager service via an OSGI service tracker, waiting for at most 5 seconds. 3. Then, we create a JXSE peer configuration and set it in the NetworkManager service. 4. Next, we retrieve a configured NetworkManager object instance. 5. We start and stop the JXTA network. 6. At last, we stop the service tracker and the OSGi framework.

55

Exploring Connectivity Issues
Creating & Using Seeds
As mentioned previously, seeds are means by which pockets of peers get to communicate with each other outside the LAN or when TCP communication is not enabled. The NetworkConfigurator offers several methods to set-up RDV seeds:

addRdvSeedingURI(URI seedURI) – With this method, one can set a URI location from which a list of rendezvous seeds is read every 30 minutes.

addRdvSeedingURI(String seedURIStr) – This method is identical to the previous one, but the URI is provided as a string.

addSeedRendezvous(URI seedURI) – With this method, one can provide a physical endpoint location of a rendezvous peer. Contrary to the above methods, no list of rendezvous seed is read from it. Edge peers try to connect to a rendezvous via this endpoint.

setRendezvousSeedingURIs(List<String> seedingURIs) – This method can be used to set a group of URI locations (as strings) from which seeds will be read, with a 30 minutes refresh.

setRendezvousSeeds(Set<String> seeds) – This method can be used to set a group of physical endpoint locations to which edge peers will try to connect to.

clearRendezvousSeedingURIs() – This method removes all registered seeding URIs from which sets of seeds are read.


55

clearRendezvousSeeds() – This method removes all registered physical endpoint

By default, JXSE release 2.6 uses the Apache Felix OSGI framework (see http://felix.apache.org/site/index.html). However, the delivered JXSE .jar contains proper bundle configuration properties to be started from another OSGi framework implementation.

Using JXSE Exploring Connectivity Issues - 163

seeds. The NetworkConfigurator offers corresponding methods for relay seeds. The following code describes how to create seeds and to set them in the NetworkConfigurator:
... public static final String Name = "Creating and setting seeds"; public static final File ConfigurationFile = new File("." + System.getProperty("file.separator") + Name); public static void main(String[] args) { try { // Creation of the network manager NetworkManager MyNetworkManager = new NetworkManager(NetworkManager.ConfigMode.EDGE, Name, ConfigurationFile.toURI()); // Retrieving the network configurator NetworkConfigurator MyNetworkConfigurator = MyNetworkManager.getConfigurator(); // Checking if RendezVous_Jack should be a seed MyNetworkConfigurator.clearRendezvousSeeds(); // Creating an endpoint seed and setting it URI TheSeed = URI.create("tcp://33.44.55.66:9202"); MyNetworkConfigurator.addSeedRendezvous(TheSeed); // Creating a document read by seeding URIs XMLDocument MyDoc = (XMLDocument)StructuredDocumentFactory.newStructuredDocument( MimeMediaType.XML_DEFAULTENCODING, "jxta:seeds"); MyDoc.addAttribute("ordered", "false"); MyDoc.addAttribute("xmlns:jxta", "http://www.jxta.org"); // First seed RouteAdvertisement MyRouteAdv = (RouteAdvertisement) AdvertisementFactory.newAdvertisement(RouteAdvertisement.getAdvertisementType()); PeerID MyRDV = IDFactory.newPeerID(PeerGroupID.defaultNetPeerGroupID, "My first RDV".getBytes()); AccessPointAdvertisement MyAPA = (AccessPointAdvertisement) AdvertisementFactory.newAdvertisement( AccessPointAdvertisement.getAdvertisementType()); MyAPA.addEndpointAddress(new EndpointAddress("tcp://18.22.1.69:3333")); MyRouteAdv.setDestPeerID(MyRDV); MyRouteAdv.setDest(MyAPA); XMLDocument MyRouteAdvDoc = (XMLDocument) MyRouteAdv.getDocument(MimeMediaType.XMLUTF8); Tools.copyElements(MyDoc, MyDoc.getRoot(), MyRouteAdvDoc.getRoot(), true, false); // Second seed RouteAdvertisement MyRouteAdv2 = (RouteAdvertisement) AdvertisementFactory.newAdvertisement(RouteAdvertisement.getAdvertisementType()); PeerID MyRDV2 = IDFactory.newPeerID(PeerGroupID.defaultNetPeerGroupID, "My second RDV".getBytes()); AccessPointAdvertisement MyAPA2 = (AccessPointAdvertisement) AdvertisementFactory.newAdvertisement( AccessPointAdvertisement.getAdvertisementType()); MyAPA2.addEndpointAddress(new EndpointAddress("tcp://171.17.22.4:2876")); MyRouteAdv2.setDestPeerID(MyRDV2); MyRouteAdv2.setDest(MyAPA2); XMLDocument MyRouteAdvDoc2 = (XMLDocument) MyRouteAdv2.getDocument( MimeMediaType.APPLICATION_XML_DEFAULTENCODING);

Using JXSE Exploring Connectivity Issues - 164

Tools.copyElements(MyDoc, MyDoc.getRoot(), MyRouteAdvDoc2.getRoot(), true, false); // Third seed RouteAdvertisement MyRouteAdv3 = (RouteAdvertisement) AdvertisementFactory.newAdvertisement(RouteAdvertisement.getAdvertisementType()); PeerID MyRDV3 = IDFactory.newPeerID(PeerGroupID.defaultNetPeerGroupID, "My third RDV".getBytes()); AccessPointAdvertisement MyAPA3 = (AccessPointAdvertisement) AdvertisementFactory.newAdvertisement( AccessPointAdvertisement.getAdvertisementType()); MyAPA3.addEndpointAddress(new EndpointAddress("tcp://240.28.16.57:4210")); MyRouteAdv3.setDestPeerID(MyRDV3); MyRouteAdv3.setDest(MyAPA3); XMLDocument MyRouteAdvDoc3 = (XMLDocument) MyRouteAdv3.getDocument(MimeMediaType.XMLUTF8); Tools.copyElements(MyDoc, MyDoc.getRoot(), MyRouteAdvDoc3.getRoot(), true, false); // Printing the result MyDoc.sendToStream(System.out); } catch (IOException Ex) { // Raised when access to local file and directories caused an error Tools.PopErrorMessage(Name, Ex.toString()); } ...

Example – Creating & Setting Seeds

1. We start be retrieving a NetworkConfigurator from a NetworkManager and remove any existing rendezvous seeds. 2. Then, we craft an endpoint seed and add it in the NetworkConfigurator. 3. Next, we create a document containing seed route advertisements. This is the type of seed documents (located by an URI) which is read periodically by peers. Remark: We do not add it directly to the NetworkConfigurator. In a real application, this document would typically be posted on the web and accessed by peers. The created seed document looks like this:
<?xml version="1.0"?> <!DOCTYPE jxta:seeds> <jxta:seeds xmlns:jxta="http://www.jxta.org" ordered="false"> <jxta:RA> <DstPID> urn:jxta:uuid-59616261646162614E504720503250334D79206669724374A052C45603 </DstPID> <Dst> <jxta:APA> <EA> tcp://18.22.1.69:3333 </EA> </jxta:APA> </Dst> </jxta:RA> <jxta:RA> <DstPID> urn:jxta:uuid-59616261646162614E504720503250334D79207365634F6EA420D2445603

Using JXSE Exploring Connectivity Issues - 165

</DstPID> <Dst> <jxta:APA> <EA> tcp://171.17.22.4:2876 </EA> </jxta:APA> </Dst> </jxta:RA> <jxta:RA> <DstPID> urn:jxta:uuid-59616261646162614E504720503250334D79207468694264A052C45603 </DstPID> <Dst> <jxta:APA> <EA> tcp://240.28.16.57:4210 </EA> </jxta:APA> </Dst> </jxta:RA> </jxta:seeds>

A similar document can be created for relay seeds.

About The Default JXTA Seeds
In the previous edition of this book, we described the way to set 'default seed' in order to connect to a rendezvous. Unfortunately, the default seed peers have not been maintained by the community and are not reachable anymore. Thus, this example does not work anymore and has not been included here. Consequently the http://rdv.jxtahosts.net/cgi-bin/rendezvous.cgi?3 and http://rdv.jxtahosts.net/cgi-bin/rendezvous.cgi?2 URLs are not valid anymore.

Running Multiple Peers On A Single Device
It is possible to simultaneously run several applications using JXSE (i.e., peers) on the same device and to have them connect to each other when configured properly. Since most readers do not necessarily have several PCs connected together to explore JXTA and JXSE features, we are going to use this technique to let them run the examples describing the features of JXTA on a single PC (or device).

Multiple Peer In The Same JVM
It is not possible to run multiple peers in the same JVM, unless one starts peers with separate ClassLoaders. This will probably change in future releases as the OSGi integration progresses.

Using JXSE Exploring Connectivity Issues - 166

The Proper Angle To Strike A Match
One of the key issues new comers to JXTA face is getting their peers to connect to each other properly. This can be a frustrating experience. Quite often, many try several combinations until it works, but they do not really get to understand why it works. Later, what they have tried may not work anymore and they don't understand why. They may also experience that what works on their LAN does not seem to work that well beyond their LAN. We are going to explore these issues with two peers called Jack the Rendezvous and Anna the Edge on the same PC. Each time the reader starts any of these peers, he or she will have the opportunity to erase any existing configuration on those peers. The reader is free to run those examples from NetBeans for example, or to compile the code for each peer and run these in separately.

Jack, The Rendezvous
The following is the code used for Jack the rendezvous peer:
... public class RendezVous_Jack { public static final String Name = "RendezVous Jack"; public static final int TcpPort = 9710; public static final PeerID PID = IDFactory.newPeerID(PeerGroupID.defaultNetPeerGroupID, Name.getBytes()); public static final File ConfigurationFile = new File("." + System.getProperty("file.separator") + Name); public static void main(String[] args) { try { // Check for removal of any existing configuration? Tools.CheckForExistingConfigurationDeletion(Name, ConfigurationFile); // Creation of the network manager NetworkManager MyNetworkManager = new NetworkManager( NetworkManager.ConfigMode.RENDEZVOUS, Name, ConfigurationFile.toURI()); // Retrieving the configurator NetworkConfigurator MyNetworkConfigurator = MyNetworkManager.getConfigurator(); // Setting configuration MyNetworkConfigurator.setTcpPort(TcpPort); MyNetworkConfigurator.setTcpEnabled(true); MyNetworkConfigurator.setTcpIncoming(true); MyNetworkConfigurator.setTcpOutgoing(true); MyNetworkConfigurator.setUseMulticast(false); // Setting the Peer ID Tools.PopInformationMessage(Name, "Setting the peer ID to :\n\n" + PID.toString()); MyNetworkConfigurator.setPeerID(PID); // Starting the JXTA network Tools.PopInformationMessage(Name, "Start the JXTA network"); PeerGroup NetPeerGroup = MyNetworkManager.startNetwork(); // Waiting for rendezvous connection

Using JXSE Exploring Connectivity Issues - 167

Tools.PopInformationMessage(Name, "Waiting for other peers to connect"); // Retrieving connected peers Tools.popConnectedPeers(NetPeerGroup.getRendezVousService(), Name); // Stopping the network Tools.PopInformationMessage(Name, "Stop the JXTA network"); MyNetworkManager.stopNetwork(); } catch (IOException Ex) { // Raised when access to local file and directories caused an error Tools.PopErrorMessage(Name, Ex.toString()); } catch (PeerGroupException Ex) { // Raised when the net peer group could not be created Tools.PopErrorMessage(Name, Ex.toString()); } } }

Jack The Rendezvous

Here is what Jack is doing: 1. We create a context by: a) Defining the name of the peer: “RendezVous Jack” b) Setting a unique port: 9710 (Anna will use another one to avoid conflicts) c) Defining a unique peer ID d) Defining a unique location for saving the configuration of Jack. 2. When Jack is started, we ask the user whether any existing configuration should be deleted. This is an opportunity to start from scratch. 3. We create the NetworkManager and set the configuration mode to RENDEZVOUS, together with the location for saving the local configuration. 4. We retrieve the NetworkConfigurator and make sure TCP communication is enabled properly. We also set the port to be used and the peer ID of Jack. 5. We wait for the user to start the JXTA network. 6. We wait for Anna to connect to Jack the RendezVous. This gives the user time to start Anna. 7. We check for peers connected to Jack and display the list of them. If none are connected, we display a corresponding message.

Using JXSE Exploring Connectivity Issues - 168

8. We wait for the user to stop the JXTA network.

Anna, The Edge
The following is the code used for Anna the edge peer:
... public class Edge_Anna { public static final String Name = "Edge Anna"; public static final int TcpPort = 9712; public static final PeerID PID = IDFactory.newPeerID(PeerGroupID.defaultNetPeerGroupID, Name.getBytes()); public static final File ConfigurationFile = new File("." + System.getProperty("file.separator") + Name); public static void main(String[] args) { try { // Removing any existing configuration? Tools.CheckForExistingConfigurationDeletion(Name, ConfigurationFile); // Creation of the network manager NetworkManager MyNetworkManager = new NetworkManager(NetworkManager.ConfigMode.EDGE, Name, ConfigurationFile.toURI()); // Retrieving the network configurator NetworkConfigurator MyNetworkConfigurator = MyNetworkManager.getConfigurator(); // Checking if RendezVous_Jack should be a seed MyNetworkConfigurator.clearRendezvousSeeds(); String TheSeed = "tcp://" + InetAddress.getLocalHost().getHostAddress() + ":" + RendezVous_Jack.TcpPort; Tools.CheckForRendezVousSeedAddition(Name, TheSeed, MyNetworkConfigurator); // Setting Configuration MyNetworkConfigurator.setTcpPort(TcpPort); MyNetworkConfigurator.setTcpEnabled(true); MyNetworkConfigurator.setTcpIncoming(true); MyNetworkConfigurator.setTcpOutgoing(true); MyNetworkConfigurator.setUseMulticast(false); // Setting the Peer ID Tools.PopInformationMessage(Name, "Setting the peer ID to :\n\n" + PID.toString()); MyNetworkConfigurator.setPeerID(PID); // Starting the JXTA network Tools.PopInformationMessage(Name, "Start the JXTA network and to wait for a rendezvous” + “\nconnection with " + RendezVous_Jack.Name + " for maximum 2 minutes"); PeerGroup NetPeerGroup = MyNetworkManager.startNetwork(); // Disabling any rendezvous autostart NetPeerGroup.getRendezVousService().setAutoStart(false); if (MyNetworkManager.waitForRendezvousConnection(120000)) { Tools.popConnectedRendezvous(NetPeerGroup.getRendezVousService(),Name); } else { Tools.PopInformationMessage(Name, "Did not connected to a rendezvous"); } // Stopping the network Tools.PopInformationMessage(Name, "Stop the JXTA network"); MyNetworkManager.stopNetwork(); } catch (IOException Ex) {

Using JXSE Exploring Connectivity Issues - 169

// Raised when access to local file and directories caused an error Tools.PopErrorMessage(Name, Ex.toString()); } catch (PeerGroupException Ex) { // Raised when the net peer group could not be created Tools.PopErrorMessage(Name, Ex.toString()); } } }

Anna The Edge

Here is what Anna is doing: 1. We create a context by: a) Defining the name of the peer: “Edge Anna” b) Setting a unique port: 9712 (different than the port of Jack 9710) c) Defining a unique peer ID d) Defining a unique location for saving the configuration of Anna. 2. When Anna is started, we ask the user whether any existing configuration should be deleted. This is an opportunity to start from scratch. 3. We create the NetworkManager and set the configuration mode to EDGE, together with the location for saving the local configuration. 4. We retrieve the NetworkConfigurator and set Jack as a rendezvous seed. 5. We also make sure TCP communication is enabled properly. We set the port to be used by Anna and ask the peer ID of Anna. 6. We wait for the user to start the JXTA network and to wait for a connection with Jack for maximum 2 minutes. 7. Right after the JXTA network is started, we make sure that Anna never becomes a rendezvous spontaneously. 8. If a connection is established, we display the peer ID of the peer Anna is connected to, else we display a message indicating that no connection could be established. 9. We wait for the user to stop the JXTA network.

Using JXSE Exploring Connectivity Issues - 170

Testing Angles Between Jack And Anna
In the previous edition of this book, the examples contained a bug when it came to setting seeds when running multiple peers on the same device. The addRdvSeedingURI(URI seedURI) method was used instead of addSeedRendezvous(URI seedURI). A conclusion was made that running multiple peers on the same device required multicasting. This is false.

Angle I - Start Jack, Then Anna, Delete Configuration & Approve Seed
The first angle we are going to explore to establish a connection between Jack and Anna is the following: 1. Start Jack. 2. Approve deletion of any existing configuration. 3. Start the JXTA network for Jack. 4. When the screen indicating that RendezVous Jack is waiting for peers to connect is displayed, do not click on OK. 5. Start Anna. 6. Approve deletion of any existing configuration. 7. Approve the addition of Jack as a seed. 8. Start the JXTA network for Anna and wait for a connection to a rendezvous. 9. After about a couple of seconds, you should get a message indicating that Anna has managed to connect to a rendezvous. The displayed peer ID should be the one of Jack. Click on OK. 10. Go back to Jack and click on the OK button to finish waiting for Anna to connect. 11. Jack is displaying the peer ID of connected peers, that is, Anna (only). Click on OK

Using JXSE Exploring Connectivity Issues - 171

12. Stop the JXTA network for Jack. 13. Stop the JXTA network for Anna. We have managed to establish a connection between two peers, one being a rendezvous and the other being an edge. If the reader observes the content of the directories containing the configuration and the set of JXTA operational data registered by both peers, he or she will notice that it is more developed for Jack. Metaphorically: You have established two tribes on a single island. None has created its box of dried leaves yet. They cannot get access to each other by land, since they are separated by insurmountable mountains. The only possibility to make a connection is to navigate from one side of the island to the other. The tribe ruled by Anna has heard about the other tribe ruled by Jack, but Jack does not know about Anna. The Anna tribe decides to go on a quest for the Jack tribe and manages to find them. The Jack tribe now knows about the Anna tribe. They have both created their own box of dried leave and registered the route to navigate to each other. They have also kept a description of each other on some other dried leaves. In these descriptions, the Anna tribe remembers that the Jack tribe is capable of propagating messages to other tribes on her behalf in the future. The end of the day has come and both the Jack and the Anna tribe have decided to go hide in their respective caves in the mountains. They will not be accessible by other tribes until they decide to come out again.

Angle II - Start Anna, Then Jack, Delete Configuration & Approve Seed
This angle is exactly the same as angle I, except that the JXTA network of Anna is started before the JXTA network of Jack. In this case, Anna will not be able to make a connection to Jack, until Jack is started: 1. When the screen indicating that RendezVous Jack is waiting for peers to connect is displayed, do not click OK. 2. Start Anna. 3. Approve the deletion of any existing configuration. 4. Approve the addition of Jack as a seed. Using JXSE Exploring Connectivity Issues - 172

5. Start the JXTA network for Jack and the wait for a connection to a rendezvous. 6. After about less than 10 seconds, you should get a message indicating that Anna has managed to connect to rendezvous Jack. Click on OK. 14. Go back to Jack and click on the OK button to finish the wait for Anna to connect. 15. Jack is displaying the peer ID of connected peers, that is, Anna (only). Click on OK 16. Stop the JXTA network for Jack. 17. Stop the JXTA network for Anna. Metaphorically: After the Anna tribe has managed to meet the Jack tribe, both tribes went into their respective caves. After some time, both tribes decide to come out of their caves again. The Anna tribe tries to establish contact with the Jack tribe again, but this time, she has to wait until Jack comes out of his cave.

Angle III - Start Jack, Then Anna, Keep Configuration & Disapprove Seed
In this angle Jack is not set as a seed for Anna. In this case, Anna will not be able to connect with Jack regardless of the information she has managed to collect from the first encounter. Metaphorically: After the Anna tribe has managed to meet the Jack tribe, both tribes went into their respective caves. After some time, both tribes decide to come out of their caves again. The Anna tribe tries to establish contact with the Jack tribe again, but she forgot to tell her people to recontact the Jack tribe. They get lost at sea not knowing their destination. After some time, both tribes go back into their respective caves.

Remarks & Warning

If one enables multicasting only on Anna & Jack, and set Jack as a seed of for Anna, Anne will be able to establish an EDGE – RENDEZVOUS connection, but this does not make sense, since peers can already communicate using multicasting.

The rendezvous service of every peer has a method called setAutoStart(boolean auto, long period) which can be used to have a peer reconsider its role on the network at periodic times. It means that an edge peer can dynamically become a rendezvous for its peer group and vice-versa. This is a very interesting feature that can help peers maintain connections together even if all rendezvous seeds are down or if, for example, a set of peers on a LAN have lost acUsing JXSE Exploring Connectivity Issues - 173

cess to the Internet because of server failure, or if a major cable between countries or continents has been broken. Although the capacity of the JXTA network to establish connections is reduced because of physical constraints beyond its control, pockets of peers will still be able to operate until the connectivity issues have been solved. Typically, a peer should be able to establish connections with other peers in less than a minute if it has already established connections with other peers in the past. If this peer is facing challenging artificial network boundaries conditions, this can take up to a couple of minutes. Beyond, this limit (and assuming that the peer has been configured properly), one can reasonably consider that there is a bigger connectivity issue. A reasonable value for the period parameter is 4 or 5 minutes, although other values can be tested. Values less than 2 minutes are not recommended.

The NetworkConfigurator object has a method called setUseOnlyRendezvousSeeds(...) which can be used to force peers to use only provided rendezvous seeds. Unless there is a really good reason for using this, one should avoid imposing this restriction and let peers also connect to rendezvous of their peer groups which are not part of the list of known rendezvous seeds. This will increase their capacity to establish connections with other peers of their peer group.

When several peers are operating on a LAN, but multicasting is not enabled between them, one of them must act as a rendezvous to enable connectivity between them.

Aminah, The Other RendezVous
We are now introducing new peers to explore rendezvous connectivity a little more. The following is the code used for Aminah, another rendezvous peer:
... public class RendezVous_Aminah { public static final String Name = "RendezVous Aminah"; public static final int TcpPort = 9713; public static final PeerID PID = IDFactory.newPeerID(PeerGroupID.defaultNetPeerGroupID, Name.getBytes()); public static final File ConfigurationFile = new File("." + System.getProperty("file.separator") + Name); public static void main(String[] args) { try { // Check for removal of any existing configuration? Tools.CheckForExistingConfigurationDeletion(Name, ConfigurationFile);

Using JXSE Exploring Connectivity Issues - 174

// Creation of the network manager NetworkManager MyNetworkManager = new NetworkManager( NetworkManager.ConfigMode.RENDEZVOUS, Name, ConfigurationFile.toURI()); // Retrieving the configurator NetworkConfigurator MyNetworkConfigurator = MyNetworkManager.getConfigurator(); // Setting configuration MyNetworkConfigurator.setTcpPort(TcpPort); MyNetworkConfigurator.setTcpEnabled(true); MyNetworkConfigurator.setTcpIncoming(true); MyNetworkConfigurator.setTcpOutgoing(true); MyNetworkConfigurator.setUseMulticast(false); // Setting the Peer ID Tools.PopInformationMessage(Name, "Setting the peer ID to :\n\n" + PID.toString()); MyNetworkConfigurator.setPeerID(PID); // Starting the JXTA network Tools.PopInformationMessage(Name, "Start the JXTA network"); PeerGroup NetPeerGroup = MyNetworkManager.startNetwork(); // Waiting for rendezvous connection Tools.PopInformationMessage(Name, "Waiting for " + Edge_Anna.Name + " to connect to " + RendezVous_Jack.Name); // Retrieving connected peers Tools.popConnectedPeers(NetPeerGroup.getRendezVousService(), Name); // Stopping the network Tools.PopInformationMessage(Name, "Stop the JXTA network"); MyNetworkManager.stopNetwork(); } catch (IOException Ex) { // Raised when access to local file and directories caused an error Tools.PopErrorMessage(Name, Ex.toString()); } catch (PeerGroupException Ex) { // Raised when the net peer group could not be created Tools.PopErrorMessage(Name, Ex.toString()); } } }

Aminah the Other Rendezvous

Aminah is doing exactly the same thing as Jack, except that she is using another unique port (9713).

Chihiro, The Other Edge
The following is the code used for Chihiro, another edge peer:
... public class Edge_Chihiro { public static final String Name = "Edge Chihiro"; public static final int TcpPort = 9715; public static final PeerID PID = IDFactory.newPeerID(PeerGroupID.defaultNetPeerGroupID, Name.getBytes()); public static final File ConfigurationFile = new File("." + System.getProperty("file.separator") + Name);

Using JXSE Exploring Connectivity Issues - 175

public static void main(String[] args) { try { // Removing any existing configuration? Tools.CheckForExistingConfigurationDeletion(Name, ConfigurationFile); // Creation of the network manager NetworkManager MyNetworkManager = new NetworkManager(NetworkManager.ConfigMode.EDGE, Name, ConfigurationFile.toURI()); // Retrieving the network configurator NetworkConfigurator MyNetworkConfigurator = MyNetworkManager.getConfigurator(); // Adding Jack and Aminah as RendezVous seeds MyNetworkConfigurator.clearRendezvousSeeds(); String TheJackSeed = "tcp://" + InetAddress.getLocalHost().getHostAddress() + ":" + RendezVous_Jack.TcpPort; URI LocalSeedingRendezVousURI = URI.create(TheJackSeed); MyNetworkConfigurator.addSeedRendezvous(LocalSeedingRendezVousURI); String TheAminahSeed = "tcp://" + InetAddress.getLocalHost().getHostAddress() + ":" + RendezVous_Aminah.TcpPort; URI LocalSeedingRendezVousURI2 = URI.create(TheAminahSeed); MyNetworkConfigurator.addSeedRendezvous(LocalSeedingRendezVousURI2); // Setting Configuration MyNetworkConfigurator.setTcpPort(TcpPort); MyNetworkConfigurator.setTcpEnabled(true); MyNetworkConfigurator.setTcpIncoming(true); MyNetworkConfigurator.setTcpOutgoing(true); MyNetworkConfigurator.setUseMulticast(false); // Setting the Peer ID Tools.PopInformationMessage(Name, "Setting the peer ID to :\n\n" + PID.toString()); MyNetworkConfigurator.setPeerID(PID); // Starting the JXTA network Tools.PopInformationMessage(Name, "Start the JXTA network and wait for a\n" + "rendezvous connection for maximum 2 minutes"); PeerGroup NetPeerGroup = MyNetworkManager.startNetwork(); // Disabling any rendezvous autostart NetPeerGroup.getRendezVousService().setAutoStart(false); if (MyNetworkManager.waitForRendezvousConnection(120000)) { Tools.popConnectedRendezvous(NetPeerGroup.getRendezVousService(),Name); } else { Tools.PopInformationMessage(Name, "Did not connected to a rendezvous"); } // Waiting for Jack to shutdown Tools.PopInformationMessage(Name, "Waiting for rendezvous to shut down"); // Challenging existence of rendezvous Tools.PopInformationMessage(Name, "Waiting for cache to refresh for 30 seconds"); // Going to sleep for some time Tools.GoToSleep(30000); // Waiting for rendezvous connection again Tools.PopInformationMessage(Name, "Waiting for rendezvous connection again"); if (MyNetworkManager.waitForRendezvousConnection(120000)) { Tools.popConnectedRendezvous(NetPeerGroup.getRendezVousService(),Name); } else {

Using JXSE Exploring Connectivity Issues - 176

Tools.PopInformationMessage(Name, "Did not connect to a rendezvous"); } // Stopping the network Tools.PopInformationMessage(Name, "Stop the JXTA network"); MyNetworkManager.stopNetwork(); } catch (IOException Ex) { // Raised when access to local file and directories caused an error Tools.PopErrorMessage(Name, Ex.toString()); } catch (PeerGroupException Ex) { // Raised when the net peer group could not be created Tools.PopErrorMessage(Name, Ex.toString()); } } }

Chihiro the Other Edge

Chihiro is an edge peer like Anna, but she is doing something a little different than Anna: 1. We create a context by: a) Defining the name of the peer: “Edge Chihiro” b) Setting a unique port: 9715 c) Defining a unique peer ID d) Defining a unique location for saving the configuration of Chihiro. 2. When Chihiro is started, we ask the user whether any existing configuration should be deleted. This is an opportunity to start from scratch. 3. We create the NetworkManager and set the configuration mode to EDGE, together with the location for saving the local configuration. 4. We retrieve the NetworkConfigurator and set Jack and Aminah as a rendezvous seeds. 5. We also make sure TCP communication is enabled properly. We set the port to be used by Chihiro and her peer ID. 6. We wait for the user to start the JXTA network and to wait for a connection with a rendezvous for maximum 2 minutes. 7. Right after the JXTA network is started, we make sure that Chihiro never becomes a rendezvous spontaneously.

Using JXSE Exploring Connectivity Issues - 177

8. If a connection is established, we display the peer ID of the peer Chihiro is connected to, else we display a message indicating that no connection could be established. 9. Next, we offer an opportunity to wait until one of the rendezvous peer is shutdown. 10. We wait for 60 seconds to let the cache list of rendezvous peers Chihiro is connected to refresh. 11. We wait a second time for a connection to a rendezvous peer. 12. We display the connected rendezvous peers if any. 13. We shut down the network for Chihiro.

Automatic Reconnection To Other RendezVous
The following procedure describes how an edge peer can automatically connect and reconnect to rendezvous when these go down. We will use Jack the rendezvous, Aminah the other rendezvous and Chihiro the other edge. 1. Start Jack. 2. Approve deletion of any existing configuration. 3. Start the JXTA network for Jack. 4. When the screen indicating that RendezVous Jack is waiting for peers to connect is displayed, do not click on OK. 5. Start Aminah. 6. Approve deletion of any existing configuration. 7. Start the JXTA network for Aminah. 8. When the screen indicating that RendezVous Aminah is waiting for peers to connect is displayed, do not click on OK. 9. Start Chihiro. 10. Approve deletion of any existing configuration. 11. Start the JXTA network and then wait for a rendezvous connection for Chihiro. 12. When Chihiro manages to connect to a rendezvous, write down the peer ID (...36B03 = Jack, ...E6103 = Aminah).

Using JXSE Exploring Connectivity Issues - 178

13. Press the OK button of the 'waiting for peers to connect' of the rendezvous to which Chihiro is connected. 14. The corresponding rendezvous displays the peer connected to it (i.e., Chihiro). Click OK. 15. Stop the JXTA network for that rendezvous peer. 16. Go back to back to Chihiro and click OK of the windows indicating that she is waiting for the shutdown of the rendezvous peer. 17. A window indicating that Chihiro is going to wait for 60 seconds to let the cache list of connected peers refresh is displayed. Click OK. 18. After 60 seconds, Chihiro displays another window indicating that she is ready to wait for another rendezvous connection again. Click OK. 19. Relatively quickly, Chihiro indicates that she is now connected to the other rendezvous still running. Click OK and shut down the JXTA network for her. 20. Back to the remaining rendezvous peer, click on OK on the screen indicating that the rendezvous is waiting for peers to connect. 21. The remaining rendezvous indicates that Chihiro is now connected to it. 22. Click OK and shut down the JXTA network for the remaining peer. We can notice that with a bit of patience Chihiro, who was connected to one of its seed rendezvous, has managed to reconnect to another rendezvous seed when her initial rendezvous went down. This is performed automatically by JXSE. Edge peers try to maintain contact with at least and at most one rendezvous peer over time. They check their rendezvous connections every 15 seconds . Metaphorically: The Jack tribe, the Aminah tribe and the Chihiro tribe are all living on the same big island, but they cannot establish contact with each other by land because of insurmountable mountains. Chihiro has heard about the Jack and the Aminah tribes. She establishes contact with one of them, but after some time, that tribe decides to go hide in its cave. Since Chihiro does not want to be alone, she automatically establishes contact with the third tribe.
56

Connectivity Manager
This book revision contains a new example explaining how to implement a connectivity manager.
56 Unfortunately, unexpected loss of connections are not always detected and handled 'quickly' by JXSE. This a know issue. Solving it requires much refactoring in core code. This could not be accomplished for release 2.6 and has been postponed to a further release.

Using JXSE Exploring Connectivity Issues - 179

It is made of 5 java classes, but we will not include all code here:
• • •

ConnectivityMonitor – This is a frame displaying the connectivity status of peers. DelayedJxtaNetworkStopper – Allows an asynchronous stop of the JXTA network. Edge_Gina – A simple EDGE peer. A possibility to enable TCP and HTTP communication or not is provided.

• •

Relay_Robert – A simple RELAY peer. RendezVous_Mya – A simple RENDEZVOUS peer.

Robert, The Relay
The following is the code used for Robert, a relay peer:
... public class Relay_Robert { // Static public static final String Name_RELAY = "RELAY"; public static final PeerID PID_RELAY = IDFactory.newPeerID(PeerGroupID.defaultNetPeerGroupID, Name_RELAY.getBytes()); public static final int HttpPort_RELAY = 9900; public static final int TcpPort_RELAY = 9715; public static final File ConfigurationFile_RELAY = new File("." + System.getProperty("file.separator") + Name_RELAY); public static void main(String[] args) { try {

Using JXSE Exploring Connectivity Issues - 180

// Removing any existing configuration? NetworkManager.RecursiveDelete(ConfigurationFile_RELAY); // Creation of the network manager final NetworkManager MyNetworkManager = new NetworkManager( NetworkManager.ConfigMode.RELAY, Name_RELAY, ConfigurationFile_RELAY.toURI()); // Retrieving the network configurator NetworkConfigurator MyNetworkConfigurator = MyNetworkManager.getConfigurator(); // Setting Configuration MyNetworkConfigurator.setUseMulticast(false); MyNetworkConfigurator.setTcpPort(TcpPort_RELAY); MyNetworkConfigurator.setTcpEnabled(true); MyNetworkConfigurator.setTcpIncoming(true); MyNetworkConfigurator.setTcpOutgoing(true); MyNetworkConfigurator.setHttpPort(HttpPort_RELAY); MyNetworkConfigurator.setHttpEnabled(true); MyNetworkConfigurator.setHttpIncoming(true); MyNetworkConfigurator.setHttpOutgoing(true); // Setting the Peer ID MyNetworkConfigurator.setPeerID(PID_RELAY); // Starting the JXTA network PeerGroup NetPeerGroup = MyNetworkManager.startNetwork(); // Starting the connectivity monitor new ConnectivityMonitor(NetPeerGroup); // Stopping the network asynchronously ConnectivityMonitor.TheExecutor.schedule( new DelayedJxtaNetworkStopper( MyNetworkManager, "Click to stop " + Name_RELAY, "Stop"), 0, TimeUnit.SECONDS); } catch (IOException Ex) { System.err.println(Ex.toString()); } catch (PeerGroupException Ex) { System.err.println(Ex.toString()); } } }

Robert the Relay

1. Any existing configuration is deleted. 2. The network manager instance and corresponding network configurator are created. 3. Multicasting is disabled, while TCP and HTTP communication are enabled (we will explain why later). 4. A peer ID is set.

Using JXSE Exploring Connectivity Issues - 181

5. The connectivity monitor frame is set and started. It will start the JXTA network. 6. An asynchronous task is created to asynchronously stop the JXTA network. By using Robert, Mya and Gina, one can test various connectivity scenarios with the connectivity manager.

Relay Connectivity
A connection to a relay peer can be established either via TCP or HTTP . This can be checked with edge Gina by enabling/disabling TCP and HTTP communication and by using Robert and Mya. Edge peers loop through their seeds of relay to try to maintain a permanent connection to their a relay peer. One may wonder when HTTP communication would be needed if TCP can be used by peers having a private address, to connect to relay peers. Many corporations only allow outbound HTTP traffic and block other ports and TCP traffic. In this case, HTTP becomes necessary.
57

Summary
The following table indicates which type of communication should be enabled according to the connection mode:
Configuration TCP outgoing TCP incoming HTTP outgoing HTTP incoming Multicasting ADHOC Not required Not required Not required Not required Required EDGE Preferably Not essential Preferably Not essential Preferably RENDEZVOUS Yes Yes No required Not required Preferably RELAY If possible Required Not required Required If possible

• • •

It does not make sense to configure an edge with no outgoing communication enabled. If an edge is configured only with multicasting, make it an adhoc to operate better . A relay peer should have either TCP incoming or HTTP incoming allowed. Otherwise, edge peers will not be able to connect to it.
58

Peers on the same LAN do not need rendezvous to connect if they all have multicasting enabled.

57 58

In version 2.5 of the Programmer's Guide, it is mentioned that “If you are located behind a firewall or NAT, you must use HTTP and specify a relay node“. This is not correct. An edge expects availability of TCP to connect to a rendezvous.

Using JXSE Exploring Connectivity Issues - 182

Creating Peers And Peer Groups
We are now going to explore how to create peers and peer groups. Before that, we need to explain how to create basic JXTA objects.

Example 200 – Creating IDs
The following code provides examples of ID creations.
... public class _200_Creating_IDs_Example { public static void main(String[] args) { // Creating PeerGroupID PeerGroupID PeerGroupID a peer group ID MyPeerGroupID_A MyPeerGroupID_B MyPeerGroupID_C and a sub-peer group ID = IDFactory.newPeerGroupID(); = IDFactory.newPeerGroupID(MyPeerGroupID_A); = IDFactory.newPeerGroupID(MyPeerGroupID_B);

// Creating peer IDs PeerID MyPeer_A = IDFactory.newPeerID(MyPeerGroupID_A); PeerID MyPeer_B = IDFactory.newPeerID(MyPeerGroupID_B); PeerID MyPeer_C = IDFactory.newPeerID(MyPeerGroupID_C); byte[] MySeed = { 0, 1, 2, 3, 4, 5, 6 }; PeerID MyPeer_Seed = IDFactory.newPeerID(MyPeerGroupID_A, MySeed); // Creating a Pipe ID PipeID MyPipe_A = IDFactory.newPipeID(MyPeerGroupID_A); // Displaying the IDs System.out.println("Peer Group A System.out.println("Peer of A System.out.println("Pipe of A

: " + MyPeerGroupID_A.toString()); : " + MyPeer_A.toString()); : " + MyPipe_A.toString());

System.out.println("Peer of A with seed : " + MyPeer_Seed.toString()); System.out.println("Peer Group B of A System.out.println("Peer of B System.out.println("Peer Group C of B System.out.println("Peer of C } } : " + MyPeerGroupID_B.toString()); : " + MyPeer_B.toString()); : " + MyPeerGroupID_C.toString()); : " + MyPeer_C.toString());

Example 200 – Creation of IDs

1. We create a hierarchy of peer group IDs. 2. We create peer IDs, by providing peer group IDs. 3. We also create a peer by providing our own seed. 4. We create a pipe ID, by providing a peer group ID. 5. Then, we print them all. We get a result similar to:

Using JXSE Creating Peers And Peer Groups - 183

Peer Group A Peer of A Pipe of A

: urn:jxta:uuid-E2E76334369C484E8986AC6A6EE02F3E 02 : urn:jxta:uuid-E2E76334369C484E8986AC6A6EE02F3E 5BCCE1738E284BDBA60AD939D7EAB25F 03 : urn:jxta:uuid-E2E76334369C484E8986AC6A6EE02F3E FBB2B65AECF349288561BE8F5D3C7FFB 04

Peer of A with seed : urn:jxta:uuid-E2E76334369C484E8986AC6A6EE02F3E 0001020304054600800080 03 Peer Group B of A Peer of B : urn:jxta:uuid-B44AA561277449CC8843E1872D59AB47 E2E76334369C484E8986AC6A6EE02F3E 02 : urn:jxta:uuid-B44AA561277449CC8843E1872D59AB47 C0997BE0299F4140AE50DE6A85297D3C 03 : urn:jxta:uuid-48F764A983BE47C3938FD3B3B22EC2E3 B44AA561277449CC8843E1872D59AB47 02 : urn:jxta:uuid-48F764A983BE47C3938FD3B3B22EC2E3 2AE55ACDEC7B452CB6B58EE94642833C 03

Peer Group C of B Peer of C

The ID of peer group A is used to create the ID of the peer and the pipe belonging to group A, but also the ID of peer group B. The ID of peer group B is used to create the ID of the peer belonging to group B, but also the ID of peer group C. The ID of peer group C is used to create the ID of the peer belonging to group C. The ID of peer group A has also been used to create the ID of the peer belonging to A for which a seed has been provided. Metaphorically: With your finger in the sand you have drawn the distinctive sign of 3 new groups of tribes. For each group, you have drawn the distinctive sign of a new tribe belonging to it. For one of the groups, you have also drawn the distinctive sign of a trading route. The sea will wash your hand writing in the sand at the next tide.

Example 210 – Creating A New Peer
The following code describes the creation of a peer:
... public class _210_Creating_A_Peer_Example { public static void main(String[] args) { try { // Removing existing configuration Tools.DeleteConfigurationInDefaultHome(); // Creation of the network manager NetworkManager MyNetworkManager = new NetworkManager( NetworkManager.ConfigMode.EDGE, Name); // Creating a new peer PeerGroup TheNetPeerGroup = MyNetworkManager.getNetPeerGroup(); PeerID MyPeerID = IDFactory.newPeerID(TheNetPeerGroup.getPeerGroupID()); MyNetworkManager.setPeerID(MyPeerID);

Using JXSE Creating Peers And Peer Groups - 184

// Alternative method NetworkConfigurator TheNetworkConfigurator = MyNetworkManager.getConfigurator(); TheNetworkConfigurator.setPeerID(MyPeerID); // Starting and stopping the network MyNetworkManager.startNetwork(); MyNetworkManager.stopNetwork(); } catch (PeerGroupException Ex) { Tools.PopErrorMessage(Name, Ex.toString()); } catch (IOException Ex) { Tools.PopErrorMessage(Name, Ex.toString()); } } }

Example 210 – Creating a New Peer

1. We create the network manager. 2. We retrieve the net peer group. 3. We create a new peer ID using the net peer group ID. 4. We set the peer ID using the setPeerID() method in the network manager. Alternatively, we can also set the peer ID at the network configurator level. 5. We start and stop the JXTA network with our new Peer. Remember that a peer is any device running (at least the minimum set of) JXTA protocols. In our case, our peer is connected to JXTA via the net peer group and will be identified by its peer ID. Each time a peer connects to JXTA by using the startNetwork method of the NetworkConfigurator, its peer ID is passed to the net peer group PeerGroup object, which in turn is passed to the world peer group PeerGroup object. Metaphorically: You have decided to create a new tribe belonging to the humanity on your island and elected yourself as its king or queen. You have selected a new distinctive sign, Santa Claus de la JXTA, tattooed it on your chest. You have also set a flag on the beach with your sign to the attention of other tribes. You have quickly decided to go and hide in your cave.

Example 220 – Creating A Customized Peer Group
The following code explains how to create a peer group:
... public class _220_Creating_A_Custom_PeerGroup_Example { public static final String Name = "Example 220";

Using JXSE Creating Peers And Peer Groups - 185

public static final PeerID PID = IDFactory.newPeerID(PeerGroupID.defaultNetPeerGroupID, Name.getBytes()); public static final File ConfigurationFile = new File( "." + System.getProperty("file.separator") + Name); public static final String PeerGroupName = "Custom peer group name"; public static final PeerGroupID CustPeerGroupID = IDFactory.newPeerGroupID( PeerGroupID.defaultNetPeerGroupID, PeerGroupName.getBytes()); public static void main(String[] args) { try { // Removing any existing configuration? Tools.CheckForExistingConfigurationDeletion(Name, ConfigurationFile); // Creation of the network manager NetworkManager MyNetworkManager = new NetworkManager(NetworkManager.ConfigMode.EDGE, Name, ConfigurationFile.toURI()); // Starting the network PeerGroup MyNetPeerGroup = MyNetworkManager.startNetwork(); // Creating a child group with PSE PeerGroup ChildPeerGroup = MyNetPeerGroup.newGroup( CustPeerGroupID, createAllPurposePeerGroupImplAdv(), PeerGroupName, "Custom peergroup..." ); if (Module.START_OK != ChildPeerGroup.startApp(new String[0])) System.err.println("Cannot start custom peergroup"); // Checking membership implementation MembershipService ChildGroupMembership = ChildPeerGroup.getMembershipService(); Tools.PopInformationMessage(Name, "Custom group membership implementation:\n" + ChildGroupMembership.getClass().getSimpleName()); // Stopping the network Tools.PopInformationMessage(Name, "Stop the JXTA network"); MyNetworkManager.stopNetwork(); } catch (PeerGroupException Ex) { Tools.PopErrorMessage(Name, Ex.toString()); } catch (IOException Ex) { Tools.PopErrorMessage(Name, Ex.toString()); } } public static ModuleImplAdvertisement createAllPurposePeerGroupImplAdv() { ModuleImplAdvertisement implAdv = CompatibilityUtils.createModuleImplAdvertisement( PeerGroup.allPurposePeerGroupSpecID, StdPeerGroup.class.getName(), "General Purpose Peer Group"); // Create the service list for the group. StdPeerGroupParamAdv paramAdv = new StdPeerGroupParamAdv(); // set the services paramAdv.addService(PeerGroup.endpointClassID, PeerGroup.refEndpointSpecID); paramAdv.addService(PeerGroup.resolverClassID, PeerGroup.refResolverSpecID); paramAdv.addService(PeerGroup.membershipClassID, PeerGroup.refMembershipSpecID); paramAdv.addService(PeerGroup.accessClassID, PeerGroup.refAccessSpecID); // standard services paramAdv.addService(PeerGroup.discoveryClassID, PeerGroup.refDiscoverySpecID); paramAdv.addService(PeerGroup.rendezvousClassID, PeerGroup.refRendezvousSpecID); paramAdv.addService(PeerGroup.pipeClassID, PeerGroup.refPipeSpecID);

Using JXSE Creating Peers And Peer Groups - 186

paramAdv.addService(PeerGroup.peerinfoClassID, PeerGroup.refPeerinfoSpecID); paramAdv.addService(PeerGroup.contentClassID, ContentServiceImpl.MODULE_SPEC_ID); // Insert the newParamAdv in implAdv XMLElement paramElement = (XMLElement) paramAdv.getDocument(MimeMediaType.XMLUTF8); implAdv.setParam(paramElement); return implAdv; } }

Example 210 – Creating a New Custom Peer Group

Here is how we proceed: 1. We create some context information to define the name and the peer ID that we are going to use to connect to the JXTA network. 2. We also define a name and a peer group ID for the new peer group. 3. We erase the content of any existing configuration. 4. We create the network manager and set our peer ID. 5. We start the JXTA network and retrieve the net peer group. 6. We create a module implementation advertisement using reference module IDs . 7. We create the new peer group by calling the newGroup(...) method from the net peer group retrieved earlier. 8. We start the new peer group and notify the user. 9. We display its membership implementation. 10. We stop the new peer group and notify the user. 11. We stop the network manager. This method creates a new peer group on JXTA from scratch. This includes the local publication of the corresponding new peer group advertisement in the parent group. This advertisement can be later discovered by other peers who can decide to join the group (we will describe this later). This peer could also publish this advertisement remotely to notify other members of the net peer group (we will also describe this later). The newly created peer group automatically inherits from the implementation of transportation layers (TCP, HTTP, multicasting...) from its parent group, the net peer group and the world peer group when initialized and started. Using JXSE Creating Peers And Peer Groups - 187

Metaphorically: You have taken a piece of dried leaf and have drawn the distinctive sign of a new tribe corporation called the 'Custom peer group name'. You have assigned resources from your tribe and your island to run that corporation for some time, before stopping it. If other tribes had contacted you to learn about peer groups, you would have mentioned the new custom group by giving them a copy on the corresponding dried leaf describing it.

Discovery Operations
Finding Advertisements
All JXTA resources are represented by advertisements. Instead of having to hard code resource descriptions in software applications and configuration files, which is cumbersome and not flexible, peers can launch discovery operations to retrieve these advertisements and find out how to access these resources. The following code example describes how to perform advertisement discovery operations.

Example 300 - Retrieving And Flushing Local Advertisements
The following code in this example describes how to retrieve local advertisements and to flush them.
... public class _300_Retrieving_And_Flushing_Local_Advertisements_Example { public static final String Name = "Example 300"; public static final int TcpPort = 9720; public static final PeerID PID = IDFactory.newPeerID(PeerGroupID.defaultNetPeerGroupID, Name.getBytes()); public static final File ConfigurationFile = new File("." + System.getProperty("file.separator") + Name); public static void main(String[] args) { try { // Removing any existing configuration? Tools.CheckForExistingConfigurationDeletion(Name, ConfigurationFile); // Preparing context NetworkManager MyNetworkManager = new NetworkManager(NetworkManager.ConfigMode.EDGE, Name); // Retrieving network configurator NetworkConfigurator MyNetworkConfigurator = MyNetworkManager.getConfigurator(); // Checking if RendezVous_Jack should be a seed MyNetworkConfigurator.clearRendezvousSeeds(); String TheSeed = "tcp://" + InetAddress.getLocalHost().getHostAddress() + ":" + RendezVous_Jack.TcpPort; Tools.CheckForRendezVousSeedAddition(Name, TheSeed, MyNetworkConfigurator); // Setting Configuration MyNetworkConfigurator.setTcpPort(TcpPort);

Using JXSE Discovery Operations - 188

MyNetworkConfigurator.setTcpEnabled(true); MyNetworkConfigurator.setTcpIncoming(true); MyNetworkConfigurator.setTcpOutgoing(true); // Setting the Peer ID Tools.PopInformationMessage(Name, "Setting the peer ID to :\n\n" + PID.toString()); MyNetworkConfigurator.setPeerID(PID); // Starting the network and waiting for a rendezvous connection PeerGroup DefaultPeerGroup = MyNetworkManager.startNetwork(); Tools.PopInformationMessage(Name, "Waiting for rendezvous connection for maximum 60 seconds"); if (MyNetworkManager.waitForRendezvousConnection(60000)) { Tools.PopInformationMessage(Name, "Rendezvous connection successful!"); } else { Tools.PopWarningMessage(Name, "Rendezvous connection NOT successful!"); } // Retrieving local advertisements Tools.PopInformationMessage(Name, "Retrieving local advertisements"); DiscoveryService TheDiscoveryService = DefaultPeerGroup.getDiscoveryService(); Enumeration<Advertisement> TheAdvEnum = TheDiscoveryService.getLocalAdvertisements( DiscoveryService.ADV, null, null); while (TheAdvEnum.hasMoreElements()) { Advertisement TheAdv = TheAdvEnum.nextElement(); String ToDisplay = "Found " + TheAdv.getClass().getSimpleName(); if (TheAdv.getClass().getName().compareTo(RouteAdv.class.getName())==0) { // We found a route advertisement RouteAdv Temp = (RouteAdv) TheAdv; ToDisplay = ToDisplay + "\n\nto " + Temp.getDestPeerID().toString(); } else if (TheAdv.getClass().getName().compareTo(RdvAdv.class.getName())==0) { // We found a rendezvous advertisement RdvAdv Temp = (RdvAdv) TheAdv; ToDisplay = ToDisplay + "\n\nof " + Temp.getPeerID().toString(); } // Displaying the advertisement Tools.PopInformationMessage(Name, ToDisplay); // Flushing advertisement TheDiscoveryService.flushAdvertisement(TheAdv); } // Stopping JXTA Tools.PopInformationMessage(Name, "Stopping the network"); MyNetworkManager.stopNetwork(); } catch (IOException Ex) { Tools.PopErrorMessage(Name, Ex.toString()); } catch (PeerGroupException Ex) { Tools.PopErrorMessage(Name, Ex.toString()); } } }

Using JXSE Discovery Operations - 189

Example 300 – Retrieving and Flushing Local Advertisements

This example performs the following: 1. We create some context information to define the name, the peer ID and the unique port that we are going to use to connect to the JXTA network. 2. We provide the user with an opportunity to delete any existing configuration. 3. We create the network manager, retrieve the network configurator and provide the user with an opportunity to set Jack the seed as a rendezvous seeds. 4. We start the JXTA network, and wait for a rendezvous connection for maximum one minute. We display a message indicating whether a rendezvous connection could be established. 5. We retrieve the list of all local advertisements from the discovery service. 6. We display a message for each advertisement and then delete it. 7. We stop the JXTA network. In order to make this example work, start Jack the Rendezvous until his JXTA network connection is started. Erase existing configuration. Then start example 300 by erasing existing configuration and allowing Jack as a rendezvous seed. When all advertisements have been displayed, stop the JXTA network for both. In this example we are showing how to get rid of a local advertisement. It is not recommended to erase all advertisements like we do. This is just for the sake of explaining how to proceed. Metaphorically: You have heard that another tribe called the Jack tribe exists on the other side of the island, but you can't reach them by land. You decide to send your people to try to establish contact. They may come back with dried leaves describing the rendezvous role of this tribe and the route to reach them. Then, you decide to take all the dried leaves you own from your box, take a look at these, and decide to burn them all.

Example 310 – Remote Search For Advertisements
The following code introduces Maxime the Socializer, who will try to search for other peer advertisements:
... public class Edge_Maxime_The_Socializer implements DiscoveryListener {

Using JXSE Discovery Operations - 190

public static final String Name = "Edge Maxime, The Socializer"; public static final int TcpPort = 9721; public static final PeerID PID = IDFactory.newPeerID(PeerGroupID.defaultNetPeerGroupID, Name.getBytes()); public static final File ConfigurationFile = new File("." + System.getProperty("file.separator") + Name); public void discoveryEvent(DiscoveryEvent TheDiscoveryEvent) { // Who triggered the event? DiscoveryResponseMsg TheDiscoveryResponseMsg = TheDiscoveryEvent.getResponse(); if (TheDiscoveryResponseMsg!=null) { Enumeration<Advertisement> TheEnumeration = TheDiscoveryResponseMsg.getAdvertisements(); while (TheEnumeration.hasMoreElements()) { try { PeerAdvertisement ThePeer = (PeerAdvertisement) TheEnumeration.nextElement(); Tools.PopInformationMessage(Name, "Received advertisement of: " + ThePeer.getName()); } catch (ClassCastException Ex) { // We are not dealing with a Peer Advertisement } } } } public static void main(String[] args) { try { // Removing any existing configuration? Tools.CheckForExistingConfigurationDeletion(Name, ConfigurationFile); // Creation of the network manager NetworkManager MyNetworkManager = new NetworkManager(NetworkManager.ConfigMode.EDGE, Name, ConfigurationFile.toURI()); // Retrieving the network configurator NetworkConfigurator MyNetworkConfigurator = MyNetworkManager.getConfigurator(); // Checking if RendezVous_Jack should be a seed MyNetworkConfigurator.clearRendezvousSeeds(); String TheSeed = "tcp://" + InetAddress.getLocalHost().getHostAddress() + ":" + RendezVous_Jack.TcpPort; Tools.CheckForRendezVousSeedAddition(Name, TheSeed, MyNetworkConfigurator); // Setting Configuration MyNetworkConfigurator.setTcpPort(TcpPort); MyNetworkConfigurator.setTcpEnabled(true); MyNetworkConfigurator.setTcpIncoming(true); MyNetworkConfigurator.setTcpOutgoing(true); // Setting the Peer ID Tools.PopInformationMessage(Name, "Setting the peer ID to :\n\n" + PID.toString()); MyNetworkConfigurator.setPeerID(PID); // Starting the JXTA network Tools.PopInformationMessage(Name, "Start the JXTA network and to wait for a rendezvous\nconnection with " + RendezVous_Jack.Name + " for maximum 2 minutes"); PeerGroup NetPeerGroup = MyNetworkManager.startNetwork();

Using JXSE Discovery Operations - 191

// Disabling any rendezvous autostart if (MyNetworkManager.waitForRendezvousConnection(120000)) { Tools.popConnectedRendezvous(NetPeerGroup.getRendezVousService(),Name); } else { Tools.PopInformationMessage(Name, "Did not connect to a rendezvous"); } // Launching query to retrieve peer advertisements Tools.PopInformationMessage(Name, "Start peer discovery and going to sleep for 60 seconds"); DiscoveryService TheDiscoveryService = NetPeerGroup.getDiscoveryService(); TheDiscoveryService.getRemoteAdvertisements(null, DiscoveryService.PEER, null, null, 0, new Edge_Maxime_The_Socializer()); // Sleeping for 60 seconds Tools.GoToSleep(60000); // Stopping the network Tools.PopInformationMessage(Name, "Stop the JXTA network"); MyNetworkManager.stopNetwork(); } catch (IOException Ex) { // Raised when access to local file and directories caused an error Tools.PopErrorMessage(Name, Ex.toString()); } catch (PeerGroupException Ex) { // Raised when the net peer group could not be created Tools.PopErrorMessage(Name, Ex.toString()); } } }

Example 310 – Remote Search for Advertisements

Maxime the socializer is different than other peers since he implements the DiscoveryListener to receive answers to his queries to other peers. Each time an answer is received, his discoveryEvent() method is called and information can be extracted from the received data. Otherwise, Maxime is performing the same initial operations as Anna until he manages to connect to Jack. Then, he retrieves the discovery service from the net peer group he is connected to. He launches a query to get remote peer advertisements by calling the getRemoteAdvertisement() method. This method contains several parameters: 1. String peerid – If this parameter is left null, the query is propagated to every peer of the subgroup via the connected rendezvous and by multicasting on the LAN. If a peer ID is specified, the query will be propagated to the specified peer only. 2. int type – This parameter indicates the type of the discovery: peer, peer groups or (other types of) advertisements.

Using JXSE Discovery Operations - 192

3. String attribute – This parameter, in combination with the value parameter, can be used to filter the advertisements to be returned by peers receiving the query. Every advertisement contains several attributes (see Appendix for lists) having values themselves. 4. String value – This parameter must be used in combination with the attribute parameter to filter returned advertisement values. Wildcards '*' can be used and the search is not case sensitive. 5. int threshold – This limit indicates the maximum number of advertisements each peer should return. If the type parameter is set to PEER and the threshold is set to 0, each peer receiving the query should return its peer advertisement to the peer initiating the query. 6. DiscoveryListener listener – This parameter can be used to specify the object implementing a proper DiscoveryListener that will be called each time an answer to the query is received. In order to make this example work, one should first start Jack the Rendezvous and then start Anna the Edge and wait until Anna establishes a connection with Jack. Then, Maxime should be started. After the peer discovery is started, Maxime will receive several answers containing peer advertisements of peers who have received and answered the query. Do not forget that you can get several answers for the same peer advertisement from different peers. Metaphorically: The Jack, Anna and Maxime tribes are living on the same island, but are separated by insurmountable mountains. The Anna tribe and the Maxime tribe both have heard about the Jack tribe and make contact with it. Maxime, who is a socializer, wants to know about other unknown tribes. He asks his people to navigate the sea and around the island to check for those tribes. The Jack tribe gets to know about Maxime's request and Jack answers it himself by asking his people to give a copy of dried leaves describing known tribes to Maxime's people. The Jack tribe also notifies the Anna tribe about Maxime's request and she decides to provide a copy of known advertisements to Maxime's people too. This is how Maxime gets to know about Anna. Remark: In order to connect to another peer group, a user can search for its advertisement (for example: The Dave Brubeck Fan Club) and start an instance of it with the newGroup(Advertisement pgAdv) method from the peer group it is connected to. The reader can try to create such a peer, have it connect to Jack the Rendezvous, start Example 220 and perform the necessary actions to retrieve the corresponding peer group advertisement and to connect to it. The auUsing JXSE Discovery Operations - 193

thor suggests to call him Tebogo, the Jazz fan.

Local And Remote Publication
The discovery service of peer groups offers several methods to publish advertisements locally and remotely. When published locally, a lifetime can be set. When published remotely, an expiration can be set. In both cases, these indicate how long the advertisement will be cached on peers. Remote publication can be performed for every peer belonging to the peer group or to a specific peer only. The reader will find more details about the description of the publish() and remotePublish() methods in the javadoc.

Messages & Advertisements
Example 400 – Creating An Empty Message
The following code describes how to create an empty message in JXSE:
... public class _400_Creating_An_Empty_Message_Example { public static final String Name = "Example 400"; public static void main(String[] args) { Message MyMessage = new Message(); Tools.DisplayMessageContent(Name, MyMessage); } }

Example 400 – Creating an Empty Message

Running the above code displays a simple message box with an empty message.

Example 410 – Add String, Long & Int Elements
The following code describes how to add Java String, long and int elements in your message:
... public class _410_Add_String_Long_Int_Elements_Example { public static final String Name = "Example 410"; public static void main(String[] args) { // Creating an empty message Message MyMessage = new Message(); // Creating string element

Using JXSE Messages & Advertisements - 194

StringMessageElement MyStringMessageElement = new StringMessageElement( "MyStringElement", "My string message content", null); // Creating int element StringMessageElement MyIntMessageElement = new StringMessageElement( "MyIntElement", Integer.toString(33), null); // Creating long element StringMessageElement MyLongMessageElement = new StringMessageElement( "MyLongElement", Long.toString(29345677), null); // Adding string message elements MyMessage.addMessageElement("MyNameSpace", MyStringMessageElement); MyMessage.addMessageElement("MyNameSpace", MyIntMessageElement); MyMessage.addMessageElement("MyNameSpace", MyLongMessageElement); // Displaying message Tools.DisplayMessageContent(Name, MyMessage); } }

Example 410 – Add String, Long & Int Elements

Adding simple Java objects in messages is pretty straight forward. By running the above code, the reader should get the following message box. JXSE offers the possibility to define you own name space and element names when inserting them in messages. This can be very useful for data organization purposes.

Example 420 – Retrieving Message Elements
The following code describes how to retrieve message elements:
... public class _420_Retrieving_Message_Elements_Example { public static final String Name = "Example 420"; public static void main(String[] args) { // Creating an empty message Message MyMessage = new Message(); // Creating string element StringMessageElement MyNameMessageElement = new StringMessageElement( "NameElement", "John Arthur", null); // Creating int element StringMessageElement MyAddressMessageElement = new StringMessageElement( “AddressElement", "42nd Street", null); // Creating long element StringMessageElement MyOtherMessageElement = new StringMessageElement( "OtherElement", "Enjoys pizzas", null); // Adding string message elements

Using JXSE Messages & Advertisements - 195

MyMessage.addMessageElement("MyNameSpace", MyNameMessageElement); MyMessage.addMessageElement("MyNameSpace", MyAddressMessageElement); MyMessage.addMessageElement("MyNameSpace", MyOtherMessageElement); // Displaying message Tools.DisplayMessageContent(Name, MyMessage); // Retrieving message element Tools.PopInformationMessage(Name, "Retrieving message element:\n\n" + MyMessage.getMessageElement("MyNameSpace", "AddressElement").toString()); } }

Example 420 – Retrieve Message Elements

The above code creates a simple message and displays it. Then, we extract the address message element content and display it. A message box displaying “ 42nd Street” will pop up.

Example 430 – Add Byte Array Element And Retrieve InputStream
The following code describes how to insert a Java byte array in a message and how to get an InputStream to retrieve its content:
... public class _430_Add_ByteArray_Element_And_Retrieve_InputStream_Example { public static final String Name = "Example 430"; public static void main(String[] args) { try { // Creating byte array and filling it byte[] MyByteArray = new byte[10]; for (int i = 0; i < MyByteArray.length; i++) { MyByteArray[i] = (byte) i; } Message MyMessage = new Message(); ByteArrayMessageElement MyByteArrayMessageElement = new ByteArrayMessageElement( "MyByteArrayElement", MimeMediaType.AOS, MyByteArray, null); MyMessage.addMessageElement("MyNameSpace", MyByteArrayMessageElement); MessageElement MyElement = MyMessage.getMessageElement("MyNameSpace", "MyByteArrayElement"); InputStream MyInputStream = MyElement.getStream();

int Read = MyInputStream.read(); String Result = ""; while (Read != -1) { Result = Result + Read + " "; Read = MyInputStream.read(); } Tools.PopInformationMessage(Name, "Extracted byte array content:\n\n" + Result); } catch (IOException Ex) { Tools.PopErrorMessage(Name, Ex.toString());

Using JXSE Messages & Advertisements - 196

} } }

Example 430 – Add Byte Array Element and Retrieve InputStream

The above code creates a simple message and adds a byte array. Then, we extract the content of the byte array and display its content.

Example 440 – Adding An Advertisement In A Message
The following code describes how to insert an advertisement in a message:
... public class _440_Adding_An_Advertisement_In_Message_Example { public static final String Name = "Example 440"; public static void main(String[] args) { // Creating a customized advertisement _500_Customized_Advertisement_Example MyAdvertisement = new _500_Customized_Advertisement_Example(); MyAdvertisement.SetName("John"); MyAdvertisement.SetAge(33); // Creating the message Message MyMessage = new Message(); // Creating the message element and adding it TextDocumentMessageElement MyTextDocumentMessageElement = new TextDocumentMessageElement( "CUSTOMIZED_ADVERTISEMENT", (XMLDocument) MyAdvertisement.getDocument(MimeMediaType.XMLUTF8), null); MyMessage.addMessageElement("CUSTOMIZED_ADVERTISEMENT",MyTextDocumentMessageElement); // Retrieving the advertisement from the message MessageElement MyMessageElement = MyMessage.getMessageElement( "CUSTOMIZED_ADVERTISEMENT","CUSTOMIZED_ADVERTISEMENT"); try { XMLDocument TheDocument = (XMLDocument) StructuredDocumentFactory.newStructuredDocument( MyMessageElement.getMimeType(), MyMessageElement.getStream()); _500_Customized_Advertisement_Example MyCustomizedAdvertisement = new _500_Customized_Advertisement_Example(TheDocument.getRoot()); // Displaying advertisement Tools.PopInformationMessage(Name, MyCustomizedAdvertisement.toString()); } catch (IOException Ex) { // Thrown when message element cannot be read. Tools.PopErrorMessage(Name, Ex.toString()); } catch (IllegalArgumentException Ex) { // Thrown when the document or advertisement has an invalid structure // (illegal values or missing tags...) Tools.PopErrorMessage(Name, Ex.toString());

Using JXSE Messages & Advertisements - 197

} } }

Example 440 – Adding an Advertisement in a Message

Again, the above code is straight forward: 1. We create an advertisement (in this case, it is a customized advertisement which we will cover next). 2. We add a text document element using the XML format and UTF8 encoding. We set name of the namespace to "CUSTOMIZED_ADVERTISEMENT". 3. Next, we attempt to retrieve our advertisement by first extracting it from the message (it has an XML document format). Then we provide it to our customized advertisement's constructor. 4. At last, we display the retrieved advertisement, which should look as the message box above. The method we have described here can easily be adapted to include XML documents in messages too.

Example 500 – Customized Advertisement
The following code describes how to create a customized advertisement:
... public class _500_Customized_Advertisement_Example extends Advertisement { public static final String Name = "Example 500"; // Advertisement elements, tags and indexables public final static String AdvertisementType = "jxta:CustomizedAdvertisement"; private ID AdvertisementID = ID.nullID; private String TheName = ""; private int TheAge = -1; private final static String IDTag = "MyIDTag"; private final static String NameTag = "MyNameTag"; private final static String AgeTag = "MyAgeTag"; private final static String[] IndexableFields = { IDTag, NameTag };

Using JXSE Messages & Advertisements - 198

public _500_Customized_Advertisement_Example() { // Accepting default values } public _500_Customized_Advertisement_Example(Element Root) { // Retrieving the elements TextElement MyTextElement = (TextElement) Root; Enumeration TheElements = MyTextElement.getChildren(); while (TheElements.hasMoreElements()) { TextElement TheElement = (TextElement) TheElements.nextElement(); ProcessElement(TheElement); } } public void ProcessElement(TextElement TheElement) { String TheElementName = TheElement.getName(); String TheTextValue = TheElement.getTextValue(); if (TheElementName.compareTo(IDTag)==0) { try { URI ReadID = new URI(TheTextValue); AdvertisementID = IDFactory.fromURI(ReadID); return; } catch (URISyntaxException Ex) { // Issue with ID format Ex.printStackTrace(); } catch (ClassCastException Ex) { // Issue with ID type Ex.printStackTrace(); } } if (TheElementName.compareTo(NameTag)==0) { TheName = TheTextValue; return; } if (TheElementName.compareTo(AgeTag)==0) { TheAge = Integer.parseInt(TheTextValue); return; } } @Override public Document getDocument(MimeMediaType TheMimeMediaType) { // Creating document StructuredDocument TheResult = StructuredDocumentFactory.newStructuredDocument( TheMimeMediaType, AdvertisementType); // Adding elements

Using JXSE Messages & Advertisements - 199

Element MyTempElement; MyTempElement = TheResult.createElement(NameTag, TheName); TheResult.appendChild(MyTempElement); MyTempElement = TheResult.createElement(AgeTag, Integer.toString(TheAge)); TheResult.appendChild(MyTempElement); return TheResult; } public void SetID(ID TheID) { AdvertisementID = TheID; } @Override public ID getID() { return AdvertisementID; } @Override public String[] getIndexFields() { return IndexableFields; } public void SetName(String InName) { TheName = InName; } public void SetAge(int InAge) { TheAge = InAge; } public String GetName() { return TheName; } public int GetAge() { return TheAge; } @Override public _500_Customized_Advertisement_Example clone() throws CloneNotSupportedException { _500_Customized_Advertisement_Example Result = (_500_Customized_Advertisement_Example) super.clone(); Result.AdvertisementID = this.AdvertisementID; Result.TheName = this.TheName; Result.TheAge = this.TheAge; return Result; } @Override public String getAdvType() { return _500_Customized_Advertisement_Example.class.getName(); } public static String getAdvertisementType() { return AdvertisementType; } public static class Instantiator implements AdvertisementFactory.Instantiator { public String getAdvertisementType() { return _500_Customized_Advertisement_Example.getAdvertisementType(); }

Using JXSE Messages & Advertisements - 200

public Advertisement newInstance() { return new _500_Customized_Advertisement_Example(); } public Advertisement newInstance(net.jxta.document.Element root) { return new _500_Customized_Advertisement_Example(root); } } }

Example 500 – Customized Advertisement

The above code describes how to create a customized advertisement containing three attributes: advertisement ID, name and age. Our customized advertisement has to implement the Advertisement abstract class which requires defining some specific attributes, overriding some methods and defining an Instantiator class.

Attributes
Our attribute section contains static and non-static fields. The first static field is the advertisement type which is necessary to implement the getAdvertisementType() method of the Advertisement abstract class. Then, we have a set of static fields describing the XML tags which will be used when transforming the data contained in our advertisement into an XML document and viceversa. The last, but very important, static field is the list of tag elements which can be used to index the document (i.e. advertisement) when it will be transmitted between peers. The non static attributes are an ID, the name (of a user for example) and an age. The reader will notice that in our case, the age is not part of the indexable fields.

Methods
Our customized advertisement contains two sets of methods, those inherited and overridden from the Advertisement abstract class. We will start by describing the inherited methods:

Advertisement clone() – This typical method ought to be overridden to make sure that attributes added at our level will be properly copied and initialized in the duplicated object.

static String getAdvertisementType() – This method returns information to identify the JXTA type (i.e., not the Java class runtime type) of the advertisement.

static String getAdvType() – This method returns information to identify the Java class runtime type of the advertisement. In our case, we need to indicate that our advert-

Using JXSE Messages & Advertisements - 201

isement is a _500_Customized_Advertisement_Example Java class.

Document getDocument(MimeMediaType asMimeType) – This methods is necessary to convert our customized advertisement into an XML document.

• • •

ID getID() – Returns the advertisement ID. String[] getIndexFields() – Returns the list of indexable fields. String toString() – Returns a string representation of the advertisement.

Regarding the other methods, we provide two constructors; one to create a empty customized advertisement and one based on the root element of an XML document describing the advertisement. The latter is necessary to convert XML documents back into advertisements. We also provide setter and getter methods for the advertisement attributes.

Instantiator
The implementation of an instantiator is an absolute necessity to make sure our new customized advertisement will be usable by peers on the network. It will be used by the standard implementation of JXTA protocols in JXSE (via the AdvertisementFactory) to create Java object instances of our customized advertisement when they reach peers for example.

Example 510 – Registering A Customized Advertisement Instance
The following code describes how to register customized advertisements in the AdvertisementFactory object:
import Examples.Z_Tools.Tools; import net.jxta.document.AdvertisementFactory; public class _510_Registering_Customized_Advertisement_Instance_Example { public static final String Name = "Example 510"; public static void main(String[] args) { // Registering our customized advertisement instance AdvertisementFactory.registerAdvertisementInstance( _500_Customized_Advertisement_Example.getAdvertisementType(), new _500_Customized_Advertisement_Example.Instantiator()); // Notifying the user Tools.PopInformationMessage(Name, "Registered in Advertisement Factory:\n\n" + _500_Customized_Advertisement_Example.getAdvertisementType()); } }

Example 510 – Registering a Customized Advertisement Instance

Using JXSE Messages & Advertisements - 202

This operation must be performed on every peer that will use our customized advertisement, but not necessarily those who will transport or index a message containing our advertisement. Else, the advertisement will not be processed correctly by peers receiving it. This mechanism, in combination with the Initiator static class created as part of our customized advertisement, will ensure that peers receiving our customized advertisement will receive it as a Java object of type _500_Customized_Advertisement_Example. This eliminates tricky code manipulations for developers; the received advertisement can safely be cast automatically into the proper Java object type. Technically speaking, the JXTA protocols in JXSE will invoke an Instantiator for the advertisement type mentioned in the XML document they receive. Since the AdvertisementFactory will have been initialized properly, it will be able to return such an Instantiator. The protocols can then create an empty instance of our customized advertisement by invoking the newInstance() method. Then, they will be able to fill this new instance with the remaining data contained in the XML document by invoking the ProcessElement(TextElement TheElement) method in our customized advertisement. Metaphorically: We have now learned how to write down messages on dried leaves. We have also learned how to create special dried leaves to describe/advertise our non-standard JXTA resources.

Private Keys, Certificates & KeyStores
Before we start describing how to use pipes to exchange messages, we need to describe how to work with private keys, certificates and keystores.

Example 600 - Exporting & Importing Private Keys And X.509 Certificates
The following code describes how to quickly generate a X509 certificate and its corresponding private key, plus how to export them into a String and re-import them from that same String:
... public class _600_Exporting_And_Importing_Private_Keys_And_X509_Certificates { public static final String Name = "Importing and Exporting Private Keys and Certificates"; public static void main(String[] args) { try { // Certificate and Private Key X509Certificate TheX509Certificate; PrivateKey ThePrivateKey;

Using JXSE Private Keys, Certificates & KeyStores - 203

// Initialization PSEUtils.IssuerInfo ForPSE = PSEUtils.genCert(Name, null); TheX509Certificate = ForPSE.cert; ThePrivateKey = ForPSE.issuerPkey; // String encoded certificate & private key String Base64_X509Certificate = PSEUtils.base64Encode(TheX509Certificate.getEncoded()); String Base64_ThePrivateKey = PSEUtils.base64Encode(ThePrivateKey.getEncoded()); // Printing Results System.out.println("------------------------------"); System.out.println(Base64_X509Certificate); System.out.println("------------------------------"); System.out.println(Base64_ThePrivateKey); System.out.println(ThePrivateKey.getFormat()); System.out.println("------------------------------"); // Recreating certificate & private key X509Certificate RecreateX509Certificate; PrivateKey RecreatePrivateKey; // Recreating the X509 certificate byte[] Temp = PSEUtils.base64Decode(new StringReader(Base64_X509Certificate)); CertificateFactory TheCF = CertificateFactory.getInstance("X509"); RecreateX509Certificate = (X509Certificate) TheCF.generateCertificate( new ByteArrayInputStream(Temp)); System.out.println("-X509-Original-------------"); System.out.println(TheX509Certificate.toString()); System.out.println("-X509-Recreated------------"); System.out.println(RecreateX509Certificate.toString()); System.out.println("---------------------------"); // Restoring the private key Temp = PSEUtils.base64Decode(new StringReader(Base64_ThePrivateKey)); KeyFactory keyFactory = KeyFactory.getInstance("RSA"); PKCS8EncodedKeySpec MyPKCS8EncodedKeySpec = new PKCS8EncodedKeySpec(Temp); RecreatePrivateKey = keyFactory.generatePrivate(MyPKCS8EncodedKeySpec); System.out.println("-Private-Key-Original-------------"); System.out.println(ThePrivateKey.toString()); System.out.println("-Private-Key-Recreated------------"); System.out.println(RecreatePrivateKey.toString()); System.out.println("----------------------------------"); } catch (Exception Ex) { Tools.PopErrorMessage(Name, Ex.toString()); } } }

Example 600 - Exporting & Importing Private Keys And Certificates

This example is performing the following: 1. We generate a pair of corresponding X509 certificate and private key using the PSEUtils tools provided as part of JXTA. The RSA key size is set to 1024 by default. REM: If the reader is not satisfied with those settings, he or she can take a look at the code of PSEUtils to find out how to modify it or to write a new method inspired from it. Using JXSE Private Keys, Certificates & KeyStores - 204

2. We export both the X509 certificate and the private key into base 64 strings and display the result. These strings can be easily exchanged, transported or stored by applications. Do not forget that the private key is not encrypted and has no protection. 3. We re-import the X509 certificate and the private key from the base 64 strings. Then, we display the original and the re-imported result for comparison. Some readers will notice some difference between the display of the original X509 certificate and the recreated X509 certificate. In fact, the modulus and the exponent are expressed in decimals in one case and in hexadecimals in the other case, but the values are the same.

Example 610 – Working With A KeyStore
The following code example describes how to create a keystore and to interact with it:
... public class _610_Working_With_A_Keystore { public static final String Name = "Example 610"; public static final PeerID PID = IDFactory.newPeerID(PeerGroupID.defaultNetPeerGroupID, Name.getBytes()); public static final File ConfigurationFile = new File("." + System.getProperty("file.separator") + Name); public static final String MyPrincipalName = "Principal - " + Name; public static final String MyPrivateKeyPassword = "PrivateKey Password - " + Name; public static final String MyKeyStoreFileName = "MyKeyStoreFile"; public static final String MyKeyStoreLocation = "." + System.getProperty("file.separator") + Name + File.separator + "MyKeyStoreLocation"; public static final String MyKeyStorePassword = "KeyStore Password - " + Name; public static final String MyKeyStoreProvider = "KeyStore Provider - " + Name; public static final File MyKeyStoreDirectory = new File(MyKeyStoreLocation); public static final File MyKeyStoreFile = new File(MyKeyStoreLocation + File.separator + MyKeyStoreFileName); public static final X509Certificate TheX509Certificate; public static final PrivateKey ThePrivateKey; static { // Static initialization PSEUtils.IssuerInfo ForPSE = PSEUtils.genCert(Name, null); TheX509Certificate = ForPSE.cert; ThePrivateKey = ForPSE.issuerPkey; } public static void main(String[] args) { try { // Removing any existing configuration? Tools.CheckForExistingConfigurationDeletion(Name, ConfigurationFile); // Preparing data MyKeyStoreDirectory.mkdirs(); // Creating the key store FileKeyStoreManager MyFileKeyStoreManager = new FileKeyStoreManager(

Using JXSE Private Keys, Certificates & KeyStores - 205

(String)null, MyKeyStoreProvider, MyKeyStoreFile); MyFileKeyStoreManager.createKeyStore(MyKeyStorePassword.toCharArray()); if (!MyFileKeyStoreManager.isInitialized()) { Tools.PopInformationMessage(Name, "Keystore is NOT initialized"); } else { Tools.PopInformationMessage(Name, "Keystore is initialized"); } // Loading the (empty) keystore KeyStore MyKeyStore = MyFileKeyStoreManager.loadKeyStore(MyKeyStorePassword.toCharArray()); // Setting data X509Certificate[] Temp = { TheX509Certificate }; MyKeyStore.setKeyEntry(PID.toString(), ThePrivateKey, MyPrivateKeyPassword.toCharArray(), Temp); // Saving the data MyFileKeyStoreManager.saveKeyStore(MyKeyStore, MyKeyStorePassword.toCharArray()); // Reloading the KeyStore MyKeyStore = MyFileKeyStoreManager.loadKeyStore(MyKeyStorePassword.toCharArray()); // Retrieving Certificate X509Certificate MyCertificate = (X509Certificate) MyKeyStore.getCertificate(PID.toString()); if (MyCertificate==null) { Tools.PopInformationMessage(Name, "X509 Certificate CANNOT be retrieved"); } else { Tools.PopInformationMessage(Name, "X509 Certificate can be retrieved"); System.out.println(MyCertificate.toString()); } // Retrieving private key PrivateKey MyPrivateKey = (PrivateKey) MyKeyStore.getKey(PID.toString(), MyPrivateKeyPassword.toCharArray()); if (MyPrivateKey==null) { Tools.PopInformationMessage(Name, "Private key CANNOT be retrieved"); } else { Tools.PopInformationMessage(Name, "Private key can be retrieved"); System.out.println(MyPrivateKey.toString()); } } catch (NoSuchAlgorithmException Ex) { Tools.PopErrorMessage(Name, Ex.toString()); } catch (UnrecoverableKeyException Ex) { Tools.PopErrorMessage(Name, Ex.toString()); } catch (NoSuchProviderException Ex) { Tools.PopErrorMessage(Name, Ex.toString()); } catch (KeyStoreException Ex) { Tools.PopErrorMessage(Name, Ex.toString()); } catch (IOException Ex) { Tools.PopErrorMessage(Name, Ex.toString()); } } }

Example 610 – Working With a KeyStore

Using JXSE Private Keys, Certificates & KeyStores - 206

This example is performing the following: 1. We define a set of static variables that will be used later in the code. We also create a static code section that will be executed as soon as the _610_Working_With_A_Keystore class is referenced for the first time. This code will create a pair of corresponding private key and certificate for later use. 2. We start by providing the user an opportunity to erase any existing file in the directory that will be used to create the keystore. 3. Then, we create the keystore and set a keystore password. We let the user know whether it has been initialized successfully. 4. We load the keystore (which is empty) and fill it with the X509 certificate and the private key. 5. Next we reload the keystore and try to extract the X509 certificate and the private key. We let the user know whether these operations are successful.

Example 620 – Custom PSE Peer Group & Joining
The following code example describes how to create custom PSE peer group and to join it:
... public class _620_Creating_A_Custom_PSE_PeerGroup_Example { public static final String Name = "Example 620"; public static final PeerID PID = IDFactory.newPeerID(PeerGroupID.defaultNetPeerGroupID, Name.getBytes()); public static final File ConfigurationFile = new File("." + System.getProperty("file.separator") + Name); public static final String MyPrincipalName = "Principal - " + Name; public static final String MyPrivateKeyPassword = "PrivateKey Password - " + Name; public static final String MyKeyStoreFileName = "MyKeyStoreFile"; public static final String MyKeyStoreLocation = "." + System.getProperty("file.separator") + Name + File.separator + "MyKeyStoreLocation"; public static final String MyKeyStorePassword = "KeyStore Password - " + Name; public static final String MyKeyStoreProvider = "KeyStore Provider - " + Name; public static final File MyKeyStoreDirectory = new File(MyKeyStoreLocation); public static final File MyKeyStoreFile = new File(MyKeyStoreLocation + File.separator + MyKeyStoreFileName); public static final X509Certificate TheX509Certificate; public static final PrivateKey ThePrivateKey; public static final String PsePeerGroupName = "PSE peer group name"; public static final PeerGroupID PsePeerGroupID = IDFactory.newPeerGroupID(PeerGroupID.defaultNetPeerGroupID, PsePeerGroupName.getBytes()); static { // Static initialization of certificates PSEUtils.IssuerInfo ForPSE = PSEUtils.genCert(Name, null);

Using JXSE Private Keys, Certificates & KeyStores - 207

TheX509Certificate = ForPSE.cert; ThePrivateKey = ForPSE.issuerPkey; } public static void main(String[] args) { try { // Removing any existing configuration? Tools.CheckForExistingConfigurationDeletion(Name, ConfigurationFile); // Preparing data MyKeyStoreDirectory.mkdirs(); // Creating the key store FileKeyStoreManager MyFileKeyStoreManager = new FileKeyStoreManager( (String)null, MyKeyStoreProvider, MyKeyStoreFile); MyFileKeyStoreManager.createKeyStore(MyKeyStorePassword.toCharArray()); if (!MyFileKeyStoreManager.isInitialized()) { Tools.PopInformationMessage(Name, "Keystore is NOT initialized"); } else { Tools.PopInformationMessage(Name, "Keystore is initialized"); } // Loading the (empty) keystore KeyStore MyKeyStore = MyFileKeyStoreManager.loadKeyStore(MyKeyStorePassword.toCharArray()); // Setting data X509Certificate[] Temp = { TheX509Certificate }; MyKeyStore.setKeyEntry(PID.toString(), ThePrivateKey, MyPrivateKeyPassword.toCharArray(), Temp); // Saving the data MyFileKeyStoreManager.saveKeyStore(MyKeyStore, MyKeyStorePassword.toCharArray()); // Reloading the KeyStore MyKeyStore = MyFileKeyStoreManager.loadKeyStore(MyKeyStorePassword.toCharArray()); // Retrieving Certificate X509Certificate MyCertificate = (X509Certificate) MyKeyStore.getCertificate(PID.toString()); if (MyCertificate==null) { Tools.PopInformationMessage(Name, "X509 Certificate CANNOT be retrieved"); } else { Tools.PopInformationMessage(Name, "X509 Certificate can be retrieved"); System.out.println(MyCertificate.toString()); } // Retrieving private key PrivateKey MyPrivateKey = (PrivateKey) MyKeyStore.getKey(PID.toString(), MyPrivateKeyPassword.toCharArray()); if (MyPrivateKey==null) { Tools.PopInformationMessage(Name, "Private key CANNOT be retrieved"); } else { Tools.PopInformationMessage(Name, "Private key can be retrieved"); System.out.println(MyPrivateKey.toString()); } // Creation of the network manager NetworkManager MyNetworkManager = new NetworkManager(NetworkManager.ConfigMode.EDGE, Name, ConfigurationFile.toURI()); // Retrieving the network configurator NetworkConfigurator MyNetworkConfigurator = MyNetworkManager.getConfigurator(); // Setting the keystore MyNetworkConfigurator.setKeyStoreLocation(MyKeyStoreFile.toURI()); MyNetworkConfigurator.setPassword(MyKeyStorePassword);

Using JXSE Private Keys, Certificates & KeyStores - 208

// Starting the network PeerGroup MyNetPeerGroup = MyNetworkManager.startNetwork(); // Checking membership implementation MembershipService NPGMembership = MyNetPeerGroup.getMembershipService(); Tools.PopInformationMessage(Name, "NetPeerGroup membership implementation:\n" + NPGMembership.getClass().getSimpleName()); // Creating a child group with PSE PeerGroup ChildPeerGroup = MyNetPeerGroup.newGroup( PsePeerGroupID, createAllPurposePeerGroupWithPSEModuleImplAdv(), PsePeerGroupName, "Checking PSE..." ); if (Module.START_OK != ChildPeerGroup.startApp(new String[0])) System.err.println("Cannot start PSE peergroup"); // Checking membership implementation MembershipService ChildGroupMembership = ChildPeerGroup.getMembershipService(); Tools.PopInformationMessage(Name, "Child group membership implementation:\n" + ChildGroupMembership.getClass().getSimpleName()); // Joining the peer group AuthenticationCredential MyAuthenticationCredit = new AuthenticationCredential( MyNetPeerGroup, "StringAuthentication", null ); StringAuthenticator MyStringAuthenticator = (StringAuthenticator) ChildGroupMembership.apply(MyAuthenticationCredit); MyStringAuthenticator.setAuth1_KeyStorePassword(MyKeyStorePassword); MyStringAuthenticator.setAuth2Identity(PID); MyStringAuthenticator.setAuth3_IdentityPassword(MyPrivateKeyPassword); Credential MyCredential = null; if (MyStringAuthenticator.isReadyForJoin()) { MyCredential = ChildGroupMembership.join(MyStringAuthenticator); } if (MyCredential!=null) { Tools.PopInformationMessage(Name, "Credentials created successfully"); } else { Tools.PopInformationMessage(Name, "Credentials NOT created successfully"); } // Stopping the network Tools.PopInformationMessage(Name, "Stop the JXTA network"); MyNetworkManager.stopNetwork(); } catch (PeerGroupException Ex) { Tools.PopErrorMessage(Name, Ex.toString()); } catch (NoSuchAlgorithmException Ex) { Tools.PopErrorMessage(Name, Ex.toString()); } catch (UnrecoverableKeyException Ex) { Tools.PopErrorMessage(Name, Ex.toString()); } catch (NoSuchProviderException Ex) { Tools.PopErrorMessage(Name, Ex.toString()); } catch (KeyStoreException Ex) { Tools.PopErrorMessage(Name, Ex.toString()); } catch (IOException Ex) {

Using JXSE Private Keys, Certificates & KeyStores - 209

Tools.PopErrorMessage(Name, Ex.toString()); } catch (ProtocolNotSupportedException Ex) { Tools.PopErrorMessage(Name, Ex.toString()); } } public static ModuleImplAdvertisement createAllPurposePeerGroupWithPSEModuleImplAdv() { ModuleImplAdvertisement implAdv = CompatibilityUtils.createModuleImplAdvertisement( PeerGroup.allPurposePeerGroupSpecID, StdPeerGroup.class.getName(), "General Purpose Peer Group with PSE Implementation"); // Create the service list for the group. StdPeerGroupParamAdv paramAdv = new StdPeerGroupParamAdv(); // set the services paramAdv.addService(PeerGroup.endpointClassID, PeerGroup.refEndpointSpecID); paramAdv.addService(PeerGroup.resolverClassID, PeerGroup.refResolverSpecID); paramAdv.addService(PeerGroup.membershipClassID, PSEMembershipService.pseMembershipSpecID); paramAdv.addService(PeerGroup.accessClassID, PSEAccessService.PSE_ACCESS_SPEC_ID); // standard services paramAdv.addService(PeerGroup.discoveryClassID, PeerGroup.refDiscoverySpecID); paramAdv.addService(PeerGroup.rendezvousClassID, PeerGroup.refRendezvousSpecID); paramAdv.addService(PeerGroup.pipeClassID, PeerGroup.refPipeSpecID); paramAdv.addService(PeerGroup.peerinfoClassID, PeerGroup.refPeerinfoSpecID); paramAdv.addService(PeerGroup.contentClassID, ContentServiceImpl.MODULE_SPEC_ID); // Insert the newParamAdv in implAdv XMLElement paramElement = (XMLElement) paramAdv.getDocument(MimeMediaType.XMLUTF8); implAdv.setParam(paramElement); return implAdv; } }

Example 620 – Custom PSE Peer Group & Joining

This example is performing the following: 1. Just like in the previous example, we create a keystore and load it with a X509 certificate and a private key. 2. Then, we create a custom PSE peer group using the same method as for a non-PSE peer group. Notice that the module implementation advertisement references the PSE membership ID and the PSE access service. 3. Next, we run the process to join the PSE peergroup. Warning: the PSE access service implementation is still in experimental mode.

Simple Pipe Communication
Pipes and the Pipe Service are some of the most important features of JXTA and JXSE. They are

Using JXSE Simple Pipe Communication - 210

the natural means for peers to exchange end user messages. However, most developers will rarely (if ever) use these simple pipes in their software application. They will use other tools provided by JXSE: bidirectional pipes and JXTA sockets. The code example presented in this section is a 2-in-1 example. With a single pair of peers, we will show how to run the 2 types of JXTA pipes: UnicastType and PropagateType.

Chandra, The Rendezvous Listening to Messages
The following is the code used for Chandra, a rendezvous peer that will listen to messages coming from a pipe:
... public class RendezVous_Chandra_Receiving_Messages implements PipeMsgListener { // PipeService.UnicastType or PipeService.UnicastSecureType or PipeService.PropagateType public static final String PipeType = PipeService.UnicastType; // Static attributes public static final String Name = "RendezVous Chandra, Receiving Messages"; public static final int TcpPort = 9722; public static final PeerID PID = IDFactory.newPeerID(PeerGroupID.defaultNetPeerGroupID, Name.getBytes()); public static final File ConfigurationFile = new File("." + System.getProperty("file.separator") + Name); // Catching messages public void pipeMsgEvent(PipeMsgEvent PME) { // We received a message Message ReceivedMessage = PME.getMessage(); String TheText = ReceivedMessage.getMessageElement("DummyNameSpace", "HelloElement").toString(); // Notifying the user Tools.PopInformationMessage(Name, "Received message:\n\n" + TheText); } public static PipeAdvertisement GetPipeAdvertisement() { // Creating a Pipe Advertisement PipeAdvertisement MyPipeAdvertisement = (PipeAdvertisement) AdvertisementFactory.newAdvertisement(PipeAdvertisement.getAdvertisementType()); PipeID MyPipeID = IDFactory.newPipeID(PeerGroupID.defaultNetPeerGroupID, Name.getBytes()); MyPipeAdvertisement.setPipeID(MyPipeID); MyPipeAdvertisement.setType(PipeType); MyPipeAdvertisement.setName("Test Pipe"); MyPipeAdvertisement.setDescription("Created by " + Name); return MyPipeAdvertisement; } public static void main(String[] args) { try { // Removing any existing configuration? Tools.CheckForExistingConfigurationDeletion(Name, ConfigurationFile); // Creation of network manager NetworkManager MyNetworkManager = new NetworkManager(

Using JXSE Simple Pipe Communication - 211

NetworkManager.ConfigMode.RENDEZVOUS, Name, ConfigurationFile.toURI()); // Retrieving the network configurator NetworkConfigurator MyNetworkConfigurator = MyNetworkManager.getConfigurator(); // Setting more configuration MyNetworkConfigurator.setTcpPort(TcpPort); MyNetworkConfigurator.setTcpEnabled(true); MyNetworkConfigurator.setTcpIncoming(true); MyNetworkConfigurator.setTcpOutgoing(true); // Setting the Peer ID Tools.PopInformationMessage(Name, "Setting the peer ID to :\n\n" + PID.toString()); MyNetworkConfigurator.setPeerID(PID); // Saving the configuration MyNetworkConfigurator.save(); // Starting the JXTA network Tools.PopInformationMessage(Name, "Start the JXTA network"); PeerGroup NetPeerGroup = MyNetworkManager.startNetwork(); // Retrieving the PSE membership service MembershipService MyMembershipService = NetPeerGroup.getMembershipService(); // Waiting for other peers to connect to JXTA Tools.PopInformationMessage(Name, "Waiting for other peers to connect to JXTA"); // Creating an input pipe PipeService MyPipeService = NetPeerGroup.getPipeService(); MyPipeService.createInputPipe(GetPipeAdvertisement(), new RendezVous_Chandra_Receiving_Messages()); // Displaying pipe advertisement to identify potential compilation issues System.out.println( RendezVous_Chandra_Receiving_Messages.GetPipeAdvertisement().toString()); // Going to sleep for some time Tools.GoToSleep(60000); // Retrieving connected peers Tools.popConnectedPeers(NetPeerGroup.getRendezVousService(), Name); // Resigning all credentials MyMembershipService.resign(); // Stopping the network Tools.PopInformationMessage(Name, "Stop the JXTA network"); MyNetworkManager.stopNetwork(); } catch (IOException Ex) { Tools.PopErrorMessage(Name, Ex.toString()); } catch (PeerGroupException Ex) { Tools.PopErrorMessage(Name, Ex.toString()); } } }

Chandra, the Rendezvous Listening to Messages

Chandra implements the PipeMsgListener interface which requires implementing the pipeMsgEvent(...) method. This method is necessary to handle messages received by a peer from a pipe. For the sake of our example, it also implements a GetPipeAdvertisement(...) method

Using JXSE Simple Pipe Communication - 212

to retrieve the pipe advertisement that will be used by our peers who will communicate over a pipe. Chandra is performing the following operations: 1. We provide the user with an opportunity to erase any existing configuration. 2. Before we start the JXTA network, we set several configuration parameters in the NetworkConfigurator. 3. We start Chandra as a rendezvous. 4. We wait for other peers to connect. 5. Once the user clicks OK on the displayed box, we create the input pipe and provide a listener that will be called each time a messaged is received. This listener will display the received message to the user. 6. We also print the pipe advertisement (the reason for this will be described further). 7. We sleep for 60 seconds. This will give the other peer enough time to send its message. 8. We display connected peers. 9. We stop the JXTA network.

Dimitri, The Edge Sending Messages
The following is the code used for Dimitri, an edge peer that sends a message to Chandra via a pipe:
... public class Edge_Dimitri_Sending_Messages implements OutputPipeListener { public static final String Name = "Edge Dimitri, Sending Messages"; public static final int TcpPort = 9723; public static final PeerID PID = IDFactory.newPeerID(PeerGroupID.defaultNetPeerGroupID, Name.getBytes()); public static final File ConfigurationFile = new File("." + System.getProperty("file.separator") + Name); // Catching connections to the pipe public void outputPipeEvent(OutputPipeEvent OPE) { try { // Notifying the user Tools.PopInformationMessage(Name, "Someone connected to the pipe, sending hello message!"); // Retrieving the output pipe to the peer who connected to the input end OutputPipe MyOutputPipe = OPE.getOutputPipe(); // Creating a Hello message !!! Message MyMessage = new Message();

Using JXSE Simple Pipe Communication - 213

StringMessageElement MyStringMessageElement = new StringMessageElement("HelloElement", "Hello from " + Name, null); MyMessage.addMessageElement("DummyNameSpace", MyStringMessageElement); // Sending the message MyOutputPipe.send(MyMessage); } catch (IOException Ex) { Tools.PopErrorMessage(Name, Ex.toString()); } } public static void main(String[] args) { try { // Removing any existing configuration? Tools.CheckForExistingConfigurationDeletion(Name, ConfigurationFile); // Creation of network manager NetworkManager MyNetworkManager = new NetworkManager(NetworkManager.ConfigMode.EDGE, Name, ConfigurationFile.toURI()); // Retrieving the network configurator NetworkConfigurator MyNetworkConfigurator = MyNetworkManager.getConfigurator(); // Checking if RendezVous_Jack should be a seed MyNetworkConfigurator.clearRendezvousSeeds(); String TheSeed = "tcp://" + InetAddress.getLocalHost().getHostAddress() + ":" + RendezVous_Chandra_Receiving_Messages.TcpPort; Tools.CheckForRendezVousSeedAddition(Name, TheSeed, MyNetworkConfigurator); // Setting Configuration MyNetworkConfigurator.setTcpPort(TcpPort); MyNetworkConfigurator.setTcpEnabled(true); MyNetworkConfigurator.setTcpIncoming(true); MyNetworkConfigurator.setTcpOutgoing(true); // Setting the Peer ID Tools.PopInformationMessage(Name, "Setting the peer ID to :\n\n" + PID.toString()); MyNetworkConfigurator.setPeerID(PID); // Saving the configuration MyNetworkConfigurator.save(); // Starting the JXTA network Tools.PopInformationMessage(Name, "Start the JXTA network and to wait for a rendezvous connection with\n" + RendezVous_Chandra_Receiving_Messages.Name + " for maximum 2 minutes"); PeerGroup NetPeerGroup = MyNetworkManager.startNetwork(); // Disabling any rendezvous autostart NetPeerGroup.getRendezVousService().setAutoStart(false); if (MyNetworkManager.waitForRendezvousConnection(120000)) { Tools.popConnectedRendezvous(NetPeerGroup.getRendezVousService(),Name); } else { Tools.PopInformationMessage(Name, "Did not connect to a rendezvous"); } // Creating an ouput pipe PipeService MyPipeService = NetPeerGroup.getPipeService(); MyPipeService.createOutputPipe( RendezVous_Chandra_Receiving_Messages.GetPipeAdvertisement(), new Edge_Dimitri_Sending_Messages()); // Displaying pipe advertisement to identify potential compilation issues System.out.println( RendezVous_Chandra_Receiving_Messages.GetPipeAdvertisement().toString()); // Going to sleep for some time Tools.GoToSleep(60000);

Using JXSE Simple Pipe Communication - 214

// Stopping the network Tools.PopInformationMessage(Name, "Stop the JXTA network"); MyNetworkManager.stopNetwork(); } catch (IOException Ex) { // Raised when access to local file and directories caused an error Tools.PopErrorMessage(Name, Ex.toString()); } catch (PeerGroupException Ex) { // Raised when the net peer group could not be created Tools.PopErrorMessage(Name, Ex.toString()); } } }

Dimitri, the Edge Sending Messages

Dimitri implements the OutputPipeListener interface which requires implementing the outputPipeEvent(...) method. This method is invoked each time an input pipe has been located. This peer can then invoke the corresponding output pipe and send a message through it. Dimitri is performing the following operations: 1. We provide the user with an opportunity to erase any existing configuration. 2. Before we start the JXTA network, we set several configuration parameters in the NetworkConfigurator. This includes setting Chandra as a rendezvous seed. 3. We start Dimitri as an edge and wait until it connects to Chandra. We display a message notifying the connection to the rendezvous (or not). 4. We create the output pipe and provide a listener that will be called each time an input pipe for the given pipe advertisement is detected. This listener will then send a simple hello message via the corresponding output pipe. 5. We also print the pipe advertisement (the reason for this will be described further). 6. We sleep for 60 seconds. 7. We stop the JXTA network.

Running The Example
In order to establish a successful communication between Chandra and Dimitri, the following procedure must be followed precisely. Failing to do so will result in wrong results or unexpected behavior.

Using JXSE Simple Pipe Communication - 215

1. To chose the type of pipe (PipeService.UnicastType or PipeService.PropagateType) that will be used between Chandra and Dimitri, modify the value of the PipeType static attribute in the code of Chandra. 2. Recompile both Chandra and Dimitri. If you fail to do so, the example will not work. Both peers print the pipe advertisement they are using. If you have modified the PipeType and failed to recompile both peers, you will notice a difference in the pipe type used by both peers. This can explain why the example is not working. 3. Start Chandra and wait until it starts waiting for others peer to connect (delete any existing configuration). 4. Start Dimitri and wait until it displays the ID of the rendezvous peer it has managed to connect to (erase any existing configuration and allow Chandra to be a rendezvous seed). 5. Go back to Chandra and click OK on the box indicating that she is waiting for other peers to connect. 6. Go back to Dimitri and click OK on the box displaying the ID of the rendezvous peer it has connected to. 7. Click OK on boxes which will be displayed by Dimitri until he indicates that someone has connected to the pipe. Click OK to have him send a message. Sometimes, this message can appear twice. 8. Pretty quickly too, Chandra gets the message from Dimitri and displays it. 9. Click OK boxes until both Chandra and Dimitri stop their connection to the JXTA network. This example describes how simple pipes can be used to communicate between peers. A rendezvous connection between both peers is necessary to make sure both peers obtain routes to each other. For the sake of clarity and simplicity, we did not have one of the peer fetch the pipe advertisement from the other peer, which is an artificial situation. In reality, that would be necessary in order to establish a pipe connection. Metaphorically: Chandra and Dimitri are the leaders of two tribes that have decided to establish trading routes between them. They have given a distinctive sign/name to their trading route. This means that if one of them, or both, decide to move from one island to the other, the trading route remains and they will still be able to use it to exchange goods. One type of trading route they have decided to create includes a secret code system that prevents

Using JXSE Simple Pipe Communication - 216

any pirates from understanding the dried leaf messages they may try to steal from each other.

Unicast Secure Pipes
To operate unicast secure pipes, one should create a PSE group and join it. Then, a modified version of Chandra and Dimitri can be implemented with PipeService.UnicastSecure pipes. All operations should be performed from the PSE group.

Bidirectional Pipe Communication
The example we have shown above enables a one way communication between two peers. In practice, bidirectional communication is often necessary between many peers. One could implement two simple pipes between each peer to achieve this purpose, but JXSE offers bidirectional pipes .
59

Adelaide, The RendezVous At One End
The following is the code used for Adelaide, a rendezvous peer at one end of the bidirectional pipe:
... public class RendezVous_Adelaide_At_One_End implements PipeMsgListener { // Static attributes public static final String Name = "RendezVous Adelaide, at one end"; public static final int TcpPort = 9726; public static final PeerID PID = IDFactory.newPeerID(PeerGroupID.defaultNetPeerGroupID, Name.getBytes()); public static final File ConfigurationFile = new File("." + System.getProperty("file.separator") + Name); public void pipeMsgEvent(PipeMsgEvent PME) { // We received a message Message ReceivedMessage = PME.getMessage(); String TheText = ReceivedMessage.getMessageElement("DummyNameSpace", "HelloElement").toString(); // Notifying the user Tools.PopInformationMessage(Name, "Received message:\n\n" + TheText); } public static PipeAdvertisement GetPipeAdvertisement() { // Creating a Pipe Advertisement PipeAdvertisement MyPipeAdvertisement = (PipeAdvertisement) AdvertisementFactory.newAdvertisement(PipeAdvertisement.getAdvertisementType()); PipeID MyPipeID = IDFactory.newPipeID(PeerGroupID.defaultNetPeerGroupID, Name.getBytes()); MyPipeAdvertisement.setPipeID(MyPipeID); MyPipeAdvertisement.setType(PipeService.UnicastType); MyPipeAdvertisement.setName("Test BidiPipe"); MyPipeAdvertisement.setDescription("Created by " + Name);

59

There is a lurking bug in JXTA release 2.5 regarding connectivity behind NATs.

Using JXSE Bidirectional Pipe Communication - 217

return MyPipeAdvertisement; } public static void main(String[] args) { try { // Removing any existing configuration? Tools.CheckForExistingConfigurationDeletion(Name, ConfigurationFile); // Creation of the network manager NetworkManager MyNetworkManager = new NetworkManager( NetworkManager.ConfigMode.RENDEZVOUS, Name, ConfigurationFile.toURI()); // Retrieving the network configurator NetworkConfigurator MyNetworkConfigurator = MyNetworkManager.getConfigurator(); // Setting more configuration MyNetworkConfigurator.setTcpPort(TcpPort); MyNetworkConfigurator.setTcpEnabled(true); MyNetworkConfigurator.setTcpIncoming(true); MyNetworkConfigurator.setTcpOutgoing(true); // Setting the Peer ID Tools.PopInformationMessage(Name, "Setting the peer ID to :\n\n" + PID.toString()); MyNetworkConfigurator.setPeerID(PID); // Starting the JXTA network Tools.PopInformationMessage(Name, "Start the JXTA network"); PeerGroup NetPeerGroup = MyNetworkManager.startNetwork(); // Waiting for other peers to connect to JXTA Tools.PopInformationMessage(Name, "Waiting for other peers to connect to JXTA"); // Preparing the listener and creating the BiDiPipe PipeMsgListener MyListener = new RendezVous_Adelaide_At_One_End(); JxtaServerPipe MyBiDiPipeServer = new JxtaServerPipe(NetPeerGroup, GetPipeAdvertisement()); Tools.PopInformationMessage(Name, "Bidirectional pipe server created!"); MyBiDiPipeServer.setPipeTimeout(30000); JxtaBiDiPipe MyBiDiPipe = MyBiDiPipeServer.accept(); if (MyBidiPipe != null) { MyBiDiPipe.setMessageListener(MyListener); Tools.PopInformationMessage(Name, "Bidirectional pipe connection established!"); // Sending a hello message !!! Message MyMessage = new Message(); StringMessageElement MyStringMessageElement = new StringMessageElement( "HelloElement", “Hello from " + Name, null); MyMessage.addMessageElement("DummyNameSpace", MyStringMessageElement); MyBiDiPipe.sendMessage(MyMessage); // Sleeping for 10 seconds Tools.GoToSleep(10000); // Sending a goodbye message !!! MyMessage = new Message(); MyStringMessageElement = new StringMessageElement("HelloElement", "Goodbye from " + Name, null); MyMessage.addMessageElement("DummyNameSpace", MyStringMessageElement); MyBiDiPipe.sendMessage(MyMessage); // Sleeping for 10 seconds Tools.GoToSleep(10000); // Closing the bidi pipe MyBiDiPipe.close();

Using JXSE Bidirectional Pipe Communication - 218

} // Closing the bidi pipe server MyBiDiPipe.close(); // Retrieving connected peers Tools.popConnectedPeers(NetPeerGroup.getRendezVousService(), Name); // Stopping the network Tools.PopInformationMessage(Name, "Stop the JXTA network"); MyNetworkManager.stopNetwork(); } catch (IOException Ex) { Tools.PopErrorMessage(Name, Ex.toString()); } catch (PeerGroupException Ex) { Tools.PopErrorMessage(Name, Ex.toString()); } } }

Adelaide, The Rendezvous At One End

Adelaide is performing the following: 1. Adelaide implements the PipeMsgListener interface. This requires implementing the pipeMsgEvent method to handle messages which will be received via the bidirectional pipe. 2. For the sake of simplicity, Adelaide also implements a static method to retrieve the pipe advertisement to be used by both peers to establish the bidirectional pipe. 3. We set some context information via static attributes as usual. 4. We provide the user with an opportunity to erase any existing configuration. Usual NetworkConfigurator parameters are set. 5. We start Adelaide as a rendezvous and wait until other peers connect to it. 6. We create a bidirectional pipe server which will be able to accept the request for bidirectional connections from other peers. We notify the user. 7. We wait for a maximum of 30 seconds for a bidirectional connection request from other peers. 8. If such a connection is established, we register a listener to collect messages sent by the other party. a) We notify the user that a bidirectional connection has been established.

Using JXSE Bidirectional Pipe Communication - 219

b) We send a hello message to the other party and sleep for 10 seconds. c) We send a goodbye message to the other party and sleep for 10 seconds. d) We close the bidirectional pipe. 9. We stop the bidirectional pipe server. 10. We stop the JXTA network after displaying the list of connected peers.

Quinisela, The Edge At The Other End
The following is the code used for Quinisela, an edge peer at the other end of the bidirectional pipe:
... public class Edge_Quinisela_At_The_Other_End implements PipeMsgListener { public static final String Name = "Edge Quinisela, at the other end"; public static final int TcpPort = 9725; public static final PeerID PID = IDFactory.newPeerID(PeerGroupID.defaultNetPeerGroupID, Name.getBytes()); public static final File ConfigurationFile = new File("." + System.getProperty("file.separator") + Name); public void pipeMsgEvent(PipeMsgEvent PME) { // We received a message Message ReceivedMessage = PME.getMessage(); String TheText = ReceivedMessage.getMessageElement("DummyNameSpace", "HelloElement").toString(); // Notifying the user Tools.PopInformationMessage(Name, "Received message:\n\n" + TheText); } public static void main(String[] args) { try { // Removing any existing configuration? Tools.CheckForExistingConfigurationDeletion(Name, ConfigurationFile); // Creation of network manager NetworkManager MyNetworkManager = new NetworkManager(NetworkManager.ConfigMode.EDGE, Name, ConfigurationFile.toURI()); // Retrieving the network configurator NetworkConfigurator MyNetworkConfigurator = MyNetworkManager.getConfigurator(); // Checking if RendezVous_Adelaide_At_One_End should be a seed MyNetworkConfigurator.clearRendezvousSeeds(); String TheSeed = "tcp://" + InetAddress.getLocalHost().getHostAddress() + ":" + RendezVous_Adelaide_At_One_End.TcpPort; Tools.CheckForRendezVousSeedAddition(Name, TheSeed, MyNetworkConfigurator); // Setting Configuration MyNetworkConfigurator.setTcpPort(TcpPort); MyNetworkConfigurator.setTcpEnabled(true); MyNetworkConfigurator.setTcpIncoming(true); MyNetworkConfigurator.setTcpOutgoing(true); // Setting the Peer ID Tools.PopInformationMessage(Name, "Setting the peer ID to :\n\n" + PID.toString());

Using JXSE Bidirectional Pipe Communication - 220

MyNetworkConfigurator.setPeerID(PID); // Starting the JXTA network Tools.PopInformationMessage(Name, "Start the JXTA network and to wait for a rendezvous connection with\n" + RendezVous_Adelaide_At_One_End.Name + " for maximum 2 minutes"); PeerGroup NetPeerGroup = MyNetworkManager.startNetwork(); // Disabling any rendezvous autostart NetPeerGroup.getRendezVousService().setAutoStart(false); if (MyNetworkManager.waitForRendezvousConnection(120000)) { Tools.popConnectedRendezvous(NetPeerGroup.getRendezVousService(),Name); } else { Tools.PopInformationMessage(Name, "Did not connect to a rendezvous"); } // Preparing the listener and Creating the BiDiPipe PipeMsgListener MyListener = new Edge_Quinisela_At_The_Other_End(); JxtaBiDiPipe MyBiDiPipe = new JxtaBiDiPipe(NetPeerGroup, RendezVous_Adelaide_At_One_End.GetPipeAdvertisement(), 30000, MyListener); Tools.PopInformationMessage(Name, "Bidirectional pipe created!"); // Sending a hello message !!! Message MyMessage = new Message(); StringMessageElement MyStringMessageElement = new StringMessageElement("HelloElement", "Hello from " + Name, null); MyMessage.addMessageElement("DummyNameSpace", MyStringMessageElement); MyBiDiPipe.sendMessage(MyMessage); // Sleeping for 10 seconds Tools.GoToSleep(10000); // Sending a goodbye message !!! MyMessage = new Message(); MyStringMessageElement = new StringMessageElement("HelloElement", "Goodbye from " + Name, null); MyMessage.addMessageElement("DummyNameSpace", MyStringMessageElement); MyBiDiPipe.sendMessage(MyMessage); // Sleeping for 10 seconds Tools.GoToSleep(10000); // Stopping the network Tools.PopInformationMessage(Name, "Stop the JXTA network"); MyNetworkManager.stopNetwork(); } catch (IOException Ex) { // Raised when access to local file and directories caused an error Tools.PopErrorMessage(Name, Ex.toString()); } catch (PeerGroupException Ex) { // Raised when the net peer group could not be created Tools.PopErrorMessage(Name, Ex.toString()); } } }

Quinisela, the Edge at the Other End

Quinisela is performing the following: 1. Quinisela implements the PipeMsgListener interface. This requires implementing the

Using JXSE Bidirectional Pipe Communication - 221

pipeMsgEvent method to handle messages which will be received via the bidirectional pipe. 2. We set some context information via static attributes as usual. 3. We provide the user with an opportunity to erase any existing configuration and to set Adelaide as a rendezvous. Usual NetworkConfigurator parameters are set. 4. We start Quinisela as an edge and wait until it connects to a rendezvous for maximum 2 minutes. 5. We create a bidirectional pipe and wait for maximum 30 seconds for a connection with another peer. 6. If such a connection is established: a) We notify the user that a bidirectional connection has been established. b) We send a hello message to the other party and sleep for 10 seconds. c) We send a goodbye message to the other party and sleep for 10 seconds. 7. We close the bidirectional pipe. 8. We stop the JXTA network.

Running The Example
In order to establish a successful communication between Adelaide and Quinisela, the following procedure must be performed: 1. Start Adelaide the rendezvous until it waits for connections from other peers (delete any existing configuration). 2. Start Quinisela until it manages to connect to Adelaide (delete any existing configuration and allow Adelaide as a rendezvous seed). 3. Go back to Adelaide and click OK on the box mentioning she is waiting for peers to connect. 4. Go back to Quinisela and click OK on his box. 5. Click OK on the next boxes showed by Adelaide and Quinisela (i.e., confirmations that they have managed to establish a bidirectional connection). 6. Click on OK on both sides to see the messages sent by each to the other... Using JXSE Bidirectional Pipe Communication - 222

7. ...until both stop the JXTA network. For the sake of simplicity, we did not have one of the peers fetch the advertisement from the other, although in reality, most software applications would do so. Typically, every peer should run its own bidirectional pipe server to allow other peers to establish bidirectional communications. A very interesting feature of bidirectional pipes is the getRemotePeerAdvertisement(...) method which allows one peer to know about the peer on the other side. This was not possible with simple pipes. Another interesting method is the connect(...) method which can be used to try to establish a connection with a specific peer. The last feature which makes bidirectional pipes very interesting is that unlike unicast pipes, they are reliable, assuming that sent messages do not exceed 64K in size when received by the other party (do not forget the Matryoshka approach of messages in JXTA when they pass from one protocol to the other).

JXTA Socket & Socket Server
JXTA sockets are like Java sockets. They allow peers to exchange streams of bytes and datagram packets. The JXTA socket and JXTA Socket Server operate similarly to bidirectional pipes.

Lidong, The Rendezvous And JXTA Socket Server
The following is the code used for Lidong, a rendezvous peer acting as a JXTA socket server:
... public class RendezVous_Lidong_The_JXTA_Socket_Server { // Static attributes public static final String Name = "RendezVous Lidong, the JXTA socket server"; public static final int TcpPort = 9731; public static final PeerID PID = IDFactory.newPeerID(PeerGroupID.defaultNetPeerGroupID, Name.getBytes()); public static final File ConfigurationFile = new File("." + System.getProperty("file.separator") + Name); public static PipeAdvertisement GetPipeAdvertisement() { // Creating a Pipe Advertisement PipeAdvertisement MyPipeAdvertisement = (PipeAdvertisement) AdvertisementFactory.newAdvertisement(PipeAdvertisement.getAdvertisementType()); PipeID MyPipeID = IDFactory.newPipeID(PeerGroupID.defaultNetPeerGroupID, Name.getBytes()); MyPipeAdvertisement.setPipeID(MyPipeID); MyPipeAdvertisement.setType(PipeService.UnicastType); MyPipeAdvertisement.setName("Test Socket"); MyPipeAdvertisement.setDescription("Created by " + Name); return MyPipeAdvertisement; } public static void main(String[] args) {

Using JXSE JXTA Socket & Socket Server - 223

try { // Removing any existing configuration? Tools.CheckForExistingConfigurationDeletion(Name, ConfigurationFile); // Creation of network manager NetworkManager MyNetworkManager = new NetworkManager( NetworkManager.ConfigMode.RENDEZVOUS, Name, ConfigurationFile.toURI()); // Retrieving the network configurator NetworkConfigurator MyNetworkConfigurator = MyNetworkManager.getConfigurator(); // Setting more configuration MyNetworkConfigurator.setTcpPort(TcpPort); MyNetworkConfigurator.setTcpEnabled(true); MyNetworkConfigurator.setTcpIncoming(true); MyNetworkConfigurator.setTcpOutgoing(true); // Setting the Peer ID Tools.PopInformationMessage(Name, "Setting the peer ID to :\n\n" + PID.toString()); MyNetworkConfigurator.setPeerID(PID); // Starting the JXTA network Tools.PopInformationMessage(Name, "Start the JXTA network"); PeerGroup NetPeerGroup = MyNetworkManager.startNetwork(); // Waiting for other peers to connect to JXTA Tools.PopInformationMessage(Name, "Waiting for other peers to connect to JXTA"); // Creating the JXTA socket server int BackLog = 20; int Timeout = 30000; JxtaServerSocket MyJXTAServerSocket = new JxtaServerSocket(NetPeerGroup, GetPipeAdvertisement(), BackLog, Timeout); Tools.PopInformationMessage(Name, "JXTA socket server created"); Socket MySocket = MyJXTAServerSocket.accept(); if (MySocket != null) { Tools.PopInformationMessage(Name, "Socket connection established"); // Retrieving the input streams InputStream MyInputStream = MySocket.getInputStream(); DataInput MyDataInput = new DataInputStream(MyInputStream); String IncomingMessage = MyDataInput.readUTF(); Tools.PopInformationMessage(Name, "Received socket message:\n\n" + IncomingMessage); // Retrieving the output stream OutputStream MyOutputStream = MySocket.getOutputStream(); DataOutput MyDataOutput = new DataOutputStream(MyOutputStream); // Sending a message MyDataOutput.writeUTF("Hello from " + Name); MyOutputStream.flush(); // Sleeping for 10 seconds Tools.GoToSleep(10000); // Closing the streams MyOutputStream.close(); MyInputStream.close(); // Closing the socket MySocket.close(); } // Closing the JXTA socket server MyJXTAServerSocket.close();

Using JXSE JXTA Socket & Socket Server - 224

// Retrieving connected peers Tools.popConnectedPeers(NetPeerGroup.getRendezVousService(), Name); // Stopping the network Tools.PopInformationMessage(Name, "Stop the JXTA network"); MyNetworkManager.stopNetwork(); } catch (IOException Ex) { Tools.PopErrorMessage(Name, Ex.toString()); } catch (PeerGroupException Ex) { Tools.PopErrorMessage(Name, Ex.toString()); } } }

Lidong, The Rendezvous and JXTA Socket Server

Lidong is performing the following: 1. For the sake of simplicity, Lidong implements a static method to retrieve the pipe advertisement that will be used by both peers to establish the socket connection. 2. We set some context information via static attributes as usual. 3. We provide the user with an opportunity to erase any existing configuration. Usual NetworkConfigurator parameters are set. 4. We start Lidong as a rendezvous and wait until other peers connect to it. 5. We create a JXTA socket server and set the maximum delay for a connection to 30 seconds. We notify the user. 6. We wait for a socket connection from other peers. 7. If such a connection is established, we notify the user. a) We try to read a message from the JXTA socket and display it to the user when we get it. b) We send a Hello message to the other party and flush the OutputStream. This is necessary, otherwise JXTA may wait for more calls for information to be sent before actually sending the message to other peers. If we did not invoke the flush() method, the other party would most probably lock when trying to read data from the JXTA socket. c) We close the streams and the sockets.

Using JXSE JXTA Socket & Socket Server - 225

8. We close the JXTA socket server. 9. We stop the JXTA network after displaying the list of connected peers.

Ayrton, The Edge And JXTA Socket
The following is the code used for Ayrton, an edge peer creating a JXTA socket and connecting to the JXTA Socket server:
... public class Edge_Ayrton_The_JXTA_Socket { public static final String Name = "Edge Ayrton, the JXTA socket"; public static final int TcpPort = 9730; public static final PeerID PID = IDFactory.newPeerID(PeerGroupID.defaultNetPeerGroupID, Name.getBytes()); public static final File ConfigurationFile = new File("." + System.getProperty("file.separator") + Name); public static void main(String[] args) { try { // Removing any existing configuration? Tools.CheckForExistingConfigurationDeletion(Name, ConfigurationFile); // Creation of network manager NetworkManager MyNetworkManager = new NetworkManager(NetworkManager.ConfigMode.EDGE, Name, ConfigurationFile.toURI()); // Retrieving the network configurator NetworkConfigurator MyNetworkConfigurator = MyNetworkManager.getConfigurator(); // Checking if RendezVous_Lidong_The_JXTA_Socket_Server should be a seed MyNetworkConfigurator.clearRendezvousSeeds(); String TheSeed = "tcp://" + InetAddress.getLocalHost().getHostAddress() + ":" + RendezVous_Lidong_The_JXTA_Socket_Server.TcpPort; Tools.CheckForRendezVousSeedAddition(Name, TheSeed, MyNetworkConfigurator); // Setting Configuration MyNetworkConfigurator.setTcpPort(TcpPort); MyNetworkConfigurator.setTcpEnabled(true); MyNetworkConfigurator.setTcpIncoming(true); MyNetworkConfigurator.setTcpOutgoing(true); // Setting the Peer ID Tools.PopInformationMessage(Name, "Setting the peer ID to :\n\n" + PID.toString()); MyNetworkConfigurator.setPeerID(PID); // Starting the JXTA network Tools.PopInformationMessage(Name, "Start the JXTA network and to wait for a rendezvous connection with\n" + RendezVous_Lidong_The_JXTA_Socket_Server.Name + " for maximum 2 minutes"); PeerGroup NetPeerGroup = MyNetworkManager.startNetwork(); // Disabling any rendezvous autostart NetPeerGroup.getRendezVousService().setAutoStart(false); if (MyNetworkManager.waitForRendezvousConnection(120000)) { Tools.popConnectedRendezvous(NetPeerGroup.getRendezVousService(),Name); } else { Tools.PopInformationMessage(Name, "Did not connect to a rendezvous"); } // Creating the JXTA socket JxtaSocket MySocket = new JxtaSocket(NetPeerGroup, null, RendezVous_Lidong_The_JXTA_Socket_Server.GetPipeAdvertisement(), 30000, true);

Using JXSE JXTA Socket & Socket Server - 226

if (MySocket!=null) { // Retrieving the output stream OutputStream MyOutputStream = MySocket.getOutputStream(); DataOutput MyDataOutput = new DataOutputStream(MyOutputStream); // Sending a message MyDataOutput.writeUTF("Hello from " + Name); MyOutputStream.flush(); // Retrieving the input streams InputStream MyInputStream = MySocket.getInputStream(); DataInput MyDataInput = new DataInputStream(MyInputStream); String IncomingMessage = MyDataInput.readUTF(); Tools.PopInformationMessage(Name, "Received socket message:\n\n" + IncomingMessage); // Sleeping for 10 seconds Tools.GoToSleep(10000); // Closing the streams MyOutputStream.close(); MyInputStream.close(); // Closing the socket MySocket.close(); } // Stopping the network Tools.PopInformationMessage(Name, "Stop the JXTA network"); MyNetworkManager.stopNetwork(); } catch (IOException Ex) { // Raised when access to local file and directories caused an error Tools.PopErrorMessage(Name, Ex.toString()); } catch (PeerGroupException Ex) { // Raised when the net peer group could not be created Tools.PopErrorMessage(Name, Ex.toString()); } } }

Ayrton, The Edge and JXTA Socket

Ayrton is performing the following: 1. We set some context information via static attributes as usual. 2. We provide the user with an opportunity to erase any existing configuration and to set Lidong as a rendezvous. Usual NetworkConfigurator parameters are set. 3. We start Ayrton as an edge and wait until it connects to a rendezvous for maximum 2 minutes. 4. We create a JXTA socket using the common pipe advertisement with Lidong. We set the maximum delay for a connection to 30 seconds.

Using JXSE JXTA Socket & Socket Server - 227

5. If a connection is established: a) We send a hello message to the other party. We flush the OutputStream to make sure the other party won't block when trying to read data from the socket. b) We try to read a message from the other party and display it to the user. c) We close the streams and the JXTA socket. 6. We stop the JXTA network.

Running The Example
In order to establish a successful communication between Lidong and Ayrton, the following procedure must be performed: 1. Start Lidong the rendezvous until it waits for connections from other peers (delete any existing configuration). 2. Start Ayrton until he manages to connect to Lidong (delete any existing configuration and allow Lidong as a rendezvous seed). 3. Go back to Lidong and click OK on the box mentioning he is waiting for peers to connect. A message indicating that he has created a JXTA socket server is displayed. 4. Go back to Ayrton and click OK on the box mentioning that he has connected to a rendezvous. 5. Go back to Lidong and click OK on the box mentioning that he has created a JXTA socket server. 6. Pretty quickly, Lidong will mention that a JXTA socket connection has been established. 7. By clicking on OK from both sides, hello messages exchanged by both peers will be displayed. 8. Carry on clicking OK on boxes until both peers stop the JXTA network. As in previous examples, we did not have one of the peer fetch the advertisement from the other. Just as for bidirectional pipes, most peers will run their JXTA servers to accept socket connections from others.

Using JXSE JXTA Socket & Socket Server - 228

JXTA Multicast Socket
JXTA multicast sockets allow peers in peer groups to exchange datagrams with other peers of the same peer group connected via a common JXTA multicast socket.

Hans, The Rendezvous, A Multicast Participant
The following is the code used for Hans, a rendezvous peer connected to a JXTA multicast socket:
... public class RendezVous_Hans_A_Multicast_Participant { // Static attributes public static final String Name = "RendezVous Hans, a JXTA multicast socket participant"; public static final int TcpPort = 9731; public static final PeerID PID = IDFactory.newPeerID(PeerGroupID.defaultNetPeerGroupID, Name.getBytes()); public static final File ConfigurationFile = new File("." + System.getProperty("file.separator") + Name); public static PipeAdvertisement GetPipeAdvertisement() { // Creating a Pipe Advertisement PipeAdvertisement MyPipeAdvertisement = (PipeAdvertisement) AdvertisementFactory.newAdvertisement(PipeAdvertisement.getAdvertisementType()); PipeID MyPipeID = IDFactory.newPipeID(PeerGroupID.defaultNetPeerGroupID, Name.getBytes()); MyPipeAdvertisement.setPipeID(MyPipeID); MyPipeAdvertisement.setType(PipeService.PropagateType); MyPipeAdvertisement.setName("Test Multicast"); MyPipeAdvertisement.setDescription("Created by " + Name); return MyPipeAdvertisement; } public static void main(String[] args) { try { // Removing any existing configuration? Tools.CheckForExistingConfigurationDeletion(Name, ConfigurationFile); // Creation of network manager NetworkManager MyNetworkManager = new NetworkManager( NetworkManager.ConfigMode.RENDEZVOUS, Name, ConfigurationFile.toURI()); // Retrieving the network configurator NetworkConfigurator MyNetworkConfigurator = MyNetworkManager.getConfigurator(); // Setting more configuration MyNetworkConfigurator.setTcpPort(TcpPort); MyNetworkConfigurator.setTcpEnabled(true); MyNetworkConfigurator.setTcpIncoming(true); MyNetworkConfigurator.setTcpOutgoing(true); // Setting the Peer ID Tools.PopInformationMessage(Name, "Setting the peer ID to :\n\n" + PID.toString()); MyNetworkConfigurator.setPeerID(PID); // Starting the JXTA network Tools.PopInformationMessage(Name, "Start the JXTA network"); PeerGroup NetPeerGroup = MyNetworkManager.startNetwork();

Using JXSE JXTA Multicast Socket - 229

// Waiting for other peers to connect to JXTA Tools.PopInformationMessage(Name, "Waiting for other peers to connect to JXTA"); // Creating the JXTA socket server JxtaMulticastSocket MyMulticastSocket = new JxtaMulticastSocket( NetPeerGroup, GetPipeAdvertisement()); Tools.PopInformationMessage(Name, "JXTA multicast socket created"); // Creating a datagram and sending it String Message = "Hello from " + Name; DatagramPacket MyDatagramPacket = new DatagramPacket(Message.getBytes(), Message.length()); Tools.PopInformationMessage(Name, "Multicasting following message:\n\n" + Message); MyMulticastSocket.send(MyDatagramPacket); // Sleeping a little (10 seconds) Tools.GoToSleep(10000); // Closing the JXTA socket MyMulticastSocket.close(); // Retrieving connected peers Tools.popConnectedPeers(NetPeerGroup.getRendezVousService(), Name); // Stopping the network Tools.PopInformationMessage(Name, "Stop the JXTA network"); MyNetworkManager.stopNetwork(); } catch (IOException Ex) { Tools.PopErrorMessage(Name, Ex.toString()); } catch (PeerGroupException Ex) { Tools.PopErrorMessage(Name, Ex.toString()); } } }

Hans, The Rendezvous, a Multicast Participant

Hans is performing the following: 1. As in previous pipe examples, Hans implements a static method to retrieve the pipe advertisement that will be used by both peers to establish a multicast connection. 2. We set some context information via static attributes as usual. 3. We provide the user with an opportunity to erase any existing configuration. Usual NetworkConfigurator parameters are set. 4. We start Hans as a rendezvous and wait until other peers connect to it. 5. We create a JXTA multicast socket and notify the user. 6. We create a hello datagram message, notify the user and send it. 7. We go to sleep for 10 seconds and close the multicast socket. 8. We stop the JXTA network after displaying the list of connected peers. Using JXSE JXTA Multicast Socket - 230

Teyacapan, The Edge, Another Multicast Participant
The following is the code used for Teyacapan, an edge peer also connected to a JXTA multicast socket:
... public class Edge_Teyacapan_Another_Multicast_Participant { public static final String Name = "Edge Teyacapan, another JXTA multicast socket participant"; public static final int TcpPort = 9735; public static final PeerID PID = IDFactory.newPeerID(PeerGroupID.defaultNetPeerGroupID, Name.getBytes()); public static final File ConfigurationFile = new File("." + System.getProperty("file.separator") + Name); public static void main(String[] args) { try { // Removing any existing configuration? Tools.CheckForExistingConfigurationDeletion(Name, ConfigurationFile); // Creation of network manager NetworkManager MyNetworkManager = new NetworkManager(NetworkManager.ConfigMode.EDGE, Name, ConfigurationFile.toURI()); // Retrieving the network configurator NetworkConfigurator MyNetworkConfigurator = MyNetworkManager.getConfigurator(); // Checking if RendezVous_Hans_A_Multicast_Participant should be a seed MyNetworkConfigurator.clearRendezvousSeeds(); String TheSeed = "tcp://" + InetAddress.getLocalHost().getHostAddress() + ":" + RendezVous_Hans_A_Multicast_Participant.TcpPort; Tools.CheckForRendezVousSeedAddition(Name, TheSeed, MyNetworkConfigurator); // Setting Configuration MyNetworkConfigurator.setTcpPort(TcpPort); MyNetworkConfigurator.setTcpEnabled(true); MyNetworkConfigurator.setTcpIncoming(true); MyNetworkConfigurator.setTcpOutgoing(true); // Setting the Peer ID Tools.PopInformationMessage(Name, "Setting the peer ID to :\n\n" + PID.toString()); MyNetworkConfigurator.setPeerID(PID); // Starting the JXTA network Tools.PopInformationMessage(Name, "Start the JXTA network and to wait for a rendezvous connection with\n" + RendezVous_Hans_A_Multicast_Participant.Name + " for maximum 2 minutes"); PeerGroup NetPeerGroup = MyNetworkManager.startNetwork(); // Disabling any rendezvous autostart NetPeerGroup.getRendezVousService().setAutoStart(false); if (MyNetworkManager.waitForRendezvousConnection(120000)) { Tools.popConnectedRendezvous(NetPeerGroup.getRendezVousService(),Name); } else { Tools.PopInformationMessage(Name, "Did not connect to a rendezvous"); } // Creating the JXTA socket server JxtaMulticastSocket MyMulticastSocket = new JxtaMulticastSocket(NetPeerGroup, RendezVous_Hans_A_Multicast_Participant.GetPipeAdvertisement()); Tools.PopInformationMessage(Name, "JXTA multicast socket created"); // Reading a datagram byte[] MyBuffer = new byte[1000]; DatagramPacket MyDatagramPacket = new DatagramPacket(MyBuffer, MyBuffer.length); MyMulticastSocket.receive(MyDatagramPacket);

Using JXSE JXTA Multicast Socket - 231

String MyString = new String(MyDatagramPacket.getData(), 0, MyDatagramPacket.getLength()); Tools.PopInformationMessage(Name, "Received multicast message:\n\n" + MyString); // // // // // // // // // //

REM: To return a message to the sender only: String MyResponse = "Response"; DatagramPacket DatagramReponse = new DatagramPacket(MyResponse.getBytes(), MyResponse.length()); DatagramResponse.setAddress(MyDatagramPacket); MyMulticastSocket.send(DatagramResponse);

// Closing the JXTA socket MyMulticastSocket.close(); // Stopping the network Tools.PopInformationMessage(Name, "Stop the JXTA network"); MyNetworkManager.stopNetwork(); } catch (IOException Ex) { // Raised when access to local file and directories caused an error Tools.PopErrorMessage(Name, Ex.toString()); } catch (PeerGroupException Ex) { // Raised when the net peer group could not be created Tools.PopErrorMessage(Name, Ex.toString()); } } }

Teyacapan, The Edge, Another Multicast Participant

Teyacapan is performing the following: 1. We set some context information via static attributes as usual. 2. We provide the user with an opportunity to erase any existing configuration and to set Hans as a rendezvous. Usual NetworkConfigurator parameters are set. 3. We start Teyacapan as an edge and wait until she connects to a rendezvous for maximum 2 minutes. 4. We create a JXTA multicast socket using the common pipe advertisement with Hans. 5. We read any incoming message and display it to the user. We also explain in comment how a message could be returned to the peer who has sent the received message. 6. We close the JXTA multicast socket. 7. We stop the JXTA network.

Using JXSE JXTA Multicast Socket - 232

Running The Example
In order run the JXTA multicast socket example successfully, the following procedure must be performed: 1. Start Hans the rendezvous until he waits for connections from other peers (delete any existing configuration). 2. Start Teyacapan until she manages to connect to Hans (delete any existing configuration and allow Hans as a rendezvous seed). 3. Go back to Hans and click OK on the box mentioning he is waiting for peers to connect. A message indicating that he has created a JXTA multicast socket is displayed. 4. Go back to Teyacapan and click OK on the box mentioning that she has connected to a rendezvous. A message indicating that she has created a JXTA multicast socket is displayed. 5. Go back to Hans and click OK on the box mentioning that he has created a JXTA multicast socket. 6. Pretty quickly, Hans will mention that he is going to multicast a message. Click on OK. 7. Teyacapan will display the received multicast message. 8. Carry on clicking OK on boxes until both peers stop the JXTA network. As in previous examples, we did not have one of the peers fetch the advertisement from the other peer. More Teyacapan peers can be added to this example to explore the multicasting aspect of sending messages via a JXTA multicast socket.

Implementing A Customized Service
Introduction
We are going to describe how to implement an astrology service, to have it loaded by an astrologer and to have a customer request a prediction from that astrologer and to get an answer. We will start by describing how to generate module IDs before the astrology service itself and we will finish with the description of peers.

Example 700 – Creating Module IDs
The following code describes how to create module IDs: Using JXSE Implementing A Customized Service - 233

... public class _700_Module_IDs_Creation_Example { public static final String Name = "Example 700"; public static void main(String[] args) { // Creating a new random module class ID ModuleClassID MyModuleClassID = (ModuleClassID) IDFactory.newModuleClassID(); // Creating a new random module specification ID ModuleSpecID MyModuleSpecID = IDFactory.newModuleSpecID(MyModuleClassID); // Printing IDs System.out.println(MyModuleClassID.toURI().toString() + "\n"); System.out.println(MyModuleSpecID.toURI().toString() + "\n"); } }

Example 700 – Creating Module IDs

One should not forget that in JXSE, a service is a type of module. Three types of advertisements describe modules in JXTA, but there are only two types of module IDs: ModuleClassID and ModuleSpecID. The latter is created based on the former. These IDs are required in order to create module advertisements.

Example 710 – Astrology Service
The following code implements an astrology service:
... public class _710_Astrology_Service_Example implements Service, Runnable { // Static public static final String Name = "Astrology Service"; public static final String NameSpace = "AstrologyService"; public static final String CustomerNameElement = "CustomerName"; public static final String BirthDateElement = "CustomerBirthDate"; public static final String BirthLocationElement = "CustomerBirthLocation"; public static final String PredictionElement = "Prediction"; public static final String MyModuleClassIDString = "urn:jxta:uuid-F7A712D25D3047B88656FD706AEDE8DB05"; public static final String MyModuleSpecIDString = "urn:jxta:uuid-F7A712D25D3047B88656FD706AEDE8DBC6A510B2026F4FD59A7DFA4F6712142506"; public static ModuleClassID MyModuleClassID = null; public static ModuleSpecID MyModuleSpecID = null; static { try { MyModuleClassID = ModuleClassID.create(new URI(MyModuleClassIDString)); MyModuleSpecID = ModuleSpecID.create(new URI(MyModuleSpecIDString)); } catch (Exception Ex) {

Using JXSE Implementing A Customized Service - 234

Tools.PopErrorMessage(Name, Ex.toString()); } } // Not static private PeerGroup ThePeerGroup = null; private ID TheID = null; private ModuleImplAdv TheImplementationAdvertisement = null; private JxtaServerPipe MyBiDiPipeServer = null; public static void main(String[] args) { // Dummy main method for compilation } public _710_Astrology_Service_Example() { } public static PipeAdvertisement GetPipeAdvertisement() { // Creating a Pipe Advertisement PipeAdvertisement MyPipeAdvertisement = (PipeAdvertisement) AdvertisementFactory.newAdvertisement(PipeAdvertisement.getAdvertisementType()); PipeID MyPipeID = IDFactory.newPipeID(PeerGroupID.defaultNetPeerGroupID, Name.getBytes()); MyPipeAdvertisement.setPipeID(MyPipeID); MyPipeAdvertisement.setType(PipeService.UnicastType); MyPipeAdvertisement.setName("Astrology Service Pipe"); MyPipeAdvertisement.setDescription("Created by " + Name); return MyPipeAdvertisement; } public static ModuleSpecAdvertisement GetModuleSpecificationAdvertisement() { ModuleSpecAdvertisement Result = (ModuleSpecAdvertisement) AdvertisementFactory.newAdvertisement(ModuleSpecAdvertisement.getAdvertisementType()); Result.setCreator("The Astrologers"); Result.setDescription("Astrology Service"); Result.setModuleSpecID(MyModuleSpecID); Result.setVersion("1.0"); Result.setPipeAdvertisement(GetPipeAdvertisement()); return Result; } public static ModuleImplAdvertisement GetModuleImplementationAdvertisement() { ModuleImplAdvertisement Result = (ModuleImplAdvertisement) AdvertisementFactory.newAdvertisement(ModuleImplAdvertisement.getAdvertisementType()); // Setting parameters Result.setDescription("Astrology Service"); Result.setModuleSpecID(MyModuleSpecID); Result.setProvider(Name); Result.setCode(_710_Astrology_Service_Example.class.getName()); // Setting compatibility & binding Result.setCompat(StdPeerGroup.STD_COMPAT); // Retrieving the location of the .jar file JFileChooser MyFileChooser = new JFileChooser(); File SelectedFile = null; Tools.PopInformationMessage(Name, "Retrieving the implementation location of the astrology service");

Using JXSE Implementing A Customized Service - 235

int TheReturnedValue = MyFileChooser.showOpenDialog(null); if (TheReturnedValue == JFileChooser.APPROVE_OPTION) { SelectedFile = MyFileChooser.getSelectedFile(); } if (SelectedFile==null) { Tools.PopWarningMessage(Name, "No file selected"); } else { Result.setUri(SelectedFile.toURI().toString()); } return Result; } public Service getInterface() { return this; } public Advertisement getImplAdvertisement() { return TheImplementationAdvertisement; } public ID getID() { return TheID; } public void init(PeerGroup InPG, ID InID, Advertisement InAdvertisement) throws PeerGroupException { // Initialization ThePeerGroup = InPG; TheID = InID; TheImplementationAdvertisement = (ModuleImplAdv) InAdvertisement; } public int startApp(String[] arg0) { try { MyBiDiPipeServer = new JxtaServerPipe(ThePeerGroup, GetPipeAdvertisement(), 5000); Thread thread = new Thread(this); thread.start(); Tools.PopInformationMessage(Name, "Start Successful"); return START_OK; } catch (IOException Ex) { Tools.PopErrorMessage(Name, Ex.toString()); Tools.PopInformationMessage(Name, "Start Unsuccessful"); return START_DISABLED; } } public void run() { while (MyBiDiPipeServer != null) { try {

Using JXSE Implementing A Customized Service - 236

JxtaBiDiPipe MyBiDiPipe = this.MyBiDiPipeServer.accept(); if (MyBiDiPipe != null) { // Processing customers Thread thread = new Thread(new CustomerHandler(MyBiDiPipe)); thread.start(); } } catch (SocketTimeoutException Ex) { // We don't care if we get a timeout after 5 seconds // We try to accept a connection again } catch (IOException Ex) { Tools.PopErrorMessage(Name, Ex.toString()); } } } public void stopApp() { // Closing bidipipe server if (MyBiDiPipeServer != null) { try { MyBiDiPipeServer.close(); MyBiDiPipeServer = null; Tools.PopInformationMessage(Name, "Stop Successful"); } catch (IOException Ex) { Tools.PopErrorMessage(Name, Ex.toString()); } } } private static class CustomerHandler implements Runnable, PipeMsgListener { private JxtaBiDiPipe MyJxtaBiDiPipe = null; CustomerHandler(JxtaBiDiPipe InPipe) { MyJxtaBiDiPipe = InPipe; MyJxtaBiDiPipe.setMessageListener(this); } public static final int ComputeHoroscopeHash(String InString) { int Result = 0; if (InString != null) { for (int i=0;i<InString.length();i++) { Result = Result + (int) InString.charAt(i); } } // Returning result return ( Result % 3 ); } public void pipeMsgEvent(PipeMsgEvent event) { try {

Using JXSE Implementing A Customized Service - 237

long PredictionHash = System.currentTimeMillis(); // Retrieve the message Message MyMessage = event.getMessage(); MessageElement MyMessageElement = MyMessage.getMessageElement(NameSpace, CustomerNameElement); PredictionHash = PredictionHash + ComputeHoroscopeHash(MyMessageElement.toString()); MyMessageElement = MyMessage.getMessageElement(NameSpace, BirthDateElement); PredictionHash = PredictionHash + ComputeHoroscopeHash(MyMessageElement.toString()); MyMessageElement = MyMessage.getMessageElement(NameSpace, BirthLocationElement); PredictionHash = PredictionHash + ComputeHoroscopeHash(MyMessageElement.toString()); PredictionHash = PredictionHash % 3; String Prediction = ""; switch ((int)PredictionHash) { case 0: Prediction = "You will be rich!"; break; case 1: Prediction = "You will be famous!"; break; default: Prediction = "You need to make more sacrifices to the Gods!"; } // Sending answer MyMessage = new Message(); StringMessageElement MyStringMessageElement = new StringMessageElement(PredictionElement, Prediction, null); MyMessage.addMessageElement(NameSpace, MyStringMessageElement); MyJxtaBiDiPipe.sendMessage(MyMessage); // Closing the connection MyJxtaBiDiPipe.close(); } catch (IOException Ex) { Tools.PopErrorMessage(Name, Ex.toString()); } } public void run() { // The pipeMsgEvent will be called when necessary } } }

Example 710 – Astrology Service

We will describe the code in several parts:

Static And Non-Static Attributes
The static attributes of the astrology service not only includes its name, but also the text element

Using JXSE Implementing A Customized Service - 238

names that will be used when the astrologer and the customer will communicate with messages. The ModuleClassID and ModuleSpecID are recreated from previously generated strings. The non-static attributes include a couple of attributes that will be set at initialization, but most importantly, a JxtaServerPipe which will be used to communicate with customers.

Static Methods
We define some static methods to retrieve advertisements: GetPipeAdvertisement(), GetModuleSpecificationAdvertisement() and GetModuleImplementationAdvertisement(). The pipe advertisement method will be used by the astrologer and the customer to create a bidirectional pipe communication. The other methods are required to generate the minimum set of advertisements necessary to run this example. Typically, one would also include a method to generate a module class advertisement, but it has not been implemented here. In order to create the module implementation advertisement, we ask the user to indicate where the .jar file corresponding to the implementation of the astrology service can be implemented. We will come back to this later.

Static Class
We also define a static inner class called CustomerHandler to handle customers' requests for predictions. Each time a request arrives via the JxtaServerPipe, a new instance of the class is created and started in a separate thread. The prediction is computed based on the received information and sent back to the customer. The thread and the class die automatically.

Implementation Of Interfaces
The astrology service implements the Service and Runnable interface. The Service interface requires implementing a couple of methods to initiate, start and stop the service. The Runnable interface is required to run the JxtaServerPipe in a separate thread to accept pipe connections from customers. Metaphorically: A method to predict ones future has been written in a book that only astrologers have. Each time they open their shop, they have the copy of their book ready for consultation.

RendezVous Joe, The Astrologer
The following is the code used for Joe, a rendezvous peer running the astrology service:

Using JXSE Implementing A Customized Service - 239

... public class RendezVous_Joe_The_Astrologer { // Static attributes public static final String Name = "RendezVous Joe, The Astrologer"; public static final int TcpPort = 9745; public static final PeerID PID = IDFactory.newPeerID(PeerGroupID.defaultNetPeerGroupID, Name.getBytes()); public static final File ConfigurationFile = new File("." + System.getProperty("file.separator") + Name); public static void main(String[] args) { try { // Removing any existing configuration? Tools.CheckForExistingConfigurationDeletion(Name, ConfigurationFile); // Creation of network manager NetworkManager MyNetworkManager = new NetworkManager( NetworkManager.ConfigMode.RENDEZVOUS, Name, ConfigurationFile.toURI()); // Retrieving the network configurator NetworkConfigurator MyNetworkConfigurator = MyNetworkManager.getConfigurator(); // Setting more configuration MyNetworkConfigurator.setTcpPort(TcpPort); MyNetworkConfigurator.setTcpEnabled(true); MyNetworkConfigurator.setTcpIncoming(true); MyNetworkConfigurator.setTcpOutgoing(true); // Setting the Peer ID Tools.PopInformationMessage(Name, "Setting the peer ID to :\n\n" + PID.toString()); MyNetworkConfigurator.setPeerID(PID); // Starting the JXTA network Tools.PopInformationMessage(Name, "Start the JXTA network"); PeerGroup NetPeerGroup = MyNetworkManager.startNetwork(); // Loading the astrology service Tools.PopInformationMessage(Name, "Loading the astrology service"); Module MyAstrologyModule = NetPeerGroup.loadModule( _710_Astrology_Service_Example.MyModuleClassID, _710_Astrology_Service_Example.GetModuleImplementationAdvertisement()); // Starting the astrology service Tools.PopInformationMessage(Name, "Starting the astrology service"); MyAstrologyModule.startApp(new String[0]); // Waiting for other peers to connect to JXTA Tools.PopInformationMessage(Name, "Waiting for other peers to connect to JXTA"); // Ending the service Tools.PopInformationMessage(Name, "Click OK to end the astrology service"); MyAstrologyModule.stopApp(); // Retrieving connected peers Tools.popConnectedPeers(NetPeerGroup.getRendezVousService(), Name); // Stopping the network Tools.PopInformationMessage(Name, "Stop the JXTA network"); MyNetworkManager.stopNetwork(); } catch (ProtocolNotSupportedException Ex) { Tools.PopErrorMessage(Name, Ex.toString()); } catch (IOException Ex) { Tools.PopErrorMessage(Name, Ex.toString()); } catch (PeerGroupException Ex) {

Using JXSE Implementing A Customized Service - 240

Tools.PopErrorMessage(Name, Ex.toString()); } } }

RendezVous Joe, The Astrologer

Joe is performing the following: 1. We set some context information via static attributes as usual for rendezvous peers. 2. We provide the user with an opportunity to erase any existing configuration. Usual NetworkConfigurator parameters are set. 3. We start Joe as a rendezvous and wait for the user to load the astrology service. 4. Once the user clicked OK, we load the astrology service using the loadModule(...) method from the net peer group. We provide its module implementation advertisement as a parameter. JXSE will retrieve the location of the .jar file corresponding to the service from this advertisement and load it. 5. Remark: In our example, the user will retrieve .jar file from its local PC (or device), but in reality, it will most probably be located somewhere on the Internet. 6. We start the astrology service and wait for other peers to connect to JXTA. 7. After clicking OK, the user is given an opportunity to control the stopping of the astrology service. 8. Next, we stop the JXTA network after displaying the list of connected peers.

Edge Jill, The Customer
The following is the code used for Jill, an edge peer consulting Joe, the astrologer:
... public class Edge_Jill_The_Customer implements PipeMsgListener { public static final String Name = "Edge Jill, The Customer"; public static final int TcpPort = 9746; public static final PeerID PID = IDFactory.newPeerID(PeerGroupID.defaultNetPeerGroupID, Name.getBytes()); public static final File ConfigurationFile = new File("." + System.getProperty("file.separator") + Name); public void pipeMsgEvent(PipeMsgEvent PME) { // We received a message Message ReceivedMessage = PME.getMessage(); String TheText = ReceivedMessage.getMessageElement( _710_Astrology_Service_Example.NameSpace,

Using JXSE Implementing A Customized Service - 241

_710_Astrology_Service_Example.PredictionElement).toString(); // Notifying the user Tools.PopInformationMessage(Name, "Received message:\n\n" + TheText); } public static void main(String[] args) { try { // Removing any existing configuration? Tools.CheckForExistingConfigurationDeletion(Name, ConfigurationFile); // Creation of network manager NetworkManager MyNetworkManager = new NetworkManager(NetworkManager.ConfigMode.EDGE, Name, ConfigurationFile.toURI()); // Retrieving the network configurator NetworkConfigurator MyNetworkConfigurator = MyNetworkManager.getConfigurator(); // Checking if RendezVous Joe should be a seed MyNetworkConfigurator.clearRendezvousSeeds(); String TheSeed = "tcp://" + InetAddress.getLocalHost().getHostAddress() + ":" + RendezVous_Joe_The_Astrologer.TcpPort; Tools.CheckForRendezVousSeedAddition(Name, TheSeed, MyNetworkConfigurator); // Setting Configuration MyNetworkConfigurator.setTcpPort(TcpPort); MyNetworkConfigurator.setTcpEnabled(true); MyNetworkConfigurator.setTcpIncoming(true); MyNetworkConfigurator.setTcpOutgoing(true); // Setting the Peer ID Tools.PopInformationMessage(Name, "Setting the peer ID to :\n\n" + PID.toString()); MyNetworkConfigurator.setPeerID(PID); // Starting the JXTA network Tools.PopInformationMessage(Name, "Start the JXTA network and to wait for a rendezvous connection with\n" + RendezVous_Joe_The_Astrologer.Name + " for maximum 2 minutes"); PeerGroup NetPeerGroup = MyNetworkManager.startNetwork(); // Disabling any rendezvous autostart NetPeerGroup.getRendezVousService().setAutoStart(false); if (MyNetworkManager.waitForRendezvousConnection(120000)) { Tools.popConnectedRendezvous(NetPeerGroup.getRendezVousService(),Name); } else { Tools.PopInformationMessage(Name, "Did not connect to a rendezvous"); } // Preparing the listener and Creating the BiDiPipe PipeMsgListener MyListener = new Edge_Jill_The_Customer(); // Retrieving the pipe advertisement from the module implementation advertisement ModuleSpecAdvertisement TheModuleSpecAdvertisement = _710_Astrology_Service_Example.GetModuleSpecificationAdvertisement(); PipeAdvertisement ThePipeAdvertisement = TheModuleSpecAdvertisement.getPipeAdvertisement(); JxtaBiDiPipe MyBiDiPipe = new JxtaBiDiPipe(NetPeerGroup, ThePipeAdvertisement, 30000, MyListener); if (MyBiDiPipe.isBound()) { Tools.PopInformationMessage(Name, "Connection with astrology service established, asking for predictions!"); // Sending request for prediction message !!! Message MyMessage = new Message(); StringMessageElement MyStringMessageElement = new StringMessageElement( _710_Astrology_Service_Example.BirthDateElement, "04112036", null); MyMessage.addMessageElement(_710_Astrology_Service_Example.NameSpace,

Using JXSE Implementing A Customized Service - 242

MyStringMessageElement); MyStringMessageElement = new StringMessageElement( _710_Astrology_Service_Example.BirthLocationElement, "New Jersey, USA", null); MyMessage.addMessageElement(_710_Astrology_Service_Example.NameSpace, MyStringMessageElement); MyStringMessageElement = new StringMessageElement( _710_Astrology_Service_Example.CustomerNameElement, Name, null); MyMessage.addMessageElement(_710_Astrology_Service_Example.NameSpace, MyStringMessageElement); MyBiDiPipe.sendMessage(MyMessage); // Sleeping for 5 seconds Tools.GoToSleep(5000); } // Stopping the network and the bidipipe Tools.PopInformationMessage(Name, "Stop the JXTA network"); MyBiDiPipe.close(); MyNetworkManager.stopNetwork(); } catch (IOException Ex) { // Raised when access to local file and directories caused an error Tools.PopErrorMessage(Name, Ex.toString()); } catch (PeerGroupException Ex) { // Raised when the net peer group could not be created Tools.PopErrorMessage(Name, Ex.toString()); } } }

Edge Jill, The Customer

Jill is performing the following: 1. Jill implements the PipeMsgListener interface. This requires implementing the pipeMsgEvent method to handle messages which will be received from Joe. 2. We set some context information via static attributes as usual. 3. We provide the user with an opportunity to erase any existing configuration and to set Joe as a rendezvous. Usual NetworkConfigurator parameters are set. 4. We start Jill as an edge and wait until she connects to a rendezvous for maximum 2 minutes. 5. We retrieve the module specification advertisement corresponding to the astrology service and we create a bidirectional pipe by extracting the corresponding pipe advertisement. We wait for maximum 30 seconds for a connection with Joe. 6. If such a connection is established, we send a request for prediction message to Joe and

Using JXSE Implementing A Customized Service - 243

set a listener for answers. 7. We give the user an opportunity to control when the bidirectional pipe and the network should be stopped.

Running The Example
In order to run the example successfully, the following procedure must be performed: 1. Compile the astrology service into a .jar file and copy it in a special directory on your PC. 2. Start Joe the rendezvous until he waits for connections from other peers (delete any existing configuration). You will be requested to provide the location of the astrology .jar file created earlier. 3. Start Jill until she manages to connect to Joe (delete any existing configuration and allow Joe as a rendezvous seed). 4. Click OK to establish a pipe connection with Joe. 5. Click OK to have Jill send her request for prediction message to Joe. 6. The astrology service ran by Joe should automatically return an answer to Jill, who will display it. 7. Click OK on the next boxes showed by Joe and Jill until both stop their JXTA network. For the sake of simplicity, we did not have one of the peers fetch the module and pipe advertisements from the other, although in reality, most software applications would do so. This illustrates how one can load and run a service on a peer for other peers. One might be asked to join a peer group of astrologers before accessing this service. Some monitoring of the workload of each astrologer running this service could be implemented too to redirect customers. We have not implemented this here for the sake of clarity.

Self-Service Weather Forecasting Method
Typically, a self-service weather forecasting method could be implemented the same way as the astrology method and made accessible to other peers via a URI. The corresponding module implementation advertisement would be published too, or fetched by peers willing to run the weather forecasting method. This implementation would be downloaded and run as a service for other tribes. Using JXSE Implementing A Customized Service - 244

Remark: We mentioned earlier that some services are implemented at a peer level and at a peer group level. Typically, if all astrologers run the same implementation of astrology service within their peer group, this service will be available at a peer group level. When initialized, this service is given a unique ID, that is, the module class ID corresponding to the astrology service. Each astrologer is running the astrology service with the same ID. Some readers will have noticed that Jill only needs to find the module specification advertisement of the astrology service, not the module implementation advertisement. This is enough to connect to any astrologer. If a service is implemented at a peer level, it would have its own module class ID and module specification ID deriving from it. The module specification advertisement, containing the corresponding module specification ID, would be unique. Since other peers would not necessarily have access to a module implementation advertisement for this peer level service, they would not be able to load it and run it themselves. All customers of that peer level service would connect to one peer only via the corresponding module specification advertisement who would be published to anyone's attention.

Peer Information
Activation Of The Peer Information Service
In JXSE 2.6, the peer information service has been fully integrated. There is no need to generate classes using ant anymore. However, it has not been activated. For more details on activation, refer to the Programmer's Guide 2.6 available at http://jxse.kenai.com. Some original documentation remains available at: https://jxse-metering.dev.java.net/docs/BuildingAndConfiguringMonitoring.pdf and https://jxse-metering.dev.java.net/.

Ping
Most software developers will want to know whether a peer is still online or not. If one thinks about it, it is impossible to know for a given peer whether another peer is online or not. If one cannot establish some connection with another peer, the reason cannot be guessed from the lack of connectivity only. There could be an issue with the network. The other peer might be online, but unreachable. Using JXSE Ping - 245

Moreover, if one can establish a connection now with another peer, it does not necessarily mean that one will be able to establish a connection in the future too. Therefore, any information gathered about one's capacity to establish a connection with another peer is degrading with time. Do not forget that trying to extract any IP address from a known peer route or endpoint address and pinging it is useless, since it may be the result of a NAT translation. Conversely, it is not because one does not have a route to a peer that a peer is not online and accessible. As we have mentioned it earlier, release 2.6 comes with a new endpoint service functionality called isReachable(...). We will now describe how one can find out whether a connection to another peer can be established or not. If a route can be established, then we know that the target peer is online.

Example 800 – Ping
The following is the code used to ping another peer:
... public class _800_Adhoc_Ping_Example { public static final String Name = "Example 800"; public static final int TcpPort = 9756; public static final PeerID PID = IDFactory.newPeerID(PeerGroupID.defaultNetPeerGroupID, Name.getBytes()); public static final File ConfigurationFile = new File("." + System.getProperty("file.separator") + Name); public static void main(String[] args) { try { // Removing any existing configuration? Tools.CheckForExistingConfigurationDeletion(Name, ConfigurationFile); // Creation of network manager NetworkManager MyNetworkManager = new NetworkManager(NetworkManager.ConfigMode.ADHOC, Name, ConfigurationFile.toURI()); // Retrieving the network configurator NetworkConfigurator MyNetworkConfigurator = MyNetworkManager.getConfigurator(); // Setting Configuration MyNetworkConfigurator.setUseMulticast(true); // Setting the Peer ID Tools.PopInformationMessage(Name, "Setting the peer ID to :\n\n" + PID.toString()); MyNetworkConfigurator.setPeerID(PID); // Starting the JXTA network Tools.PopInformationMessage(Name, "Start the JXTA network and try to establish a route to:\n\n" + _810_Adhoc_Pong_Example.Name); PeerGroup NetPeerGroup = MyNetworkManager.startNetwork(); // Retrieving the endpoint service and the message transport EndpointService MyEndpointService = NetPeerGroup.getEndpointService(); Tools.PopInformationMessage(Name, "Trying to reach " + _810_Adhoc_Pong_Example.Name + " without resolving");

Using JXSE Ping - 246

if ( MyEndpointService.isReachable(_810_Adhoc_Pong_Example.PID, false) ) { Tools.PopInformationMessage(Name, "We can establish a route to: " + _810_Adhoc_Pong_Example.Name); } else { Tools.PopInformationMessage(Name, "We CAN'T establish a route to: " + _810_Adhoc_Pong_Example.Name); } Tools.PopInformationMessage(Name, "Trying to reach " + _810_Adhoc_Pong_Example.Name + " with resolving"); if ( MyEndpointService.isReachable(_810_Adhoc_Pong_Example.PID, true) ) { Tools.PopInformationMessage(Name, "We can establish a route to: " + _810_Adhoc_Pong_Example.Name); } else { Tools.PopInformationMessage(Name, "We CAN'T establish a route to: " + _810_Adhoc_Pong_Example.Name); } // Stopping the network Tools.PopInformationMessage(Name, "Stop the JXTA network"); MyNetworkManager.stopNetwork(); } catch (IOException Ex) { Tools.PopErrorMessage(Name, Ex.toString()); } catch (PeerGroupException Ex) { Tools.PopErrorMessage(Name, Ex.toString()); } } }

Example 800 - Ping

The Ping peer is performing the following: 1. We set some context information via static attributes as usual. 2. We provide the user with an opportunity to erase any existing configuration. Usual NetworkConfigurator parameters are set. 3. We start the JXTA network. 4. We try to find out whether we can establish a route to Pong, without attempting to resolve a route and notify the user of the result (which is negative). 5. Then, we try again by attempting to resolve a route. The result will be positive. 6. We stop the JXTA network.

Example 810 – Pong
The following is the code used to create a peer, called Pong, which will be ping-ed by peer Ping:
... public class _810_Adhoc_Pong_Example {

Using JXSE Ping - 247

// Static attributes public static final String Name = "Example 810"; public static final int TcpPort = 9755; public static final PeerID PID = IDFactory.newPeerID(PeerGroupID.defaultNetPeerGroupID, Name.getBytes()); public static final File ConfigurationFile = new File("." + System.getProperty("file.separator") + Name); public static void main(String[] args) { try { // Removing any existing configuration? Tools.CheckForExistingConfigurationDeletion(Name, ConfigurationFile); // Creation of network manager NetworkManager MyNetworkManager = new NetworkManager(NetworkManager.ConfigMode.ADHOC, Name, ConfigurationFile.toURI()); // Retrieving the network configurator NetworkConfigurator MyNetworkConfigurator = MyNetworkManager.getConfigurator(); // Setting more configuration MyNetworkConfigurator.setUseMulticast(true); // Setting the Peer ID Tools.PopInformationMessage(Name, "Setting the peer ID to :\n\n" + PID.toString()); MyNetworkConfigurator.setPeerID(PID); // Starting the JXTA network Tools.PopInformationMessage(Name, "Start the JXTA network"); PeerGroup NetPeerGroup = MyNetworkManager.startNetwork(); // Stopping the network Tools.PopInformationMessage(Name, "Stop the JXTA network"); MyNetworkManager.stopNetwork(); } catch (IOException Ex) { Tools.PopErrorMessage(Name, Ex.toString()); } catch (PeerGroupException Ex) { Tools.PopErrorMessage(Name, Ex.toString()); } } }

Exemple 810 - RendezVous Pong

Pong is performing the following: 1. We set some context information via static attributes as usual. 2. We provide the user with an opportunity to erase any existing configuration. Usual NetworkConfigurator parameters are set. 3. We start Pong as a rendezvous and wait for Ping to ping it. 4. The user is given an opportunity to control when Pong should be stopped.

Using JXSE Ping - 248

Running the Example
In order to run the example successfully, the following procedure must be performed: 1. Start Pong. 2. Start Ping and perform the connectivity tests. 3. Stop Ping. 4. Stop Pong. Warning: as mentioned earlier, unexpected disconnection between peers (for example, between an edge and its rendezvous) are not always detected and handled 'quickly'. This is a know issue which may impact the isReachable(...) functionality. Deep core code refactoring is required and should be performed in a future release.

Miscellaneous
Typically, software developers will not interfere with the default implementation of JXTA services in other ways than described before. However, one may by-pass the service hierarchy and use the endpoint service directly to send a message or invoke the resolver service to send customized queries.

Sending A Message With The Endpoint Service
Sending a message via the endpoint service of a peer requires retrieving that service from the corresponding PeerGroup object and calling the getMessenger(...) method. This method takes an endpoint address as a parameter, which can be retrieved from a locally stored route advertisement for example, and returns a Messenger object. Next, the user can call the one of the sendMessage(...) method from the messenger. Some versions allow specifying a target service and service parameter. This method returns a boolean indicating that the message was successfully sent, but it does not guarantee that it will be received. This is why bidirectional pipes (for example) are preferred over this method in terms of reliability.

Customized Queries
Those willing to send customized queries and query answers between peers will have to create these with the ResolverQuery and ResolverResponse objects. Do not forget to set the target handling service name in these objects to make sure the proper handler will get them. Next, send Using JXSE Miscellaneous - 249

these queries and responses by calling the sendQuery(...) and sendResponse(...) method of the ResolverService, which is accessible from PeerGroup objects in each peer. A target peer ID must be provided as a parameter when calling these methods. At last, do not forget to register some listeners beforehand in each peer via the registerHandler(...) method of the ResolverService, else queries and responses will be discarded.

About Registering Handlers In Services
Typically, software developers using JXTA/JXSE in a standard way will not need to register listeners in delivered services in other ways than described until now. If they need to register such handlers anyway, they should read the corresponding javadoc carefully.

JXSE Shell
There was a possibility to test and use JXTA and JXSE concepts with a Unix-like command shell developed by the JXTA community. Unfortunately this project has not been maintained for JXSE 2.6 because of a lack of volunteers and interest. Information is accessible from https://jxse-shell.dev.java.net/.

Using JXSE JXSE Shell - 250

About The Future...
In the first edition of this book, several factors having an impact on the future JXTA were introduced and discussed. Today, we introduce more categories (P2P, JXTA and JXSE) to classify these factors and add new ones.

...Of P2P
Perception vs. Facts
P2P is often associated with copyright infringement and sometimes with propagation of virus. These perceptions are, of course, not based on facts. When taking a look at details, one will notice that client-server based solutions are no more (or less) safe than P2P solutions.

About Needs That Have Shaped IT Solutions – Part II
As we mentioned earlier in this book, let's recall the needs that have shaped IT solutions. Remember that these emerged from the client/server paradigm:
➢ ➢ ➢ ➢ ➢

Remote access to a resource Concurrent access to a resource Exchange of information between resources Collection, centralization and organization of information from resources Replication of resources

The client/server model was developed to deliver/obtain services that one's local machine could not provide. This paradigm was further supported by the Network Address Translation (NAT) mechanism, which meant that a PC could not be directly reached if it used a private address. The P2P paradigm has been hampered in its development by this technical limitation, but NAT traversal solutions are now appearing.

Distributed Content
The concept of super peers introduced by Kazaa implied centralizing some information about content available in a P2P system. Distributed hash table techniques were developed during the early Millenium boom to solve this issue: Chord, CAN, Tapestry, Pastry, Kademlia, Koorde...

About The Future... ...Of P2P - 251

All these techniques propose theoretical results for finding the node containing the searched information matching a key. All these results are based on a value of 1 to establish a contact to a remote peer. Unfortunately, this is an unrealistic assumption, since we know that it is not always possible to establish a direct connection to a peer. More effort involving multiple can be necessary. Moreover, the purpose of P2P system is not to centralize content on super peers, which would be equivalent to central server systems. Super peers maintain pointers to peers offering the content. Therefore, more than one connection is required to connect to the peer offering the content. It would be interesting to perform real measurements of connection cost using, for example, a Monte Carlo method on a representative sample or churn modeling.

CHURN
The churn is the term describing the joining and leaving of peers in a P2P system. The vitality and amount of available resources of a P2P system depends on its churn. Modeling churn is important, because it is virtually impossible to test the design of P2P systems on a real scale, with thousands or millions of devices. In 2006, Daniel Stutzbach and Reza Rejaie from the University of Oregon attempted to study churn in different P2P systems, and more specifically the uptime and downtime of peers (i.e., session duration). Their findings indicate that sessions length seem to follow a Weibull distribution.

Economical
The economical and financial implications of new technologies have a big impact on adoption of by private sector companies. If they can help save money or make money on the long term, they always appeal to many. Else, they don't.

Costs And Return On Investment
Contrary to many other technologies, JXTA does not require much resources, such as servers, bandwidth, and technicians to operate, since it relies mostly on the resources of each device to operate the network. Its general design makes it more economical than traditional client/server applications. Therefore, it is a competitive technology on the market regarding operational costs. Other costs include training (i.e., time required to learn about JXTA) and software implementation or redesign costs. Some companies prefer not to invest in new technologies and to stay with the devil they know. This logic makes economical sense, since they don't have to go through the effort About The Future... ...Of P2P - 252

of rewriting their application or training their personnel. This strategy brings a kind of comfort which can be sufficient for them. If it does the job, why change it? A common mistake when taking a look at costs is thinking at a micro level and not considering the macro level, or forgetting to take hidden costs into account. A complete analysis can cut both ways. It can result in a positive or negative surprise. This issue is not specific to JXTA, it applies to all technologies. The balance of forces pushing for or against new technologies from an economical point-of-view is often summarized in the return on investment. However, linear thinking rarely produces linear results in finance and economy. Let's explain this deeper with an example. Many companies have become quite wary about IT investments since the end of the nineties. Many have invested fortunes in systems that were supposed to save them a lot of time and money, but the benefits never reached expectations. Some readers may be tempted to attribute this to the Internet bubble, but that is a vague explanation. Firstly, the Internet bubble was not caused by the Internet itself, but was the result of a change in the financial methods used to valuate companies in the early nineties. Instead of only taking into account the tangible assets and debts of companies, one would take into account the potential profit a company could make in the future. Since small Internet companies had the potential to access millions of customers with very little resources, they were valuated at sky level limits. It was easy to make money on Wall Street at that time, you just had to invest in virtually anything related to IT or the Internet. On the other side, the rise of the IT industry in the 1990's led many companies to adopt a “go west, young man”-like attitude to capture markets and customers. Some developed more and more complex products offering more and more functionalities to satisfy the customer's demand regardless of technologies' maturity and constraints. Products were delivered with bugs and the promise of a solution in the next version. It was a time when customers would buy that. Unfortunately, complexity is the highway to bugs in software applications; it had to have some consequences. This situation created a concurrent access on competent technical resources, which led to scarcity and exorbitant wages. The offer was far from meeting the demand and what happened had to happened. Many small Internet companies never managed to live up to their expectations. Investors decided to stop investing and the bubble burst. This did not reduce the tension on demand for competent resources which remained very high. This triggered India's and other countries' About The Future... ...Of P2P - 253

boom in the IT industry. Some pieces of software became incredibility expensive to maintain (i.e., much more than anticipated), not only because of the scarcity of technical competence, but also because of software complexity itself, destroying any return on investment previsions. IT Industry clients became much more demanding in the quality of software applications and cautious when investing in new systems. They felt the financial pinch and did not forget it. This illustrates that costs have major impacts in the adoption and evolution of technologies in general, but that these impacts are not linear or necessarily predictable on the long term. Although JXTA offers some apparent economical benefit, we cannot rely on a linear or progressive prediction regarding its future level adoption using that criteria only.

Potential For Profit
We have seen that P2P technologies have been used in the past to exchange copyright protected content over the Internet. We have also seen that this issue was not inherent or caused by P2P applications themselves, but by the way they were designed. The illegal copying of digitally protected content is a complex issue. It is comparable to photocopying books or paper documents illegally. One cannot prevent it fully. Copyright laws help protecting authors and mitigating this issue, but it is far from being perfect in this electronic age. There is a possibility to encrypt and to protect access to electronic documents. However, attempts on music and video files have not been accepted very well by end users since they have the possibility to create their own digital content. The two fundamental questions are: where can one put control from a technological and legal point-of-view? And where should this control be enforced? Making profit by offering access to content or to services requires being capable of controlling who is accessing these resources. This has been made possible with client/server applications; why wouldn't it be possible with P2P applications? It is just a matter of controlling access to peers, rather than servers. The author strongly believes that JXTA based applications can be made profitable by implementing a proper access-to-resources license system to peers containing resources or offering services for example. This will raise more and more business attention sooner or later.

About The Future... ...Of P2P - 254

...Of JXTA
Technological
Simplification Of Complexity - Universality
If a technology can help in streamlining business operations or have a positive impact on operational efficiency, there is a higher probability that it will be adopted. If it helps to develop new and efficient end-to-end processes, standardize behaviors or if it facilitates interoperability and communications on available platforms, its adoption factor will increase too. JXTA can help software developers and engineers developing software applications without having to worry about Internet connectivity issues or protocol issues. It can be used to facilitate the communication and the exchange of services between heteroclite systems. The capacity to integrate diversity is one of its key features, making it very interesting to those who are looking forward to integrate systems or to deploy applications on diverse systems and devices. JXTA can be considered and used as a catalyst to simplify complex system by relying on its universality.

New Applications
The set of applications based on JXTA and P2P concepts has most probably not reached its peak yet. Just like petrol was considered as a hassle on one's land at the end of 19 century, it turned out to be very profitable and to have thousands of applications in our economy today. JXTA is universal in its intention and P2P has already demonstrated some surprising applications, such as phoning over the Internet with Skype. The author strongly believes that many software developers and architects will find new ways to use JXTA and P2P concepts in general as these will become more and more popular and understood.
th

Accountability & Vendor's Credibility
The traditional proprietary versus open source technology arguments apply to JXTA, since it is part of the open source. On one side, proprietary technologies engage the accountability and the credibility of those providing it. This can make clients more comfortable, because they know that if there is an issue with the technology, the provider's profitability and credibility is on the line. But has this always been true in markets dominated by unique players (i.e., monopolies)? If there is no other choice available, About The Future... ...Of JXTA - 255

where is the pressure on the provider to adapt? If there are other choices, how much does it cost to shift to another technology? Is that barrier high? If yes, does it play in favor of the customer? On the other side, open source technologies are free, but no one is really responsible for them. This can put a stress on the customer, since they cannot really blame anyone if there is an issue. Yet, several technologies coming from the open source have been pretty successful; for example, Linux and its multiple versions, MySQL (a database system) and Apache, which runs many web servers today. Many companies have adopted them regardless of the risk. It seems like since everyone has an interest in seeing those free technologies work for the benefit of everyone; individuals manage to make them work. Economically speaking, some big companies have an interest in spending resources to make open source technologies work to satisfy their needs, because if they had to buy a product on the market, it would cost them more to satisfy their needs. If many engineers are using these technologies, the training effort also diminishes. Many public and private companies, have investigated and been pushing for universal IT standards. Many have decided to use open source technologies, because they did not want to be locked with specific vendors anymore. The pendulum of the quality/price ratio of IT that was lost at the beginning of the Millennium has come back to balance today. A couple of years ago, there has been a trend from dominating IT software companies to provide their technologies for free in order to stop the flow of developers who are moving to open source technologies. The rise of operational alternatives has created competition and some market efficiency. However, there are two limits to the development an open source technology: a) one will contribute to its development if and only if it helps him/her save some money globally and b) the contributor must have revenues coming from side activities, else he/she will not be able to contribute. If one of these conditions is not met, the support for the development of a given open source technology goes down and it may eventually be abandoned.

Educational
Documentation, Books And Tutorials
A technology can only be well adopted if it is properly and well documented. Software developers and architects need access to these documents to learn about the technology and how to use it. As for many open source technologies, access to proper documentation, books and tutorials have been JXTA's weakness, especially in recent years when the technology has undergone many About The Future... ...Of JXTA - 256

changes. Several books have been published about JXTA the year 2002. Today, most have become obsolete although some still have informative chapters. Nevertheless, today's newcomers to JXTA are still facing difficulties understanding and setting up their own JXTA network. The purpose of this book is to help them bridge that knowledge gap and make JXTA more accessible to those interested in using it. The good news is that all those who have crossed the initial difficulties of learning about JXTA and of making it work are actually very happy with it. The author hopes that this book will accelerate this learning process and that it will boost the JXTA adoption factor in general. In addition, the Programmer's Guide version 2.6 contains a chapter describing what is happening 'under the hood'.

Code Examples
Sometimes, just words in books and documents are not always as good as code examples when it comes to understand new technologies. People learn in different ways and often need concrete examples of code to understand how they should proceed to achieve their objectives. This book also provides several small code examples. It has been written with the intention of having its readers understand JXTA concepts one by one and to let them use them in their own applications as building blocks with little adaptation.

The Community
The JXTA trademark belongs to Sun Microsystems. Since the acquisition of Sun Microsystems by Oracle, the future of the structure supporting the JXTA technology has been questioned. Sun's involvement has significantly diminished since release 2.5, although some individuals have remained available to answer technical questions. Today, JXTA contributors still have to sign a Sun's Contributor Agreement (SCA), which fundamentally protects Sun Microsystems for its usage of the technology in Glassfish . Unfortunately, this administrative approval process has become very slow and reminders often had to be sent for follow-up. It has become dysfunctional and yet, the JXTA community could do with more contributors. It is essential for its development. The board of directors is made of three members, one appointed by Sun Microsystem and 2 elec60 See https://glassfish.dev.java.net/.
60

About The Future... ...Of JXTA - 257

ted by the community. Unfortunately, the provisions of board rules leave little power to elected members when it comes to legal empowerment and decision making on fundamental issues. This is another dysfunctional issue of the current structure. Three evolutions are possible:
• • •

The situation stays as is, with its flaws. The community migrates to Apache, which requires Sun/Oracle's approval. The community decides to branch out under a new name, since the current code license allows it.

Only time will tell.

The Protocols
The latest version of the JXTA protocols is 2.0. Some areas need a refresh and clarification. Some member of the community have been requesting a binary wiring of messages instead of using XML. In fact, version 2 of binary wiring is already specified in the specifications, but has not been implemented yet.

JXTA vs. OSGi
Another lurking issue is the future of services in the JXTA protocols. Peers are allowed to fetch and load services, but as we know, Java is ill-equipped to implement these via .jar. On the other side, OSGi has already solved this problem. Does it make sense to put more efforts in re-inventing the wheel? Should JXTA stick to P2P issues only and delegate other issues to other technologies? The answer is probably yes.

...Of JXSE
Security
Security has become one of the key features that companies and users are looking for in software applications. Information and access to information has become vital in the new economy. JXTA is allowing software developers and architects to use TLS 1.0 or to implement their own security system on the transportation layer offered by JXTA. JXSE provides enough security for private communications and exchange of non-sensitive information. However, it is not sufficient to meet US administration standards for example. Providing ac-

About The Future... ...Of JXSE - 258

cess to TLS 1.1 cipher suites and to the possibility of revoking weak cipher suites would help in solving this issue.

Cache Pollution
The mechanism allowing signing advertisements and secured filtering of information exchanged between peers has not been finalized yet in JXSE. It is possible for anyone to pollute cache of remote peers using remote publication for example. A long term solution is required.

Conclusion
JXTA belongs to the open source and is available for free. It has every chances of becoming the leading P2P technology for software development, since this field remains to be investigated in the IT industry on a broad scale. Therefore, one can reasonably expect that JXTA and P2P technologies have their future ahead.

About The Future... Conclusion - 259

- 260

Appendix
Protocol Messages Types
Protocols Peer Discovery Protocol Sub-Protocols Message Discovery Query Message Discovery Query Response Peer Information Protocol Pipe Query Message Pipe Response Message Peer Resolver Protocol Resolver Query Message Resolver Query Response SRDI Message Pipe Binding Protocol Rendezvous Protocol Message Propagation Protocol PeerView Protocol Rendezvous Lease Protocol Pipe Resolver Message Lease Request Message Lease Granted Protocol Lease Cancel Protocol Endpoint Routing Protocol Route Query Message Route Response Message NACK Message

Appendix

- 261

Advertisement Attributes
The following pages provide the list of attributes for each advertisement defined by JXTA as of version 2.5.3 of the specification document.

Peer Advertisement
Attribute <PID> <GID> <Name> <Desc> <Svc> Description Peer ID Peer Group ID Peer name Peer description Set of group services parameter pairs class IDs and Required Yes Yes No No No

Peer Group Advertisement
Attribute <GID> <MSID> <Name> <Desc> <Svc> Description Peer Group ID Module Specification ID of the Peer Group Peer Group Name Peer Group description Set of group services class IDs parameter pairs and Required Yes Yes No No No

Module Class Advertisement
Attribute <MCID> <Name> <Desc> Description Module Class ID Class Name Class description Required Yes No No

Module Specification Advertisement

Appendix Advertisement Attributes - 262

Attribute <MSID> <Vers> <Name> <Desc> <CRTR> <SURI> <Param>

Description Module Specification ID Version of the specification Specification name Specification description Creator of the specification URI to a document providing information about this specification Any parameter to be interpreted by each JXTA implementation

Required Yes Yes No No No No No No

<jxta:PipeAdvertisement> Possibility to bind to a pipe input end of a nearby running implementation of this specification. This is an embedded pipe advertisement. <Proxy> Module Specification ID of a proxy module which can be used to communicate with modules of this specification Module Specification ID of an authenticator module that may be required to communicate with modules of this specification

No

<Auth>

No

Module Implementation Advertisement
Attribute <MSID> <Comp> <Code> <PURI> <Prov> <Desc> <Param> Description Module Specification ID Compatibility element describing the environment in which this implementation may be executed. Contains anything that is needed to load and execute the code of this implementation. It can be the code itself. URI to package containing the code of this implementation if it is not delivered in <Code> itself The provider of this implementation URI to a document providing information about this specification Any parameter to be interpreted by each JXTA implementation Required Yes Yes No No Yes No No

Pipe Advertisement

Appendix Advertisement Attributes - 263

Attribute <Id> <Type> <Name>

Description Pipe ID Type of the pipe (JxtaUnicast, JxtaUnicastSecure or JxtaPropagate) Pipe Name

Required Yes No No

Rendezvous Advertisement
Attribute <RdvGroupId> <RdvPeerId> <RdvServiceName> <Name> <RdvRoute> Description Peer Group ID for which the peer is a rendezvous Peer ID Peerview to which the rendezvous peer belongs (i.e., name of a service handler) Name of the rendezvous peer Embedded route advertisement Required Yes Yes Yes No No

Route Advertisement
Attribute <PID> <EA> <DstPID> <Dst> <Hops> Description Peer ID (not required in a context where the Peer ID is known) Endpoint Address for the peer Destination Peer ID Embedded Access Point Advertisement Semi-ordered collection Advertisement of Access Point Required No No No Yes

Access Point Advertisement
Access point advertisements are not described in terms of attributes, since they are made of a list of endpoint addresses for peers. Do not forget that a peer can publish several endpoint addresses for multiple network communication protocols.

Appendix Advertisement Attributes - 264

Index
2
2-tier 21 Astrologer Astrology Service Asymmetric Key Attribute Authentication Code Author About the Ayrton, The Edge And JXTA Socket 239 234 114 70 115 11 226

A
Access Control 71, 142 Implementation 152 Access Point Advertisement 56 Access Service 45, 72 Accessibility LAN 96 Subnet 96 WAN 95 Acknowledgments 11 Address Pooling 109 Adelaide, The RendezVous At One End 217 ADHOC 144 Advertisement 47 Access Point 264 Attributes 262 Caching 48 Customized 198 ERP 56 Finding 188 Module Class 262 Module Implementation 263 Module Specification 262 Peer 262 Peer Group 262 Pipe 64, 263 Registering a Customized Instance 202 Remote Search 190 RendezVous 264 Retrieving and Flushing Local 188 Route 264 AES 114, 117, 151 ALG 106 Alice, Bob and Eve 113 Aminah, The Other RendezVous 174 ANB 89 Anna, The Edge 169 Anonymity 28 Anti-Virus 17 Application layer 35 Application Layer Gateways 106 ARPANET 18 Artificial Network Boundaries 89

B
Behave Compliant NAT Binding C/C++ JXME Birthday Paradox BitTorrent Block Cipher Mode Boat Broadcasting Bruce Schneier Business Logic 108 37 37 124 28 151 39 81 12, 16, 131 21

C
C/C++ 37 CAN 251 Capacity 142 CBC 151 CDC 37 Centralized Computer System 20 Certificate Authority 115 Certificate Practice Statement 120 Certificate Revocation List 120 Certification of Certificate Authority 120 Chandra, The Rendezvous Listening to Messages 211 Chihiro, The Other Edge 175 Chord 251 CHURN 252 Cipher Suite 135 Cipher-Block Chaining (CBC) 151 CLDC 37 Client/Server 20 Cloud Computing 23 Clustering 21 Codats 50

Appendix Index - 265

Collision Issue Communication Protocol Suite ConfigParam Loading From a URI Configuration Objects Configuration Mode Configuration Parameters Connected Device Configuration Connected Limited Device Configuration Connectivity Issues Content Copyright Infringement Core layer Correspondent Inference Theory Counter (CTR) CPS CRL Cryptography Assumptions Implementating Your Own Layer CTR Customer

124 33 159 159 160 143 159 37 37 163 50 17 35 16 151 120 120 151 125 151 151 241

Duties Certificate Authority

120

E
EDGE Edge Probe Edward E. Jones Endpoint Receiving Sending Endpoint Address Endpoint Routing Protocol (ERP) Endpoint Service ERP Exportation Limitations 144 60 16 54 63 63 54 53, 54 46, 53 53 151

F
Failure Notification Firewall Overcoming Forum Freenet Frequently Asked Questions (FAQ) Full Cone Full-Featured Edge Peer FutureNet 60 83 90 37 28 37 100 143 88

D
Database Datagram Decentralization DES Design Principles Dictionary Attack Diffie-Hellman Digital Rights Management Dimitri, The Edge Sending Messages Direct Routing Directory Services Discovery Operations Discovery Query Message Discovery Query Response Discovery Service Distinctive Sign Distributed Communication Distributed Computing Divisible Problem Domain Name System (DNS) Dried Leaf DRM 20 82 19, 26 137 20 131 117 126 213 80 123 188 70 70 46 39 19 23, 29 29 33 47 126

G
Gaia Gnutella Grid Computing Groove Groove Networks 44 26 23 16 16

H
Hairpin Issue 98 Handler 65 Handshake 3-way 81 Hans, The Rendezvous, A Multicast Participant 229 Hash Function 116, 123 Hops 54 Host 80 HTTP Default Port 149

I
IANA ICE 83 107

Appendix Index - 266

ICE-TCP ICMP ICQ ID Creation Creation Of A Peer Importation From Other Systems Well-known Identity Definition in JXTA Issues IETF Ignition Process Illusion DRM Inclusion Indirect Routing Indivisible Problem Internet Introduction Secure Communication IP Address Addresses as Identities Automatic Change of Address Default Ports External Gateways Internal IP Obstacles IPv4 IPv6 Island

108 105 24 49 183 141 141 74 140 139 134 73 126 142 80 29 18 114 80 80 139 159 149 85 80 85 97 81 81 39

Shell Transportation Layer Using JXTA Bootstrapping Concept Overview Core Specification First Connection Layer Peer Types Project Protocols Security Layer Specification Document Starting And Stopping Transportation Layer JXTA Multicast Socket JXTA Socket JXTA Socket Server

250 90 153 34 74 40 42 154 34 143 36 52 135 36 154 89 229 223 223

K
Kademlia Kazaa Keith Davis Key Asymmetric Symmetric Key Size KeyStore Creation Types Working With Kings & Queens Koorde 251 27 16 114 114 125 127 128 135 205 39 251

J
Jack, The Rendezvous Java Cryptography Architecture Java ME Javadocs JXTA Jill, The Customer JKS Joe, The Astrologer JXME JXSE Community Configuration Mode Configuration Modes Cryptographic Layer Documentation 167 127 37 154 241 135 239 37 36 143 144 113 37

L
LAN 80 Lease 61 Lease Cancel Message 61 Lease Granted Message 61 Lease Request Message 61 Lidong, The Rendezvous And JXTA Socket Server 223 Load balancing 21 Local Configuration 154 Creation 156 Directory Structure 160 Modifying 157 Prevent Creation Of 155 Retrieving 157 Saving 157

Appendix Index - 267

M
MAC 116 Mainframe 18 Mapping Arbitrary 109 Paired 109 MARS 151 Master Server 22 Matryoshka Doll 53 Maven 154 Maxime, The Socializer 190 MD5 123, 137 Membership Control 142 Membership Service 46, 72 Message 53 Adding an Advertisement 197 Creating An Empty 194 Duplicate 61 ERP 56 Individual 58 Loop 61 Protocol Types... 261 Sending With Endpoint Service 249 Message Authentication Code 116 Message Element 53 Adding 194 Retrieving 195 Message Propagation Protocol 58 Metaphor Tribes-in-islands 39 Metaphors 42, 44, 48-50, 53-55, 60, 64, 66, 84, 89, 90, 141, 155, 157, 158, 172, 173, 179, 184, 185, 188, 190, 193, 203, 216, 239 Middleware 22 MIDP 37 Minimal Dialect 39 Minimal Edge Peer 143 Mobile Information Device Profile 37 Modern Cryptography 21 Module 50 IDs Creation 233 Implementation of 73 Module Class Advertisement 51 Module Class ID 51 Module Implementation Advertisement 52 Module Specification Advertisement 51 Module Specification ID 51 Monitor Filter 68 Monitor Listener 68

Monitor Report Monitoring Multi-tier Multicasting Default IP Address Default Port Multiple Peer In Same JVM

68 142 21 81 150 150 166

N
NACK Message 56 Napster 25 Napster Napster 19 NAT 84 Limitations 86 Overcoming 91 Traversal 97 NATBlaster 104 National Institute of Standards and Technology 114 NatTrav 104 Natural Network Boundaries 88 Needs 23 Neil Ferguson 131 Net Peer Group 43 NetBeans 153, 167 NetBeans Creating A Project 153 Network Address Translation 84 Network Administration 149 Network Communication 20 Network Configurator 157 Network Manager 155 Network Scope 147 Network Transport layer 80 New NAT Classification 102 Niels Ferguson 12 NIST 114 NNB 88 Nomadic 41, 56 NSA 125 NUTSS 103

O
OSGi Connection Ouroboros 160 41, 117, 118

P

Appendix Index - 268

P2P Benefits 30 Drawbacks 30 Initial Objectives 29 Introduction 16 Pure 28 Pure P2P network 28 Reputation 16 P2PNAT 103 Panama 43 Participant Probe 60 Participant Referral Response 60 Participant Response 60 Pastry 251 PAT 86 PBP 63 PC 18 PDA 41 PDP 70 Peer 41 Accessibility 95 Advertisement 48 Blind 95 Creation 184 Distant 95 Inaccessible 90, 95 Pockets 95 Running Multiple ... on a Single Device 166 Peer Discovery Protocol (PDP) 70 Peer Group 43 Advertisement 48 As A Service 74 Creation 141, 185 Identity 141 Parent 44 Peer Info Service 46 Peer Information Protocol (PIP) 68 Peer Information Service Activation 245 Peer Monitor Info 69 Peer Resolver Protocol (PRP) 65 Peer to Peer 16 Peerview Message 59 Rendezvous 59 PeerView Protocol 59 Personal Computer 18 Personal Security Environment (PSE) 127 Ping 245 Ping

Instruction PIP PIP Query Message PIP Response Message Pipe Advertisement Bidirectional Communication JxtaPropagate JxtaUnicast JxtaUnicastSecure Simple Communication Unicast secure Unidirectional Asynchronous Unicast Pipe Binding Protocol (PBP) Pipe Resolver Message Pipe Service Pipes PKCS#12 PKI Platform layer PlatformConfig Port Blocked Listening Port Prediction Prerequisites Principal Private Key Encryption Exporting And Importing Private Key System Probe Message Propagate Pipe Message Header Propagation Control Protocol Understanding The Role Of Proxy Proxy Overcoming PRP PSE Configuration Public Key Infrastructure Public Key System Publication Local And Remote Punching Holes PWNAT

105 68 69 69 64 217 63 63 63 210 217 63 63 64 46 50 135 119 35 157 82 83 81, 82 98 15 123 135 203 114 59 65 59, 61 32 87, 146 92 65 132 119 114 48 194 98 105

Q Appendix Index - 269

Queries Query Customized Multicasting Quinisela, The Edge At The Other End

20 249 96 220

Router Multicasting Versus Subnets RSA Ruler RVP

87 87 114 41 58

R
RC6 Relay Connectivity To Be or Not To Be? Relay Peer Relay Service RendezVous Automatic Reconnection Peer Connection to To Be or Not To Be? Rendezvous Advertisement Rendezvous Lease Protocol Rendezvous Peer Rendezvous Peer Connection Rendezvous Protocol (RVP) Rendezvous Service Requirements JXTA Resolver Query Message Resolver Response Message Resolver Service Resolver SRDI Message Resource Response Message Restricted Cone RFC RFC 4787 RFC 5245 RFC 5382 RFC 5128 Rijndael Rings RIPEMD Robert, The Relay Route Route Direct Route Advertisement Route Query Message Route Resolver Query Route Response Message 151 145 182 147 42, 143 91 145 178 61 148 60 61 42, 143 59 58 46, 58 41 66 66 46, 65 67 47 59 100 109 107 108 99 114 80 123 180 55 54 56 56 55 56

S
Salt-And-Stretch 131 Salting 131 Seclusion 142 Secure Socket Layer (SSL) 134 Seed 28, 94 Seed Implementation 150 Multiple Layer 149 Number of 149 Segment 80 Self-Service 244 Serpent 151 Service 44 About Implementation of... 146 About Registering Handlers 250 Astrology 40, 234 Customized 233 Implementation of 74 Loading 77 Peer Group Level Implementation 245 Peer Level Implementation 245 Service layer 35 Service Metric 68 Service Monitor 68 Service Monitor Filter 68 Service Oriented Architecture 22 SETI 29 SHA 123, 131, 151 Shared Resource Distributed Index (SRDI) 66 Shell 250 Shutdown Notification 60 Sign 39 Skype 29, 255 Slave 22 SOA 22 SRDI service 67 STUN 99 STUNT 100 STUNT #1 101 Subnet 80 About... 150 Configuration 150

Appendix Index - 270

Super node Symmetric Symmetric Key

27 100 114

T
Tapestry 251 TCP 81 Handshake 81 Tebogo, The Jazz Fan 194 Teyacapan, The Edge, Another Multicast Participant 231 Three Layer Cake 35 Three-tier 21 Tiger 123 Time Sharing 24 Time To Live (TTL) 26, 61, 65 TLS 63, 134, 135, 151, 258 Transport Layer Security 63 Transport Security Layer (TLS) 134 Tribe Language 39 Tribes 39 Tribes-in-Islands 39 Trojan Horse 83 TTL-less Version of STUNT 102 TURN 99 Twofish 151

UDP Unicast Unicast Secure Pipes Universality P2P UPnP URI URL URN

82 81 217 32 107 15 15 15

V
Value Virtual Private Network (VPN) 70 134

W
Weather Forecasting Method Web 2.0 Web Of Trust World Peer Group 40, 244 23 121 43

X
X.500 Principal X.509 Automatic Certification Creation Exporting And Importing Registration XML 123 123 122 128 203 132 35

U

Appendix Index - 271

You're Reading a Free Preview

Download
scribd
/*********** DO NOT ALTER ANYTHING BELOW THIS LINE ! ************/ var s_code=s.t();if(s_code)document.write(s_code)//-->