[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Subject: [regrep-cooperating] JXTA cooperative protocols
Team, I think that the following JXTA protocol specification provides some valuable insights and experiences to draw upon: http://spec.jxta.org/v1.0/docbook/JXTAProtocols.html <full disclosure> While JXTA is an open source effort it does have its origins within Sun Microsystems. </full disclosure> Lets share thoughts after you have had a chance to read it. -- Regards, FarrukhTitle: jxta.org
Project JXTA |
Revision History | ||
---|---|---|
Revision 1.2 | June 22, 2001 | |
preliminary DocBook format | ||
Revision 1.2.2 | September 22, 2001 | |
first release based on DocBook format (no intended changes from 1.2 revision) | ||
Revision 1.2.3 | November 20, 2001 | |
Updates to the IDs chapter to document new IDs design. Information on components provided as part of reference implementations is also being moved to the reference implementation section (this may eventually be a separate document). | ||
Revision 1.2.4 | November 20, 2001 | |
Updates to Protocol chapter, discovery behavior and minor changes to the Resolver section. | ||
Revision 1.2.5 | November 21, 2001 | |
Updates to Advertisements chapter, added sections for ModuleClassAdvertisement, ModuleSpecAdvertisement, ModuleImplAdvertisement. Updated sections for PeerAdvertisement and PeerGroupAdvertisement. | ||
Revision 1.2.6 | November 28, 2001 | |
Updates to Advertisements chapter, added sections for PeerInfoAdvertisement. also includes typo corrections in various sections | ||
Revision 1.2.7 | November 29, 2001 | |
Updates to the Protocol Section, and more description on PeerInfoAdvertisement traffic field | ||
Revision 1.2.8 | December, 2001 | |
Integrated docbookized version of Eric's sections about enpoint service and router. Made some cosmetic fixes per last review. | ||
Revision 1.2.9 | December 4, 2001 | |
Updates to protocols chapter to use schemas to describe message structure more formally. Remove Peer Membership Protocol. Remove Content Advertisement (may be readded in documentation of CMS, but not part of or used by core protocols) Minor cosmetic improvements to copyright and ids chapter. | ||
Revision 1.2.10 | December 7, 2001 | bondolo@jxta.org |
Updates to protocols chapter to use mores schemas to describe message structure more formally. Examples for each as well. | ||
Revision 1.2.11 | December 7, 2001 | bondolo@jxta.org |
More updates to the protocols chapter. Converting raw program listings to figures and examples, addition of live cross references. Preparing for glossary and bibliography. | ||
Revision 1.2.12 | December 9, 2001 | bondolo@jxta.org |
More updates to the protocols chapter. PeerInfoProtocol and Pipe Binding Protocol now have schemas. Converting raw program listings to figures and examples, addition of live cross references. Preparing for glossary and bibliography. Cosmetic changes to Messages chapter | ||
Revision 1.2.13 | December 17, 2001 | bondolo@jxta.org |
Peer Info Protocol was redone because the previous schema though XML-like, was not representable with XML. (Endpoint Addresses as tag names were the culprit). PIP now looks more like the Peer Discovery Protocol with separate schemas for query and response. Document has been restructured into three major sections; Core Specification, Standard Services, and Reference Implementations. This restructuring makes understanding the JXTA Protocols more straight-forward because requirements and behaviours are now divided between functionality required by all JXTA peers, functionality needed to interoperate with the optional JXTA Protocols, and functionality required to interoperate with specific JXTA implementations. | ||
Revision 1.3 | January 3, 2002 | bondolo@jxta.org |
Wrote introductions for each of the new document sections. Introduced a glossary and bibliography. More restructuring of the source docbook files. Changes to prepare for a printable form document. | ||
Revision 1.3.1 | January 9, 2002 | bondolo@jxta.org |
Spelling and grammar corrections. More reorganization of material into core, standard services and reference implementation parts. Updating stylesheets and docbook usage based on techniques seen in other docbook projects. | ||
Revision 1.3.2 | January 9, 2002 | bondolo@jxta.org |
More moving content around into core and standard services. More chapters reorganized. New text in advertisments chapter. More bibliographic information. | ||
Revision 1.3.3 | January 14, 2002 | bondolo@jxta.org |
Redid the schemas for the advertisement chapter. Moved all of the protocol advertisements and schemas to the appropriate protocols chapters. Use of <literal> has now been replaced with <phrase> and a role attribute of "rfc2119". Improved field descriptions for some of the core advertisements. | ||
Revision 1.3.4 | February 13, 2002 | bondolo@jxta.org |
Lots of minor revisions based on review cycle. Thanks to all of the reviewers who took time to review and respond! | ||
Revision 1.3.5 | April 19, 2002 | bondolo@jxta.org |
Redid some of the schema descriptions in a new and clearer style, more will be converted of over time. Redid schemas and examples for Pipe Binding Protocol section. A few changes to FO generation which generates much better PDF output. Corrected a few specific issues pointed out by Brendon Wilson. |
Table of Contents
List of Figures
List of Tables
List of Examples
Table of Contents
The JXTA protocols 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 independently of their positions in the network (edges, firewalls), and without the need of a centralized management infrastructure.
In designing the JXTA protocols, we sought to create a set of protocols that had very low overhead, made few assumptions about the underlying network transport and limited requirements of the peer environment, but yet were 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 needing to understand or manage the potentially complex and dynamic network topologies which are becoming 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 partial ordered list of gateway peers through which the message might be routed. If a route information is incorrect, the intermediate peer can assist in dynamically finding a new route.
The JXTA protocols are composed of six protocols that work together to allow the discovery, organization, monitoring and communication between peers:
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)
Each of the JXTA protocols is independent of the others, and a peer is not required to implement all six protocols. A peer just needs to implement the protocols that it needs to use. For example, a device may have all the advertisements it uses pre-stored in memory, so that peer does not need to implement the Peer Discovery Protocol. A peer may use a pre-configured set of peer routers to route all its messages, hence the peer does not need to implement the Endpoint Routing Protocol. It just sends messages to the routers to be forwarded. A peer may not need to obtain or wish to provide status information to other peers, hence the peer does not to implement the Peer Information Protocol. The same can be said about all of the other protocols.
The JXTA protocols do no require periodic messages of any kind at any level to be sent within the network. For example, JXTA does not require periodic polling, link status sensing, or neighbor detection messages, and does not rely on these functions from any underlying network transport in the network. This entirely on-demand behavior of the JXTA protocols and lack of periodic activity allows the number of overhead messages caused by JXTA to scale all the way down to zero, when all peers are stationary with respect to each other and all routes needed for current communication have already been discovered.
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 environment, caching is more efficient.
An unique characteristic of P2P networks, like JXTA, is their ability to replicate information toward end-users. Popular contents tend to be replicated more often, making them easier to find as more copies are available. Peers do not have to always go back to the same peer to obtain the information they want (current client/server model). Peers can obtain information from neighboring peers that have already cached the information. Each peer becomes a provider to all other peers.
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-hops network environment where the message latency may be difficult to predict. Furthermore, peers in a P2P network tends to have nondeterministic behaviors. They may appear or leave the network very frequently.
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 behavior of the JXTA network.
The key words must, must not, required, shall, shall not, should, should not, recommended, may, and optional in this document are to be interpreted as described in "IETF RFC 2119" [RFC2119].
A peer shall not make 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.
You should assume that capability and complexity of the network peers supporting these protocols can range from a single light switch to a highly-available supercomputer cluster.
A peer must implement the JXTA protocols such that all interaction with other peers is correct and conformant.
A peer may implement only the JXTA protocols it requires and for correct and conformant interaction with other peers.
A peer may implement only a portion (client-side or server-side only for example) of a protocol.
Peers wishing to interact with other peers within the JXTA network should be willing to participate fully in the protocols. In particular, peers should cache advertisements and forward messages for other peers in the JXTA network. But, this participation is optional.
The JXTA protocols may be implemented over the Internet, a corporate intranet, a dynamic proximity network, or in a home networking environment.
Peers receiving a corrupted or compromised message must discard the message. Messages may be corrupted or intentionally altered in transmission on the network.
Peers may appear, disappear and move 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.
Communication ability between any pair of peers may at 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, allowing one peer to successfully send messages to the other while no communication is possible in the reverse direction.
The JXTA protocols may take advantage of additional optimizations, such as the easy ability to reverse a source route to obtain a route back to the origin of the original route.
The JXTA protocols are defined as idempotent protocol exchanges. The same messages may be sent/received more than once during 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 not be made about the time required for a message to reach a destination peer. JXTA Protocols shall not impose any timing requirements for message receipt.
A JXTA protocol message which is routed through multiple hops should not be assumed to reliably delivered, even if only reliable transports such as TCP/IP are used through all hops. A congested peer may drop messages at any time rather than routing them.
Bidirectional, reliable data transfers or specific data transfers (streaming) are expected to be provided at a service layer.
Message encodings for network transports must allow for the transmission of arbitrary numbers of message sections containing an arbitrary amount of data.
While the JXTA protocols are defined in term of XML messages, an XML parser is optional. XML messages may be pre-compiled on small implementations.
The diameter of a multi-hops network is the minimum number of hops necessary for a message to reach from any peers located at one extreme edge of the network to another peer located at the opposite extreme. Empirical measurements on P2P networks such as Gnutella or Freenet shows this diameter to be around 5-7 hops.
The JXTA protocols must not require a broadcast or multicast capability of the underlying network transport. Messages intended for receipt by multiple peers (propagation) may be implemented using point-to-point communications.
One should make the assumption that if a destination address is not available at any time during the message transmission, the message will be lost.
Each peer must be a member of the World peer group. Membership in this group is automatic.
Peers must be members of the same peer group in order to exchange messages. (Remember that all peers are members of the World peer group)
A peer must not assume 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.
A peer may be assigned a unique string as a name. Any naming scheme can be used.
Names are not unique unless a coordinated Naming service is used to guarantee name uniqueness. A Naming service is typically a centralized service that guarantees 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.
Once a content has been published to the JXTA network, it must not be 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 not be 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.
The JXTA Project is an open network computing platform designed for peer-to-peer (P2P) computing.
The JXTA protocols standardize the manner in which peers:
Discover each others
Self-organize into peer groups
Advertise and discover network resources
Communicate with each others
Monitor each other
The JXTA protocols do not:
Require the use of any particular computer language or operating system.
Require the use of any particular network transport or topology.
Require the use of any particular authentication, security or 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.
The JXTA Project intends to address this problem by providing a simple and generic P2P platform to host any kinds of network services:
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.
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.
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.
The JXTA Project is divided in three layers.
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.
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.
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 customer.
Table of Contents
JXTA is intended to be a small system with a limited number of concepts at its core. This chapter introduces the concepts which are core to JXTA.
A peer is any networked device (sensors, phones, PDAs, PCs, servers, supercomputers, etc.) that implements the core JXTA protocols.
Each peer operates independently and asynchronously of all other peers. Some peers may have more dependencies with other peers due to special relationships (gateways or routers).
Peers spontaneously discover each other on the network to form transient or persistent relationships called peer groups. Peergroups are a collection of peers that have some common interests. Peergroups may also be statically predefined.
Peers that provide the same set of services tend to be inter-changeable. It may not matter which peers a peer interact with.
Peers may publish network resources (CPU, Storage, Routing) to other peers.
A peer may cache information, but it is optional. Peers may have persistent storage.
Peers typically interact with a small number of other peers (network neighbors or buddy peers).
Assumptions must not be made about peer reliability or connectivity. A peer may appear or leave the network at any time.
Peers may provide network services that can be used by other peers.
Peers may have multiple network interfaces, though a peer does not need to publish all of its interfaces for use with the JXTA protocols. 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 connection between two 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 may have to use one or more intermediary peers to route a message to another peer.
Each peer is uniquely identified by a unique Peer Id.
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 does 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:
To create a secure environment. Peergroup boundaries permit member peers to access and publish protected contents. Peergroups form logical regions which 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.
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.
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 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:
The Discovery service is used by peer members to search for peergroup resources (peers, peer groups, pipes, and services).
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 is required to have discovered at least one member of the peergroup.
Peers wishing to join a peer group must first locate a current member, and then request to join. The application to join is either rejected or accepted by the collective set of current members. The membership service may enforce a vote of peers or elect a designated group representative to accept or reject new membership applications. A peer may belong to more than one peergroup simultaneously.
The Access service is used to validate requests made by one peer to another. The peer receiving the request provides the requesting peers 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 which only some peers are permitted to use.
The pipe service is used to manage and create pipe connection between the different peer group members.
The resolver service is used to address queries to services running on peers in the group and collect responses.
The monitoring service is used to allow one peer to monitor other members of the same peer group.
Not all the above services must be implemented by a peergroup. Each service may implement one or more of the JXTA protocols, the specifications for which are the main content of this document. A service will typically implement one protocol for simplicity and modularity reasons, but some service may not implement any protocols.
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.
The way network services are invoked is beyond the scope of this specification. Upcoming standards such as WSDL, ebXML, SOAP, UPnP can be used.
The JXTA protocols recognize two levels of network services:
A peer service is accessible only on the peer that is publishing the service. If that peer happens to fail, then 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.
Service invocation is beyond the scope of JXTA. JXTA intent is to interoperate and be compatible with any Web service standard (WSDL, uPnP, RMI, etc.). The JXTA protocols define a generic framework to publish and discover Advertisements which 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.
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 contains 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.
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:
The endpoint sends a message, no guarantee of delivery is made.
The endpoint sends a message, and receives a correlated answer.
Bulk reliable data transfer of binary data.
Efficient control-flow data transfer.
The uni-directional and asynchronous pipe is the required by the JXTA protocols, the other forms may be used my other services and protocols.
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 (receiving end) and output pipes (sending end).
Pipe endpoints are dynamically bounded to a peer endpoint at runtime, via the Pipe Binding Protocol. The pipe binding process consists of searching and connecting the two or more endpoints of a pipe.
When a message is sent into a pipe, the message is sent by the local output pipe to the destination pipe input currently listening to this pipe. The set of currently listening peer endpoints (where the input pipe is located) is discovered using the Pipe Binding Protocol.
A pipe offers two modes of communication:
A point to point pipe connects exactly two pipe endpoints together, an input pipe that receives messages sent from the 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).
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.
Pipes may connect two peers that do not have a direct physical link. One of more intermediary peer endpoints are used to route messages between the two pipe endpoints
The information transmitted using pipes and between endpoints is packaged as messages. Messages define an envelope to transfer any kind of data. A message may contain 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 a Java object or "C" structure.
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.
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:
The complete specification of advertisements is given in the Advertisements chapter. The JXTA protocols make heavy reference to these advertisements, so the reader should be familiar with advertisements before moving on 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 .
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 may change quickly and the policies governing access control need to be flexible in allowing or denying access.
Four basic security requirements must be provided:
guarantees that the contents of the message are not disclosed to unauthorized individuals.
guarantees that the sender is authorized to send a message.
guarantees that the message was not modified accidentally or deliberately in transit.
guarantees the message was transmitted by a properly identified sender and is not a replay of a previously transmitted message.
XML messages allow to add a large variety of metadata information to message 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 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 for message-based architectures such as Secure Sockets Layer (SSL) and Internet Protocol Security (IPSec). However, secure transport protocols such as SSL and IPSec only provide the integrity and confidentiality of message transfer between two communicating peers. In order to provide secure transfer in multi-hops network, one MUST establish a trust association among all the intermediaries peers. Security is compromised if anyone of the communication links is not secured.
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 way of referring to that entity.
URNs are used for the expression of JXTA IDs.
The JXTA protocols assume that many kinds of contents may be shared, exchanged, and replicated between peers. A content can be a text file, a structured document (like a PDF or a XML file), a Java .jar or loadable library, code or even an executable process (checkpointed state). No size limitation is assumed.
A content is published and shared amongst the peer members of a peergroup. A content may only belong to one peergroup. If the same content must be published in two different peergroups, two different contents must be created.
Each content is uniquely identified by a unique id.
All contents make their existence known to other members by publishing a content advertisement.
An instance of content is a copy of a content. Each content copy may be replicated on different peers in the peergroup. Each copy has the same content id as well as a similar value.
Replicating contents within a peergroup help any single item of content be more available. For example, if an item has two instances residing on two different peers, only one of the peers needs to be alive and respond to the content request.
The JXTA protocols does not specify how contents are replicated. This decision is left to a higher-level content service manager.
JXTA is designed to be a small system with only a few required components and behaviours. The functionality which is required of all implementations is defined by the JXTA Core Specification and is documented in this section. Implementations which wish to be be JXTA compliant must implement all of the Core Specification.
Implementation of the Core Specification 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 Core Specification. Existing implementations of these components are described separately in JXTA Standard Services and Reference Implementations Information. In order for a JXTA implementation to be interoperable with other implementations it may be necessary to implement some of the components described there.
Table of Contents
Table of Contents
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. Using a JXTA ID you can know that you have an unambiguous reference to the various JXTA entities. Currently 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] for more information on URNs.
A JXTA ID is a standard URN in the JXTA ID namespace. JXTA ID URNs are identified by the namespace identifier "jxta". Each JXTA ID URN also contains an 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. Currently 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.
The following format specifications use the ABNF syntax as defined in "IETF RFC 2234" [RFC2234].
Figure 1.1. JXTA ID ABNF
<JXTAURN> ::= "urn:" <JXTANS> ":" <JXTAIDVAL> <JXTANS> ::= "jxta" <JXTAIDVAL> ::= <JXTAFMT> "-" <JXTAIDUNIQ> <JXTAFMT> ::= 1 * <URN chars> <JXTAIDUNIQ> ::= 1 * <URN chars> <URN chars> ::= <trans> | "%" <hex> <hex> <trans> ::= <upper> | <lower> | <number> | <other> | <reserved> <upper> ::= "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" <lower> ::= "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" <hex> ::= <number> | "A" | "B" | "C" | "D" | "E" | "F" | "a" | "b" | "c" | "d" | "e" | "f" <number> ::= "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" <other> ::= "(" | ")" | "+" | "," | "-" | "." | ":" | "=" | "@" | ";" | "$" | "_" | "!" | "*" | "'" <reserved> ::= "%" | "/" | "?" | "#"
The jxta URN namespace does not currently define any special symbols from the reserved set.
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 may be compared for equality as strings. JXTA ID URIs can also be resolved to the resource they reference. Finally, JXTA ID URIs can be decomposed and interpreted by JXTA bindings. In order to interpret a JXTA ID a JXTA binding must support the ID Format used by that JXTA ID. For many JXTA protocols and operations it is not necessary to decompose the JXTA IDs.
The following examples demonstrate valid JXTA ID presentation. They are not necessarily valid JXTA IDs.
Example 1.1. JXTA IDs
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
In the preceding examples, example 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". The interpretation of the ID following the "-" is specific to each ID Format.
Every JXTA ID, regardless of format or type has the following properties:
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 follow the general requirements for URNs and the JXTA ID Properties, will be usable by conformant JXTA implementations.
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.
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, but support for other peer groups is optional. Example: You are defining an ID Format for Peer IDs based upon drivers license number. Drivers licenses are not organized into groups. This can be considered equivalent to all drivers licenses belonging to the same group, the global "world peer group".
Peer IDs refer to peers. A Peer ID should canonically, uniquely and unambiguously refer to a peer. Support for this ID Type is optional. If a JXTA binding recognizes the ID Format, it should be able to extract a Peer Group ID from a Peer ID. This Peer Group ID identifies the peer group of which the peer is a member.
Codat IDs refer to codats. A Codat ID should canonically, uniquely and unambiguously refer to a codat. This ID Type is optional, ID Formats are not required to implement it. If a JXTA binding recognizes the ID Format, it should be able to extract a Peer Group ID from a Codat ID. This Peer Group ID identifies the peer group to which the codat belongs.
Pipe IDs refer to pipes. A Pipe ID should canonically, uniquely and unambiguously refer to a pipe. This ID Type is optional, ID Formats are not required to implement it. If a JXTA binding recognizes the ID Format, it should be able to extract a Peer Group ID from a Pipe ID. This Peer Group ID identifies the peer group to which the pipe belongs.
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. This ID Type is optional, ID Formats are not required to implement it. 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 IDs "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" running a different data set.
A ModuleSpecID uniquely identifies a particular network behavior (wire protocol and choreography) that may be embodied by a Jxta Module. There may be any number of implementations of a given Module Spec ID. A ModuleSpecID uniquely identifies an abstract module, of which an implementation compatible with the local JXTA implementation may be located and instantiated. All such implementations are assumed to be network compatible. A Module Spec ID should canonically, uniquely and unambiguously refer to a module specification. This ID Type is optional, ID Formats are not required to implement it. If a JXTA binding recognizes the ID Type, it should be able to extract a Module Class ID from a Module Spec ID.
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.
Table of Contents
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 key information or 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. 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:
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:
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 Specification and the JXTA Standard Services are specified using the XML Schema Definition Language [XSD2001-1][XSD2001-2]. This allows the contents to be strongly type-checked and semanticly validated beyond the syntactical validation provided by XML with DTDs. Service and protocol authors are recommended to specify their Advertisements or Advertisement sub-types using XML Schema Language.
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.
A Peer Advertisement describes the peer resources. The primary use of this advertisement is to hold specific information about the peer, such as its name, peer id, currently available endpoint addresses and any run-time attributes that individual group services want to publish (such as being a rendezvous peer for the group).
As a secondary use, a Peer Advertisement is also used to represent the configuration of a Peer. This configuration is private to the Peer and never published.
Both variants have the same structure, but the content differs: a configuration Peer Advertisement contains parameters that control the behaviour of the various services as well as permanent values, such as the peer name or ID. A published Peer Advertisement contains public attributes of the various services and of the peer itself. Some of the configuration parameters may be replicated verbatim in the published Peer Advertisement, some configuration parameters may impact published attributes, and some may not get published in any form (such as the Debug Level).
Figure 2.1. Peer Advertisement Schema
<xs:complexType name="PA"> <xs:element name="Name" type="xs:string" minOccurs="0"/> <xs:element name="PID" type="JXTAID"/> <xs:element name="GID" type="JXTAID"/> <xs:element name="Desc" type="xs:anyType" minOccurs="0"/> <xs:element name="Svc" type="jxta:serviceParams" minOccurs="0" maxOccurs="unbounded"/> </xs:complexType> <xs:simpleType name="JXTAID"> <xs:restriction base="xs:anyURI"> <pattern value="([uU][rR][nN]:[jJ][xX][tT][aA]:)+\-+"/> </xs:restriction> </xs:simpleType> <xs:complexType name="serviceParam"> <xs:element name="MCID" type="JXTAID"/> <xs:element name="Parm" type="xs:anyType"/> </xs:complexType>
A Peer Group Advertisement describes peergroup specific resources: name, group id, description, specification, and service parameters.
Figure 2.2. Peer Group Advertisement Schema
<xs:complexType name="PGA"> <xs:element name="GID" type="JXTAID"/> <xs:element name="MSID" type="JXTAID"/> <xs:element name="Name" type="xs:string" minOccurs="0"/> <xs:element name="Desc" type="xs:anyType" min0ccurs="0"/> <xs:element name="Svc" type="jxta:serviceParam" minOccurs="0" maxOccurs="unbounded"/> </xs:complexType>
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 2.3. Module Class Advertisement Schema
<xs:complexType name="MCA"> <xs:element name="MCID" type="JXTAID"/> <xs:element name="Name" type="xs:string" minOccurs="0"/> <xs:element name="Desc" type="xs:anyType" min0ccurs="0"/> </xs:complexType>
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 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 2.4. Module Specification Advertisement Schema
<xs:complexType name="MSA"> <xs:element name="MSID" type="JXTAID"/> <xs:element name="Name" type="xs:string" minOccurs="0"/> <xs:element name="Crtr" type="xs:string" minOccurs="0"/> <xs:element name="SURI" type="xs:anyURI" min0ccurs="0"/> <xs:element name="Vers" type="xs:string"/> <xs:element name="Desc" type="xs:anyType" min0ccurs="0"/> <xs:element name="Parm" type="xs:anyType" min0ccurs="0"/> <xs:element name="PipeAdvertisement" type="jxta:PipeAdvertisement" min0ccurs="0"/> <xs:element name="Proxy" type="xs:anyURI" min0ccurs="0"/> <xs:element name="Auth" type="JXTAID" min0ccurs="0"/> </xs:complexType>
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 which interpretation is subject to the module's compatibility. For example, the standard peer group implementation of the java reference implementation expects Code to be a fully qualified java class name which designates a subclass of net.jxta.platform.Module and PURI to be the URI of a downloadable package (a jar file). Other execution environments could expect the code to be inline within the Code element, or even have several options.
Figure 2.5. Module Implementation Advertisement Schema
<xs:complexType name="MIA"> <xs:element name="MSID" type="JXTAID"/> <xs:element name="Comp" type="xs:anyType"/> <xs:element name="Code" type="xs:anyType"/> <xs:element name="PURI" type="xs:anyURI" min0ccurs="0"/> <xs:element name="Prov" type="string" min0ccurs="0"/> <xs:element name="Desc" type="xs:anyType" min0ccurs="0"/> <xs:element name="Parm" type="xs:anyType" min0ccurs="0"/> </xs:complexType>
Table of Contents
The Peer Resolver Protocol (PRP) permits the dissemination of generic queries to one or multiple handlers within the group and match them with 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 group, possibly all, and processed according to the handler name if such a handler name is defined on that peer.
The Peer Resolver Protocol is the resolver protocol of the world peer group. Custom resolver services may choose to leverage PRP. If a peer group does not need to define its own resolver protocol, it may use the world peer group PRP.
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 it to a specified peer.
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 3.1. Resolver Query Schema
<xs:element name="ResolverQuery" type="jxta:ResolverQuery"/> <xs:complexType name="ResolverQuery"> <xs:element name="Credential" type="xs:anyType" minOccurs="0"/> <xs:element name="SrcPeerID" type="JXTAID"/> <xs:element name="HandlerName" type="xs:string"/> <xs:element name="QueryID" type="xs:string" minOccurs="0"/> <xs:element name="Query" type="xs:anyType"/> </xs:complexType>
Example 3.1. Resolver Query
<?xml version="1.0"?>
<!DOCTYPE jxta:ResolverQuery>
<jxta:ResolverQuery xmlns:jxta="http://jxta.org">
<HandlerName>
urn:jxta:uuid-DEADBEEFDEAFBABAFEEDBABE0000000305
</HandlerName>
<Credential>
JXTACRED
</Credential>
<QueryID>
0
</QueryID>
<SrcPeerID>
urn:jxta:uuid-59616261646162614A7874615032503304BD268FA4764960AB93A53D7F15044503
</SrcPeerID>
<Query>
<?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>
</Query>
</jxta:ResolverQuery>
A resolver response message is used to send a resolver response message in response to a resolver query message.
Figure 3.2. Resolver Response Schema
<xs:element name="ResolverResponse" type="ResolverResponse"/> <xs:complexType name="ResolverResponse"> <xs:element name="Credential" type="xs:anyType" minOccurs="0"/> <xs:element name="HandlerName" type="xs:string"/> <xs:element name="QueryID" type="xs:string" minOccurs="0"/> <xs:element name="Response" type="xs:anyType"/> </xs:complexType>
Example 3.2. Resolver Response
<?xml version="1.0"?>
<!DOCTYPE jxta:ResolverResponse>
<jxta:ResolverResponse xmlns:jxta="http://jxta.org">
<HandlerName>
urn:jxta:uuid-DEADBEEFDEAFBABAFEEDBABE0000000305
</HandlerName>
<Credential>
JXTACRED
</Credential>
<QueryID>
0
</QueryID>
<Response>
<?xml version="1.0"?>
<!DOCTYPE jxta:DiscoveryResponse>
<jxta:DiscoveryResponse xmlns:jxta="http://jxta.org">
<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>
</Response>
</jxta:ResolverResponse>
The PRP communicates by way of Endpoint Messages. Endpoint Addresses specify a handler name. The PRP attaches a listener by that name to the Endpoint Service. Endpoint Service.
All PRP implementation 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.
Figure 3.3. Listener Naming Syntax ABNF
<JXTARSLVRRSQRY> ::= <JXTARSLVRNAM> <JXTAIDVAL> <JXTARSLVRQRYTAG>
<JXTARSLVRRSRSP> ::= <JXTARSLVRNAM> <JXTAIDVAL> <JXTARSLVRRSPTAG>
<JXTARSLVRQRYTAG> ::= "ORes"
<JXTARSLVRRSPTAG> ::= "IRes"
<JXTARSLVRNAM> ::= "jxta.service.resolver"
<JXTAIDVAL> ::= See JXTA ID ABNF
Thus, the listeners used by the PRP are currently named as follows:
Query and response messages are included in messages as elements named as follows:
The Handler Name in PRP messages play 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 reference implementation, 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 its reference implementation DOES refuse to register more than one handler with the same name. A service should register for any handler name that it uses as a destination, therefore other services may not register 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 very service and SHOULD handle these messages as specified. PRP is designed for same-to-same communication, not client-server.
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.
The PRP does not assume the presence of a reliable transport is. 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. As a service, the reference implementation helps other services by taking care of all messaging aspects, caching queries and responses 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. The Rendezvous service is responsible for determining the set of peers that should receive a message being propagated, but does never re-propagate an incoming propagated message. The decision of propagating a message one step further, is left to the service handling that message. The PRP's policy in that respect 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.
The JXTA network is an ad hoc, multi-hop, and adaptive network by nature. Connections in the network may be transient, and message routing is nondeterministic. Routes may be unidirectional and change rapidly. Peers may appear and leave frequently. A peer behind 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 behind the firewall.
The Endpoint Routing Protocol defines a set of request/query messages, that is processed by a routing service to help a peer route message to its destination.
When a peer is asked to send a message to a given peer endpoint address, it looks in its local cache 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 a route 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 provides the low-level infrastructures to route a message 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 (different transport) or logical (firewall and NAT) networks. A peer can dynamically found its router peer via a qualified discovery search. A peer can found out if a peer it has discovered is a peer router via the peer advertisement properties tag.
When a peer router receives a route query, if it knows the destination (a route to the destination), it answers the query by returning the route information as an enumeration of hops. The 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 be obsolete requiring the current router to find a new route.
The peer endpoint adds extra routing information in the messages sent by a peer. When a message goes through a peer, the endpoint of that peers leaves its trace onto 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 the 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 intent is to provide just the hook 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 to be performed above the core by high-level routing services, and have those routine services provide intelligent hints to the peer router to route messages.
The Endpoint Routing Protocol (ERP) is used by a peer router to send messages to another peer router to find the available routes to send a message to a destination peer. Two communicating peers may need to use a peer router to route messages depending on their network location. For instance, the two peers may be on different transports, or the peers may be separated by a firewall.
Route information are represented as follow:
<?xml version="1.0" encoding="UTF-8"?> <jxta:EndpointRouter> <Src> peer id of the source </Src> <Dest> peer id of the destination </Dest> <TTL> time to live </TTL> <Gateway> ordered sequence of gateway </Gateway> <...................> <Gateway> ordered sequence of gateway </Gateway> </jxta:EndpointRouter>
The time-to-live parameter 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.
Table 3.1. Endpoint Route
Element Name | Occurrence | Element Value Type |
---|---|---|
Src | 1 | JxtaID |
Dest | 1 | JxtaID |
TTL | 1 | int |
Gateway | + | JxtaID |
The ERP protocol is composed of two messages a route request, and a route answer from the router peer. There is no guarantee that a route response will be received after a query is sent.
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.
This message is sent by a peer to a peer router to request a route information. Route information may be cached or not. The query may indicate to bypass the cache content of a router, and search dynamically for a new route.
<?xml version="1.0" encoding="UTF-8"?> <jxta:EndpointRouterQuery> <Credential> credential </Credential> <Dest> peer id of the destination </Dest> <Cached> true: if the reply can be a cached reply false: if the reply must not come from a cache </Cached> </jxta:EndpointRouterQuery>
Table 3.2. Endpoint Router Query
Element Name | Occurrence | Element Value Type |
---|---|---|
Credential | 0/1 | Credential |
Dest | 1 | JxtaID |
Cached | 1 | boolean |
This message is sent by a router peer to a peer in response to a route information request.
<?xml version="1.0" encoding="UTF-8"?> <jxta:EndpointRouterAnswer> <Credential> credential </Credential> <Dest> peer id of the destination </Dest> <RoutingPeer> Peer ID of the router that knows a route to DestPeer </RoutingPeer> <RoutingPeerAdv> Advertisement of the routing peer </RoutingPeerAdv> <Gateway> ordered sequence of gateway </Gateway> < ...................> <Gateway> ordered sequence of gateway </Gateway> </EndpointRouterAnswer>
Table 3.3. Endpoint Router Answer
Element Name | Occurrence | Element Value Type |
---|---|---|
Credential | 0/1 | Credential |
Dest | 1 | JxtaID |
RoutingPeer | 1 | JxtaID |
RouterPeerAdv | 0/1 | PeerAdvertisement |
Gateway | + | JxtaID |
Table of Contents
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 itself responsible for routing messages for peers that are not directly connected to each other. This task is performed by one of the underlying JXTA Transport Protocol, the Endpoint Router, which provides the illusion that the src and destination peers are directly connected.
The Endpoint Service adds a single element to the message: the source peer ID.
The element name is : "jxta:EndpointHeaderSrcPeer"; its value is a string representation of the peer ID at the point of emission 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.
The source and destination addresses of a message are represented as strings in URI format as follows:
protocol://address_as_per_protocol/unique_name_of_recipient/unique_name_in_recipient_context
The Endpoint Service delegates the sending of outgoing messages to the enpoint protocol designated by the "protocol" part of the message's destination address.
The Endpoint Service delivers incoming messages to the listener registered under the name that matches the concatenation of the "unique_name_of_recipient" and "unique_name_in_recipient_context" parts of the message's destination address.
The Endpoint Router is a JXTA Transport Protocol that seat under the Endpoint Service, aside of 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 direction connection to the Endpoint Service.
The Endpoint Router protocol defines a set of queries and responses in order to communicate with other instances of the Endpoint Router on other peers:
In addition to those queries and answer, the Endpoint Router defines an informational message which does not need to be answered:
Those messages are sent and received by the EndpointRouter using the JXTA Resolver Service.
The Endpoint Router Transport Protocol also includes its own message element in each message it transports. The name of the message element is JxtaEndpointRouter and contains an XML document containing the following:
All queries and responses defined by the Endpoint Router protocol are sent using the JXTA Resolver Service. The messages are represented by an XML document (passed to and by the Resolver Service) of the following type:
<!ELEMENT jxta:EndpointRouter (Version, Type, DestPeer?, RoutingPeer?, RoutingPeerAdv?, NbOfHops?, GatewayForward*) > <!ELEMENT Version #PCDATA > <!ELEMENT Type #PCDATA > <!ELEMENT DestPeer #PCDATA > <!ELEMENT RoutingPeer #PCDATA > <!ELEMENT RoutingPeerAdv #PCDATA > <!ELEMENT NbOfHops #PCDATA > <!ELEMENT GatewayForward #PCDATA >
While this DTD does not define the contents of the tag, the following defines what each tag is expected to be:
Table 4.1. Router Query
Element Name | Occurrence | Element Value Type |
---|---|---|
Version integer | 1 | integer (current = 2) |
Type | 1 | RouteQuery | RouteResponse | PingQuery | PingResponse | NACK |
DestPeer | 0/1 | EndpointRouter EndpointAddress |
RoutingPeer | 0/1 | EndpointRouter EndpointAddress |
RoutingPeerAdv | 0/1 | Peer Advertisement |
NbOfHops | 0/1 | integer |
GatewayForward | 0/1 | EndpointRouter EndpointAddress |
Beside Version and Type, depending on the query or the response, only a subset of tags are used:
The Endpoint Router transport protocol includes a message element named JxtaEndpointRouter. The format of the message element is an XML document defined as follows:
<!ELEMENT jxta:EndpointRouterMessage ( jxta:Src, jxta:Dest, jxta:Last, jxta:NBOH, GatewayReverse*, GatewayForward* ) > <!ELEMENT jxta:Src #PCDATA > <!ELEMENT jxta:Dest #PCDATA > <!ELEMENT jxta:Last #PCDATA > <!ELEMENT jxta:NBOH #PCDATA > <!ELEMENT GatewayReverse #PCDATA > <!ELEMENT GatewayForward #PCDATA >
While this DTD does not define the nature of contents of the tag, the following defines was is expected to be each tag:
Table 4.2. Router Element In Messages
Element Name | Occurrence | Element Value Type |
---|---|---|
jxta:Src | 1 | EndpointRouter EndpointAddress |
jxta:Dest | 1 | EndpointRouter EndpointAddress |
jxta:Last | 0/1 | EndpointRouter EndpointAddress |
jxta:NBOH | 0/1 | integer |
GatewayForward | 0/1 | EndpointRouter EndpointAddress |
GatewayReverse | 0/1 | EndpointRouter EndpointAddress |
The meaning of these elements is as follows:
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 mechanism could be added or change in other implementation 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 since a P2P network, route are rather dynamic. 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 have a route yet, it sends out, using the Resolver Service, a RouteQuery. When the router is asked to route a message, 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 a RouteResponse including the forward route.
[PENDING TASK] PingQuery and PingResponse is 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.
Table of Contents
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. There are two standard representations for messages, XML and binary. Each JXTA transport will use the representations most appropriate.
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, and transports), each level may add one or more named elements to the message. As a message passes back up the stack, the protocol will remove those elements.
A message is an ordered sequence of message elements. The most recently added element appears at the end of the message.
A message element contains a name, type and content.
Element names are represented as UTF8 strings. A name has two parts: a namespace and a simple name. These are separated with a ":" colon.
Name = simple_name | namespace ":" simple_name
Simple_name may not contain a colon character. Simple_name must not be empty.
The namespace is not allowed to contain the colon character. Namespace must contain at least one character. Use of an empty namespace is not allowed, use simple_name instead.
The namespace is to prevent name collision between various services, and users of these services. Core services will use the namespace "jxta". For example "jxta:TTL". Applications may use the empty namespace (simple name).
Legal names: jxta:abc ; Namespace=jxta, simple name=abc. lmn ; Namespace empty, simple name=lmn. Illegal names jxta: ; Empty simple name not allowed. :abc ; Empty namespace not allowed. ; Empty name not allowed.
A type is specified as a MIME type. See [RFC2046]. MIME types are UTF8 strings. The type is used by the applications and services which use the element. So there is no need to use a particular set of MIME types understood by the core, for example. In addition to the applications and services which use the particular element, the type of the element may also be used by the JXTA transport to determine how to format the message element in the most readable way. (If the transport produces human readable messages, such as the HTTP transport.)
If the type is not specified for an element "application/octet-stream" is assumed.
Transports, such as TCP, which require a compact representation for a message will use the binary format.
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 the UTF8 string value. The message format is specified using ABNF [RFC2234]. ABNF is normally used for ASCII grammars, but here we use it to define a byte sequence for a binary message.
msg ::= "jxmg" version ; One byte. Must be 0. namespaces element_count ; two bytes 1* elm
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 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.
namespaces ::= namespace_count ; two bytes 0* namespace ; Each namespace is a string namespace = string
Each message element name is part of a namespace. The namespaces of all elements are collected in to this 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 namespace string matching is case sensitive.
The namespaces part of a binary message starts with a two byte namespace count. This count will always be at least '2' to accomodate the two standard namespaces. The count is followed by a sequence of namespace names. It is permissible for this sequence to be empty.
elm ::= "jxel" ; signature namespaceid ; one byte flags ; Indicates which parts follow simple_name [type] ; Present if (flags & HAS_TYPE) len4 ; Four byte length of content content
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 element name can be reconstructed as follows: If the namespace id is 0, then the simple name is the name. Otherwise concatenate the namespace name designated by the id with a colon (:) and the simple name. The next byte is the flags byte. Bits in this flag byte indicate which of the optional components of an element are present. Only the type is optional right now.
flags ::= byte ; 0x00 If type is not present ; 0x01 if type is present.
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.
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.
Example 5.1. XML Message
<?xml version="1.0"?> <!DOCTYPE Message> <Message version="0"> <Element name="jxta:SourceAddress" mime_type="text/plain"> tcp://123.456.205.212 </Element> <Element name="stuff" encoding="base64" mime_type="application/octet-stream"> AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8gISIjJCUmJygpKissLS4vMDEyMzQ1Njc4 OTo7PD0+P0BBQkNERUZHSElKS0xNTk9QUVJTVFVWV1hZWltcXV5fYGFiY2RlZmdoaWprbG1ub3Bx cnN0dXZ3eHl6e3x9fn+AgYKDhIWGh4iJiouMjY6PkJGSk5SVlpeYmZqbnJ2en6ChoqOkpaanqKmq q6ytrq+wsbKztLW2t7i5uru8vb6/wMHCw8TFxsc= </Element> </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.
Each Element must have a name and mime_type attribute. Optionally an encoding attribute may be present.
This a required attribute names the element. The name contains the namespace, followed by a colon, followed by the simple name of the element.
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.
Encoding is optional. The only supported encoding at this time is base64. 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.
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.
The JXTA Core Specification 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 must 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.
Table of Contents
Table of Contents
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.
The discovery query message is used to send a discovery request to find advertisements.
Figure 1.1. Discovery Query Schema
<xs:element name="DiscoveryQuery" type="jxta:DiscoveryQuery"/> <xs:complexType name="DiscoveryQuery"> <!-- this should be an enumeration --> <xs:element name="Type" type="xs:string"/> <xs:element name="Threshold" type="xs:unsignedInt" minOccurs="0"/> <xs:element name="PeerAdv" type="xs:string" minOccurs="0"/> <xs:element name="Attr" type="xs:string" minOccurs="0"/> <xs:element name="Value" type="xs:string" minOccurs="0"/> </xs:complexType>
Only advertisements containing an element of name Attribute and of value Value are eligible to be found. Value may begin or end with "*", or both. In that case Value will match all values that end with or beginning with, or contain the rest of the string. If Value contains only "*" the result is unspecified. Some implementations may not match any advertisement.
Only advertisements of type Type will be matched.
Threshold specifies the maximum number of advertisements that each responding peer may provide. The total number of results received depends on the number of peers that respond and the advertisements they have. If Type is 0 (PEER) and Threshold is 0, then the query has a special meaning: its objective is to collect Peer Advertisements of respondents. Therefore any peer should respond to such a query, even though no results are to be included.
PeerAdvertisement is the the advertisement of the requesting peer.
Attribute and Value must either be both present or absent. If absent, then each respondent should supply a random set of documents up to Threshold.
Example 1.1. Discovery Query
<?xml version="1.0" encoding="UTF-8"?>
<jxta:DiscoveryQuery>
<Type>2</Type>
<Threshold>1</Threshold>
<PeerAdv>
<?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>
</PeerAdv>
<Attr>Name</Attr>
<Value>*sidus*</Value>
</jxta:DiscoveryQuery>
A Discovery response message is used by a peer to respond to a discovery query message.
Figure 1.2. Discovery Response Schema
<xs:element name="DiscoveryResponse" type="jxta:DiscoveryResponse"/> <xs:complexType name="DiscoveryResponse"> <!-- this should be an enumeration --> <xs:element name="Type" type="xs:string"/> <xs:element name="Count" type="xs:unsignedInt" minOccurs="0"/> <xs:element name="PeerAdv" type="xs:anyType" minOccurs="0"> <xs:attribute name="Expiration" type="xs:unsignedLong"/> </xs:element> <xs:element name="Attr" type="xs:string" minOccurs="0"/> <xs:element name="Value" type="xs:string" minOccurs="0"/> <xs:element name="Response" type="xs:anyType" maxOccurs="unbounded"> <xs:attribute name="Expiration" type="xs:unsignedLong"/> </xs:element> </xs:complexType>
Type is the type of all the advertisements returned in the Response element(s).
Count, if present, is the number of Response elements included in this response.
PeerAdvertisement, if present, is the advertisement of the respondent. The Expiration attribute is the associated relative expiration time in milliseconds.
Attribute and Value, if present, reflect that of the DiscoveryQuery to which this is the response.
Response An advertisement. The Expiration attribute is the associated relative expiration time in milliseconds.
Example 1.2. Discovery Response
<?xml version="1.0" encoding="UTF-8"?>
<jxta:DiscoveryResponse>
<Type>2</Type>
<Count>1</Count>
<PeerAdv>
<?xml version="1.0"?>
<!DOCTYPE jxta:PA>
<jxta:PA xmlns:jxta="http://jxta.org">
<PID>
urn:jxta:uuid-59616261646162614A7874615032503304BD268FA4764960AB93A53D7F15044503
</PID>
... omitted ...
</jxta:PA>
</PeerAdv>
<Attr>Name</Attr>
<Value>*sidus*</Value>
<Response Expiration="36000000">
<?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>
</Response>
</jxta:DiscoveryResponse>
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 to be honored. Only a best effort is made at matching the query to results in it's cache.
There is no guarantee that a response to a discovery query request will be made. It is important to point out 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.
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.
<?xml version="1.0" encoding="UTF-8"?> <jxta:RdvAdvertisement> <Name> name of the rendezvous peer</Name> <RdvGroupId> PeerGroup UUID </RdvGroupId> <RdvPeerId>Peer ID of the rendezvous peer</RdvPeerId> </jxta:RdvAdvertisement>
Table 1.1. Rdv Advertisement
Element Name | Occurrence | Element Value Type |
---|---|---|
Name | 0/1 | String |
RdvGroupId | 1 | JxtaID |
RdvPeerId | 1 | JxtaID |
NOTE: the Peer Resolver protocol is not used to send those message: the Rendezvous Protocol sits directly on top of the Endpoint Routing Protocol (see Endpoint Routing Protocol). The reason of this is layering: the Peer Resolver Protocol seats itself on top of the Rendezvous Protocol.
The Rendezvous Protocol is responsible for controlling the propagation of messages. This is done by detecting:
Figure 1.3. RendezVous Propagate Message Schema
<xs:element name="RendezVousPropagateMessage" type="jxta:RendezVousPropagateMessage"/> <xs:complexType name="RendezVousPropagateMessage"> <xs:element name="MessageId" type="xs:string"/> <!-- This should be a constrained subtype --> <xs:element name="DestSName" type="xs:string"/> <xs:element name="DestSParam" type="xs:string"/> <xs:element name="TTL" type="xs:unsignedInt"/> <xs:element name="Path" type="xs:anyURI" maxOccurs="unbounded"/> </xs:complexType>
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 by PIP. Multiple peer information messages may be sent. None, one or multiple responses may be received in response to any query.
PIP is layered upon the Peer Resolver Protocol. Of importance is use of the QueryID field to match PIP queries containing request fields to the PIP Response Messages containing the matching 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 could utilize the request field to offer expanded capabilities.
The query message is sent to a peer to query the current state of the peer, and to get 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 1.4. PIP Query Message
<xs:element name="PeerInfoQueryMessage" type="jxta:PeerInfoQueryMessage"/> <xs:complexType name="PeerInfoQueryMessage"> <xs:element name="sourcePid" type="xs:anyURI"/> <xs:element name="targetPid" type="xs:anyURI"/> <xs:element name="request" type="xs:anyType" minOccurs="0"/> </xs:complexType>
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.
Figure 1.5. PIP Response Message
<xs:element name="PeerInfoResponse" type="jxta:PeerInfoResponse"/> <xs:complexType name="PeerInfoResponse"> <xs:element name="sourcePid" type="xs:anyURI"/> <xs:element name="targetPid" type="xs:anyURI"/> <xs:element name="uptime" type="xs:unsignedLong" minOccurs="0"/> <xs:element name="timestamp" type="xs:unsignedLong" minOccurs="0"/> <xs:element name="response" type="xs:anyType" minOccurs="0"/> <xs:element name="traffic" type="jxta:piptraffic" minOccurs="0"/> </xs:complexType> <xs:complexType name="piptraffic"> <xs:element name="lastIncomingMessageAt" type="xs:unsignedLong" minOccurs="0"/> <xs:element name="lastOutgoingMessageAt" type="xs:unsignedLong" minOccurs="0"/> <xs:element name="in" type="jxta:piptrafficinfo" minOccurs="0"/> <xs:element name="out" type="jxta:piptrafficinfo" minOccurs="0"/> </xs:complexType> <xs:complexType name="piptrafficinfo"> <xs:element name="transport" type="xs:unsignedLong" maxOccurs="unbounded"> <xs:attribute name="endptaddr" type="xs:anyURI"/> </xs:element> </xs:complexType>
traffic Contains information about the network traffic performed by the target peer. This element is optional.
in If present, contains elements which describe incoming traffic from various endpoint addresses.
out If present, contains elements which describe outgoing traffic to various endpoint addresses.
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 through 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, so it can use a variety of transport protocols, such as the JXTA HTTP Transport, the JXTA TCP/IP Transport, or the secure JXTA TLS Transport.
There are currently three different types of pipes:
The type of a pipe is defined within its advertisement.
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 PBP to bind the pipe to an endpoint.
A reliable transport is optional. Multiple binding query messages may be sent. None, one or multiple responses may be received.
A PipeAdvertisement describes a pipe. A pipe advertisement is used by the pipe service to create associated input and output pipe endpoints.
Each pipe advertisement can include an optional symbolic name, to name the pipe and a pipe type to indicate the type of the pipe (point-to-point, propagate, secure, etc.).
Figure 1.6. Pipe Advertisement Schema
<xs:element name="PipeAdvertisment" type="jxta:PipeAdvertisment"/> <xs:complexType name="PipeAdvertisement"> <xs:element name="Name" type="xs:string" minOccurs="0"/> <xs:element name="Id" type="JXTAID"/> <xs:element name="Type" type="xs:string"/> </xs:complexType>
This is an required element that defines the type of the pipe. The following types are currently defined:
Example 1.3. Pipe Advertisement
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE jxta:PipeAdvertisement> <jxta:PipeAdvertisement xmlns:jxta="http://jxta.org"> <Name>Talk to Me!</Name> <Id>urn:jxta:uuid-094AB61B99C14AB694D5BFD56C66E512FF7980EA1E6F4C238A26BB362B34D1F104</Id> <Type>JxtaUnicast</Type> </jxta:PipeAdvertisement>
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.
Figure 1.7. Pipe Resolver Message Schema
<xs:element name="PipeResolver" type="jxta:PipeResolver"/> <xs:complexType name="PipeResolver"> <!-- MsgType should be an enumeration choice --> <xs:element name="MsgType" type="xs:string"/> <xs:element name="PipeId" type="JXTAID"/> <xs:element name="Type" type="xs:string" minOccurs="0"/> <!-- following are used in the query --> <xs:element name="Cached" type="xs:boolean" default="false" minOccurs="0"/> <xs:element name="Peer" type="JXTAID" minOccurs="0"/> <!-- following are used in the answer --> <xs:element name="Found" type="xs:boolean" minOccurs="0"/> <!-- This should refer to a peer adv, but is instead a whole doc --> <xs:element name="PeerAdv" type="xs:string" minOccurs="0"/> </xs:complexType>
Used to indicate if it is the Query or the Answer. May be one of:
Table of Contents
The following section describes the transport binding of the JXTA protocols over TCP/IP. The document describes the message wire format of JXTA endpoint messages over a TCP/IP socket connection.
This section defines the TCP/IP message wire format. Each TCP/IP message is composed of a header and a body.
Header
Body
The format of the header is:
Type | Src IP | Src Port | Size | Option | Unused |
The header fields are as follow:
Type: 1 byte. The byte info is used to either unicast or multicast the request.
1 = this is a propagate message.
2 = this is a unicast message.
3 = This for ACK //unused
4 = This is for NACK // unused
Src IP: 4 bytes (IP addresses are in the IPv4 format)
Src Port: 2 bytes (network byte order representation). The port is present since each peer may decide to bind its transport service to a specific port number. The TCP binding does not require that a specific port be used.
Size: 4 bytes body size not counting the header (network byte order representation)
Option: 1 byte option. These options are intended to be used to specify the kind of of socket connections (uni or bi-directional) in used.
HANDCHECK = 1 not implemented yet (bi-directional)
NONBLOCKING = 2 (unidirectional transfer)
Unused: 8 bytes
The TCP/IP binding is stateless; it does not require any states to be maintained. The normal operation is for one peer to send a TCP/IP packet to another one, and close the socket after the packet is sent. This is the minimum functionality required to implement unidirectional pipes.
The HTTP message receiver supports two operations: an HTTP POST of a JXTA message, and an HTTP GET that is effectively a 'ping' operation. Both the POST and the GET operation are performed on the base URI of the HTTP endpoint for the JXTA peer.
The HTTP request must adhere to the following rules:
The request method must be POST
The Content-Length must be specified
The Content-Type must be 'application/octet-stream'
The request body must a binary JXTA message
No Transfer-Encoding may be specified
The HTTP request must adhere to the following rules:
The request method must be GET
The request URI must be '/ping'
The Message Relay protocol allows clients to use a relay server to receive messages on the client's behalf. The relay server implements a simple lease-based protocol that allows a client to 'lease' the relay services from the relay server. The relay server accepts the following four commands in a querystring over HTTP POST:
obtainLease: Client requests a new lease with the relay server.
renewLease: Client requests to renew an existing lease with the relay server.
block: Client requests to stay connected while waiting for a message on the relay server.
poll: Client requests to receive a queued message.
The obtainLease command instructs the relay server to issue a new lease for a peer.
The following querystring variables that must be set by the client are as follows:
command: Must be equal to 'obtainLease'
peerId: The Peer ID of the client.
The following querystring variables must be included by the relay server in the response:
leaseId: The ID for the new lease
If the request is malformed, the response must be 400. If the relay server rejects the request, the response must be 400.
The renewLease command instructs the relay server to renew an existing lease. Messages queued under the existing lease must be maintained for the renewed lease.
The following querystring variables that must be set by the client are as follows:
leaseId: Must be set to the leaseId of the existing lease.
The following querystring variables must be included by the relay server in the response:
leaseId: The ID for the new lease. This may be the same as the existing leaseId, or it may be different.
If the request is malformed, the response must be 400. If the relay server rejects the request, the response must be 400.
The block command instructs the relay server to respond with a JXTA message destined for the client. In the case that there is not a pending message for the client, the relay server will keep the HTTP request open for some self-determined period of time.
The following querystring variables that must be set by the client are as follows:
leaseId: Must be set to the leaseId of the lease.
If no message is queued for the client within this time, a response with Content-Length of 0 will be sent. Otherwise, exactly one JXTA message will be sent in the response body. The Content-Length must be set to the length of the JXTA Message. The Content-Type must be set to 'application/octet-stream'.
If the leaseId is not valid (e.g. the lease is expired), the response must be 400.
The poll command instructs the relay server to respond with a JXTA message destined for the client. In the case that there is not a pending message for the client, the relay server should respond immediately.
The following querystring variables that must be set by the client are as follows:
leaseId: Must be set to the leaseId of the lease.
If no message is queued for the client within this time, a response with Content-Length of 0 will be sent. Otherwise, exactly one JXTA message will be sent in the response body. The Content-Length must be set to the length of the JXTA Message. The Content-Type must be set to 'application/octet-stream'.
If the leaseId is not valid (e.g. the lease is expired), the response must be 400.
In order to produce complete implementations, the developers of the various JXTA Reference Bindings have needed to produce 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.
Table of Contents
Table of Contents
These ID Formats have been defined for JXTA Language Binding Reference Implementations.
The Java 2SE reference implementation of JXTA provides an implementation of JXTA IDs based upon UUIDs. This optional ID Format is identified as the "uuid" format. In this implementation, UUIDs are encoded as hex digits as the basis creating unique identifiers. At the end of each UUID ID two hex characters that identify the type of JXTA ID. Currently, six ID Types have been defined.
Figure 1.1. JXTA "uuid" ID Format ABNF
<JXTAUUIDURN> ::= "urn:" <JXTANS> ":" <JXTAUUIDFMT> "-" <(1*(<hex> <hex>)) <JXTAUUIDIDTYPE> <JXTAUUIDFMT> ::= "uuid" <JXTAUUIDIDTYPE> ::= <CODATID> | <PEERGROUPID> | <PEERID> | <PIPEID> | <MODULECLASSID> | <MODULESPECID> <CODATID> ::= "01" <PEERGROUPID> ::= "02" <PEERID> ::= "03" <PIPEID> ::= "04" <MODULECLASSID> ::= "05" <MODULESPECID> ::= "06"
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 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 though 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 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.
Example 1.1. Sample "uuid" Format ID
urn:jxta:uuid-00030102040501
Decodes to:
0:00 | 1:03 | 2:01 | 3:02 | 4:04 | 5:05 | 6-62:00 | 63:01 |
For each of the five types of JXTA IDs 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.
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.
Table 1.1. JXTA UUID Codat ID Fields
0:Group MSB | 0-15:...GROUP UUID... | ||||
...GROUP UUID (cont.)... | 15:Group LSB | ||||
16:ID MSB | 16-31:...CODAT UUID... | ||||
...CODAT UUID (cont.)... | 31:ID LSB | ||||
32:Hash | 32-51:CODAT SHA1 Hash... | ||||
...CODAT SHA1 Hash... | |||||
...CODAT SHA1 Hash | 51:Hash | ||||
63:ID Type |
Each peer group is assigned a unique id that enables canonical references to that peer group.
Table 1.2. JXTA UUID PeerGroup ID Fields
0:MSB | 0-15...GROUP UUID... | ||
...GROUP UUID (cont.) | 15:LSB | ||
63:IDType |
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.
Table 1.3. JXTA UUID Peer ID Fields
0:Group MSB | 0-15...GROUP UUID... | ||
...GROUP UUID (cont.) | 15:Group LSB | ||
16:ID MSB | 16-31:...PEER UUID... | ||
...PEER UUID (cont.)... | 31:ID LSB | ||
63:IDType |
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.
Table 1.4. JXTA UUID Pipe ID Fields
0:Group MSB | 0-15...GROUP UUID... | ||
...GROUP UUID (cont.) | 15:Group LSB | ||
16:ID MSB | 16-31:...PIPE UUID... | ||
...PIPE UUID (cont.)... | 31:ID LSB | ||
63:IDType |
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.
Table 1.5. JXTA UUID Module Class ID Fields
0:MSB | 0-15...MODULE UUID... | ||
...MODULE UUID (cont.) | 15:LSB | ||
63:IDType |
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.
Table 1.6. JXTA UUID Module Spec ID Fields
0:CLASS MSB | 0-15...MODULE CLASS... | ||
...MODULE CLASS (cont.) | 15:CLASS LSB | ||
16:SPEC MSB | 16-31:...SPEC UUID... | ||
...SPEC UUID (cont.)... | 31:SPEC LSB | ||
63:IDType |
The JXTA Core Specification consists of the required components and behaviours which are present in all conforming JXTA implementations.
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.
[RFC2046] IETF RFC. 2046. Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types . Internet Engineering Task Force. November 1996.
[RFC2119] IETF RFC. 2119. Key words for use in RFCs to Indicate Requirement Levels . Internet Engineering Task Force. March 1997.
[RFC2141] IETF RFC. 2141. URN Syntax . Internet Engineering Task Force. May 1997.
[RFC2234] IETF RFC. 2234. Augmented BNF for Syntax Specifications: ABNF . Internet Engineering Task Force. November 1997.
[XSD2001-1] XML Schema Part 1: Structures . W3C. 2 May 2001.
[XSD2001-2] XML Schema Part 2: Datatypes . W3C. 2 May 2001.
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Powered by eList eXpress LLC