not assigned M. Duigou Internet-Draft Project JXTA Expires: August 28, 2003 February 27, 2003 JXTA v2.0 Protocols Specification draft-duigou-jxta-protocols-02 Status of this Memo This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http:// www.ietf.org/ietf/1id-abstracts.txt. The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. This Internet-Draft will expire on August 28, 2003. Copyright Notice Copyright (C) The Internet Society (2003). All Rights Reserved. Abstract The JXTA protocols defines a suite of six XML-based protocols that standardize the manner in which peers self-organize into peergroups, publish and discover peer resources, communicate, and monitor each other. The Endpoint Routing Protocol (ERP) is the protocol by which a peer can discover a route (sequence of hops) to send a message to another peer potentially traversing firewalls and NATs. The Rendezvous Protocol (RVP) is used for propagating a message within a peergroup. The Peer Resolver Protocol (PRP) is the protocol used to send a generic query to one or more peers, and receive a response (or multiple responses) to the query. The Peer Discovery Protocol (PDP) is used to publish and discover resource advertisements. The Peer Information Protocol (PIP) is the protocol by a which a peer may obtain status information about another peers. The Pipe Binding Duigou & Project JXTA Expires August 28, 2003 [Page 1] Internet-Draft JXTA v2.0 Protocols Specification February 2003 Protocol (PBP) is the protocol by which a peer can establish a virtual communication channel or pipe between one or more peers. The JXTA protocols permit the establishment a virtual network overlay on top of physical networks allowing peers to directly interact and organize independently of their network location and connectivity. The JXTA protocols have been designed to be easily implemented on unidirectional links and asymmetric transports. Production Notes Third Internet-Draft submission. This draft has been generated from a DocBook XML file which was transformed into an RFC 2629 XML source file. This draft does not include the tables from the original XML source as table conversion has yet to be implemented. To review the tables please access the XML source or HTML and PDF output versions at http://spec.jxta.org Duigou & Project JXTA Expires August 28, 2003 [Page 2] Internet-Draft JXTA v2.0 Protocols Specification February 2003 1. Conventions The following conventions are used throughout this document. 1.1 Significant Keywords The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, NOT RECOMMENDED, MAY, and OPTIONALin this document are to be interpreted as described in "IETF RFC 2119" [RFC2119] [5]. 1.2 Text Representations All strings and text found in the JXTA Protocols should be assumed to be encoded using Unicode [USA28] [13]Canonical UTF8 (NFC) (see Unicode Standard Annex #15 : Unicode Normalization Forms [USA15] [12]) unless otherwise specified. Duigou & Project JXTA Expires August 28, 2003 [Page 3] Internet-Draft JXTA v2.0 Protocols Specification February 2003 2. Introduction 2.1 The JXTA Protocols The JXTAprotocols are a set of six protocols that have been specifically designed for ad hoc, pervasive, and multi-hop peer-to-peer (P2P) network computing. Using the JXTA protocols, peers can cooperate to form self-organized and self-configured peer groups independent of their positions in the network (edges, firewalls, network address translators, public vs. private address spaces), and without the need of a centralized management infrastructure. The design of the JXTA protocols seeks to create a set of protocols that have very low overhead, make few assumptions about the underlying network transport and impose few requirements on the peer environment, and yet are able to be used to deploy a wide variety of P2P applications and services in a highly unreliable and changing network environment. Peers use the JXTA protocols to advertise their resources and to discover network resources (services, pipes, etc.) available from other peers. Peers form and join peergroups to create special relationships. Peers cooperate to route messages allowing for full peer connectivity. The JXTA protocols allow peers to communicate without the need to understand or manage the potentially complex and dynamic network topologies which are increasingly common. The JXTA protocols allow peers to dynamically route messages across multiple network hops to any destination in the network (potentially traversing firewalls). Each message carries with it either a complete or partially ordered list of gateway peers through which the message might be routed. Intermediate peers in the route may assist the routing by using routes they know of to shorten or optimize the route a message is set to follow. The JXTA protocols are composed of six protocols that work together to allow the discovery, organization, monitoring and communication between peers: o Peer Resolver Protocol (Section 4.4.1)( PRP) is the mechanism by which a peer can send a query to one or more peers, and receive a response (or multiple responses) to the query. The PRPimplements a query/response protocol. The response message is matched to the query via a unique id included in the message body. Queries can be directed to the whole group or to specific peers within the group. o Peer Discovery Protocol (Section 5.2.1)( PDP) is the mechanism by which a peer can advertise its own resources, and discover the Duigou & Project JXTA Expires August 28, 2003 [Page 4] Internet-Draft JXTA v2.0 Protocols Specification February 2003 resources from other peers (peer groups, services, pipes and additional peers). Every peer resource is described and published using an advertisement. Advertisements are programming language-neutral metadata structures that describe network resources. Advertisements are represented as XML documents. o Peer Information Protocol (Section 5.2.3)( PIP) is the mechanism by a which a peer may obtain status information about other peers, such as state, uptime, traffic load, capabilities, etc. o Pipe Binding Protocol (Section 5.2.4)( PBP) is the mechanism by which a peer can establish a virtual communication channel or pipe between one or more peers. The PBP is used by a peer to bind two or more ends of the connection (pipe endpoints). Pipes provide the foundation communication mechanism between peers. o Endpoint Routing Protocol (Section 4.4.2)( ERP) is the mechanism by which a peer can discover a route (sequence of hops) used to send a message to another peer. If a peer "A"wants to send a message to peer "C", and there is no known direct route between "A"and "C", then peer "A"needs to find intermediary peer(s) who will route the message to "C". ERP is used to determine the route information. When the network topology has changed such that the route to "C"can no longer be used, because a link along the route no longer works, the peer can use ERP to find any routes other peers know to construct a route to "C". o Rendezvous Protocol (Section 5.2.2)( RVP) is the mechanism by which peers can subscribe or be a subscriber to a propagation service. Within a PeerGroup, peers can be rendezvous peers, or peers that are listening to rendezvous peers. The Rendezvous Protocol allows a peer to send messages to all the listening instances of the service. The RVP is used by the Peer Resolver Protocol and by the Pipe Binding Protocol in order to propagate messages. All of these protocols are implemented using a common messaging layer. This messaging layer is what binds the JXTA protocols to various network transports. (see Messages (Section 4.6)) Each of the JXTA protocols is independent of the others. A peer is not required to implement all of the JXTA protocols to be a JXTA peer. A peer only implements the protocols that it needs to use. Examples: o A device may have all the necessary advertisements it uses pre-stored in memory, so that peer does not need to implement the Peer Discovery Protocol. Duigou & Project JXTA Expires August 28, 2003 [Page 5] Internet-Draft JXTA v2.0 Protocols Specification February 2003 o A peer may use a pre-configured set of router peers to route all its messages, hence the peer does not need to fully implement the Endpoint Routing Protocol, it just sends messages to the known routers to be forwarded. o A peer may not need to obtain or wish to provide status information to other peers, hence the peer might not implement the Peer Information Protocol. There are two protocols which each peer must implement in order to be addressable as a peer: the Peer Resolver Protocol, the Endpoint Resolver Protocol. These two protocols and the advertisements, services and definitions they depend upon are known as the JXTA Core Specification. The JXTA Core Specification (Section 4)establishes the base infrastructure used by other services and applications. The remaining JXTA protocols, services and advertisements are optional. JXTA implementations are not required to provide these services, but are strongly recommended to do so. Implementing these services will provide greater interoperability with other implementations and broader functionality. These common JXTA services are known as the JXTA Standard Services. +------------------------+ +------------------------+ | +------------------+ | | +------------------+ | | | Peer Information | <-------> | Peer Information | | | +------------------+ | | +------------------+ | | | | | | +------------------+ | | +------------------+ | | | Peer Rendezvous | <-------> | Peer Rendezvous | | | +------------------+ | | +------------------+ | | | | | | +------------------+ | | +------------------+ | | | Pipe Binding | <-------> | Pipe Binding | | | +------------------+ | | +------------------+ | | | | | | +------------------+ | | +------------------+ | | | Peer Discovery | <-------> | Peer Discovery | | | +------------------+ | | +------------------+ | |Peer | |Peer | +------------------------+ +------------------------+ +------------------------+ +------------------------+ | +------------------+ | | +------------------+ | | | Peer Resolver | <-------> | Peer Resolver | | | +------------------+ | | +------------------+ | | | | | | +------------------+ | | +------------------+ | Duigou & Project JXTA Expires August 28, 2003 [Page 6] Internet-Draft JXTA v2.0 Protocols Specification February 2003 | | Endpoint Routing | <-------> | Endpoint Routing | | | +------------------+ | | +------------------+ | |Endpoint | |Endpoint | +------------------------+ +------------------------+ +------------------------+ +------------------------+ | Transport | | Transport | +------------------------+ +------------------------+ Figure 1: JXTA Protocols A peer may decide to cache advertisements discovered via the Peer Discovery Protocol for later usage. It is important to point out that caching is not required by the JXTA architecture, but caching can be an important optimization. The caching of advertisements by a peers avoids performing a new discovery each time the peer is accessing a network resource. In highly-transient environment, performing the discovery is the only viable solution. In static environments, caching is more efficient. A unique characteristic of P2P networks, like JXTA, is their ability to spontaneously replicate information toward end-users. Popular advertisements are likely to be replicated more often, making them easier to find as more copies become available. Peers do not have to return to the same peer to obtain the advertisements they are interested in. Instead of querying the original source of an advertisement, peers may query neighboring peers that have already cached the information. Each peer may potentially become an advertisement provider to any other peer. The JXTA protocols have been designed to allow JXTA to be easily implemented on uni-directional links and asymmetric transports. In particular, many forms of wireless networking do not provide equal capability for devices to send and receive. JXTA permits any uni-directional link to be used when necessary, improving overall performance and network connectivity in the system. The intent is for the JXTA protocols to be as pervasive as possible, and easy to implement on any transport. Implementations on reliable and bi-directional transports such as TCP/IP or HTTP should lead to efficient bi-directional communications. The JXTA uni-directional and asymmetric transport also plays well in multi-hop network environments where the message latency may be difficult to predict. Furthermore, peers in a P2P network tend to have nondeterministic behaviours. They may join or leave the network on a very frequent basis. Duigou & Project JXTA Expires August 28, 2003 [Page 7] Internet-Draft JXTA v2.0 Protocols Specification February 2003 2.2 JXTA Assumptions This section is a guide to the assumptions that inform the design of JXTA. There are two types of assumptions stated here, those which describe the requirements of JXTA implementations and those which describe the expected behaviour of the JXTA network. A peer SHALL NOTmake assumptions about the runtime environments or programming languages in use by another peer. The network of peers reachable by any peer is likely to be contain many peers with very heterogeneous implementations and capabilities. A peer SHOULDassume that the capabilities and complexity of the network peers supporting these protocols can range from a single light switch to a highly-available supercomputer cluster. A peer MUSTimplement the JXTA protocols such that all interaction with other peers is correct and conformant. A peer MAYimplement only the JXTA protocols it requires for correct and conformant interaction with other peers. A peer MAYchoose to partially implement protocols if unimplemented portions will never be used. (e.g. client-side or server-side only) Peers wishing to interact with other peers within the JXTA network SHOULDbe willing to participate fully in the protocols. In particular, peers SHOULDcache advertisements and forward messages for other peers in the JXTA network. But, this participation is OPTIONAL. The JXTA protocols MAYbe deployed over a wide variety of network configurations including the Internet, corporate intranets, a dynamic proximity network, or in a home networking environment. Applications should avoid assumptions about the underlying network environment. Peers receiving a corrupted or detectably compromised message MUSTdiscard the message. Messages may be corrupted or intentionally altered during network transmission. Peers MAYappear, disappear and migrate at any time without notice. In particular, the JXTA protocols support very arbitrary environment changes allowing a peer to dynamically discover and reconnect to its changing environment. The Communication path between any pair of peers MAYat times not work equally well in both directions. That is, communications between two peers will in many cases be able to operate bi-directionally, but at times the connection between two peers may be only uni-directional, Duigou & Project JXTA Expires August 28, 2003 [Page 8] Internet-Draft JXTA v2.0 Protocols Specification February 2003 allowing one peer to successfully send messages to the other while no communication is possible in the reverse direction. The JXTA protocols are defined as idempotent protocol exchanges. The same messages MAYbe sent/received more than once d uring the course of a protocol exchange. No protocol states are required to be maintained at both ends. Due to unpredictability of P2P networks, assumptions MUST NOTbe made about the time required for a message to reach a destination peer. The JXTA Core Protocols (Section 4.4) MUST NOTimpose any timing requirements for message receipt. The JXTA Transport Protocols (see Core JXTA Message Transport Bindings (Section 4.5)and Standard JXTA Message Transports (Section 5.3)) MUST NOTimpose any timing requirements on the JXTA Core Protocols (Section 4.4)but MAYhave timing requirements internal to themselves. The Standard Protocols (Section 5.2)(e.g. Peer Discovery Protocol (Section 5.2.1), Peer Information Protocol (Section 5.2.3), Peer Discovery Protocol (Section 5.2.4), etc. ) and application defined protocols MAYimpose timing requirements on message delivery and receipt. A JXTA protocol message which is routed through multiple hops SHOULD NOTbe assumed to reliably delivered, even if only reliable transports such as TCP/IP are used through all hops. A congested peer MAYdrop messages at any time rather than routing them. While the JXTA protocol messages and advertisements are defined using XML messages, an XML parser is OPTIONAL. Small JXTA implementations MAYchoose to use pre-built XML or XML templates for message and advertisement construction. The JXTA protocols MUST NOTrequire a broadcast or multicast capability of the underlying network transport. Messages intended for receipt by multiple peers (propagation) MAYbe implemented using point-to-point communications. A peer SHOULDmake the assumption that if a destination address is not available at any time during the message transmission, the message will not be delivered. Each peer MUSTbe a member of the World Peergroup and Net Peergroups. Membership in these groups is automatic. Peers MUSTbe members of the same peer group in order to exchange Duigou & Project JXTA Expires August 28, 2003 [Page 9] Internet-Draft JXTA v2.0 Protocols Specification February 2003 messages. A peer MUST NOTassume that there is a guaranteed return route to a peer from which it has received communication. The lack of a return route may either be temporary or permanent. Names are not unique unless a coordinated Naming service is used to guarantee name uniqueness. A Naming service is typically a service that guarantees, within a given scope, the uniqueness of name and can be used to register name mapping. Examples of Name services are DNS and LDAP. A naming service is OPTIONAL. JXTA does not define its own naming service. Once content has been published to the JXTA network, it SHOULD NOTbe assumed that that the content can be later retrieved from the JXTA network. The content may be only available from peers that are not currently reachable or nowhere. Once a content has been published to the JXTA network, it MUST NOTbe assumed that the content can be deleted. Republication of content by peers is unrestricted and the content may propagate to peers which are not reachable from the publishing peer. 2.3 Why JXTA? The JXTA Protocols are an open network computing platform designed for peer-to-peer (P2P) computing. The JXTA protocols standardize the manner in which peers: o Discover each others o Self-organize into peer groups o Advertise and discover network resources o Communicate with each others o Monitor each other The JXTA protocols DO NOT: o Require the use of any particular computer language or operating system. o Require the use of any particular network transport or topology. o Require the use of any particular authentication, security or Duigou & Project JXTA Expires August 28, 2003 [Page 10] Internet-Draft JXTA v2.0 Protocols Specification February 2003 encryption model. The JXTA protocols enable developers to build and deploy interoperable services and applications, further spring-boarding the peer to peer revolution on the Internet. JXTA intends to achieves this by providing a simple and generic P2P platform to host all types of network services o JXTA is defined by a small number of protocols. Each protocol is easy to implement and integrate into P2P services and applications. Thus service offerings from one vendor can be used transparently by the user community of another vendor's system. o The JXTA protocols are defined to be independent of programming languages, so that they can be implemented in C/C++, Java, Perl, and numerous other languages. Heterogeneous devices with completely different software stacks can interoperate with the JXTA protocols. o The JXTA protocols are designed to be independent of transport protocols. They can be implemented on top of TCP/IP, HTTP, Bluetooth, HomePNA, and many other protocols. 2.4 The JXTA Three Layer Cake The JXTA Project is divided in three layers. o Platform. This layer encapsulates minimal and essential primitives that are common to P2P networking, including peers, peergroups, discovery, communication, monitoring, and associated security primitives. This layer is ideally shared by all P2P devices so that interoperability becomes possible. o Services. This layer includes network services that may not be absolutely necessary for a P2P network to operate but are common or desirable to be available to the P2P environment. Examples of network services, include search and indexing, directory, storage systems, file sharing, distributed file systems, resource aggregation and renting, protocol translation, authentication and PKI services. o Applications. This layer includes P2P instant messaging, entertainment content management and delivery, P2P E-mail systems, distributed auction systems, and many others. Obviously, the boundary between services and applications is not rigid. An application to one customer can be viewed as a service to another Duigou & Project JXTA Expires August 28, 2003 [Page 11] Internet-Draft JXTA v2.0 Protocols Specification February 2003 customer. Duigou & Project JXTA Expires August 28, 2003 [Page 12] Internet-Draft JXTA v2.0 Protocols Specification February 2003 3. Conceptual Overview JXTA is intended to be a small system with a limited number of concepts at its core. This chapter introduces the concepts which are central to JXTA. 3.1 Peers A JXTA peer is any networked device (sensor, phone, PDA, PC, server, supercomputer, etc.) that implements the core JXTA protocols. Each peer is identified by a unique ID. Peers are autonomous and operate independently and asynchronously of all other peers. Some peers MAYhave dependencies upon other peers due to special requirements such as the need for gateways, proxies, routers, etc. Peers MAYpublish network services and resources ( CPU, storage, databases, documents, etc.) for use by other peers. Peers are typically configured to spontaneously discover each other on the network to form transient or persistent relationships with other peers. Peers that provide the same set of services tend to be inter-changeable so peers typically only need to interact with a small number of other peers (network neighbours or buddy peers). Peers SHOULD NOTmake assumptions about the reliability of other peers. Peers MAYjoin or leave the network at any time. A peer SHOULDalways anticipate that connectivity may be lost with any peer it is currently communicating. A peer MAYcache advertisements for JXTA resources, but doing so is OPTIONAL. Peers MAYhave persistent storage. Peers MAYadvertise multiple network interfaces. Each published interface is advertised as a peer endpoint. A peer endpoint is a URI that uniquely identify a peer network interface. Peer endpoints are used by peers to establish direct point-to-point connections between two peers. Communicating peers peers may not have direct point-to-point network connection between themselves, either due to lack of physical network connections, or network configuration (NATs, firewalls, proxies, etc.). A peer MAYhave to use one or more intermediary peers to route a message to another peer. 3.1.1 Peers and Users Frequently a peer will be under the control of a human operator, the "User". The peer will interact with the network on the basis of the user's direction. Not every peer has a user. Many peers exist to provide services and resources to the network, but are not associated Duigou & Project JXTA Expires August 28, 2003 [Page 13] Internet-Draft JXTA v2.0 Protocols Specification February 2003 with any user. Examples include devices such as sensors and printers, but also services such as databases. The concept of "user"exists primarily for identification. This is needed by applications to allow users to tell each other apart and to manage their interactions. Identity is frequently also tied to security and permissions. There is no explicit relationship between users and peers within JXTA, but for many applications the two concepts are closely associated. 3.2 Peer Groups Peers self-organize into Peer Groups. A peer group is a collection of peers that have a common set of interests. Each peer group is uniquely identified by a unique PeerGroup Id. The JXTA protocols do not dictate when, where, or why peergroups are created. The JXTA protocols only describe how a peers may publish, discover, join, and monitor peergroups. JXTA recognizes three common motivations for creating peer groups: o To create a secure environment. Peergroup boundaries permit member peers to access and publish protected contents. Peergroups form logical regions whose boundaries limit access to the peergroup resources. A peergroup does not necessarily reflect the underlying physical network boundaries such as those imposed by routers and firewalls. Peergroups virtualize the notion of routers and firewalls, subdividing the network in secure regions without respect to actual physical network boundaries. o To create a scoping environment. Peergroups are typically formed and self-organized based upon the mutual interest of peers. No particular rules are imposed on the way peergroups are formed, but peers with the same interests will tend to join the same peergroups. Peergroups serve to subdivide the network into abstract regions providing an implicit scoping mechanism. Peergroup boundaries define the search scope when searching for a group's content. o To create a monitoring environment. Peergroups permit peers to monitor a set of peers for any special purpose (heartbeat, traffic introspection, accountability, etc.). A peergroup provides a set of services called peergroup services. JXTA defines a core set of peergroup services. The JXTA protocols specify the wire format for these core peergroup services. Additional Duigou & Project JXTA Expires August 28, 2003 [Page 14] Internet-Draft JXTA v2.0 Protocols Specification February 2003 peergroup services can be developed for delivering specific services. For example, a lookup service could be implemented to find active (running on some peer) and inactive (not yet running) service instances. The core peer group services are: Discovery Service : The Discovery service is used by member peers to search for peergroup resources (peers, peer groups, pipes, and services). Membership Service : The membership service is used by the current members to reject or accept a new group membership application. We expect that most peergroups will have at least a membership service, though it may be a "null"authenticator service which imposes no real membership policy. The membership service is used by a member peer to allow a new peer to join a peergroup. In order for a peer to join a peergroup, a peer MAYneed to discover at least one member of the peergroup. Peers wishing to join a peer group MAYfirst have to locate a current member, and then request to join. The request to join is either rejected or accepted by the collective set of current members. The membership service MAYenforce a vote of peers or elect a designated group representative to accept or reject new membership requests. A peer MAYbelong to more than one peergroup simultaneously. 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. Pipe Service : The pipe service is used to manage and create pipe connections between the different peer group members. Resolver Service : The resolver service is used to address queries to services running on peers in the group and collect responses. Monitoring Service : The monitoring service is used to allow one peer to monitor other members of the same peer group. Not all the above services MUSTbe implemented by a peergroup. Each service MAYimplement one or more of the JXTA protocols, the Duigou & Project JXTA Expires August 28, 2003 [Page 15] Internet-Draft JXTA v2.0 Protocols Specification February 2003 specifications for which are the main content of this document. A service will typically implement one protocol for simplicity and modularity reasons, but some services may not implement any protocols. 3.3 Network Services Peers cooperate and communicate to publish, discover and invoke network services. A peer can publish as many services that it can provide. Peers discover network services via the Peer Discovery Protocol. Network Service specifications are beyond the scope of this document. Upcoming standards such as WSDL, ebXML, SOAP, UPnP might be used within a JXTA Network. The JXTA protocols recognize two levels of network services: o Peer Services o PeerGroup Services A peer service is accessible only on the peer that is publishing the service. If that peer happens to fail, then the service also fails. Multiple instances of the service can be run on different peers, but each instance publishes its own advertisement. A peergroup service is composed of a collection of instances (potentially cooperating with each other) of the service running on multiple members of the peergroup. If any one peer fails, the collective peergroup service is not affected, because chances are the service is still available from another peer member. Peergroup services are published as part of the peergroup advertisement. Services can either be pre-installed into a peer or loaded from the network. The process of finding, downloading and installing a service from the network is similar to performing a search on the internet for a web page, retrieving the page, and then installing the required plug-in. In order to actually run a service, a peer may have to locate an implementation suitable for the peer's runtime environment. Multiple implementations of the same service may allow Java peers to use Java code implementations, and native peers to use native code implementations. 3.3.1 Service Invocation Service invocation is outside the scope of JXTA. JXTA is designed to interoperate and be compatible with any Web service standards; WSDL, Duigou & Project JXTA Expires August 28, 2003 [Page 16] Internet-Draft JXTA v2.0 Protocols Specification February 2003 uPnP, RMI, etc. The JXTA protocols define a generic framework to publish and discover Advertisements that may describe services. Peers publish and discover advertisements via the Peer Discovery Protocol. An advertisement for a service will typically contain all the necessary information to either invoke or instantiate the service being described. The JXTA protocols define Module Advertisements but any other form of service description may be introduced. 3.3.2 JXTA-Enabled Services JXTA-Enabled services are services that are published by using the ModuleSpecAdvertisement. A module spec advertisement may specify a pipe advertisement that can be used by a peer to create output pipes to invoke the service. ModuleSpec Advertisement may be extended in the future to contain a list of pre-determined messages that can be sent by a peer to interact with the service. A ModuleSpecAdvertisement may also contain references to two other services which can be used as an authenticator for the service and as a local proxy for the service. Each Jxta-enabled service is uniquely identified by its ModuleSpecID. 3.4 IDs Within the JXTA protocols there are a number of entities that need to be uniquely identifiable. These are peers, peergroups, pipes and contents. A JXTA ID uniquely identifies an entity and serves as a canonical means of referring to that entity. URNs are used for the expression of JXTA IDs. 3.5 Advertisements All network resources, such as peers, peergroups, pipes and services are represented by advertisements. Advertisements are JXTA's language neutral metadata structures for describing resources. The JXTA Core Specification and Standard Services define, among others, the following advertisement types: o Peer Advertisement o PeerGroup Advertisement o ModuleClass Advertisement o ModuleSpec Advertisement o ModuleImpl Advertisement Duigou & Project JXTA Expires August 28, 2003 [Page 17] Internet-Draft JXTA v2.0 Protocols Specification February 2003 o Pipe Advertisement o Rendezvous Advertisement The complete specification of advertisements is given in the Advertisements (Section 4.3)chapter. The JXTA protocols make heavy reference to these advertisements, so the reader should be familiar with advertisements before moving on to the protocol specification chapters. Advertisements are, by far, the most common document exchanged in the protocol messages. Services or peer implementations can create their own advertisement types, either from scratch or by subtyping the existing types. 3.6 Credentials The need to support different levels of resource access in a dynamic and ad hoc P2P network leads to a role-based trust model in which an individual peer will act under the authority granted to it by another trusted peer to perform a particular task. Peer relationships MAYchange quickly and the policies governing access control need to be flexible in allowing or denying access. Four basic security requirements MUSTbe provided: Confidentiality : guarantees that the contents of the message are not disclosed to unauthorized individuals. Authorization : guarantees that the sender is authorized to send a message. Data integrity : guarantees that the message was not modified accidentally or deliberately in transit. Refutability : guarantees the message was transmitted by a properly identified sender and is not a replay of a previously transmitted message. The structure of JXTA messages enables JXTA applications to add abitrary metadata information to messages such as credentials, digests, certificates, public keys, etc. A credential is a token that when presented in a message body is used to identify a sender and can be used to verify that sender's right to send the message to the specified endpoint. The credential is an opaque token that must be presented each time a message is sent. The sending address placed in the message envelope is cross-checked Duigou & Project JXTA Expires August 28, 2003 [Page 18] Internet-Draft JXTA v2.0 Protocols Specification February 2003 with the sender's identity in the credential. Each credential's implementation is specified as a plug-in configuration, which allows multiple authentication configurations to co-exist on the same network. Message digests guarantee the data integrity of messages. Messages may also be encrypted and signed for confidentiality and refutability. It is the intent of the JXTA protocols to be compatible with widely accepted transport-layer security mechanisms. Some JXTA implementations contain a virtualized TLS implementation that allows it to secure Endpoint to Endpoint communications regardless of the number of hops required to deliver each message. TLS and IPSec could also be used as JXTA transports. However, when used as transports they provide integrity and confidentiality of message transfer only between the two communicating peers. 3.7 Pipes Pipes are virtual communication channels used to send and receive messages between services or applications over endpoints. Pipes provide a network abstraction over the peer endpoint transport. Peer endpoints correspond to the available peer network interfaces that can be used to send and receive data from another peer. Pipes provide the illusion of a virtual in and out mailbox that is independent of any single peer location, and network topology (multi-hops route). Different quality of services can be implemented by a pipe. For example: Uni-directional asynchronous : The endpoint sends a message, no guarantee of delivery is made. Synchronous request-response : The endpoint sends a message, and receives a correlated answer. Bulk transfer : Bulk reliable data transfer of binary data. Streaming : Efficient control-flow data transfer. Secure : Secure reliable data streams. The uni-directional asynchronous pipe is REQUIREDby the JXTA protocols. Other pipe variations may be implemented for use by services and their associated protocols. Duigou & Project JXTA Expires August 28, 2003 [Page 19] Internet-Draft JXTA v2.0 Protocols Specification February 2003 Pipes connect one or more peer endpoints. At each endpoint software to send or receive, as well as to manage associated pipe message queues or streams, is assumed, but message queues are OPTIONAL. The pipe endpoints are referred to as input pipes (receiver) and output pipes (transmitter). Pipe endpoints are dynamically bounded to a peer endpoint at runtime, via the Pipe Binding Protocol (Section 5.2.4). The pipe binding process consists of searching for and connecting the two or more endpoints of a pipe. When a message is sent into an output pipe, the message is sent by the local peer endpoint to the peer endpoint(s) where the associated input pipe is located. The set of peer endpoints currently associated with the input pipes is discovered using the Pipe Binding Protocol (Section 5.2.4). A pipe offers two modes of communication: Point to Point : A point to point pipe connects exactly two pipe endpoints together, an input pipe that receives messages sent from an output pipe. No reply or acknowledgment operation is supported. Additional information in the message payload like a unique id may be required to thread message sequences. The message payload may also contain a pipe advertisement that can be used to open a pipe to reply to the sender (send/response). Propagate Pipe : A propagate pipe connects one output pipe to multiple input pipes together. Messages flow into the input pipes from the output pipe (propagation source). A propagate message is sent to all listening input pipes. This process may create multiple copies of the message to be sent. On TCP/IP, when the propagate scope maps an underlying physical subnet in a 1 to 1 fashion, IP multicast may be used as an implementation for propagate. Propagate can be implemented using point to point communication on transports that do not provide multicast such as HTTP. Pipe Modes +-------+ (i) = Input Pipe | | (o) = Output Pipe | peer | | | +---+---+ Propagate | | | Pipe |(i)|(o)|-------------+ | | | | Duigou & Project JXTA Expires August 28, 2003 [Page 20] Internet-Draft JXTA v2.0 Protocols Specification February 2003 +---+---+ | | send | | | | | receive | receive V +------+-----+ | +-----+------+ | | (i) |<---------------+ | | (i) | | | peer +-----+ Point to Point | | +-----+ peer | | | (o) | Pipe | | | (o) | | +------+-----+ | | +-----+------+ | | | | send | V +---+---+ | | | |(o)|(i)| | | | +---+---+ | | | peer | | | +-------+ Pipes may connect two peers that do not have a direct physical link. One or more intermediary peer endpoints are used to route messages between the two pipe endpoints. 3.8 Messages The information transmitted using pipes and between endpoints is packaged as messages. Messages define an envelope to transfer any kind of data. A message MAYcontain an arbitrary number of named sub-sections which can hold any form of data. It is the intent that the JXTA protocols be compliant with W3C XML Protocol standards, so the JXTA protocols can be implemented on XML transports such as SOAP, XML-RPC, etc. The JXTA protocols are specified as a set of XML messages exchanged between peers. Each software platform binding describes how a message is converted to and from a native data structures such as Java objects or "C"structures. The use of XML messages to define protocols allows many different kinds of peers to participate in a protocol. Each peer is free to implement the protocol in a manner best suited to its abilities and role. Duigou & Project JXTA Expires August 28, 2003 [Page 21] Internet-Draft JXTA v2.0 Protocols Specification February 2003 3.9 Codats The JXTA protocols assume that many types of contents may be shared, exchanged, and replicated between peers. A content can be a text file, a structured document (like a PDF or an XML file), a Java .jaror loadable library, code or even an executable process (checkpointed state). No size limitation is assumed. Content are published and shared amongst peer members of a peergroup. When a content is shared within the JXTA network it is associated with a JXTA ID. The combination of a content and a JXTA ID is known as a Codat. A codat may only belong to one peergroup. If the same content must be published in two different peergroups, two different codats are created. The two codats MAY, of course, represent the same content. Each codat is uniquely identified by a JXTA ID. All codats make their existence known to peer members by publishing a content advertisement. A codat instance is a copy of a codat. Each codat copy may be replicated on different peers in the peergroup. Each copy has the same codat id and an identical content. Replicating codats within a peergroup helps to ensure that each item of content be more readily available. For example, if an item has two instances residing on two different peers, only one of the peers needs to be alive to respond to the content request. The JXTA protocols do not specify how codats are replicated. This decision is left to higher-level content service managers. Duigou & Project JXTA Expires August 28, 2003 [Page 22] Internet-Draft JXTA v2.0 Protocols Specification February 2003 4. JXTA Core Specification 4.1 Introduction JXTA is designed to be a small system with only a few required components and behaviours. The functionality that is required of all implementations is defined by the JXTA Core Specification and is documented in this section. Implementations that wish to be JXTA compliant MUST implement all of the JXTA Core Specification (Section 4). Implementation of the JXTA Core Specification (Section 4) does not guarantee or even necessarily provide interoperability with other JXTA implementations. There are a number of types of components and behaviours which need to be provided by JXTA implementation which are not part of the JXTA Core Specification (Section 4). Existing implementations of these components are described separately in JXTA Standard Services (Section 5) and JXTA Reference Implementations Information (Section 6). In order for a JXTA implementation to be interoperable with other implementations it may be necessary to implement some of the components described there. 4.2 IDs 4.2.1 Introduction The JXTA protocols often need to refer to peers, peer groups, pipes and other JXTA resources. These references are presented in the protocols as JXTA IDs. JXTA IDs are a means for uniquely identifying specific peer groups, peers, pipes, contents and service instances. JXTA IDs provide unambiguous references to the various JXTA entities. There are six types of JXTA entities which have JXTA ID types defined: peergroups, peers, pipes, content, module classes and module specifications. Additional JXTA ID types may be defined in the future. JXTA IDs are normally presented as URNs. URNs are a form of URI that "... are intended to serve as persistent, location-independent, resource identifiers". Like other forms of URI, JXTA IDs are presented as text. See "IETF RFC 2141" [RFC2141] [6] for more information on URNs. 4.2.2 JXTA ID Properties Every JXTA ID, regardless of format or type has the following properties: Duigou & Project JXTA Expires August 28, 2003 [Page 23] Internet-Draft JXTA v2.0 Protocols Specification February 2003 o Unambiguous. It MUST be a complete reference to the resource. o Relatively Unique. It MUST refer to a single resource. o Canonical. References to the same resource SHOULD encode to the same JXTA ID. This enables IDs to be compared to determine if they refer to the same resource, but understandably may not be achievable by all ID Formats. o Opacity. In their URN presentation JXTA IDs SHOULD be assumed to be opaque. The context of an ID within a protocol message generally is sufficient to establish its type. A JXTA binding may be able to interpret an ID if it supports the ID Format. Generally, only the immediate participants in a JXTA protocol need to understand the contents of a JXTA ID, if at all. 4.2.3 Using JXTA IDs in Protocols When JXTA IDs are used within protocols they are manipulated as text string URIs. There are three operations available for URIs; compare, resolve, decompose. JXTA ID URIs are comparable for equality as strings. JXTA ID URIs can also be resolved to the resource they reference. Finally, JXTA ID URIs can optionally be decomposed and interpreted by JXTA bindings. In order to interpret a JXTA ID, a JXTA binding must support the JXTA ID Format used by that JXTA ID. For many JXTA protocols and operations it is not necessary to decompose the JXTA IDs. 4.2.4 Format of a JXTA ID URN A JXTA ID is a standard URN in the JXTA ID namespace. JXTA ID URNs are identified by the URN namespace identifier "jxta". Each JXTA ID URN also contains a JXTA ID Format keyword. The ID Format keyword indicates how the ID was created and may also allow JXTA bindings to extract additional information from the ID. Two ID formats have been defined which are identified by the "jxta" and "uuid" keywords. It is possible to define additional JXTA ID Formats in order to refer to resources both within JXTA and to bridge to other technologies. 4.2.5 Example JXTA ID URNs The following examples demonstrate valid JXTA ID presentation forms. These examples are not necessarily valid JXTA IDs. Duigou & Project JXTA Expires August 28, 2003 [Page 24] Internet-Draft JXTA v2.0 Protocols Specification February 2003 A. urn:jxta:idform-1234567890 B. URN:jxta:idform-1234567890 C. urn:JXTA:idform-1234567890 D. urn:JXTA:IDForm-1234567890 E. urn:jxta:idform2-ABCDEFG F. urn:jxta:idform3-31:08:66:42:67:::91:24::73 Figure 3: Sample JXTA IDs In the preceding examples, A., B. and C. represent the same JXTA ID. Both the "URN" portion and the "JXTA" are case insensitive. Example D. is not equivalent to any of A., B. or C. because the data portion of the URN is case sensitive. In the six examples, four different JXTA ID Formats are used: "idform", "IDForm", "idform2" and "idform3". Definition of ID Format names that differ only in character case is NOT RECCOMENDED. The interpretation of the characters following the "-" is specific to each ID Format. 4.2.6 JXTA ID Representation JXTA IDs are presented as URNs of the "jxta" namespace. The JXTA ID Namespace specifies additional restrictions upon the format of the URN. These requriements are detailed in JXTA ID ABNF (Figure 4). The following figure uses the ABNF syntax as defined in "IETF RFC 2234" [RFC2234] [7]. ::= "urn:" ":" ::= "jxta" ::= "-" ::= 1 * ::= 1 * ::= | "%" ::= | | | | ::= "A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" | "J" | "K" | "L" | "M" | "N" | "O" | "P" | "Q" | "R" | "S" | "T" | "U" | "V" | "W" | "X" | "Y" | "Z" ::= "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" | "i" | "j" | "k" | "l" | "m" | "n" | "o" | "p" | Duigou & Project JXTA Expires August 28, 2003 [Page 25] Internet-Draft JXTA v2.0 Protocols Specification February 2003 "q" | "r" | "s" | "t" | "u" | "v" | "w" | "x" | "y" | "z" ::= | "A" | "B" | "C" | "D" | "E" | "F" | "a" | "b" | "c" | "d" | "e" | "f" ::= "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" ::= "(" | ")" | "+" | "," | "-" | "." | ":" | "=" | "@" | ";" | "$" | "_" | "!" | "*" | "'" ::= "%" | "/" | "?" | "#" Figure 4: JXTA ID ABNF The jxta URN namespace does not currently define any special symbols from the "reserved" set. 4.2.7 JXTA ID Formats JXTA IDs are designed to support multiple ID Formats. ID Formats allow JXTA developers to utilize existing naming and ID schemes within JXTA. In the JXTA ID presentation, the ID's "Format" follows the JXTA URN namespace. Any JXTA ID Format which follows the general requirements for URNs and the JXTA ID Properties (Section 4.2.2) will be usable by conformant JXTA implementations. 4.2.8 JXTA ID Types JXTA IDs may refer to many types of resources; pipes, peers, etc. Each JXTA ID format type may support references to one or more of these resource types. Currently, five standard resource types have been identified; peer groups, peers, pipes, content and service instances. Other types may be defined. Each of the individual ID Types MAY provide additional requirements specific to its type. 4.2.8.1 Peer Group IDs Peer Group IDs refer to peer groups. A peer group ID should canonically, uniquely and unambiguously refer to a peer group. Every ID Format MUST support this ID Type because all of the other ID Types refer to the peer group to which they belong. Every ID Format MUST support encoding of the World Peer Group. Support for other peer groups is OPTIONAL. Example: You are defining an ID Format for Peer Duigou & Project JXTA Expires August 28, 2003 [Page 26] Internet-Draft JXTA v2.0 Protocols Specification February 2003 IDs based upon driver's license number. Driver's licenses are not organized into groups. This can be considered equivalent to all driver's licenses belonging to the same group, the global "world peer group". 4.2.8.2 Peer IDs Peer IDs refer to peers. A Peer ID SHOULD canonically, uniquely and anambiguously refer to a peer. Support for this ID Type is OPTIONAL. If a JXTA binding recognizes the ID Format, it SHOULD be able to determine the assocaiated Peer Group ID from a Peer ID. This Peer Group ID identifies the peer group of which the peer is a member. 4.2.8.3 Codat IDs Peer IDs refer to codats. A Codat ID SHOULD canonically, uniquely and anambiguously refer to a codat. Support for this ID Type is OPTIONAL. If a JXTA binding recognizes the ID Format, it SHOULD be able to determine the assocaiated Peer Group ID from a Codat ID. This Peer Group ID identifies the peer group of which the codat is a member. 4.2.8.4 Pipe IDs Peer IDs refer to pipes. A Pipe ID SHOULD canonically, uniquely and anambiguously refer to a pipe. Support for this ID Type is OPTIONAL. If a JXTA binding recognizes the ID Format, it SHOULD be able to determine the assocaiated Peer Group ID from a Pipe ID. This Peer Group ID identifies the peer group of which the pipe is a member. 4.2.8.5 Module Class IDs A Module Class ID identifies a particular local behavior, that is, a specific API for each execution environment for which an implementation exists. A Module Class ID SHOULD canonically, uniquely and unambiguously refer to a module class as defined by an advertisement. Support for this ID Type is OPTIONAL. If a JXTA binding recognizes the ID Type, it should be able to extract a Base Class ID from a Module Class ID. The Base Class ID allows applications to determine if two Module Class IDs differ only in the "role" they perform. Module Spec ID's "roles" allow for the same module to be reused within a group and have instances distinguished. This is necessary when, for example, a common database service is used, with each "role" accessing a different data set. 4.2.8.6 Module Spec IDs A ModuleSpecID uniquely identifies a particular network behavior (wire protocol and choreography) that may be embodied by a Jxta Duigou & Project JXTA Expires August 28, 2003 [Page 27] Internet-Draft JXTA v2.0 Protocols Specification February 2003 Module. There may be any number of implementations of a given Module Spec ID. A ModuleSpecID uniquely identifies an abstract module for which there may be multiple platform specific implementations. A ModuleSpecID is used to locate a compatible implementation such that it can be instantiated. All such implementations are assumed to be network compatible. A Module Spec ID SHOULD canonically, uniquely and unambiguously refer to a module specification. Support for this ID Type is OPTIONAL. If a JXTA binding recognizes the ID Type, it should be able to extract a Module Class ID from a Module Spec ID. 4.2.9 JXTA ID Formats : jxta ID Format The "jxta" ID Format is a REQUIRED ID Format that is used for encoding "well known" JXTA identifiers. All JXTA binding implementations MUST support this ID Format. There are three special reserved JXTA IDs; the Null ID, the World Peer Group ID and the Net Peer Group ID. The "jxta" ID Format exists so that for these few "well known" IDs only a single representation exists. ::= "urn:" ":" "-" ::= "jxta" ::= | | ::= "Null" ::= "WorldGroup" ::= "NetGroup" Figure 5: JXTA ID : "jxta" ID Format ABNF 4.3 Advertisements 4.3.1 Introduction Advertisements are meta-data documents used by JXTA protocols to describe resources. Advertisements are used to describe peers, peer groups, pipes, content, services and many other types of resources. JXTA Advertisements are presented in XML. Many of the JXTA protocols depend on Advertisements to provide necessary information. JXTA protocols are used to pass Advertisements between peers. Services can define new Advertisement types by sub-typing existing Advertisement types or by defining completely new Advertisements. Duigou & Project JXTA Expires August 28, 2003 [Page 28] Internet-Draft JXTA v2.0 Protocols Specification February 2003 Advertisement sub-types allow for additional information to be provided as well as richer meta-data. Advertisements are composed of a series of hierarchically arranged elements. The elements may appear in any order within the advertisement. Each element can contain its data or additional elements. An element can also have attributes. Attributes are name-value string pairs. An attribute is used to store meta-data, which helps to describe the data within the element. The Core JXTA Protocols rely on the following advertisements: o Peer Advertisement (Section 4.3.3) o Peer Group Advertisement (Section 4.3.4) o Module Class Advertisement (Section 4.3.5) o Module Specification Advertisement (Section 4.3.6) o Module Implementation Advertisement (Section 4.3.7) 4.3.2 XML and JXTA Advertisements All JXTA advertisements are represented in XML. XML provides a powerful means of representing data and metadata throughout a distributed system. XML provides a universal (software-platform neutral) representation: o XML is programming language agnostic o XML is self-describing o XML content can be strongly-typed o XML ensures correct syntax These advantages allow peers to manage and use Advertisements safely and to be able to ensure correct interactions with other peers. The Advertisements defined by the JXTA Core Specificationand the JXTA Standard Servicesare specified using the XML Schema Definition Language [XSD2001-1] [14][XSD2001-2] [15]. Use of XML Schemas allows the advertisement contents to be strongly type-checked and semanticly validated beyond the syntactical validation provided by XML with DTDs. Service and protocol authors are RECOMMENDEDto specify their Advertisements or Advertisement sub-types using XML Schema Language. DTDs are normally prepared from the schema descriptions for use in Duigou & Project JXTA Expires August 28, 2003 [Page 29] Internet-Draft JXTA v2.0 Protocols Specification February 2003 environments which do not support XML schema. The other powerful feature of XML is its ability to be translated into other encodings such as HTML and WML. This feature allows peers that do not support XML to access advertised resources. Figure 6: Common Advertisement Fragments Schemas 4.3.3 Peer Advertisement A Peer Advertisement describes a peer and the resources it provides to the group. The Peer Advertisement holds specific information about the peer such as its its unique id, its group id and optionally its name and descriptive information. It may also contain endpoint addresses and any run-time attributes that individual peer services want to publish (such as being a rendezvous peer for a group). Duigou & Project JXTA Expires August 28, 2003 [Page 30] Internet-Draft JXTA v2.0 Protocols Specification February 2003 Figure 7: Peer Advertisement Schema : This is a required element that uniquely identifies this peer. Each peer has a unique id. : This is a required element that identifies the Peer Group to which this peer belongs. : This is an optional string that can be associated with a peer. The name is not required to be unique unless the name is obtained from a centralized naming service that guarantees name uniqueness. : This is an optional string that can be used to index and search for a peer. The string is not guaranteed to be unique. Two peers may have the same keywords. The keywords string may contain spaces. : Any number of such elements may exist. Each of them describes the association between a group service denoted by its Class ID (the value of an MCID element), and arbitrary parameters encapsulated in a Parm element. For example, all accessible endpoint addresses are published in association with the Endpoint Service Class ID. The TLS Root certificate is published under the PeerGroup Class ID (There is a class ID for Peer Group as well). The flag that denotes that this peer is a rendezvous for this group is published under the Rendezvous Service Class ID. Ultimately, each service is responsible for what is published under its Class ID. The Service section may also optionally contain an element "isOff" meaning that this service is disabled. This element is used to convey a configuration choice made by the owner of the peer. 4.3.4 Peer Group Advertisement A Peer Group Advertisement describes peergroup specific resources: Duigou & Project JXTA Expires August 28, 2003 [Page 31] Internet-Draft JXTA v2.0 Protocols Specification February 2003 name, group id, description, specification, and service parameters. Figure 8: Peer Group Advertisement Schema : This element provides the Peer Group ID. The Peer Group ID is the canonical way of refering to a group and uniquely identifies the peer group. See Peer Group IDs (Section 4.2.8.1)for more information on peer group ids. : Peer group Specification ID. This designates the module that provides the peer group mechanism itself for that group. The spec ID designates an abstraction of that mechanism. This abstraction is optionally described by a ModuleSpecAdvertisement, and any number of implementations may exist, each described by a ModuleImplAdvertisement. These advertisements may all be searched by this SpecID. : This is an optional name that can be associated with a peergroup. The name is not required to be unique unless the name is obtained from a centralized naming service that guarantee name uniqueness. : This is an optional element provides descriptive information that may be used to index and search for a peergroup. The content of this element may not be unique. For example, two peergroups may have the same keywords. : Any number of such elements may exist. Each of them describes the association between a group service denoted by its Class ID (the value of an MCID element), and arbitrary parameters encapsulated in a Parm element. This optional parameter may only be meaningful to some services. It is used to configure a service specifically in relation with its use by this group. For example, a simple membership service may find an encrypted password list there. Duigou & Project JXTA Expires August 28, 2003 [Page 32] Internet-Draft JXTA v2.0 Protocols Specification February 2003 4.3.5 Module Class Advertisement A Module Class Advertisement describes a class of modules. That is, an expected local behavior and and expected API for each JXTA binding (that supports such modules). The purpose of this advertisement is to provide a description of what a particular Module Class ID stands for. A Module Class ID is what other modules or other code running on JXTA uses to designate modules which it depends upon. The ModuleClassAdvertisement is not required to provide a completely formal description of the module's behavior and API. It is intended for humans who want to create modules with a similar functionality. It is not required to publish a Module Class Advertisement for a Module Class ID to be valid, although it is a good practice. Figure 9: Module Class Advertisement Schema : Module Class ID. This is a required element that uniquely identifies the class. Each module class has a unique id. The class id representation is given in the Id Chapter. : This is an optional name that can be associated with a class. The name is not required to be unique unless the name is obtained from a centralized naming service that guarantee name uniqueness. : Description. This is an optional string that can be used to describe and search for a class. 4.3.6 Module Specification Advertisement A Module Specification Advertisement describes the specification of a module. That is, an expected on-wire behavior and protocol. The purpose of this advertisement is to provide a description of what a particular Module Specification ID stands for. A Module Specification ID is what other modules or other code running on JXTA uses to Duigou & Project JXTA Expires August 28, 2003 [Page 33] Internet-Draft JXTA v2.0 Protocols Specification February 2003 designate a particular network-compatible family of implementations of a given class. It is more importantly how a group implementation may designate the components which provide the various services that this group supports. All the built-in core peergroup services (discovery, membership, resolver,...) are modules. It is not required to publish a Module Spec Advertisement for a Module Spec ID to be valid, although it is a good practice. A Module Spec Advertisement may also describe how to invoke and use a module. A Module may be used through its API, by locating an implementation, loading it and starting it, or a module may be usable through a pipe or through a proxy module. Modules which permit this include one or both of a Pipe Advertisement or the Module Spec ID of a proxy module, in their ModuleSpecID. Publication of the Module Spec Advertisement is of course required in that case. A Module Specification Advertisement is not required to provide a completely formal description of the module's network behavior or protocol, it is intended for humans who want to create compatible implementation of that specification. Figure 10: Module Specification Advertisement Schema : ModuleSpecID. This is a required element that uniquely identifies the specification. Each module specification has a unique id. The spec id representation is given in the Id Chapter. Duigou & Project JXTA Expires August 28, 2003 [Page 34] Internet-Draft JXTA v2.0 Protocols Specification February 2003 : The mandatory version of the specification that this advertises. : This is an optional name that can be associated with a spec. The name is not required to be unique unless the name is obtained from a centralized naming service that guarantee name uniqueness. : Description. This is an optional string that can be used to describe and search for a spec. : Creator. This optional element designates the creator of this specification. : Spec URI. This optional element is a URI that permits to retrieve a document containing the specification that this advertises. : Arbitrary parameters to be interpreted by each implementation. : Pipe advertisement. A pipe advertisement which this module binds to an input pipe and which thus may be used to establish a pipe to a nearby running implementation of this specification. Note that the element name is identical to the Pipe Advertisement document type since the entire element is an embedded pipe advertisement document. : Proxy Spec ID. Optional ModuleSpecID of a proxy module that may be used in order to communicate with modules of this specification. Note that the process may be recursive. The proxy module may be usable via pipes, or through a subsequent proxy module, and itself require a subsequent authenticator. However publishers of modules should probably avoid such designs. : Authenticator Spec ID. Optional ModuleSpecID of an authenticator module that may be required in order to communicate with modules of this specification. Note that the process may be recursive. The authenticator module may be usable via pipes, or through a subsequent proxy module, and itself require a subsequent authenticator. However publishers of modules should probably avoid such designs. Duigou & Project JXTA Expires August 28, 2003 [Page 35] Internet-Draft JXTA v2.0 Protocols Specification February 2003 4.3.7 Module Implementation Advertisement A Module Implementation Advertisement describes one of the implementations of a module specification. Implementations of a given specification may be searched by the SpecID. An implementation may be selected by the type of environment in which it can be used (its compatibility statement) as well as by its name, description or the content of its parameters section. A Module Implementation Advertisement also provides a means to retrieve all the necessary data required in order to execute the implementation being described. This information is encapsulated in the Code and PURI elements. The interpretation of these elements are subject to the the module's compatibility. For example, the standard peer group implementation of the Java reference implementation expects the element to specify a fully qualified Java class name that designates a subclass of "net.jxta.platform.Module"and PURI to be the URI of a downloadable package (a .jarfile). Other execution environments could expect the code to be inline within the element or even offer several options. Figure 11: Module Implementation Advertisement Schema : ModuleSpecID. This is a required element that uniquely identifies the specification being implemented. The SpecID representation is given in the Id Chapter. : Compatibility. A mandatory arbitrary element that describes the environment in with this implementation may be executed. Each framework capable of loading and executing module has its own requirement on the contents of this element. Duigou & Project JXTA Expires August 28, 2003 [Page 36] Internet-Draft JXTA v2.0 Protocols Specification February 2003 : This arbitrary element contains anything that is needed in addition to the package in order to load and execute the code of this implementation. In the case of a java implementation it contains the fully qualified class name containing the module's entry points. In other cases it may contain the entire code. : Package URI. This optional element is a URI that permits to retrieve a package containing the code of this implementation. : Provider. The provider of that implementation. : Description. This is an optional string that can be used to describe and search for a spec. : Parameter. Arbitrary parameters to be interpreted by the implementation's code. 4.4 JXTA Core Protocols 4.4.1 Peer Resolver Protocol 4.4.1.1 Introduction The Peer Resolver Protocol (PRP) permits the dissemination of generic queries to one or multiple handlers within a peer group and identify matching responses. Each query is addressed to a specific handler name. This handler name defines the particular semantics of the query and its responses, but is not associated with any specific peer. A given query MAY be received by any number of peers in the peer group, possibly all, and processed according to the handler name if such a handler name is defined on that peer. The intent is for PRP to provide the essential generic query/response infrastructure for building high-level resolver services. In many situation, a higher level service may have a better knowledge of the group topology. The PRP uses the Rendezvous Service to disseminate a query to multiple peers or unicast messages to send queries to specified peers. Peers MAY also participate in the Shared Resource Distributed Index (SRDI). SRDI provides a generic mechanism, where JXTA services can Duigou & Project JXTA Expires August 28, 2003 [Page 37] Internet-Draft JXTA v2.0 Protocols Specification February 2003 utilize a distributed indiex of shared resources with other peers that are grouped as a set of more capable peers such as rendezvous peers. These indices can be used to direct queries in the direction where the query is most likely to be answered, and repropagate messages to peers interested in these propagated messages. 4.4.1.2 Resolver Query Message The resolver query message is used to send a resolver query to the named handler on one or more peers that are members of the peer group. The resolver query is sent as a query string to a specific handler. Each query has a unique Id. The query string can be any string that will be interpreted by the targeted handler. Figure 12: Resolver Query Schema : The credential of the sender. : A string that specifies the destination of this query. : The id of the peer originating the query (as a URN). : An opaque indentifier to be used by the querier to match replies. The SHOULD be included in the responses to this query. : specifies the number of hops the query has been through The SHOULD be incremented by each peer that fowards the query. : Contains the query. Duigou & Project JXTA Expires August 28, 2003 [Page 38] Internet-Draft JXTA v2.0 Protocols Specification February 2003 urn:jxta:uuid-DEADBEEFDEAFBABAFEEDBABE0000000305 JXTACRED 0 0 urn:jxta:uuid-59616261646162614A7874615032503304BD268FA4764960AB93A53D7F15044503 <?xml version="1.0"?> <!DOCTYPE jxta:DiscoveryQuery> <jxta:DiscoveryQuery xmlns:jxta="http://jxta.org"> <Type> 0 </Type> <Threshold> 50 </Threshold> <PeerAdv> <?xml version="1.0"?> <!DOCTYPE jxta:PA> ... REMAINDER OMITTED FOR BREVITY ... </jxta:PA> </PeerAdv> <Attr> </Attr> <Value> </Value> </jxta:DiscoveryQuery> Figure 13: Resolver Query Duigou & Project JXTA Expires August 28, 2003 [Page 39] Internet-Draft JXTA v2.0 Protocols Specification February 2003 4.4.1.3 Resolver Response Message A resolver response message is used to send a response to a resolver query message. Figure 14: Resolver Response Schema : The credential of the respondent. : Specifies how to handle the response. : The query identifier of the query to which this is a response. : The responses. urn:jxta:uuid-DEADBEEFDEAFBABAFEEDBABE0000000305 JXTACRED 0 <?xml version="1.0"?> <!DOCTYPE jxta:DiscoveryResponse> <jxta:DiscoveryResponse xmlns:jxta="http://jxta.org"> Duigou & Project JXTA Expires August 28, 2003 [Page 40] Internet-Draft JXTA v2.0 Protocols Specification February 2003 <Count> 1 </Count> <Type> 2 </Type> <PeerAdv> &lt;?xml version="1.0"?> &lt;!DOCTYPE jxta:PA> &lt;jxta:PA xmlns:jxta="http://jxta.org"> ... REMAINDER OMITTED FOR BREVITY ... &lt;/jxta:PA> </PeerAdv> <Response Expiration="7200000"> &lt;?xml version="1.0"?> &lt;!DOCTYPE jxta:PipeAdvertisement> &lt;jxta:PipeAdvertisement xmlns:jxta="http://jxta.org"> &lt;Id> urn:jxta:uuid-59616261646162614E50472050325033D1D1D1D1D1D1D1D1D1D1D1D1D1D1D1D104 &lt;/Id> &lt;Type> JxtaPropagate &lt;/Type> &lt;Name> JxtaTalkUserName.IP2PGRP &lt;/Name> &lt;/jxta:PipeAdvertisement> </Response> </jxta:DiscoveryResponse> Figure 15: Resolver Response 4.4.1.4 Resolver SRDI Message The resolver SRDI message is used to send a resolver SRDI message to the named handler on one or more peers that are members of the peer group. The resolver SRDI message is sent to a specific handler. The payload string can be any string that will be interpreted by the targeted handler. Duigou & Project JXTA Expires August 28, 2003 [Page 41] Internet-Draft JXTA v2.0 Protocols Specification February 2003 Figure 16: Resolver SRDI Schema : A string that specifies the destination of this message. : The credential of the sender. : Contains the payload. urn:jxta:uuid-DEADBEEFDEAFBABAFEEDBABE0000000305 JXTACRED <?xml version="1.0"?> <!DOCTYPE jxta:GenSRDI> ... REMAINDER OMITTED FOR BREVITY ... </jxta:GenSRDI> Figure 17: Resolver SRDI 4.4.1.5 Listener and Element Naming The PRP communicates by exchanging Endpoint Messages. Endpoint Addresses specify a handler name. The PRP attaches a listener by that name to the Endpoint Service. Endpoint Service (Section 4.5.1). Duigou & Project JXTA Expires August 28, 2003 [Page 42] Internet-Draft JXTA v2.0 Protocols Specification February 2003 All PRP implementations MUST use the same scheme for building their handler names. The convention used by all services of the world peer group is to use the concatenation of the service name, the peer group ID, and a value unique within the service. ::= ::= ::= ::= "ORes" ::= "IRes" ::= "Isrdi" ::= "jxta.service.resolver" ::= SEE Figure 18: Listener Naming Syntax ABNF Thus, the listeners used by the PRP are currently named as follows: Queries : jxta.service.resolver[group unique Id string]ORes (ORES is a literal string) Responses : jxta.service.resolver[group unique Id string]IRes (IRESis a literal string) Srdi : jxta.service.resolver[group unique Id string]Isrdi (ISRDI is a literal string) Query and response messages are included in messages as elements named as follows: o QUERIES: [group unique Id string]ORes (ORES is a literal string) o RESPONSES: [group unique Id string]IRes (IRES is a literal string) o SRDI: [group unique Id string]Isrdi (ISRDI is a literal string) 4.4.1.6 Behavior Duigou & Project JXTA Expires August 28, 2003 [Page 43] Internet-Draft JXTA v2.0 Protocols Specification February 2003 4.4.1.6.1 Handler Name The Handler Name in PRP messages plays a role similar to that of the handler name in the Endpoint Message addresses: it is a demultiplexing key that specifies how, by which higher-level protocol, or by which module, the message is to be processed. In the Java and "C" reference implementations, the users of the PRP are typically services. Each instance of a given service (one per peer per group that uses this service) generates a handler name that is unique on its peer, but will be identical for the instances of this service on other peers. This is by convention achieved by concatenating the service name (which is unique in the group), the group id, which is unique in the peer, and a additional parameter which serves to discriminate between several handlers used by the same service, if needed. The handler name is used both to register the appropriate handler for incoming queries or responses, and as a destination for outgoing queries or responses. For convenience, most clients of the resolver do define two names: one for propagated messages (mostly queries), and one for unicast messages (mostly responses). The PRP SHOULD refuse, and the existing reference implementations SHALL refuse the registration of more than one handler with the same name. A service SHOULD register for any handler name that it uses as a destination, thereby preventing other services from registering themselves to receive these messages. This means that in principle a service or application that receives queries or responses from a service instance on another peer is de-facto the local instance of that service and SHOULD handle these messages as specified. PRP is designed for same-to-same communication, not client-server. 4.4.1.6.2 Policies and Quality of Service The PRP does not guarantee peers that define a query handler name will receive that query, nor does it mandate that all peers that define this handler name will receive it. Only a best effort is made at disseminating the query in a way that maximizes the chance of obtaining a response, if one can be obtained. There is no guarantee that a response to a resolver query request will be made. It is important to point that response to a ResolverQuery request is OPTIONAL. A peer is not required to respond. There is no guarantee that a Resolver SRDI Message will be honored. It is important to point out that accepting a Resolver SRDI Message is OPTIONAL. A peer is not required to accept the message. Duigou & Project JXTA Expires August 28, 2003 [Page 44] Internet-Draft JXTA v2.0 Protocols Specification February 2003 The PRP does not assume the presence of reliable message delivery. Multiple Resolver query messages may be sent--none, one, multiple or redundant responses may be received. The PRP provides a generic mechanism for services to send queries, and receive responses and SRDI messages. As a service, the reference implementation helps other services by taking care of all messaging aspects, caching queries responses, and SRDI messages and in forwarding queries, based on the invoker's decision. The PRP performs authentication, and verification of credentials and drops incorrect messages. The actual task of propagating a query to the next set of peers is delegated to the Rendezvous Protocol (Section 5.2.2). The Rendezvous service is responsible for determining the set of peers that should receive a message being propagated, but never automatically re-propagates an incoming propagated message. It is left to the service (query handler) handling the message to determine if further propogation should be performed. The PRP's policy is the following: if the query handler does not instruct the PRP to discard the query, and if the local peer is a rendezvous, then the query is re-propagated (within the limits of loop and TTL rules enforced by the Rendezvous service). In addition, if instructed by the query handler, an identical query may be issued with the local peer as the originator. 4.4.2 Endpoint Routing Protocol The JXTA network is ad hoc, multi-hop, and adaptive by nature. Connections in the network may be transient, and message routing is nondeterministic. Routes MAY be unidirectional and change rapidly. Peers MAY join and leave frequently. A peer inside a firewall can send a message directly to a peer outside a firewall. But a peer outside the firewall cannot establish a connection directly with a peer inside the firewall. The Endpoint Routing Protocol defines a set of request/query messages that are processed by a routing service to help a peer route messages to their destination. When a peer is asked to send a message to a given peer endpoint address, it looks in its local cache to see if it has a route to this peer. If it does not find a route, it sends a route resolver query message to its available peer routers asking for routing information. A peer can have as many peer routers as it can find or they can be pre-configured. Pre-configured routers are OPTIONAL. The peer routers provide the low-level infrastructure to route Duigou & Project JXTA Expires August 28, 2003 [Page 45] Internet-Draft JXTA v2.0 Protocols Specification February 2003 messages between two peers in the network. Any number of peers in a peergroup can elect themselves to become peer routers for other peers. Peers routers offer the ability to cache route information, as well as bridging different physical or logical networks. A peer can dynamically find its router peer via a qualified discovery search. A peer can find out if a peer it has discovered is a peer router via the peer advertisement element. When a peer router receives a route query, if it knows a route to the destination, it answers the query by returning the route information as an enumeration of hops. Once a route has been discovered, a message can be sent to the first router and that router will use the route information to route the message to the destination peer. The route is ordered from the next hop to the final destination peer. At any point the routing information MAY become obsolete requiring the current router to discover a new route in order to complete the message delivery. The peer endpoint adds extra routing information to the messages sent by a peer. When a message goes through a peer, the endpoint of that peers leaves its trace on the message. The trace can be used for loop detection, and to discard recurrent messages. The trace is also used to record new route information by peer routers. ERP provides last resort routing for a peer. More intelligent routing can be implemented by more sophisticated routing services in place of the core routing service. High-level routing services can manage and optimize routes more efficiently than the core service. JXTA intends is to provide the hooks necessary for user defined routing services to manipulate and update the route table information (route advertisements) used by the peer router. The intent is to have complex route analysis and discovery be performed above the core by high-level routing services, and have those routing services provide intelligent hints to the peer router to route messages. The Endpoint Routing Protocol (ERP) is used to find the available routes to send a message to a destination peer. This is accomplished through message exchanges between peer routers. Peer routing may be necessary to enable two peers to communicate depending on their location in the network. For instance, the two peers may be on different transports; the peers may be separated by a firewall; or may be using incompatible private IP address spaces. When necessary one or more peer routers can be used to deliver a message from the originating peer endpoint to the destination peer endpoint. 4.4.2.1 Endpoint Addresses JXTA Endpoints are identified using URIs known as Endpoint Addresses. Duigou & Project JXTA Expires August 28, 2003 [Page 46] Internet-Draft JXTA v2.0 Protocols Specification February 2003 Endpoint Addresses can describe both physical network locations and virtual addresses for peers and groups. ::= ( 0*1("/" "/" 0*1())) | ( 0*1("#" "/" 0*1())) ::= | | ) 0* ::= ":" | "://" | ) 0* ":" ::= | | | "%" ::= 0* ( | ) ::= 0* ( | ) ::= 0* SEE FOR DEFINITION OF SOME TERMS. http://192.168.0.11:9700/endpoint/resolver urn:jxta:uuid-59616261646162614E50472050325033D1D1D1D1D1D1D1D1D1D1D1D1D1D1D1D104?pipeService urn:jxta:jxta-NetGroup?relay/uuid-59616261646162614A7874615032503369D1041721754AD18D7D9137C06F77DD03 The Endpoint Service delegates the sending of outgoing messages to the endpoint protocol designated by the part of the message's destination address. The Endpoint Service delivers incoming messages to the listener registered under the name that matches in order of preference : o The and seperated by a "/". o The . 4.4.2.2 Route information Route information is represented as follow: Duigou & Project JXTA Expires August 28, 2003 [Page 47] Internet-Draft JXTA v2.0 Protocols Specification February 2003 Figure 21: Route Advertisement : The Peer ID of the peer who's route is described by this advertisement. : An Access Point Advertisement containing a list of endpoint addresses associated with the specified peer id. : A semi-ordered collection of Access Point Advertisements describing a route to the peer indicated by . The time-to-live parameter is measured in hops and specifies how long this route is valid. The creator of the route can decide how long this route will be valid. The gateways are defined as an ordered sequence of peer IDs which define the route from the source peer to the destination peer. The sequence may not be complete, but at least the first gateway SHOULD be present. The first gateway is sufficient to initially route the messages. The remaining gateway sequence is OPTIONAL. Peer routers will typically cache route information. Any peer can query a peer router for route information. Any peer in a peer group MAY become a peer router. 4.4.2.3 Route Query Message Duigou & Project JXTA Expires August 28, 2003 [Page 48] Internet-Draft JXTA v2.0 Protocols Specification February 2003 This message is sent by peers to request route information for another peer. Route Query Messages are transmitted as queries within Resolver Query Message (Section 4.4.1.2). Figure 22: Endpoint Router Query : The peer id of the peer who's route is desired. : Route advertiement of the peer requesting route information. This route information is needed to ensure their is a return route for responses. 4.4.2.4 Route Response Message This message is sent by peers in response to Route Query Messages. The Route Response Message contains a route advertisement for the destination peer. Route Response Messages are transmitted as responses within Resolver Response Message (Section 4.4.1.3). Duigou & Project JXTA Expires August 28, 2003 [Page 49] Internet-Draft JXTA v2.0 Protocols Specification February 2003 Figure 23: Endpoint Router Response Message : The Route Advertisement for the peer which was requested in the Endpoint Router Query. : Route Advertiement for the destination peer. 4.5 Core JXTA Message Transport Bindings 4.5.1 Endpoint Service 4.5.1.1 Description The Endpoint Service is responsible for performing end-to-end messaging between two JXTA peers, using one of the underlying JXTA transport protocols, such as the JXTA TCP or HTTP bindings. The Endpoint Service is primarily used by other services or applications that need to have an understanding of the network topology, such as the Resolver Service or the Propagation Service. The Endpoint Service is not responsible for routing messages for peers that are not directly connected to each other. This task is performed by the Endpoint Router Transport Protocol (Section 4.5.2) which provides the illusion that the source and destination peers are directly connected. 4.5.1.2 Protocol When the Endpoint Service transmits a message it MAY add a single element to the message: the source peer ID. The element name is: "jxta:EndpointHeaderSrcPeer" and its value is a textual UTF-8 representation of the peer ID at the point of emission Duigou & Project JXTA Expires August 28, 2003 [Page 50] Internet-Draft JXTA v2.0 Protocols Specification February 2003 of the message. This information is optional and is used by the emitter endpoint service itself to detect and eliminate progagated messages that loop back to the emitter. If this element is not present the message is assumed to not be looping back. The endpoint service expects incoming and outgoing messages to have a source address and a destination address. The encapsulation of that information is specified by the message wire format being used. 4.5.2 Endpoint Router Transport Protocol 4.5.2.1 Description The Endpoint Router is a logical JXTA Transport Protocol that sits below the Endpoint Service and beside the other Transport Protocols such as the JXTA TCP and HTTP Transport Protocols. The Endpoint Router is responsible for exchanging messages between peers that do not have a direct connection between each other. The Endpoint Router provides a virtual direct connection to the peer's Endpoint Service. 4.5.2.2 Protocol The Endpoint Router protocol defines a set of queries and responses used to communicate with instances of the Endpoint Router on other peers. o Route Query: when the Endpoint Router is requested to send a message to a peer for which it does not have yet a route for, it sends a Route Query request to other peers. Peers that have an route for the given peer answers with Route Response. o Route Response: a peer that desires inform another peer about a give route sends a Route Response to the peer. A Route Response is replied following up a Route Query. In addition, the Endpoint Router defines an informational message that requires no reply. o NACK: a NACK is sent by any peer that detects that a route used by another peer is not valid. Typically, this happens by a router peer that are requested to route a message to peer for which it does not have a route itself. NACK messages are optional: routers are not required to send them, and while a NACK is typically sent to the source peer of the message, peers can send NACK to other Duigou & Project JXTA Expires August 28, 2003 [Page 51] Internet-Draft JXTA v2.0 Protocols Specification February 2003 peers of their choice. These messages are sent and received by the EndpointRouter using the JXTA Resolver Service. 4.5.2.3 EndpointRouter Message Element The Endpoint Router Transport Protocol appends its own message element to each message it transports. The name of the message element is "JxtaEndpointRouter" and contains an XML document containing the following: Figure 24: Endpoint Router Message Element : Endpoint Address of the original sender of this message. Will be a peer id based Endpoint Address. : The Endpoint Address of the intended final destination of this message. Includes final routing information of the service name and service parameter. : The Endpoint Address of the most recent peer to forward this message. When a peer forwards a message, it SHOULD update this field with its own Endpoint Address. : A loosely ordered array of Access Point Advertisements which describe a probable route for this message. Loosely ordered because it may describe alternatives. Duigou & Project JXTA Expires August 28, 2003 [Page 52] Internet-Draft JXTA v2.0 Protocols Specification February 2003 : A loosely ordered array of Access Point Advertisements which describe a known reverse route for this message. This is the path which the message has traveled thus far. Loosely ordered because it may describe alternatives. 4.5.2.3.1 EndpointRouter Endpoint Address format Since the EndpointRouter is a transport protocol, it has its own Endpoint Address format, which is: jxta://[PEERID UNIQUE VALUE] Figure 25: JXTA Endpoint Router Address Format 4.6 Messages Messages are the basic unit of data exchange between peers. Pipes send and receive messages to and from services; any protocol implemented by a service will send and receive messages. Messages are encoded using "wire" representations for transmission. Each JXTA transport will use the message representations most appropriate for its characteristics and the peers' preferences. See JXTA Message Wire Representations (Section 5.4) for information about representations. 4.6.1 Message A message is a set of named and typed contents called elements. Thus a message is essentially a set of name/value pairs. The content can be an arbitrary type. Many core services send XML advertisements as message element contents. As a message passes down a protocol stack (applications, services, endpoint and transports), each level may add one or more named elements to the message. As a message is passed back up the stack on the receiving peer, the protocol handlers SHOULD remove those elements. A message is an ordered sequence of message elements. The most recently added element appears at the end of the message. 4.6.2 Element A message element contains a namespace, an optional name, an optional type, an optional signature or digest and content. Duigou & Project JXTA Expires August 28, 2003 [Page 53] Internet-Draft JXTA v2.0 Protocols Specification February 2003 4.6.2.1 Namespace Every element is assigned to a namespace. Namespaces are used to organize elements used by different message users and transports within the same message. Two namespaces names are considered equivalent if their representation in canonical UTF8 (NFC) (see Unicode Standard Annex #15 : Unicode Normalization Forms [USA15] [12]) is byte-for-byte identical. Two message element namespaces are pre-defined, """" (empty string) and "jxta". The """" namespace is reserved for user applications and services--none of the JXTA protocols or services will use or modify elements in this namespace. The "jxta" namespace is reserved for internal use by the JXTA protocols and services. Applications SHOULD NOT create, manipulate or assume the interpretation of any of the content of elements in the "jxta" namespace. In some bindings, applications MAY be forbidden from accessing or creating elements in the "jxta" namespace. Use of namespaces by services and applications other than the "" namespace is OPTIONAL. Namespaces require no formal registration as the protocols used need only be agreed upon by the participants. 4.6.2.2 Name Elements may have an optional name. Elements in the same message MAY have the same name. 4.6.2.3 Type A type is specified as a MIME type. See [RFC2046] [4]. The MIME type is encoded in canonical UTF8 (NFC) using the presentation and encoding of Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types [RFC2046] [4], ie. any encoding specified by RFC 2046 is performed before the string is encoded into UTF8 from its native representation. The type is used by the applications and services that process the element. There is no restriction on the set of MIME types that can be used by applications and services. In addition to the applications and services which use the particular element, the type of the element may also be examined by the JXTA message transport to determine how to format the message element to ensure the most effcient transfer. Duigou & Project JXTA Expires August 28, 2003 [Page 54] Internet-Draft JXTA v2.0 Protocols Specification February 2003 If the type is not specified for an element "application/ octet-stream" is assumed. 4.6.2.4 Content The contents of the Element data are opaque to except to the applications and services which use these elements. Duigou & Project JXTA Expires August 28, 2003 [Page 55] Internet-Draft JXTA v2.0 Protocols Specification February 2003 5. JXTA Standard Services 5.1 Introduction The JXTA Core Specification (Section 4) defines the required components and behaviours for all JXTA implementations. In order to create a complete JXTA implementation there are some additional components which all implementation SHOULD provide. The JXTA Standard Services are OPTIONAL JXTA components and behaviours. Implementations are not required to provide these services, but are strongly RECOMMENDED to do so. Implementing these services will provide greater interoperability with other implementations and broader functionality. 5.2 Standard Protocols 5.2.1 Peer Discovery Protocol 5.2.1.1 Introduction The Peer Discovery Protocol is used to discover any published peer resource. Resources are represented as advertisements. A resource can be a peer, a peergroup, a pipe, a module, or any resource that has an advertisement. Each resource MUST be represented by an advertisement. The Peer Discovery Protocol (PDP) enables a peer to find advertisements in its group. The PDP protocol is the discovery protocol of the world peergroup. Custom discovery services MAY choose to leverage PDP. If a peer group does not need to define its own discovery protocol, it may use the world peergroup PDP. The intent is for PDP to provide the essential discovery infrastructure for building and bootstrapping high-level discovery services. In many situation, discovery information is better known by a high-level service, because the service may have a better knowledge of the group topology. The PDP protocol provides a basic mechanism to discover advertisements while providing hooks so high-level services and applications can participate in the discovery process. Services SHOULD be able to give hints to improve discovery (i.e. decide which advertisements are the most valuable to cache). The PDP protocol utilizes the resolver protocol to route queries and responses. Duigou & Project JXTA Expires August 28, 2003 [Page 56] Internet-Draft JXTA v2.0 Protocols Specification February 2003 5.2.1.2 Discovery Query Message The discovery query message is used by peers to send discovery requests when searching for advertisements. Figure 26: Discovery Query Schema : Only advertisements of requested type will be matched. Possible values are: "0" : Peer Advertisements "1" : Peergroup Advertisements "2" : Any Advertisements : specifies the maximum number of advertisements that each responding peer SHOULD provide. The total number of results received depends on the number of peers that respond and the advertisements they have. If is "0" (Peer Advertisements) and is "0", then the query has a special meaning: its objective is to collect Peer Advertisements of respondents. Duigou & Project JXTA Expires August 28, 2003 [Page 57] Internet-Draft JXTA v2.0 Protocols Specification February 2003 Therefore any peer SHOULD respond to such a query, e ven though no results are to be included. : If present, the advertisement of the requestor. , : Must either be both present or absent. If absent, then each respondent should supply a random set of advertisements of the appropriate type up to count. Only advertisements containing an element who's name matches and that also contains a value matching are eligible to be found. may begin or end with "*", or both. In that case will match all values that end with or beginning with, or contain the rest of the string. If contains only "*" the result is unspecified. Some implementations may choose not match any advertisement for "*". 2 1 Name *sidus* <?xml version="1.0"?> <!DOCTYPE jxta:PA> <jxta:PA xmlns:jxta="http://jxta.org"> <PID> urn:jxta:uuid-59616261646162614A7874615032503304BD268FA4764960AB93A53D7F15044503 </PID> ... REMAINDER OMITTED FOR BREVITY ... </jxta:PA> Figure 27: Discovery Query 5.2.1.3 Discovery Response Message A Discovery response message is used by a peer to respond to a discovery query message. Duigou & Project JXTA Expires August 28, 2003 [Page 58] Internet-Draft JXTA v2.0 Protocols Specification February 2003 Figure 28: Discovery Response Schema : The type of all the advertisements returned in the element(s). : If present, the number of element(s) included in this response. : If present, the advertisement of the respondent. The "Expiration" attribute is the associated relative expiration time in milliseconds. , : If present, reflects that of the DiscoveryQuery to which this is the response. : An advertisement.The "Expiration" attribute is the associated relative expiration time in milliseconds. Duigou & Project JXTA Expires August 28, 2003 [Page 59] Internet-Draft JXTA v2.0 Protocols Specification February 2003 2 1 Name *sidus* <?xml version="1.0"?> <!DOCTYPE jxta:PA> <jxta:PA xmlns:jxta="http://jxta.org"> <PID> urn:jxta:uuid-59616261646162614A7874615032503304BD268FA4764960AB93A53D7F15044503 </PID> ... OMITTED ... </jxta:PA> <?xml version="1.0"?> <!DOCTYPE jxta:PipeAdvertisement> <jxta:PipeAdvertisement xmlns:jxta="http://jxta.org"> <Id> urn:jxta:uuid-094AB61B99C14AB694D5BFD56C66E512FF7980EA1E6F4C238A26BB362B34D1F104 </Id> <Type> JxtaUnicastSecure </Type> <Name> JxtaTalkUserName.sidus </Name> </jxta:PipeAdvertisement> Figure 29: Discovery Response 5.2.1.4 Behaviour 5.2.1.4.1 Policies and Quality of Service The PDP does not guarantee peers that receive a query will respond to the query, nor does it mandate that the number of advertisements requested will be honored. Only a best effort is made at matching the Duigou & Project JXTA Expires August 28, 2003 [Page 60] Internet-Draft JXTA v2.0 Protocols Specification February 2003 query to results in the respondant's cache. There is no guarantee that a response to a discovery query request will be made. It is important to point out that responding to a DiscoveryQuery request is OPTIONAL. A peer is not required to respond to a DiscoveryQuery request. A reliable transport is OPTIONAL with the PDP. Multiple Discovery query messages may be sent. None, one, multiple or redundant responses may be received. A peer may receive a DiscoveryResponse that is not a response to any DiscoveryQuery initiated by the peer, this mechanism provides the ability to remote publish a resource. The PDP provides a mechanism for services to query the network for JXTA resources, and receive responses. As a service, the reference implementation helps other services by taking care of all messaging aspects, caching, and expiring advertisements. The actual task of propagating, and re-propagating a query to the next set of peers is delegated to the Resolver Service. 5.2.2 Rendezvous Protocol 5.2.2.1 Introduction The Rendezvous Protocol (RVP) is responsible for propagating messages within a JXTA Peergroup. While different Peergroups may have different means to propagate messages, the Rendezvous Protocol defines a simple protocol that allows: o Enables peers to connect to services (propagates messages to other peers and receive propagated messages from other peers) o Control the propagation of the message (TTL, loopback detection, etc.). 5.2.2.2 Rendezvous Advertisement A Rendezvous advertisement describes a peer that acts as a rendezvous peer for a given PeerGroup. Those advertisements can be published and retrieved, so peers that are looking for rendezvous peers can find them. Duigou & Project JXTA Expires August 28, 2003 [Page 61] Internet-Draft JXTA v2.0 Protocols Specification February 2003 Figure 30: Rendezvous Advertisement Schema : This is an optional name that can be associated with the rendezvous peer. Often the same as the peer name. : This is a required element that contains the JxtaID of the PeerGroup for which the peer is a rendezvous. : This is a required element that contains the JxtaID of the peer which is a rendezvous. 5.2.2.3 Behaviour 5.2.2.3.1 Peer connection RVP introduces the notion of special peers, called Rendezvous peers, which can be used to re-propagate messages they have received. A peer can become dynamically a rendezvous peer and/or can dynamically connect to a rendezvous peer. The connection between a peer to a rendezvous peer is achieved by an explicit connection, associated to a lease. This connection is performed by sending messages using the JXTA Endpoint Protocol. Each RVP is listening on an EndpointAddress with the following Service Name and Service Param: o service name: JxtaPropagate o service param: PeerGroup ID A set of queries and responses are defined by the Rendezvous Protocol in order to establish connections: o LEASEREQUEST This request is sent by a peer that desire to connect to a given rendezvous. No indication of the amount of the lease: the rendezvous will give whatever it feels is appropriate. A lease can always be canceled by both parties at anytime if necessary. A Duigou & Project JXTA Expires August 28, 2003 [Page 62] Internet-Draft JXTA v2.0 Protocols Specification February 2003 rendezvous that grants a lease returns LeaseGranted. o LEASEGRANTED This message is sent by a rendezvous that is granted a lease to a given client. The amount of time the lease is granted for is included in the message. o LEASECANCELREQUEST This message is sent by a client to its rendezvous in order to cancel an existing lease. The rendezvous is expected to reply with LeaseCancelled. NOTE: the Peer Resolver protocol is not used to send those message: the Rendezvous Protocol sits directly on top of the Endpoint Routing Protocol (Section 4.4.2). The reason of this is layering: the Peer Resolver Protocol itself sit on top of the Rendezvous Protocol. 5.2.2.3.2 Propagation control The Rendezvous Protocol is responsible for controlling the propagation of messages. The Rendezvous Protocol will propagate a message unless of the following conditions is detected: o Loop: if a propagated messages has already been processed on a peer, it is discarded. o TTL: propagated messages are associated with a Time To Live (TTL). Each time a propagated message is received on a peer, its TTL is decreased by one. When the TTL of a message drops to zero, the message is discarded. o Duplicate: each propagated message is associated with a unique identifier. When a propagated message has been duplicated, and has already been received on a peer, duplicates are discarded. This control is performed by embedding a Message Element within each propagated message that is defined as: Duigou & Project JXTA Expires August 28, 2003 [Page 63] Internet-Draft JXTA v2.0 Protocols Specification February 2003 Figure 31: RendezVous Propagate Message Schema 5.2.2.3.3 Lease Request Message When a peer wants to connect to a Rendezvous Peer, it sends a message with the a message element named jxta:Connect which contains its Peer advertisement. 5.2.2.3.4 Lease Granted Message When a rendezvous peer grants a lease (upon a lease request), it sends a message to the source of the lease request, containing the following message elements: jxta:ConnectedLease : This message element contains (in a String representation) the time in milliseconds the lease is granted for. This message element is mandatory. jxta:ConnectedPeer : This message element contains the PeerID of the rendezvous peer that has granted the lease. This message element is mandatory. jxta:RdvAdvReply : This message element contains the Peer Advertisement of the rendezvous peer that grants the lease. This message element is optional. 5.2.2.3.5 Lease Cancel Message When a peer wants to cancel a lease, it sends a message with the following message element: o "jxta:Disconnect": This message element contains the Peer Advertisement of the peer which is requesting to cancel the lease. This message element is mandatory. Duigou & Project JXTA Expires August 28, 2003 [Page 64] Internet-Draft JXTA v2.0 Protocols Specification February 2003 5.2.3 Peer Information Protocol Once a peer is located, its capabilities and status may be queried. PIP provides a set of messages to obtain a peer status information. PIP is an OPTIONAL JXTA protocol. Peers are not required to respond to PIP requests. A reliable transport is OPTIONAL for PIP. Multiple peer information messages may be sent. None, one or multiple responses MAY be received in response to any query. The PIP is layered upon the Peer Resolver Protocol (Section 4.4.1). The element is used to match PIP queries containing elements to the PIP Response Messages containing the matching responses. 5.2.3.1 Obtaining PIP Responses The PIP Query Message provides a REQUEST field that MAY be used to encode a specific request. PIP does not dictate the format of the REQUEST field and it is left up to the consumer to do so. Higher-level services MAY utilize the request field to offer expanded capabilities. 5.2.3.2 PIP Query Message The query message is sent to a peer to query the current state of the peer, and obtain other relevant information about the peer. A query without a defined request field returns a default set of information about a peer (i.e. uptime, message count, etc.). Figure 32: PIP Query Message : The peer id of the requesting peer. Duigou & Project JXTA Expires August 28, 2003 [Page 65] Internet-Draft JXTA v2.0 Protocols Specification February 2003 : The peer id of the peer being queried. : An optional Request structure. 5.2.3.3 PIP Response Message The Peer Information Protocol Response Message provides specific information about the current state of a peer, such as uptime, inbound and outbound message count, time last message received, and time last message sent. Duigou & Project JXTA Expires August 28, 2003 [Page 66] Internet-Draft JXTA v2.0 Protocols Specification February 2003 Figure 33: PIP Response Message : The peer id of the requesting peer. : The peer id of the peer being queried. : The relative time in milliseconds since the responding Peer Information Service began execution. Peers SHOULD provide this tag in all responses, but MAY chose to not implement it if the information is unavailable or would represent a security breach. : The relative time in milliseconds since the responding Peer Information Service began execution. Peers SHOULD provide this tag in all responses, but MAY chose to not implement it if the information is unavailable or would represent a security breach. : The absolute time at which this response was generated. Measured in milliseconds since "the epoch", namely January 1, 1970, 00:00:00 GMT. Peers SHOULD provide this tag in all responses, but MAY chose to not implement it if the information is unavailable or would represent a security breach. : Potentially contains a response to a previous request from a PIP Query. To match queries to responses the QUERYID element of the Peer Resolver Protocol (Section 4.4.1) MUST match. This field can contain any desired content. : Contains information about the network traffic performed by the target peer. This element is OPTIONAL. : The absolute time at which this peer last received a valid JXTA message on one of its transports. Measured in milliseconds since "the epoch", namely January 1, 1970, 00:00:00 GMT. Peers SHOULD provide this tag in all responses, but MAY chose to not implement it if the information is unavailable or would represent a security breach. : The absolute time at which this peer last sent a valid JXTA message on one of its transports. Measured in milliseconds since "the epoch", namely January 1, 1970, 00:00:00 GMT. Peers SHOULD provide this tag in all responses, but MAY chose to not implement it if the information is unavailable or would represent a security breach. Duigou & Project JXTA Expires August 28, 2003 [Page 67] Internet-Draft JXTA v2.0 Protocols Specification February 2003 : If present, contains elements which describe incoming traffic from various endpoint addresses. : Provides the number of bytes received by the named endpoint address. : If present, contains elements which describe outgoing traffic from various endpoint addresses. : Provides the number of bytes transmitted by the named endpoint address. 5.2.4 Pipe Binding Protocol The Pipe Binding Protocol (PBP) is used by applications and services in order to communicate with other peers. A pipe is a virtual channel between two endpoints described in a Pipe Advertisement. There are two ends of a Pipe: the Input Pipe (receiving end) and the Output Pipe (sending end). The Pipe Binding Protocol is layered upon the Endpoint Protocol, and will use a variety of Message Transports such as the JXTA HTTP Transport, the JXTA TCP/IP Transport, or the secure JXTA TLS Transport for the sending of messages. A pipe can be viewed as an abstract named message queue, supporting create, open/resolve (bind), close (unbind), delete, send, and receive operations. Actual pipe implementations may differ, but all compliant implementations use the PBP to bind the pipe to an endpoint. A reliable message transport is OPTIONAL. Multiple binding query messages may be sent. None, one or multiple responses may be received. 5.2.4.1 Pipe Advertisement A Pipe Advertisement describes a pipe. The pipe advertisement is used by the pipe service to create associated local input and output pipe endpoints. Each pipe advertisement includes a Pipe ID which is the canonical name for the pipe. Duigou & Project JXTA Expires August 28, 2003 [Page 68] Internet-Draft JXTA v2.0 Protocols Specification February 2003 Each pipe advertisement MUST include a pipe type.There are currently three different types of pipes: o "JxtaUnicast" Unicast, unsecure and unreliable. This type of pipe is used to send one-to-one messages. o "JxtaUnicastSecure" Unicast, secure (using TLS). An extension of the "JxtaUnicast", except that the data is protected using a virtual TLS connection between the endpoints. o "JxtaPropagate" Diffusion pipes. This pipe type is used to send one-to-many messages. Any peer that has enabled an Input Pipe on a propagate type pipe receives messages that are sent onto it. A pipe advertisement MAY include an optional symbolic name. Figure 34: Pipe Advertisement Schema : This is a required element that uniquely identifies the pipe. Each pipe has a unique id. See IDs (Section 4.2) for description of JXTA Ids. : This is an required element that defines the type of the pipe. The following types are currently defined: "JxtaUnicast" : may not arrive at the destination, may be delivered more than once to the same destination, may arrive in different order. "JxtaUnicastSecure" : may not arrive at the destination, may be delivered more than once to the same destination, may arrive in different order, but is encrypted using TLS. "JxtaPropagate" : one to many pipe. Duigou & Project JXTA Expires August 28, 2003 [Page 69] Internet-Draft JXTA v2.0 Protocols Specification February 2003 : This is an optional name that can be associated with a pipe. The name is not required to be unique unless the name is obtained from a centralized naming service that guarantee name uniqueness. urn:jxta:uuid-094AB61B99C14AB694D5BFD56C66E512FF7980EA1E6F4C238A26BB362B34D1F104 JxtaUnicast Talk to Me! Figure 35: Pipe Advertisement 5.2.4.2 Pipe Resolver Message This message is used by the Pipe Resolver to find an Input Pipe endpoint bound to the same pipe advertisement. The same message schema is used for both the resolve query and for the response. Duigou & Project JXTA Expires August 28, 2003 [Page 70] Internet-Draft JXTA v2.0 Protocols Specification February 2003 Figure 36: Pipe Resolver Message Schema : Used to indicate if it is the Query or the Answer. May be one of: "Query" : This is a query. "Answer" : This is a response. : The Pipe ID which is being resolved. : The type of pipe resolution being requested. This value MUST match the value of from the Pipe Advertisement. : If "false", peers which do not have the pipe bound locally as an Input Pipe MUST NOT respond to the query. They MAY forward the query to peers which they believe to have the pipe bound as an Input Pipe. This feature is deprecated and Duigou & Project JXTA Expires August 28, 2003 [Page 71] Internet-Draft JXTA v2.0 Protocols Specification February 2003 implementations SHOULD treat the tag as always being "false". : A peer id. In Queries, if present, it specifies the Peer ID of the only peer from which responses will be expected. Responses from all other peers MAY be ignored. This does not guarantee a response to the pipe binding request will be made by the peer. Response to pipe binding requests is always OPTIONAL. In Answer messages, all of the peers on which the Input Pipe is known to be bound. : Used to indicate if the Input Pipe was found on the specified peer. : Peer Advertisement of the peer which resolved the Input Pipe. This peer MAY appear in the list of peer ids on which the Input Pipe is bound, but this should not be assumed. 5.3 Standard JXTA Message Transports JXTA defines several Message Transport Bindings for implementing JXTA messaging on top of existing networks. 5.3.1 TCP/IP Message Transport 5.3.1.1 Introduction This section describes the TCP/IP Message Transport, the most commonly used Message Transport by JXTA. It is named the TCP/IP binding because it uses no other underlying protocols whereas other Message Transports build upon, for example, the HTTP [RFC2616] [9], TLS [RFC2246] [8], BEEP [RFC3080] [10][RFC3081] [11] and SMTP [RFC821] [2] protocols. The TCP/IP transport is designed to be the simplest and quickest to implement of the JXTA Message Transport bindings. Unfortunately, the TCP/IP Message Transport can be adversely affected by the partitioning of the Internet Address Space caused by Network Address Translation (NAT), Firewalls, and conflicting use of Private IP Address ranges. For these circumstances one of the other Message Transports may be more effcient. 5.3.1.2 Choreography This section describes the protocol exchange implemented by the JXTA TCP/IP Message Transport. The two participants operate symetrically, the message sequence is the same for both sides. Duigou & Project JXTA Expires August 28, 2003 [Page 72] Internet-Draft JXTA v2.0 Protocols Specification February 2003 o Connection Opens o Welcome Message o Message(s) o Connection Closes The connection MAY be closed by either peer following the transmission of any number of messages. If a peer discover an error in the transmission ( unexpected input, unsupported message content, framing problems, etc. ) it MUST close the connection. 5.3.1.3 Welcome Message The Welcome Message is sent by both peers of a JXTA TCP/IP Communication. It's primary purpose is to identify the endpoint address that each peer has associated with TCP/IP connections on that interface/port. Additionally, the welcome message provides a reasonable "ping" response if the only goal of the connection is to determine connectivity. A peer SHOULD send its Welcome Message as soon as the connection is open, but MUST NOT send any Message Bodies until it has received a Welcome Message from the remote peer. A peer MUST send its peer id as the connection endpoint address. The welcome message can be no longer than 4096 octets in length, though in practice it will almost always be much shorter. Duigou & Project JXTA Expires August 28, 2003 [Page 73] Internet-Draft JXTA v2.0 Protocols Specification February 2003 ::= ::= "JXTAHELLO" ::= octect #x20 ::= ::= ::= ::= "0" | "1" ::= "1.1" ::= octet #x0D octet #x0A This message is designed to be human readable. This primarily for the purpose of debugging. This message also allows a peer to be "pinged" using Telnet or a web browser. : The assumed destination of messages which will be sent on this connection. If a received message has no destination address then this is the address that should be used. : The public address of the JXTA Message Transport instance which is handling this connection. : Provides the peer id of the peer you have reached with this connection. : If "1" then the remote peer does not wish to receive propagate/broadcast messages on this connection. JXTAHELLO tcp://69.3.88.186:34368 tcp://209.25.154.236:9701 urn:jxta:uuid-59616261646162614A7874615032503345A8391EC0914B24B264AF31F297A6FD03 1 1.1 5.3.1.4 Message Transmission Following the Welcome Message (Section 5.3.1.3), the connection is used to send JXTA Messages. Each message is preceeded by a small amount of header information. The header information is similar to HTTP headers, but is binary encoded to provide for lighter-weight parsing. Duigou & Project JXTA Expires August 28, 2003 [Page 74] Internet-Draft JXTA v2.0 Protocols Specification February 2003 ::= ::= (
)*
::= ::= octet [length] (octets)[length] ::= octet [length msb] octet [length lsb] (octets) [length] ::= octet #x00 ::= octets The header block will contain both REQUIRED headers and may contain additional OPTIONAL headers. The headers are loosely ordered. Headers of a particular type are considered by ordered only with respect to other headers of the same type, they have no order relationship to headers of other types. In general, headers may appear in any order. The header names are case-insensitive canonical UTF8 (NFC) (see Unicode Standard Annex #15 : Unicode Normalization Forms [USA15] [12] strings. 5.3.1.4.1 JXTA Message Package - Required Headers These headers MUST appear in every message transmission and have no default values. "content-length" : the length of the portion. If "content-coding" headers are included, this length is still the transfer length, not the logical length of the body. The header body is an eight octet "network byte order" length. "content-type" : The logical type of the message body expressed as a MIME-type. The header body consists of a MIME type encoded in canonical UTF8 (NFC) using the presentation and encoding of Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types [RFC2046] [4], ie. any encoding specified by RFC 2046 is performed before the string is encoded into UTF8 from the implementation native string representation. Peers MUST treat unrecognized "content-type" specifications as an error and close the connection. 5.3.1.4.2 JXTA Message Package - Optional Headers These headers MAY appear in any message transmission and have no Duigou & Project JXTA Expires August 28, 2003 [Page 75] Internet-Draft JXTA v2.0 Protocols Specification February 2003 default values. "content-coding" : Specifies a coding which has been applied to the logical message body prior to transmission. The header body contains an eight octet "network byte order" value which was the length of the message body before encoding. This is followed by the Mime-type of the content coding. "content-coding" headers are listed in the order in which they were applied, ie. The first "content-coding" header was the first coding applied and will be the last to be removed. All other possible headers are also OPTIONAL. Unrecognized optional headers SHOULD be ignored. 5.3.1.5 IP Multicast Usage The TCP Transport may be configured to accept broadcast messages through IP Multicast. Messages received are not part of an ongoing connection between peers. Each broadcast message is idempotent. The datagram is formed similarily to that used for unicasts connections. It consists of : o A Welcome Header o A Message Package Header o A single message Additionally, in order to fully specify the source of the message, the Message Package Header MUST contain the following header field. "srcEA" : The public addresss of the transport which is sending this broadcast message. 5.3.2 HTTP Message Transport The JXTA HTTP Message Transport is logically divided into two functions: the initiator and the receiver. The initiator is able to establish connections, whereas the receiver is able accept connections. A peer may provide either function or both. The HTTP Message Transport is designed to work effeciently with or without HTTP 1.1 persistent connections and also impose a minimum of overhead beyond that required by HTTP itself. Duigou & Project JXTA Expires August 28, 2003 [Page 76] Internet-Draft JXTA v2.0 Protocols Specification February 2003 5.3.2.1 The HTTP Initiator The HTTP Initiator begins the connection between two peers. The connection is first used to determine the logical identities of the participating peers. In most cases, this is simply a verification as the connection address was chosen by the initiator to communicate with the desired peer. The HTTP Initiator uses two types of HTTP request to communicate with the recevier. "GET" requests are used for determining the logical identity of the HTTP Receiver and for polling the HTTP Receiver for messages. "POST" requests are used for sending and receiving JXTA messages with the receiver. 5.3.2.2 The HTTP Receiver The HTTP Receiver accepts incoming connections from HTTP initiators. The HTTP Receiver then acts in response to HTTP requests from the initiator. The HTTP Receiver accepts two types of HTTP request from the initiator, "GET" requests and "POST" requests. "GET" requests can be used for two tasks: determining the logical identity of the receiver, polling for messages destined to the initiator. "POST" requests are used to send messages to the receiver and optionally to receive messages from the receiver. 5.3.2.3 HTTP Messages 5.3.2.3.1 Ping Command The "ping" command is used to determine the logical identity (peer id) of a receiver. It also has the effect of determining connectivity (hence the name). The HTTP initiator issues a request as follows: Request : "GET" Resource : "/" The HTTP Receiver should respond to well-formed requests as follows: Response Code : "200" Duigou & Project JXTA Expires August 28, 2003 [Page 77] Internet-Draft JXTA v2.0 Protocols Specification February 2003 "Content-Length" : MUST always be present. "Content-Type" : MUST be "text/plain;charset="UTF-8"". Response Body : The peer id of the HTTP receiver expressed as a JXTA Endpoint Address. REQUEST: GET / HTTP/1.1 RESPONSE: 200 content-length=61 content-type=text/plain;charset="UTF-8" jxta://urn:jxta:uuid-59616261646162614A7874615032503304BD268FA4764960AB93A53D7F15044503 5.3.2.3.2 Poll Command The "poll" command is used by the HTTP intiator to retreive a message from the HTTP receivers. The HTTP initiator issues a request as follows: Request : "GET" Resource : "/"[initiator peerid]"?"[delay],[lazyClose] initiator peerid : The unique portion of the peerid of the initiator, ie. without the "urn:jxta:" prefix. delay : A time duration in milliseconds for which the HTTP Receiver SHOULD wait if there is no message for this initiator immediately pending. Expressed as a positive decimal integer. If there is no delay specified, the receiver should assume a value of "0" (zero). A delay value of "0" (zero) implies that the HTTP Receiver SHOULD hold the connection for as long as possible. The HTTP Receiver should respond to well-formed requests as follows: Duigou & Project JXTA Expires August 28, 2003 [Page 78] Internet-Draft JXTA v2.0 Protocols Specification February 2003 Response Code : "200" "Content-Length" : MUST always be present. If no message was available then "0" should be returned. "Content-Type" : MUST match the content type of the JXTA Message Body which forms the response, if any. Response Body : A well-formed JXTA Message Body REQUEST: POST /uuid-59616261646162614A7874615032503304BD268FA4764960AB93A53D7F15044503?0 HTTP/1.1 RESPONSE: 200 content-length=0 5.3.2.3.3 Send Command The "send" command is used by the HTTP intiator to send a message to the HTTP receiver and optional retrieve a response message. The HTTP initiator issues a request as follows: Request : "POST" Resource : "/"[initiator peerid]"?"[delay] initiator peerid : The unique portion of the peerid of the initiator, ie. without the "urn:jxta:" prefix. delay : A time duration in milliseconds for which the HTTP Receiver should wait if there is no message for this initiator immediately pending. Expressed as a decimal integer. If negative, the HTTP Receiver SHOULD NOT send a message in the response. If there is no delay specified, the receiver should assume a value of "0". A delay value of "0" (zero) implies that the HTTP Receiver SHOULD hold the connection for as long as possible. Duigou & Project JXTA Expires August 28, 2003 [Page 79] Internet-Draft JXTA v2.0 Protocols Specification February 2003 "Content-Length" : MUST always be present. "Content-Type" : MUST match the content type of the JXTA Message Body which forms the response. Request Body : A well-formed JXTA Message Body The HTTP Receiver should respond to well-formed requests as follows: Response Code : "200" "Content-Length" : MUST always be present. If no message was available then "0" should be returned. "Content-Type" : MUST match the content type of the JXTA Message Body which forms the response, if any. Response Body : A well-formed JXTA Message Body REQUEST: POST /uuid-59616261646162614A7874615032503304BD268FA4764960AB93A53D7F15044503?-1 HTTP/1.1 RESPONSE: 200 content-length=0 5.3.3 TLS Transport Binding 5.3.3.1 Introduction JXTA implements "IETF RFC 2246 : Transport Layer Security Version 1" [RFC2246] [8] on top of the Endpoint Router Transport Protocol (Section 4.5.2) using JXTA messages. Messages are transmitted across one of the other Transport Bindings. This implementation provides for secure message delivery between Peer Endpoints even when multiple hops across JXTA peers must be used. 5.3.3.2 TLS Messages The TLS protocol exchange is accomplished between the participant Duigou & Project JXTA Expires August 28, 2003 [Page 80] Internet-Draft JXTA v2.0 Protocols Specification February 2003 peers using JXTA Messages. Three JXTA Message Element types are used to implement the protocol: o TLS Contents o Acknowledgements o Retries 5.3.3.2.1 TLS Content Element Used to transfer TLS content between peers. Element Name : UTF-8 String containing the sequence number of this element. Sequence numbers are monotonically increasing positive integers. Element Type : "application/x-jxta-tls-block" Element Data : TLS Protocol Data per "IETF RFC 2246" [RFC2246] [8] 5.3.3.2.2 TLS ACK Element Used to transfer TLS content between peers. Element Name : "TLSACK" as a UTF-8 String. Element Type : "application/x-jxta-tls-ack" Sequential ACK : Network Byte Order Unsigned 32 Bit Integer. Indicates that the remote peer has successfully received all of the messages with sequence numbers up to and including this value. Selective ACKs (optional) : Network Byte Order Unsigned 32 Bit Integer(s). Each entry is the sequence number of a message which has been successfully received by the remote peer. Entries are all greater than the sequential ACK value and in numerically increasing order. 5.3.3.2.3 Retry Element Used to signify that this message is being sent as a retry of an Duigou & Project JXTA Expires August 28, 2003 [Page 81] Internet-Draft JXTA v2.0 Protocols Specification February 2003 apparently failed previous send attempt. If present, this element will accompany a TLS Content Element (Section 5.3.3.2.1). The element is mostly informational, but can be used to assist in window control. Element Name : "MARKRetr" as a UTF-8 String. Element Type : "text/plain;charset="UTF-8"" Element Data : "TLSRET" as a UTF-8 string. 5.4 JXTA Message Wire Representations There are two standard representations for JXTA Messages, XML and binary. Each JXTA transport will use the representations most appropriate. 5.4.1 General Requirements Message encodings for network transports MUST allow for the transmission of arbitrary numbers of message sections containing an arbitrary amount of data. Message Elements with duplicate names MUST be supported. 5.4.2 Binary Message Format Transports, such as TCP, which require a compact representation for a message will use the binary format. This format is designed such that all components are of declared size, no parsing is ever required to determine lengths. msg ::= "jxmg" version ; One byte. Currently binary "0". namespaces element_count ; two bytes (binary) 1* elm namespaces ::= namespace_count ; two bytes (binary) 0* namespace ; Each namespace is a string namespace ::= string Duigou & Project JXTA Expires August 28, 2003 [Page 82] Internet-Draft JXTA v2.0 Protocols Specification February 2003 string ::= len2 ; two bytes (binary) len2 * UTF8 chars ; characters elm ::= "jxel" ; signature namespaceid ; one byte (binary) flags ; Indicates which parts follow (binary) name ; element name [type] ; Present if (flags & HAS_TYPE) len4 ; Four byte binary length of content content ; [signature] ; associated signature element ; Present if (flags & HAS_SIGNATURE) type ::= string content ::= len4 * byte ; the bytes of the content. signature ::= elm flags ::= byte ; HAS_TYPE = 0x01; ; HAS_ENCODING = 0x02; ; HAS_SIGNATURE = 0x04; Figure 43: JXTA Binary Message ABNF 5.4.2.1 Conventions Multi-byte lengths are sent with the high order byte first (also known as "Big Endian" or "Network Byte Order"). All strings start with a two byte length, followed by a UTF-8 string value. The message format is specified using ABNF [RFC2234] [7]. ABNF is normally used for ASCII grammars, but here we use it to define a byte sequence for a binary message. 5.4.2.2 Message Each message starts with the four byte UTF8 signature "jxmg". The signature is used to aid in sanity checking a transport implementation. This is followed by a one byte version number. At present, the version number must be zero. Next is a list of Duigou & Project JXTA Expires August 28, 2003 [Page 83] Internet-Draft JXTA v2.0 Protocols Specification February 2003 namespaces used by this message. See the production rule for namespaces below. And last is a two byte element count followed by the elements themselves. 5.4.2.3 Namespaces Each message element name is part of a namespace. The namespaces of all elements are placed into a list at the start of the message. This is an ordered list. Each entry in the list is assigned an id. The first entry in the list is assigned an id of 2. The id of each successive id is one plus the id of the preceding namespace id. The ids 0, and 1 are preassigned. 0 represents the empty namespace. 1 is the "jxta" namespace. The namespaces part of a binary message starts with a two byte namespace count. The count is followed by a sequence of namespace names. It is permissible for this sequence to be empty. 5.4.2.4 Element Each message starts with the four byte UTF8 signature "jxel". The signature is used to aid in sanity checking a transport implementation. Next is the namespace id byte. This byte indicates which name space this element belongs to. The next byte is the flags byte. Bits in this flag byte indicate which of the optional components of an element are present. "HAS_ENCODING" is currently unsupported. The flags are followed by the simple name. The element name can be reconstructed from the simple name and the namespace id as described above. The mime type, if present follows next. If the type is not specified for an element "application/octet-stream" is assumed. Last but not least is the four byte length of the content, followed by the content itself. 5.4.3 XML Message Format The XML message format is used for transports which can transmit text but not raw binary data. An effort is made to keep the message elements as readable as possible. See the section on encoding. Duigou & Project JXTA Expires August 28, 2003 [Page 84] Internet-Draft JXTA v2.0 Protocols Specification February 2003 5.4.3.1 Message tcp://123.456.205.212 AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8gISIjJCUmJygpKissLS4vMDEyMzQ1Njc4 OTo7PD0+P0BBQkNERUZHSElKS0xNTk9QUVJTVFVWV1hZWltcXV5fYGFiY2RlZmdoaWprbG1ub3Bx cnN0dXZ3eHl6e3x9fn+AgYKDhIWGh4iJiouMjY6PkJGSk5SVlpeYmZqbnJ2en6ChoqOkpaanqKmq q6ytrq+wsbKztLW2t7i5uru8vb6/wMHCw8TFxsc= Figure 44: XML Message The top level XML element is the Message element. There is one required attribute, version. The value of version must be zero "0". The body of the Message element is a sequence of Element elements. 5.4.3.2 Element Each Element must have a name and mime_type attribute. Optionally an encoding attribute may be present. 5.4.3.2.1 Name This a required attribute names the element. The name contains the namespace, followed by a colon, followed by the simple name of the element. 5.4.3.2.2 MIME type A required attribute indicating the MIME type of the element. If the MIME type was not specified in the message, a type of "application/ octet-stream" is used. 5.4.3.2.3 Encoding Encoding is OPTIONAL The only supported encoding at this time is base64. "IETF RFC 1521" [RFC1521] [3] If the encoding is not present, the content is just treated as a string. While name, type and content are parts of a message which will be found in all implementations, the encoding is added by this particular format. Duigou & Project JXTA Expires August 28, 2003 [Page 85] Internet-Draft JXTA v2.0 Protocols Specification February 2003 Note: The reference implementation uses the following technique to select encoding. If the MIME major type is "text", the content is treated as a string. Therefore, no encoding attribute is present on the element. Otherwise the content is base64 encoded. This will result in human readable text where possible. The content will successfully be transferred using an XML message even if the user has incorrectly specified the MIME type. There is no requirement that an implementation follow this rule. Implementations will still interoperate whether or not this rule is used. Duigou & Project JXTA Expires August 28, 2003 [Page 86] Internet-Draft JXTA v2.0 Protocols Specification February 2003 6. JXTA Reference Implementations Information 6.1 Introduction In order to deliver complete JXTA implementations, the developers of the various JXTA Reference Bindings have produced a number of components which implement parts of the JXTA specification, but are either not required by the core specification or not specified. This section describes some of these components. These implementations may not be present in all JXTA Bindings and Binding developers are not required to support them. 6.2 Java 2 SE Reference Implementation 6.2.1 JXTA ID Formats These ID Formats have been defined for JXTA Language Binding Reference Implementations. 6.2.1.1 JXTA ID Formats : uuid ID Format The Java 2SE reference implementation of JXTA provides an implementation of JXTA IDs based upon UUIDs "ISO/IEC 11578:1996" [ISO11578] [1]. This OPTIONAL ID Format is identified as the "uuid" format. In this implementation, UUIDs are encoded as hex digits as the basis generating unique identifiers. At the end of each UUID ID are two hex characters that identify the type of JXTA ID. Currently, six ID Types have been defined. Duigou & Project JXTA Expires August 28, 2003 [Page 87] Internet-Draft JXTA v2.0 Protocols Specification February 2003 ::= "urn:" ":" "-" <(1*( )) ::= "uuid" ::= | | | | | ::= "01" ::= "02" ::= "03" ::= "04" ::= "05" ::= "06" Figure 45: JXTA "uuid" ID Format ABNF The characters preceding the ID Type identifier are the encoded form of the ID. The encoding consists of a variable number of characters dependant upon the ID Type being encoded. To decode the ID the hex characters are translated in order and placed into the elements of a byte array from which the various ID components can be retrieved. All of JXTA UUID IDs are currently manipulated as 64 byte arrays although no ID Type currently requires all the full 64 bytes to encode their contents. Position 63 always contains the UUID ID Type value. The remainder of the ID fields are defined beginning at Position 0 and increment towards Position 63. To make the text presentation of JXTA UUID IDs as URNs more compact implementations must not encode the value of unused Positions within the array. Since they are irrelevant to the value of the ID they can be assumed to be zero. Implementations must also omit from the encoding the value of any Positions that precede the unused portion and contain zero. The reference Java implementation accomplishes this by scanning from Position 62 towards Position 0 searching for the first non-zero value. It then encodes from position 0 to the discovered location followed by the encoding for Position 63. The text encoding of a JXTA ID must be canonical according to the URN specification, thus this "zero-saving" technique MUST be present in every implementation. Duigou & Project JXTA Expires August 28, 2003 [Page 88] Internet-Draft JXTA v2.0 Protocols Specification February 2003 urn:jxta:uuid-00030102040501 DECODES TO: 0:00 1:03 2:01 3:02 4:04 5:05 6-62:00 63:01 6.2.1.2 JXTA UUID Field Definitions Each of the six JXTA ID Types has a specific definition for how its fields are represented within the common 64-byte array structure. Common between the four types is the definition of Position 63. This location is reserved for the ID Type. 6.2.1.2.1 JXTA UUID Codat ID Fields Each Codat is assigned a unique codat id that enables canonical references to be made to the codat in the context of a specific peer group. A CodatID is formed by the conjunction of a PeerGroupID, a randomly chosen value that has a high probability of being unique, and an optional SHA1 cryptographic hash of the codat contents. TABLES NOT CURRENTLY CONVERTED. 6.2.1.2.2 JXTA UUID PeerGroup ID Fields Each peer group is assigned a unique id that enables canonical references to that peer group. TABLES NOT CURRENTLY CONVERTED. 6.2.1.2.3 JXTA UUID Peer ID Fields Each peer is assigned a unique peer id that enables canonical references to be made to the peer in the context of a specific peer group. TABLES NOT CURRENTLY CONVERTED. 6.2.1.2.4 JXTA UUID Pipe ID Fields Each pipe is assigned a unique pipe id that enables canonical references to be made to the pipe in the context of a specific peer group. Duigou & Project JXTA Expires August 28, 2003 [Page 89] Internet-Draft JXTA v2.0 Protocols Specification February 2003 TABLES NOT CURRENTLY CONVERTED. 6.2.1.2.5 JXTA UUID Module Class ID Fields Each Module is assigned a Module service id that enables canonical references to be made to the service in the context of a specific peer group and optionally within the context of a specific peer. TABLES NOT CURRENTLY CONVERTED. 6.2.1.2.6 JXTA UUID Module Spec ID Fields Each Service is assigned a unique service id that enables canonical references to be made to the service in the context of a specific peer group and optionally within the context of a specific peer. TABLES NOT CURRENTLY CONVERTED. 6.2.2 J2SE JXTA Endpoint Router Implementation This section describes the implementation of the Endpoint Router in the J2SE implementation of JXTA. This is just an example of how the EndpointRouter protocol can be implemented, but there is several other manners the Endpoint Router could be implemented. Other optimizations or robustness mechanisms could be added or changed in other implementations of the Endpoint Router. In this section, the term Endpoint Router refers to the J2SE Endpoint Router implementation and not to the Endpoint Router protocol as the term has been used in the previous sections. Also, the current implementation does not yet implement the entire protocol (pending tasks). What is not yet implemented is outlined in this document. The Endpoint Router manages a cache of routes to destination peers. [PENDING TASK] Currently the cache does not associate a life time to a route in the cache. This is needed as routes are dynamic and constantly changing in a peer to peer network. A life time of 15-20 minutes is probably a good guess. When the Endpoint Router is asked to send a message to a peer for which it does not yet have a route, it sends out a RouteQuery, using the Resolver Service. When the router is asked to route a message, Duigou & Project JXTA Expires August 28, 2003 [Page 90] Internet-Draft JXTA v2.0 Protocols Specification February 2003 if the message contains the forward route, this route is used, even if the router knows another route (the forward route within the message takes precedence). If the forward route is not valid (the next hop in the list is not reachable), or if the message does not contain a forward route, the local route is then used. If there is no local route, then the message is dropped. [PENDING TASK] When a router is asked to route a message, and when no route is available, it should search for a route (sending a RouteQuery), and/or send a NACK message back to the source of the message. When the Endpoint Router receives a RouteQuery, if it knows a route, it answer with a RouteResponse including the forward route. [PENDING TASK] PingQuery and PingResponse are not yet implemented. In particular, routes should be checked once in a while. [PENDING TASK] NACK is not yet implemented. When the Endpoint Router receives an incoming message, and when the incoming message contains a reverse route, the reverse route is added into the local cache of routes. Note that the Endpoint Router detects loops and other errors both in reverse route and forward route. The Endpoint Router does not remove its message element, even when routed message is eventually delivered locally to the destination application. This allow the application to decide to forward the message to another peer, while keeping the routing information, especially the reverse route, allowing the final destination to respond to the original source of the message without having to issue a RouteQuery. Duigou & Project JXTA Expires August 28, 2003 [Page 91] Internet-Draft JXTA v2.0 Protocols Specification February 2003 References [1] "Information technology - Open Systems Interconnection - Remote Procedure Call (RPC)", February 2003. [2] "Simple Mail Transfer Protocol (SMTP)", February 2003. [3] "Multipurpose Internet Mail Extensions (MIME) Part One: Mechanisms for Specifying and Describing the Format of Internet Message Bodies", February 2003. [4] "Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types", February 2003. [5] "Key words for use in RFCs to Indicate Requirement Levels", February 2003. [6] "URN Syntax", February 2003. [7] "Augmented BNF for Syntax Specifications: ABNF", February 2003. [8] "The TLS Protocol : Version 1.0", February 2003. [9] "Hypertext Transfer Protocol -- HTTP/1.1", February 2003. [10] "The Blocks Extensible Exchange Protocol Core", February 2003. [11] "The Blocks Extensible Exchange Protocol Core", February 2003. [12] "Unicode Standard Annex #15: Unicode Normalization Forms", February 2003. [13] "Unicode Standard Annex #28: Unicode 3.2", February 2003. [14] "XML Schema Part 1: Structures", February 2003. [15] "XML Schema Part 2: Datatypes", February 2003. Authors' Addresses Michael J. Duigou, editor Project JXTA EMail: bondolo@jxta.org Duigou & Project JXTA Expires August 28, 2003 [Page 92] Internet-Draft JXTA v2.0 Protocols Specification February 2003 JXTA Specification Project Project JXTA EMail: discuss@spec.jxta.org URI: http://spec.jxta.org Duigou & Project JXTA Expires August 28, 2003 [Page 93] Internet-Draft JXTA v2.0 Protocols Specification February 2003 Intellectual Property Statement The IETF takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on the IETF's procedures with respect to rights in standards-track and standards-related documentation can be found in BCP-11. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementors or users of this specification can be obtained from the IETF Secretariat. The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights which may cover technology that may be required to practice this standard. Please address the information to the IETF Executive Director. Full Copyright Statement Copyright (C) The Internet Society (2003). All Rights Reserved. This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Internet organizations, except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Standards process must be followed, or as required to translate it into languages other than English. The limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assignees. This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION Duigou & Project JXTA Expires August 28, 2003 [Page 94] Internet-Draft JXTA v2.0 Protocols Specification February 2003 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Acknowledgement Funding for the RFC Editor function is currently provided by the Internet Society. Duigou & Project JXTA Expires August 28, 2003 [Page 95]