not assigned M. Duigou
Internet-Draft Project JXTA
Expires: December 20, 2002 June 21, 2002

JXTA v1.0 Protocols Specification
draft-duigou-jxta-protocols-00

Status of this Memo

This document is an Internet-Draft and is in full conformance with
all provisions of Section 10 of RFC2026 except that the right to
produce derivative works is not granted.

Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as Internet-
Drafts.

Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."

The list of current Internet-Drafts can be accessed at http://
www.ietf.org/ietf/1id-abstracts.txt.

The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html.

This Internet-Draft will expire on December 20, 2002.

Abstract

The JXTA protocols defines a suite of six XML-based protocols that
standardize the manner in which peers self-organize into peergroups,
publish and discover peer resources, communicate, and monitor each
other. The Endpoint Routing Protocol (ERP) is the protocol by which
a peer can discover a route (sequence of hops) to send a message to
another peer potentially traversing firewalls and NATs. The
Rendezvous Protocol (RVP) is used for propagating a message within a
peergroup. The Peer Resolver Protocol (PRP) is the protocol used to
send a generic query to one or more peers, and receive a response (or
multiple responses) to the query. The Peer Discovery Protocol (PDP)
is used to publish and discover resource advertisements. The Peer

Duigou & Project JXTA Expires December 20, 2002 [Page 1]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

Information Protocol (PIP) is the protocol by a which a peer may
obtain status information about another peers. The Pipe Binding
Protocol (PBP) is the protocol by which a peer can establish a
virtual communication channel or pipe between one or more peers. The
JXTA protocols permit the establishment a virtual network overlay on
top of physical networks allowing peers to directly interact and
organize independently of their network location and connectivity.
The JXTA protocols have been designed to be easily implemented on
unidirectional links and asymmetric transports.

Production Notes

First Internet-Draft submission. This draft has been generated from
a DocBook XML file which was transformed into an RFC 2629 XML source
file. This draft does not include the tables from the original XML
source as table conversion was not implemented by the IETF 54
submission deadline. To review the tables please access the XML
source or HTML and PDF output versions source at http://spec.jxta.org

Duigou & Project JXTA Expires December 20, 2002 [Page 2]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

1. Introduction

1.1 The JXTA Protocols

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
independent of their positions in the network (edges, firewalls,
network address translators, public vs. private address spaces), and
without the need of a centralized management infrastructure.

The design of the JXTA protocols seeks to create a set of protocols
that have very low overhead, make few assumptions about the
underlying network transport and impose few requirements on the peer
environment, and yet are able to be used to deploy a wide variety of
P2P applications and services in a highly unreliable and changing
network environment.

Peers use the JXTA protocols to advertise their resources and to
discover network resources (services, pipes, etc.) available from
other peers. Peers form and join peergroups to create special
relationships. Peers cooperate to route messages allowing for full
peer connectivity. The JXTA protocols allow peers to communicate
without the need to understand or manage the potentially complex and
dynamic network topologies which are increasingly common.

The JXTA protocols allow peers to dynamically route messages across
multiple network hops to any destination in the network (potentially
traversing firewalls). Each message carries with it either a
complete or partial ordered list of gateway peers through which the
message might be routed. If the routing 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:

o Peer Resolver Protocol (Section 3.4.1) (PRP) is the mechanism by
which a peer can send a query to one or more peers, and receive a
response (or multiple responses) to the query. The PRP implements
a query/response protocol. The response message is matched to the
query via a unique id included in the message body. When a peer
is discovered via PDP, a query can be sent to that peer.

o Peer Discovery Protocol (Section 4.2.1) (PDP) is the mechanism by
which a peer can advertise its own resources, and discover the
resources from other peers (peer groups, services, pipes and

Duigou & Project JXTA Expires December 20, 2002 [Page 3]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

additional peers). Every peer resource is described and published
using an advertisement. Advertisements are programming language-
neutral metadata structures that describe network resources.
Advertisements are represented as XML documents.

o Peer Information Protocol (Section 4.2.3) (PIP) is the mechanism
by a which a peer may obtain status information about other peers,
such as state, uptime, traffic load, capabilities, etc.

o Pipe Binding Protocol (Section 4.2.4) (PBP) is the mechanism by
which a peer can establish a virtual communication channel or pipe
between one or more peers. The PBP is used by a peer to bind two
or more ends of the connection (pipe endpoints). Pipes provide
the foundation communication mechanism between peers.

o Endpoint Routing Protocol (Section 3.4.2) (ERP) is the mechanism
by which a peer can discover a route (sequence of hops) used to
send a message to another peer. If a peer A wants to send a
message to peer C, and there is no direct route between A and C,
then peer A needs to find the intermediary peer(s) to route the
message to C. ERP is used to determine the route information.
When the network topology has changed such that the route to C can
no longer be used, because a link along the route no longer works,
the peer can use ERP to find any routes other peers know to
construct a route to C.

o Rendezvous Protocol (Section 4.2.2) (RVP) is the mechanism by
which peers can subscribe or be a subscriber to a propagation
service. Within a PeerGroup, peers can be rendezvous peers, or
peers that are listening to rendezvous peers. The Rendezvous
Protocol allows a peer to send messages to all the listening
instances of the service. The RVP is used by the Peer Resolver
Protocol and by the Pipe Binding Protocol in order to propagate
messages.

All of these protocols are implemented using a common messaging
layer. This messaging layer is what binds the JXTA protocols to
various network transports. (see Messages (Section 3.6))

Each of the JXTA protocols is independent of the others, and a peer
is not required to implement all six protocols. A peer only
implements 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

Duigou & Project JXTA Expires December 20, 2002 [Page 4]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

information to other peers, hence the peer might not implement the
Peer Information Protocol. The same can be said about all of the
other protocols.

---------------------------------------------------------------------

+------------------------+ +------------------------+
| +------------------+ | | +------------------+ |
| | Peer Information | <-------> | Peer Information | |
| +------------------+ | | +------------------+ |
| | | |
| +------------------+ | | +------------------+ |
| | Peer Rendezvous | <-------> | Peer Rendezvous | |
| +------------------+ | | +------------------+ |
| | | |
| +------------------+ | | +------------------+ |
| | Pipe Binding | <-------> | Pipe Binding | |
| +------------------+ | | +------------------+ |
| | | |
| +------------------+ | | +------------------+ |
| | Peer Discovery | <-------> | Peer Discovery | |
| +------------------+ | | +------------------+ |
|Peer | |Peer |
+------------------------+ +------------------------+

+------------------------+ +------------------------+
| +------------------+ | | +------------------+ |
| | Peer Resolver | <-------> | Peer Resolver | |
| +------------------+ | | +------------------+ |
| | | |
| +------------------+ | | +------------------+ |
| | Endpoint Routing | <-------> | Endpoint Routing | |
| +------------------+ | | +------------------+ |
|Endpoint | |Endpoint |
+------------------------+ +------------------------+

+------------------------+ +------------------------+
| Transport | | Transport |
+------------------------+ +------------------------+

Figure 1: JXTA Protocols

---------------------------------------------------------------------

The JXTA protocols do not 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

Duigou & Project JXTA Expires December 20, 2002 [Page 5]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

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.

A unique characteristic of P2P networks, like JXTA, is their ability
to spontaneously replicate information toward end-users. Popular
advertisements are likely to be replicated more often, making them
easier to find as more copies become available. Peers do not have to
return to the same peer to obtain the advertisements they are
interested in. Instead of querying the original source of an
advertisement, peers may query neighboring peers that have already
cached the information. Each peer may potentially become an
advertisement provider to any other peer.

The JXTA protocols have been designed to allow JXTA to be easily
implemented on uni-directional links and asymmetric transports. In
particular, many forms of wireless networking do not provide equal
capability for devices to send and receive. JXTA permits any uni-
directional link to be used when necessary, improving overall
performance and network connectivity in the system. The intent is
for the JXTA protocols to be as pervasive as possible, and easy to
implement on any transport. Implementations on reliable and bi-
directional transports such as TCP/IP or HTTP should lead to
efficient bi-directional communications.

The JXTA uni-directional and asymmetric transport also plays well in
multi-hop network environments where the message latency may be
difficult to predict. Furthermore, peers in a P2P network tend to
have nondeterministic behaviours. They may join or leave the network
on a very frequent basis.

1.2 JXTA Assumptions

This section is a guide to the assumptions that inform the design of
JXTA. There are two types of assumptions stated here, those which

Duigou & Project JXTA Expires December 20, 2002 [Page 6]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

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, NOT RECOMMENDED, MAY, and OPTIONAL in this
document are to be interpreted as described in "IETF RFC 2119" [bib-
RFC2119 [2]].

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.

A peer SHOULD assume that the capabilities and complexity of the
network peers supporting these protocols can range from a single
light switch to a highly-available supercomputer cluster.

A peer 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 for correct
and conformant interaction with other peers.

A peer MAY choose to partially implement protocols if unimplemented
portions will never be used. (e.g. client-side or server-side only)

Peers wishing to interact with other peers within the JXTA network
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 deployed over a wide variety of network
configurations including the Internet, corporate intranets, a dynamic
proximity network, or in a home networking environment. Applications
should avoid assumptions about the underlying network environment.

Peers receiving a corrupted or detectably compromised message MUST
discard the message. Messages may be corrupted or intentionally
altered during network transmission.

Peers MAY appear, disappear and migrate at any time without notice.
In particular, the JXTA protocols support very arbitrary environment
changes allowing a peer to dynamically discover and reconnect to its
changing environment.

Communication ability between any pair of peers MAY at times not work
equally well in both directions. That is, communications between two

Duigou & Project JXTA Expires December 20, 2002 [Page 7]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

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.
The JXTA Core Protocols (Section 3.4) MUST NOT impose any timing
requirements for message receipt.

The JXTA Transport Protocols (see Core JXTA Transport Bindings
(Section 3.5) and Standard JXTA Transport Bindings (Section 4.3))
MUST NOT impose any timing requirements on the JXTA Core Protocols
(Section 3.4) but MAY have timing requirements internal to
themselves.

The Standard Protocols (Section 4.2) (e.g. Peer Discovery Protocol
(Section 4.2.1), Peer Information Protocol (Section 4.2.3), Peer
Discovery Protocol (Section 4.2.4), etc. ) and application defined
protocols MAY impose timing requirements on message delivery and
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.

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 protocol messages and advertisements are defined using
XML messages, an XML parser is OPTIONAL. Small JXTA implementations
MAY choose to use pre-built XML or XML templates for message and
advertisement construction.

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

Duigou & Project JXTA Expires December 20, 2002 [Page 8]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

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.

A peer SHOULD make the assumption that if a destination address is
not available at any time during the message transmission, the
message will not be delivered.

Each peer MUST be a member of the World Peergroup and Net Peergroups.
Membership in these groups is automatic.

Peers MUST be members of the same peer group in order to exchange
messages.

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 service
that guarantees, within a given scope, the uniqueness of name and can
be used to register name mapping. Examples of Name services are DNS
and LDAP. A naming service is OPTIONAL. JXTA does not define its
own naming service.

Once content has been published to the JXTA network, it 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.

1.3 Why JXTA?

The JXTA Protocols are an open network computing platform designed
for peer-to-peer (P2P) computing.

The JXTA protocols standardize the manner in which peers:

Duigou & Project JXTA Expires December 20, 2002 [Page 9]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

o Discover each others

o Self-organize into peer groups

o Advertise and discover network resources

o Communicate with each others

o Monitor each other

The JXTA protocols DO NOT:

o Require the use of any particular computer language or operating
system.

o Require the use of any particular network transport or topology.

o Require the use of any particular authentication, security or
encryption model.

The JXTA protocols enable developers to build and deploy
interoperable services and applications, further spring-boarding the
peer to peer revolution on the Internet.

JXTA intends to achieves this by providing a simple and generic P2P
platform to host all types of network services

o JXTA is defined by a small number of protocols. Each protocol is
easy to implement and integrate into P2P services and
applications. Thus service offerings from one vendor can be used
transparently by the user community of another vendor's system.

o The JXTA protocols are defined to be independent of programming
languages, so that they can be implemented in C/C++, Java, Perl,
and numerous other languages. Heterogeneous devices with
completely different software stacks can interoperate with the
JXTA protocols.

o The JXTA protocols are designed to be independent of transport
protocols. They can be implemented on top of TCP/IP, HTTP,
Bluetooth, HomePNA, and many other protocols.

1.4 The JXTA Three Layer Cake

The JXTA Project is divided in three layers.

o Platform. This layer encapsulates minimal and essential

Duigou & Project JXTA Expires December 20, 2002 [Page 10]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

primitives that are common to P2P networking, including peers,
peergroups, discovery, communication, monitoring, and associated
security primitives. This layer is ideally shared by all P2P
devices so that interoperability becomes possible.

o Services. This layer includes network services that may not be
absolutely necessary for a P2P network to operate but are common
or desirable to be available to the P2P environment. Examples of
network services, include search and indexing, directory, storage
systems, file sharing, distributed file systems, resource
aggregation and renting, protocol translation, authentication and
PKI services.

o Applications. This layer includes P2P instant messaging,
entertainment content management and delivery, P2P E-mail systems,
distributed auction systems, and many others. Obviously, the
boundary between services and applications is not rigid. An
application to one customer can be viewed as a service to another
customer.

Duigou & Project JXTA Expires December 20, 2002 [Page 11]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

2. Conceptual Overview

JXTA is intended to be a small system with a limited number of
concepts at its core. This chapter introduces the concepts which are
core to JXTA.

2.1 Peers

A peer is any networked device (sensor, phone, PDA, PC, server,
supercomputer, 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 doing so 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 join 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 connections between two peers.

Communicating peers peers may not have direct point-to-point network
connection between themselves, either due to lack of physical network
connections, or network configuration (NATs, firewalls, proxies,
etc.). A peer MAY have to use one or more intermediary peers to

Duigou & Project JXTA Expires December 20, 2002 [Page 12]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

route a message to another peer.

Each peer is uniquely identified by a unique Peer Id.

2.2 Peer Groups

Peers self-organize into Peer Groups. A peer group is a collection
of peers that have a common set of interests. Each peer group is
uniquely identified by a unique PeerGroup Id. The JXTA protocols do
not dictate when, where, or why peergroups are created. The JXTA
protocols only describe how a peers may publish, discover, join, and
monitor peergroups.

JXTA recognizes three common motivations for creating peer groups:

o To create a secure environment. Peergroup boundaries permit
member peers to access and publish protected contents. Peergroups
form logical regions whose boundaries limit access to the
peergroup resources. A peergroup does not necessarily reflect the
underlying physical network boundaries such as those imposed by
routers and firewalls. Peergroups virtualize the notion of
routers and firewalls, subdividing the network in secure regions
without respect to actual physical network boundaries.

o To create a scoping environment. Peergroups are typically formed
and self-organized based upon the mutual interest of peers. No
particular rules are imposed on the way peergroups are formed, but
peers with the same interests will tend to join the same
peergroups. Peergroups serve to subdivide the network into
abstract regions providing an implicit scoping mechanism.
Peergroup boundaries define the search scope when searching for a
group's content.

o To create a monitoring environment. Peergroups permit peers to
monitor a set of peers for any special purpose (heartbeat, traffic
introspection, accountability, etc.).

A peergroup provides a set of services called peergroup services.
JXTA defines a core set of peergroup services. The JXTA protocols
specify the wire format for these core peergroup services.
Additional peergroup services can be developed for delivering
specific services. For example, a lookup service could be
implemented to find active (running on some peer) and inactive (not
yet running) service instances. The core peer group services are:

Discovery Service : The Discovery service is used by member peers to
search for peergroup resources (peers, peer groups, pipes, and
services).

Duigou & Project JXTA Expires December 20, 2002 [Page 13]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

Membership Service : The membership service is used by the current
members to reject or accept a new group membership application.

We expect that most peergroups will have at least a membership
service, though it may be a "null" authenticator service which
imposes no real membership policy. The membership service is used
by a member peer to allow a new peer to join a peergroup. In
order for a peer to join a peergroup, a peer MAY need to discover
at least one member of the peergroup.

Peers wishing to join a peer group MAY first have to 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.

Access Service : The Access service is used to validate requests
made by one peer to another. The peer receiving the request
provides the requesting peer credentials and information about the
request being made to the Access Service to determine if the
access is permitted.

Not all actions within the peer group need to be checked with the
Access Service. Only those actions that are restricted to a
subset of member peers must be checked.

Pipe Service : The pipe service is used to manage and create pipe
connections between the different peer group members.

Resolver Service : The resolver service is used to address queries
to services running on peers in the group and collect responses.

Monitoring Service : The monitoring service is used to allow one
peer to monitor other members of the same peer group.

Not all the above services 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 services may not implement any
protocols.

2.3 Network Services

Peers cooperate and communicate to publish, discover and invoke
network services. A peer can publish as many services that it can

Duigou & Project JXTA Expires December 20, 2002 [Page 14]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

provide. Peers discover network services via the Peer Discovery
Protocol.

Network Service specifications are beyond the scope of this document.
Upcoming standards such as WSDL, ebXML, SOAP, UPnP might be used
within a JXTA Network.

The JXTA protocols recognize two levels of network services:

o Peer Services

o PeerGroup Services

A peer service is accessible only on the peer that is publishing the
service. If that peer happens to fail, then the service also fails.
Multiple instances of the service can be run on different peers, but
each instance publishes its own advertisement.

A peergroup service is composed of a collection of instances
(potentially cooperating with each other) of the service running on
multiple members of the peergroup. If any one peer fails, the
collective peergroup service is not affected, because chances are the
service is still available from another peer member. Peergroup
services are published as part of the peergroup advertisement.

Services can either be pre-installed into a peer or loaded from the
network. The process of finding, downloading and installing a
service from the network is similar to performing a search on the
internet for a web page, retrieving the page, and then installing the
required plug-in. In order to actually run a service, a peer may
have to locate an implementation suitable for the peer's runtime
environment. Multiple implementations of the same service may allow
Java peers to use Java code implementations, and native peers to use
native code implementations.

2.3.1 Service Invocation

Service invocation is outside the scope of JXTA. JXTA is designed to
interoperate and be compatible with any Web service standards; WSDL,
uPnP, RMI, etc. The JXTA protocols define a generic framework to
publish and discover Advertisements that may describe services.
Peers publish and discover advertisements via the Peer Discovery
Protocol. An advertisement for a service will typically contain all
the necessary information to either invoke or instantiate the service
being described. The JXTA protocols define Module Advertisements but
any other form of service description may be introduced.

Duigou & Project JXTA Expires December 20, 2002 [Page 15]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

2.3.2 JXTA-Enabled Service

JXTA-Enabled services are services that are published by using the
ModuleSpecAdvertisement. A module spec advertisement may specify a
pipe advertisement that can be used by a peer to create output pipes
to invoke the service. ModuleSpec Advertisement may be extended in
the future to contain a list of pre-determined messages that can be
sent by a peer to interact with the service. A
ModuleSpecAdvertisement may also contain references to two other
services which can be used as an authenticator for the service and as
a local proxy for the service.

Each Jxta-enabled service is uniquely identified by its ModuleSpecID.

2.4 Pipes

Pipes are virtual communication channels used to send and receive
messages between services or applications over endpoints. Pipes
provide a network abstraction over the peer endpoint transport. Peer
endpoints correspond to the available peer network interfaces that
can be used to send and receive data from another peer. Pipes
provide the illusion of a virtual in and out mailbox that is
independent of any single peer location, and network topology (multi-
hops route).

Different quality of services can be implemented by a pipe. For
example:

Uni-directional asynchronous : The endpoint sends a message, no
guarantee of delivery is made.

Synchronous request-response : The endpoint sends a message, and
receives a correlated answer.

Bulk transfer : Bulk reliable data transfer of binary data.

Streaming : Efficient control-flow data transfer.

Secure : Secure reliable data streams.

The uni-directional asynchronous pipe is REQUIRED by the JXTA
protocols. Other pipe variations may be implemented for use by
services and their associated 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 (receiver) and output

Duigou & Project JXTA Expires December 20, 2002 [Page 16]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

pipes (transmitter).

Pipe endpoints are dynamically bounded to a peer endpoint at runtime,
via the Pipe Binding Protocol (Section 4.2.4). The pipe binding
process consists of searching for and connecting the two or more
endpoints of a pipe.

When a message is sent into an output pipe, the message is sent by
the local peer endpoint to the peer endpoint(s) where the associated
input pipe is located. The set of peer endpoints currently
associated with the input pipes is discovered using the Pipe Binding
Protocol (Section 4.2.4).

A pipe offers two modes of communication:

Point to Point : A point to point pipe connects exactly two pipe
endpoints together, an input pipe that receives messages sent from
an output pipe. No reply or acknowledgment operation is
supported. Additional information in the message payload like a
unique id may be required to thread message sequences. The
message payload may also contain a pipe advertisement that can be
used to open a pipe to reply to the sender (send/response).

Propagate Pipe : A propagate pipe connects one output pipe to
multiple input pipes together. Messages flow into the input pipes
from the output pipe (propagation source). A propagate message is
sent to all listening input pipes. This process may create
multiple copies of the message to be sent. On TCP/IP, when the
propagate scope maps an underlying physical subnet in a 1 to 1
fashion, IP multicast may be used as an implementation for
propagate. Propagate can be implemented using point to point
communication on transports that do not provide multicast such as
HTTP.

---------------------------------------------------------------------

Duigou & Project JXTA Expires December 20, 2002 [Page 17]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

| |
| |
receive | receive V
+------+-----+ | +-----+------+
| | (i) |<---------------+ | | (i) | |
| peer +-----+ Point to Point | | +-----+ peer |
| | (o) | Pipe | | | (o) | |
+------+-----+ | | +-----+------+
| |
| |
send | V
+---+---+
| | |
|(o)|(i)|
| | |
+---+---+
| |
| peer |
| |
+-------+

JXTA Pipe Types

---------------------------------------------------------------------

Pipes may connect two peers that do not have a direct physical link.
One or more intermediary peer endpoints are used to route messages
between the two pipe endpoints.

2.5 Messages

The information transmitted using pipes and between endpoints is
packaged as messages. Messages define an envelope to transfer any
kind of data. A message 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
Java objects or "C" structures.

The use of XML messages to define protocols allows many different
kinds of peers to participate in a protocol. Each peer is free to

Duigou & Project JXTA Expires December 20, 2002 [Page 18]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

implement the protocol in a manner best suited to its abilities and
role.

2.6 Advertisements

All network resources, such as peers, peergroups, pipes and services
are represented by advertisements. Advertisements are JXTA's
language neutral metadata structures for describing resources. The
JXTA Core Specification and Standard Services define, among others,
the following advertisement types:

o Peer Advertisement

o PeerGroup Advertisement

o ModuleClass Advertisement

o ModuleSpec Advertisement

o ModuleImpl Advertisement

o Pipe Advertisement

o Rendezvous Advertisement

The complete specification of advertisements is given in the
Advertisements (Section 3.3) chapter. The JXTA protocols make heavy
reference to these advertisements, so the reader should be familiar
with advertisements before moving on to the protocol specification
chapters. Advertisements are, by far, the most common document
exchanged in the protocol messages.

Services or peer implementations can create their own advertisement
types, either from scratch or by subtyping the existing types.

2.7 Credentials

The need to support different levels of resource access in a dynamic
and ad hoc P2P network leads to a role-based trust model in which an
individual peer will act under the authority granted to it by another
trusted peer to perform a particular task. Peer relationships 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:

Confidentiality : guarantees that the contents of the message are
not disclosed to unauthorized individuals.

Duigou & Project JXTA Expires December 20, 2002 [Page 19]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

Authorization : guarantees that the sender is authorized to send a
message.

Data integrity : guarantees that the message was not modified
accidentally or deliberately in transit.

Refutability : guarantees the message was transmitted by a properly
identified sender and is not a replay of a previously transmitted
message.

The structure of JXTA messages enables JXTA applications to add
abitrary metadata information to messages such as credentials,
digests, certificates, public keys, etc.

A credential is a token that when presented in a message body is used
to identify a sender and can be used to verify that sender's right to
send the message to the specified endpoint. The credential is an
opaque token that must be presented each time a message is sent.

The sending address placed in the message envelope is cross-checked
with the sender's identity in the credential. Each credential's
implementation is specified as a plug-in configuration, which allows
multiple authentication configurations to co-exist on the same
network.

Message digests guarantee the data integrity of messages. Messages
may also be encrypted and signed for confidentiality and
refutability.

It is the intent of the JXTA protocols to be compatible with widely
accepted transport-layer security mechanisms. Some JXTA
implementations contain a virtualized TLS implementation that allows
it to secure Endpoint to Endpoint communications regardless of the
number of hops required to deliver each message.

TLS and IPSec could also be used as JXTA transports. However, when
used as transports they provide integrity and confidentiality of
message transfer only between the two communicating peers.

2.8 IDs

Within the JXTA protocols there are a number of entities that need to
be uniquely identifiable. These are peers, peergroups, pipes and
contents. A JXTA ID uniquely identifies an entity and serves as a
canonical means of referring to that entity.

URNs are used for the expression of JXTA IDs.

Duigou & Project JXTA Expires December 20, 2002 [Page 20]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

2.9 Content

The JXTA protocols assume that many types of contents may be shared,
exchanged, and replicated between peers. A content can be a text
file, a structured document (like a PDF or an XML file), a Java .jar
or loadable library, code or even an executable process (checkpointed
state). No size limitation is assumed.

Content is published and shared amongst peer members of a peergroup.
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.

A content instance 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 content within a peergroup helps to ensure that each item
of content be more readily available. For example, if an item has
two instances residing on two different peers, only one of the peers
needs to be alive to respond to the content request.

The JXTA protocols do not specify how contents are replicated. This
decision is left to higher-level content service managers.

Duigou & Project JXTA Expires December 20, 2002 [Page 21]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

3. JXTA Core Specification

3.1 Introduction

JXTA is designed to be a small system with only a few required
components and behaviours. The functionality that is required of all
implementations is defined by the JXTA Core Specification and is
documented in this section. Implementations that wish to be JXTA
compliant MUST implement all of the JXTA Core Specification (Section
3).

Implementation of the JXTA Core Specification (Section 3) does not
guarantee or even necessarily provide interoperability with other
JXTA implementations. There are a number of types of components and
behaviours which need to be provided by JXTA implementation which are
not part of the JXTA Core Specification (Section 3). Existing
implementations of these components are described separately in JXTA
Standard Services (Section 4) and JXTA Reference Implementations
Information (Section 5). In order for a JXTA implementation to be
interoperable with other implementations it may be necessary to
implement some of the components described there.

3.2 IDs

3.2.1 Introduction

The JXTA protocols often need to refer to peers, peer groups, pipes
and other JXTA resources. These references are presented in the
protocols as JXTA IDs. JXTA IDs are a means for uniquely identifying
specific peer groups, peers, pipes, contents and service instances.
JXTA IDs provide unambiguous references to the various JXTA entities.
There are six types of JXTA entities which have JXTA ID types
defined: peergroups, peers, pipes, content, module classes and module
specifications. Additional JXTA ID types may be defined in the
future.

JXTA IDs are normally presented as URNs. URNs are a form of URI that
"... are intended to serve as persistent, location-independent,
resource identifiers". Like other forms of URI, JXTA IDs are
presented as text. See "IETF RFC 2141" [bib-RFC2141 [3]] for more
information on URNs.

3.2.2 Format of a JXTA ID URN

A JXTA ID is a standard URN in the JXTA ID namespace. JXTA ID URNs
are identified by the 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

Duigou & Project JXTA Expires December 20, 2002 [Page 22]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

additional information from the ID. Two ID formats have been defined
which are identified by the "jxta" and "uuid" keywords. It is
possible to define additional JXTA ID formats in order to refer to
resources both within JXTA and to bridge to other technologies.

The following format specifications use the ABNF syntax as defined in
"IETF RFC 2234" [bib-RFC2234 [4]].

---------------------------------------------------------------------

<JXTANS> ::= "jxta"

<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> ::= "%" | "/" | "?" | "#"

Duigou & Project JXTA Expires December 20, 2002 [Page 23]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

Figure 3: JXTA ID ABNF

---------------------------------------------------------------------

The jxta URN namespace does not currently define any special symbols
from the "reserved" set.

3.2.3 Using JXTA IDs in Protocols

When JXTA IDs are used within protocols they are manipulated as text
string URIs. There are three operations available for URIs; compare,
resolve, decompose. JXTA ID URIs 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.

3.2.4 Example JXTA ID URNs

The following examples demonstrate valid JXTA ID presentation forms.
These examples are not necessarily valid 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

Figure 4: Sample JXTA IDs

---------------------------------------------------------------------

In the preceding examples, A., B. and C. represent the same JXTA
ID. Both the "URN" portion and the "JXTA" are case insensitive.
Example D. is not equivalent to any of A., B. or C. because the
data portion of the URN is case sensitive. In the six examples, four
different JXTA ID Formats are used: "idform", "IDForm", "idform2" and
"idform3". Definition of ID Format names that differ only in
character case is NOT RECCOMENDED. The interpretation of the
characters following the "-" is specific to each ID Format.

Duigou & Project JXTA Expires December 20, 2002 [Page 24]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

3.2.5 JXTA ID Properties

Every JXTA ID, regardless of format or type has the following
properties:

o Unambiguous. It MUST be a complete reference to the resource.

o Relatively Unique. It MUST refer to a single resource.

o Canonical. References to the same resource SHOULD encode to the
same JXTA ID. This enables IDs to be compared to determine if
they refer to the same resource, but understandably may not be
achievable by all ID Formats.

o Opacity. In their URN presentation JXTA IDs SHOULD be assumed to
be opaque. The context of an ID within a protocol message
generally is sufficient to establish its type. A JXTA binding may
be able to interpret an ID if it supports the ID Format.
Generally, only the immediate participants in a JXTA protocol need
to understand the contents of a JXTA ID, if at all.

3.2.6 JXTA ID Formats

JXTA IDs are designed to support multiple ID Formats. ID Formats
allow JXTA developers to utilize existing naming and ID schemes
within JXTA. In the JXTA ID presentation, the ID's "Format" follows
the JXTA URN namespace. Any JXTA ID Format which follows the general
requirements for URNs and the JXTA ID Properties will be usable by
conformant JXTA implementations.

3.2.7 JXTA ID Types

JXTA IDs may refer to many types of resources; pipes, peers, etc.
Each JXTA ID format type may support references to one or more of
these resource types. Currently, five standard resource types have
been identified; peer groups, peers, pipes, content and service
instances. Other types may be defined.

Each of the individual ID Types MAY provide additional requirements
specific to its type.

3.2.7.1 Peer Group IDs

Peer Group IDs refer to peer groups. A peer group ID should
canonically, uniquely and unambiguously refer to a peer group. Every
ID Format MUST support this ID Type because all of the other ID Types
refer to the peer group to which they belong. Every ID Format MUST

Duigou & Project JXTA Expires December 20, 2002 [Page 25]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

support encoding of the World Peer Group. Support for other peer
groups is OPTIONAL. Example: You are defining an ID Format for Peer
IDs based upon driver's license number. Driver's licenses are not
organized into groups. This can be considered equivalent to all
driver's licenses belonging to the same group, the global "world peer
group".

3.2.7.2 Peer IDs

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.

3.2.7.3 Codat IDs

Codat IDs refer to codats. A Codat ID should canonically, uniquely
and unambiguously refer to a codat. 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 Codat ID. This Peer Group ID
identifies the peer group to which the codat belongs.

3.2.7.4 Pipe IDs

Pipe IDs refer to pipes. A Pipe ID should canonically, uniquely and
unambiguously refer to a pipe. 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 Pipe ID. This Peer Group ID
identifies the peer group to which the pipe belongs.

3.2.7.5 Module Class IDs

A Module Class ID identifies a particular local behavior, that is, a
specific API for each execution environment for which an
implementation exists. A Module Class ID SHOULD canonically,
uniquely and unambiguously refer to a module class as defined by an
advertisement. Support for this ID Type is OPTIONAL. If a JXTA
binding recognizes the ID Type, it should be able to extract a Base
Class ID from a Module Class ID. The Base Class ID allows
applications to determine if two Module Class IDs differ only in the
"role" they perform. Module Spec ID's "roles" allow for the same
module to be reused within a group and have instances distinguished.
This is necessary when, for example, a common database service is
used, with each "role" accessing a different data set.

Duigou & Project JXTA Expires December 20, 2002 [Page 26]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

3.2.7.6 Module Spec IDs

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 for
which there may be multiple platform specific implementations. A
ModuleSpecID is used to locate a compatible implementation such that
it can be instantiated. All such implementations are assumed to be
network compatible. A Module Spec ID SHOULD canonically, uniquely
and unambiguously refer to a module specification. Support for this
ID Type is OPTIONAL. If a JXTA binding recognizes the ID Type, it
should be able to extract a Module Class ID from a Module Spec ID.

3.2.8 JXTA ID Formats : jxta ID Format

The "jxta" ID Format is a REQUIRED ID Format that is used for
encoding "well known" JXTA identifiers. All JXTA binding
implementations MUST support this ID Format. There are three special
reserved JXTA IDs; the Null ID, the World Peer Group ID and the Net
Peer Group ID. The "jxta" ID Format exists so that for these few
"well known" IDs only a single representation exists.

---------------------------------------------------------------------

<JXTAJXTAFMT> ::= "jxta"

<JXTANULL> ::= "Null"

<JXTAWORLDGROUP> ::= "WorldGroup"

<JXTANETGROUP> ::= "NetGroup"

Figure 5: JXTA ID : "jxta" ID Format ABNF

---------------------------------------------------------------------

3.3 Advertisements

Duigou & Project JXTA Expires December 20, 2002 [Page 27]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

3.3.1 Introduction

Advertisements are meta-data documents used by JXTA protocols to
describe resources. Advertisements are used to describe peers, peer
groups, pipes, content, services and many other types of resources.
JXTA Advertisements are presented in XML. Many of the JXTA protocols
depend on Advertisements to provide necessary information. JXTA
protocols are used to pass Advertisements between peers.

Services can define new Advertisement types by sub-typing existing
Advertisement types or by defining completely new Advertisements.
Advertisement sub-types allow for additional information to be
provided as well as richer meta-data.

Advertisements are composed of a series of hierarchically arranged
elements. The elements may appear in any order within the
advertisement. Each element can contain its data or additional
elements. An element can also have attributes. Attributes are name-
value string pairs. An attribute is used to store meta-data, which
helps to describe the data within the element.

The Core JXTA Protocols rely on the following advertisements:

o Peer Advertisement (Section 3.3.3)

o Peer Group Advertisement (Section 3.3.4)

o Module Class Advertisement (Section 3.3.5)

o Module Specification Advertisement (Section 3.3.6)

o Module Implementation Advertisement (Section 3.3.7)

3.3.2 XML and JXTA Advertisements

All JXTA advertisements are represented in XML. XML provides a
powerful means of representing data and metadata throughout a
distributed system. XML provides a universal (software-platform
neutral) representation:

o XML is programming language agnostic

o XML is self-describing

o XML content can be strongly-typed

o XML ensures correct syntax

Duigou & Project JXTA Expires December 20, 2002 [Page 28]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

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 [bib-XSD2001-1 [6]][bib-XSD2001-2 [7]]. Use of XML Schemas
allows the advertisement contents to be strongly type-checked and
semanticly validated beyond the syntactical validation provided by
XML with DTDs. Service and protocol authors are RECOMMENDED to
specify their Advertisements or Advertisement sub-types using XML
Schema Language. DTDs are normally prepared from the schema
descriptions for use in environments which do not support XML schema.

The other powerful feature of XML is its ability to be translated
into other encodings such as HTML and WML. This feature allows peers
that do not support XML to access advertised resources.

---------------------------------------------------------------------

<xs:element name="JXTAID" type="jxta:JXTAID"/>

<xs:simpleType name="JXTAID">
<xs:restriction base="xs:anyURI">
<xs:pattern value="([uU][rR][nN]:[jJ][xX][tT][aA]:)+\-+"/>
</xs:restriction>
</xs:simpleType>

<xs:complexType name="serviceParam">
<xs:all>
<xs:element name="MCID" type="jxta:JXTAID"/>
<xs:element name="Parm" type="xs:anyType"/>
</xs:all>
</xs:complexType>

<xs:element name="Cred" type="jxta:Cred"/>

<xs:complexType name="Cred">
<xs:all>
</xs:all>
</xs:complexType>

Figure 6: Common Advertisement Fragments Schemas

---------------------------------------------------------------------

Duigou & Project JXTA Expires December 20, 2002 [Page 29]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

3.3.3 Peer Advertisement

A Peer Advertisement describes a peer and the resources it provides
to the group. The Peer Advertisement holds specific information
about the peer such as its name, its unique id, its group id and
descriptive information. It may also contain endpoint addresses and
any run-time attributes that individual peer services want to publish
(such as being a rendezvous peer for a group).

---------------------------------------------------------------------

<xs:element name="PA" type="jxta:PA"/>

<xs:complexType name="PA">
<xs:sequence>
<xs:element name="PID" type="JXTAID"/>
<xs:element name="GID" type="JXTAID"/>
<xs:element name="Name" type="xs:string" minOccurs="0"/>
<xs:element name="Desc" type="xs:anyType" minOccurs="0"/>
<xs:element name="Svc" type="jxta:serviceParams" minOccurs="0" maxOccurs="unbounded"/>
<xs:sequence>
</xs:complexType>

Figure 7: Peer Advertisement Schema

---------------------------------------------------------------------

<PID> : This is a required element that uniquely identifies the
peer. Each peer has a unique id. The peer id representation is
given in the Id Chapter.

<GID> : This element provides the Peer Group ID. This identifies
canonically which Peer Group this peer belongs to.ftp

<Name> : This is an optional string that can be associated with a
peer. The name is not required to be unique unless the name is
obtained from a centralized naming service that guarantees name
uniqueness.

<Desc> : This is an optional string that can be used to index and
search for a peer. The string is not guaranteed to be unique.
Two peers may have the same keywords. The keywords string may
contain spaces.

<Svc> : Any number of such elements may exist. Each of them
describes the association between a group service denoted by its
Class ID (the value of an MCID element), and arbitrary parameters

Duigou & Project JXTA Expires December 20, 2002 [Page 30]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

encapsulated in a Parm element. For example, all accessible
endpoint addresses are published in association with the Endpoint
Service Class ID. The TLS Root certificate is published under the
PeerGroup Class ID (There is a class ID for Peer Group as well).
The flag that denotes that this peer is a rendezvous for this
group is published under the Rendezvous Service Class ID.
Ultimately, each service is responsible for what is published
under its Class ID. The Service section may also optionally
contain an element "isOff" meaning that this service is disabled.
This element is used to convey a configuration choice made by the
owner of the peer.

3.3.4 Peer Group Advertisement

A Peer Group Advertisement describes peergroup specific resources:
name, group id, description, specification, and service parameters.

---------------------------------------------------------------------

<xs:element name="PGA" type="jxta:PGA"/>

<xs:complexType name="PGA">
<xs:sequence>
<xs:element name="GID" type="jxta:JXTAID"/>
<xs:element name="MSID" type="jxta:JXTAID"/>
<xs:element name="Name" type="xs:string" minOccurs="0"/>
<xs:element name="Desc" type="xs:anyType" minOccurs="0"/>
<xs:element name="Svc" type="jxta:serviceParam" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>

Figure 8: Peer Group Advertisement Schema

---------------------------------------------------------------------

<GID> : This element provides the Peer Group ID. The Peer Group ID
is the canonical way of refering to a group and uniquely
identifies the peer group. See Peer Group IDs (Section 3.2.7.1)
for more information on peer group ids.

<MSID> : Peer group Specification ID. This designates the module
that provides the peer group mechanism itself for that group. The
spec ID designates an abstraction of that mechanism. This
abstraction is optionally described by a ModuleSpecAdvertisement,
and any number of implementations may exist, each described by a
ModuleImplAdvertisement. These advertisements may all be searched

Duigou & Project JXTA Expires December 20, 2002 [Page 31]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

by this SpecID.

<Name> : This is an optional name that can be associated with a
peergroup. The name is not required to be unique unless the name
is obtained from a centralized naming service that guarantee name
uniqueness.

<Desc> : This is an optional element provides descriptive
information that may be used to index and search for a peergroup.
The content of this element may not be unique. For example, two
peergroups may have the same keywords.

<Svc> : Any number of such elements may exist. Each of them
describes the association between a group service denoted by its
Class ID (the value of an MCID element), and arbitrary parameters
encapsulated in a Parm element. This optional parameter may only
be meaningful to some services. It is used to configure a service
specifically in relation with its use by this group. For example,
a simple membership service may find an encrypted password list
there.

3.3.5 Module Class Advertisement

A Module Class Advertisement describes a class of modules. That is,
an expected local behavior and and expected API for each JXTA binding
(that supports such modules). The purpose of this advertisement is
to provide a description of what a particular Module Class ID stands
for. A Module Class ID is what other modules or other code running
on JXTA uses to designate modules which it depends upon. The
ModuleClassAdvertisement is not required to provide a completely
formal description of the module's behavior and API. It is intended
for humans who want to create modules with a similar functionality.
It is not required to publish a Module Class Advertisement for a
Module Class ID to be valid, although it is a good practice.

Duigou & Project JXTA Expires December 20, 2002 [Page 32]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

---------------------------------------------------------------------

<xs:element name="MCA" type="jxta:MCA"/>

<xs:complexType name="MCA">
<xs:sequence>
<xs:element name="MCID" type="jxta:JXTAID"/>
<xs:element name="Name" type="xs:string" minOccurs="0"/>
<xs:element name="Desc" type="xs:anyType" minOccurs="0"/>
</xs:sequence>
</xs:complexType>

Figure 9: Module Class Advertisement Schema

---------------------------------------------------------------------

<MCID> : Module Class ID. This is a required element that uniquely
identifies the class. Each module class has a unique id. The
class id representation is given in the Id Chapter.

<Name> : This is an optional name that can be associated with a
class. The name is not required to be unique unless the name is
obtained from a centralized naming service that guarantee name
uniqueness.

<Desc> : Description. This is an optional string that can be used
to describe and search for a class.

3.3.6 Module Specification Advertisement

A Module Specification Advertisement describes the specification of a
module. That is, an expected on-wire behavior and protocol. The
purpose of this advertisement is to provide a description of what a
particular Module Specification ID stands for. A Module
Specification ID is what other modules or other code running on JXTA
uses to 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

Duigou & Project JXTA Expires December 20, 2002 [Page 33]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

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.

---------------------------------------------------------------------

<xs:element name="MSA" type="jxta:MSA"/>

<xs:complexType name="MSA">
<xs:sequence>
<xs:element name="MSID" type="jxta:JXTAID"/>
<xs:element name="Vers" type="xs:string"/>
<xs:element name="Name" type="xs:string" minOccurs="0"/>
<xs:element name="Desc" type="xs:anyType" minOccurs="0"/>
<xs:element name="Crtr" type="xs:string" minOccurs="0"/>
<xs:element name="SURI" type="xs:anyURI" minOccurs="0"/>
<xs:element name="Parm" type="xs:anyType" minOccurs="0"/>
<xs:element ref="jxta:PipeAdvertisement" minOccurs="0"/>
<xs:element name="Proxy" type="xs:anyURI" minOccurs="0"/>
<xs:element name="Auth" type="jxta:JXTAID" minOccurs="0"/>
</xs:sequence>
</xs:complexType>

Figure 10: Module Specification Advertisement Schema

---------------------------------------------------------------------

<MSID> : ModuleSpecID. This is a required element that uniquely
identifies the specification. Each module specification has a
unique id. The spec id representation is given in the Id Chapter.

<Vers> : The mandatory version of the specification that this
advertises.

<Name> : This is an optional name that can be associated with a
spec. The name is not required to be unique unless the name is
obtained from a centralized naming service that guarantee name
uniqueness.

<Desc> : Description. This is an optional string that can be used

Duigou & Project JXTA Expires December 20, 2002 [Page 34]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

to describe and search for a spec.

<CRTR> : Creator. This optional element designates the creator of
this specification.

<SURI> : Spec URI. This optional element is a URI that permits to
retrieve a document containing the specification that this
advertises.

<Parm> : Arbitrary parameters to be interpreted by each
implementation.

<jxta:PipeAdvertisement> : Pipe advertisement. A pipe advertisement
which this module binds to an input pipe and which thus may be
used to establish a pipe to a nearby running implementation of
this specification. Note that the element name is identical to
the Pipe Advertisement document type since the entire element is
an embedded pipe advertisement document.

<Proxy> : Proxy Spec ID. Optional ModuleSpecID of a proxy module
that may be used in order to communicate with modules of this
specification. Note that the process may be recursive. The proxy
module may be usable via pipes, or through a subsequent proxy
module, and itself require a subsequent authenticator. However
publishers of modules should probably avoid such designs.

<Auth> : Authenticator Spec ID. Optional ModuleSpecID of an
authenticator module that may be required in order to communicate
with modules of this specification. Note that the process may be
recursive. The authenticator module may be usable via pipes, or
through a subsequent proxy module, and itself require a subsequent
authenticator. However publishers of modules should probably
avoid such designs.

3.3.7 Module Implementation Advertisement

A Module Implementation Advertisement describes one of the
implementations of a module specification. Implementations of a
given specification may be searched by the SpecID. An implementation
may be selected by the type of environment in which it can be used
(its compatibility statement) as well as by its name, description or
the content of its parameters section.

A Module Implementation Advertisement also provides a means to
retrieve all the necessary data required in order to execute the
implementation being described. This information is encapsulated in
the Code and PURI elements. The interpretation of these elements are

Duigou & Project JXTA Expires December 20, 2002 [Page 35]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

subject to the the module's compatibility. For example, the standard
peer group implementation of the Java reference implementation
expects the <Code> element to specify a fully qualified Java class
name that designates a subclass of "net.jxta.platform.Module" and
PURI to be the URI of a downloadable package (a .jar file). Other
execution environments could expect the code to be inline within the
<Code> element or even offer several options.

---------------------------------------------------------------------

<xs:element name="MIA" type="jxta:MIA"/>

<xs:complexType name="MIA">
<xs:sequence>
<xs:element name="MSID" type="jxta:JXTAID"/>
<xs:element name="Comp" type="xs:anyType"/>
<xs:element name="Code" type="xs:anyType"/>
<xs:element name="PURI" type="xs:anyURI" minOccurs="0"/>
<xs:element name="Prov" type="xs:string" minOccurs="0"/>
<xs:element name="Desc" type="xs:anyType" minOccurs="0"/>
<xs:element name="Parm" type="xs:anyType" minOccurs="0"/>
</xs:sequence>
</xs:complexType>

Figure 11: Module Implementation Advertisement Schema

---------------------------------------------------------------------

<MSID> : ModuleSpecID. This is a required element that uniquely
identifies the specification being implemented. The SpecID
representation is given in the Id Chapter.

<Comp> : Compatibility. A mandatory arbitrary element that
describes the environment in with this implementation may be
executed. Each framework capable of loading and executing module
has its own requirement on the contents of this element.

<Code> : This arbitrary element contains anything that is needed in
addition to the package in order to load and execute the code of
this implementation. In the case of a java implementation it
contains the fully qualified class name containing the module's
entry points. In other cases it may contain the entire code.

<PURI> : Package URI. This optional element is a URI that permits
to retrieve a package containing the code of this implementation.

<Prov> : Provider. The provider of that implementation.

Duigou & Project JXTA Expires December 20, 2002 [Page 36]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

<Desc> : Description. This is an optional string that can be used
to describe and search for a spec.

<Parm> : Parameter. Arbitrary parameters to be interpreted by the
implementation's code.

3.4 JXTA Core Protocols

3.4.1 Peer Resolver Protocol

3.4.1.1 Introduction

The Peer Resolver Protocol (PRP) permits the dissemination of generic
queries to one or multiple handlers within a peer group and identigy
matching responses. Each query is addressed to a specific handler
name. This handler name defines the particular semantics of the
query and its responses, but is not associated with any specific
peer. A given query MAY be received by any number of peers in the
peer group, possibly all, and processed according to the handler name
if such a handler name is defined on that peer.

The intent is for PRP to provide the essential generic query/response
infrastructure for building high-level resolver services. In many
situation, a higher level service may have a better knowledge of the
group topology.

The PRP uses the Rendezvous Service to disseminate a query to
multiple peers or unicast messages to send queries to specified
peers.

3.4.1.2 Resolver Query Message

The resolver query message is used to send a resolver query to the
named handler on one or more peers that are members of the peer
group. The resolver query is sent as a query string to a specific
handler. Each query has a unique Id. The query string can be any
string that will be interpreted by the targeted handler.

Duigou & Project JXTA Expires December 20, 2002 [Page 37]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

---------------------------------------------------------------------

<xs:element name="ResolverQuery" type="jxta:ResolverQuery"/>

<xs:complexType name="ResolverQuery">
<xs:all>
<xs:element ref="jxta:Cred" minOccurs="0"/>
<xs:element name="SrcPeerID" type="jxta:JXTAID"/>

<xs:element name="HandlerName" type="xs:string"/>
<xs:element name="QueryID" type="xs:string"/>
<xs:element name="Query" type="xs:anyType"/>
</xs:all>
</xs:complexType>

Figure 12: Resolver Query Schema

---------------------------------------------------------------------

<jxta:Cred> : The credential of the sender.

<HandlerName> : A string that specifies the destination of this
query.

<SrcPeerID> : The id of the peer originating the query (as a URN).

<QueryID> : An opaque indentifier to be used by the querier to match
replies. The <QueryID> SHOULD be included in the responses to
this query.

<Query> : Contains the query.

---------------------------------------------------------------------

<?xml version="1.0"?>

<!DOCTYPE jxta:ResolverQuery>

<jxta:ResolverQuery xmlns:jxta="http://jxta.org">
<HandlerName>
urn:jxta:uuid-DEADBEEFDEAFBABAFEEDBABE0000000305
</HandlerName>
<jxta:Cred>
JXTACRED
</jxta:Cred>
<QueryID>

Duigou & Project JXTA Expires December 20, 2002 [Page 38]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

0
</QueryID>
<SrcPeerID>
urn:jxta:uuid-59616261646162614A7874615032503304BD268FA4764960AB93A53D7F15044503
</SrcPeerID>
<Query>
&lt;?xml version="1.0"?>

&lt;!DOCTYPE jxta:DiscoveryQuery>

&lt;jxta:DiscoveryQuery xmlns:jxta="http://jxta.org">
&lt;Type>
0
&lt;/Type>
&lt;Threshold>
50
&lt;/Threshold>
&lt;PeerAdv>
&lt;?xml version="1.0"?>

&lt;!DOCTYPE jxta:PA>
... REMAINDER OMITTED FOR BREVITY ...
&lt;/jxta:PA>
&lt;/PeerAdv>
&lt;Attr>
&lt;/Attr>
&lt;Value>
&lt;/Value>
&lt;/jxta:DiscoveryQuery>
</Query>
</jxta:ResolverQuery>

Figure 13: Resolver Query

---------------------------------------------------------------------

3.4.1.3 Resolver Response Message

A resolver response message is used to send a response to a resolver
query message.

Duigou & Project JXTA Expires December 20, 2002 [Page 39]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

---------------------------------------------------------------------

<xs:element name="ResolverResponse" type="ResolverResponse"/>

<xs:complexType name="ResolverResponse">
<xs:all>
<xs:element ref="jxta:Cred" minOccurs="0"/>
<xs:element name="HandlerName" type="xs:string"/>
<xs:element name="QueryID" type="xs:string"/>
<xs:element name="Response" type="xs:anyType"/>
</xs:all>
</xs:complexType>

Figure 14: Resolver Response Schema

---------------------------------------------------------------------

<jxta:Cred> : The credential of the respondent.

<HandlerName> : Specifies how to handle the response.

<QueryID> : The query identifier of the query to which this is a
response.

<Response> : The responses.

---------------------------------------------------------------------

<?xml version="1.0"?>

<!DOCTYPE jxta:ResolverResponse>

<jxta:ResolverResponse xmlns:jxta="http://jxta.org">
<HandlerName>
urn:jxta:uuid-DEADBEEFDEAFBABAFEEDBABE0000000305
</HandlerName>
<jxta:Cred>
JXTACRED
</jxta:Cred>
<QueryID>
0
</QueryID>
<Response>
&lt;?xml version="1.0"?>

&lt;!DOCTYPE jxta:DiscoveryResponse>

Duigou & Project JXTA Expires December 20, 2002 [Page 40]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

&lt;jxta:DiscoveryResponse xmlns:jxta="http://jxta.org">
&lt;Count>
1
&lt;/Count>
&lt;Type>
2
&lt;/Type>
&lt;PeerAdv>
&amp;lt;?xml version="1.0"?>

&amp;lt;!DOCTYPE jxta:PA>

&amp;lt;jxta:PA xmlns:jxta="http://jxta.org">
... REMAINDER OMITTED FOR BREVITY ...
&amp;lt;/jxta:PA>
&lt;/PeerAdv>
&lt;Response Expiration="7200000">
&amp;lt;?xml version="1.0"?>

&amp;lt;!DOCTYPE jxta:PipeAdvertisement>

&amp;lt;jxta:PipeAdvertisement xmlns:jxta="http://jxta.org">
&amp;lt;Id>
urn:jxta:uuid-59616261646162614E50472050325033D1D1D1D1D1D1D1D1D1D1D1D1D1D1D1D104
&amp;lt;/Id>
&amp;lt;Type>
JxtaPropagate
&amp;lt;/Type>
&amp;lt;Name>
JxtaTalkUserName.IP2PGRP
&amp;lt;/Name>
&amp;lt;/jxta:PipeAdvertisement>
&lt;/Response>
&lt;/jxta:DiscoveryResponse>
</Response>
</jxta:ResolverResponse>

Figure 15: Resolver Response

---------------------------------------------------------------------

3.4.1.4 Listener and Element Naming

The PRP communicates by exchanging Endpoint Messages. Endpoint
Addresses specify a handler name. The PRP attaches a listener by
that name to the Endpoint Service. Endpoint Service (Section 3.5.1).

Duigou & Project JXTA Expires December 20, 2002 [Page 41]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

All PRP implementations MUST use the same scheme for building their
handler names. The convention used by all services of the world peer
group is to use the concatenation of the service name, the peer group
ID, and a value unique within the service.

---------------------------------------------------------------------

<JXTARSLVRQRYTAG> ::= "ORes"

<JXTARSLVRRSPTAG> ::= "IRes"

<JXTARSLVRNAM> ::= "jxta.service.resolver"

<JXTAIDVAL> ::= SEE

Figure 16: Listener Naming Syntax ABNF

---------------------------------------------------------------------

Thus, the listeners used by the PRP are currently named as follows:

o QUERIES: jxta.service.resolver[group unique Id string]ORes (ORES
is a literal string)

o RESPONSES: jxta.service.resolver[group unique Id string]IRes (IRES
is a literal string)

Query and response messages are included in messages as elements
named as follows:

o QUERIES: [group unique Id string]ORes (ORES is a literal string)

o RESPONSES: [group unique Id string]IRes (IRES is a literal string)

3.4.1.5 Behavior

3.4.1.5.1 Handler Name

The Handler Name in PRP messages plays a role similar to that of the
handler name in the Endpoint Message addresses: it is a
demultiplexing key that specifies how, by which higher-level
protocol, or by which module, the message is to be processed.

Duigou & Project JXTA Expires December 20, 2002 [Page 42]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

In the Java and "C" reference implementations, the users of the PRP
are typically services. Each instance of a given service (one per
peer per group that uses this service) generates a handler name that
is unique on its peer, but will be identical for the instances of
this service on other peers. This is by convention achieved by
concatenating the service name (which is unique in the group), the
group id, which is unique in the peer, and a additional parameter
which serves to discriminate between several handlers used by the
same service, if needed.

The handler name is used both to register the appropriate handler for
incoming queries or responses, and as a destination for outgoing
queries or responses. For convenience, most clients of the resolver
do define two names: one for propagated messages (mostly queries),
and one for unicast messages (mostly responses).

The PRP SHOULD refuse, and the existing reference implementations
SHALL refuse the registration of more than one handler with the same
name. A service SHOULD register for any handler name that it uses as
a destination, thereby preventing other services from registering
themselves to receive these messages. This means that in principle a
service or application that receives queries or responses from a
service instance on another peer is de-facto the local instance of
that service and SHOULD handle these messages as specified. PRP is
designed for same-to-same communication, not client-server.

3.4.1.5.2 Policies and Quality of Service

The PRP does not guarantee peers that define a query handler name
will receive that query, nor does it mandate that all peers that
define this handler name will receive it. Only a best effort is made
at disseminating the query in a way that maximizes the chance of
obtaining a response, if one can be obtained.

There is no guarantee that a response to a resolver query request
will be made. It is important to point that response to a
ResolverQuery request is OPTIONAL. A peer is not required to
respond.

The PRP does not assume the presence of reliable message delivery.
Multiple Resolver query messages may be sent--none, one, multiple or
redundant responses may be received.

The PRP provides a generic mechanism for services to send queries,
and receive responses. 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

Duigou & Project JXTA Expires December 20, 2002 [Page 43]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

verification of credentials and drops incorrect messages.

The actual task of propagating a query to the next set of peers is
delegated to the Rendezvous Protocol (Section 4.2.2). The Rendezvous
service is responsible for determining the set of peers that should
receive a message being propagated, but never automatically re-
propagates an incoming propagated message. It is left to the service
(query handler) handling the message to determine if further
propogation should be performed. The PRP's policy is the following:
if the query handler does not instruct the PRP to discard the query,
and if the local peer is a rendezvous, then the query is re-
propagated (within the limits of loop and TTL rules enforced by the
Rendezvous service). In addition, if instructed by the query
handler, an identical query may be issued with the local peer as the
originator.

3.4.2 Endpoint Routing Protocol

The JXTA network is ad hoc, multi-hop, and adaptive by nature.
Connections in the network may be transient, and message routing is
nondeterministic. Routes MAY be unidirectional and change rapidly.
Peers MAY join and leave frequently. A peer inside a firewall can
send a message directly to a peer outside a firewall. But a peer
outside the firewall cannot establish a connection directly with a
peer inside the firewall.

The Endpoint Routing Protocol defines a set of request/query messages
that are processed by a routing service to help a peer route messages
to their destination.

When a peer is asked to send a message to a given peer endpoint
address, it looks in its local cache to see if it has a route to this
peer. If it does not find a route, it sends a route resolver query
message to its available peer routers asking for routing information.
A peer can have as many peer routers as it can find or they can be
pre-configured. Pre-configured routers are OPTIONAL.

The peer routers provide the low-level infrastructure to route
messages between two peers in the network. Any number of peers in a
peergroup can elect themselves to become peer routers for other
peers. Peers routers offer the ability to cache route information,
as well as bridging different physical or logical networks. A peer
can dynamically find its router peer via a qualified discovery
search. A peer can find out if a peer it has discovered is a peer
router via the peer advertisement <Parms> element.

When a peer router receives a route query, if it knows a route to the
destination, it answers the query by returning the route information

Duigou & Project JXTA Expires December 20, 2002 [Page 44]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

as an enumeration of hops. Once a route has been discovered, a
message can be sent to the first router and that router will use the
route information to route the message to the destination peer. The
route is ordered from the next hop to the final destination peer. At
any point the routing information MAY become obsolete requiring the
current router to discover a new route in order to complete the
message delivery.

The peer endpoint adds extra routing information to the messages sent
by a peer. When a message goes through a peer, the endpoint of that
peers leaves its trace on the message. The trace can be used for
loop detection, and to discard recurrent messages. The trace is also
used to record new route information by peer routers.

ERP provides last resort routing for a peer. More intelligent
routing can be implemented by more sophisticated routing services in
place of the core routing service. High-level routing services can
manage and optimize routes more efficiently than the core service.
JXTA intends is to provide the hooks necessary for user defined
routing services to manipulate and update the route table information
(route advertisements) used by the peer router. The intent is to
have complex route analysis and discovery be performed above the core
by high-level routing services, and have those routing services
provide intelligent hints to the peer router to route messages.

The Endpoint Routing Protocol (ERP) is used to find the available
routes to send a message to a destination peer. This is accomplished
through message exchanges between peer routers. Peer routing may be
necessary to enable two peers to communicate depending on their
location in the network. For instance, the two peers may be on
different transports; the peers may be separated by a firewall; or
may be using incompatible private IP address spaces. When necessary
one or more peer routers can be used to deliver a message from the
originating peer endpoint to the destination peer endpoint.

3.4.2.1 Route information

Route information is represented as follow:

Duigou & Project JXTA Expires December 20, 2002 [Page 45]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

---------------------------------------------------------------------

<?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>

Figure 17: Endpoint Router

---------------------------------------------------------------------

The time-to-live parameter is measured in hops and specifies how long
this route is valid. The creator of the route can decide how long
this route will be valid. The gateways are defined as an ordered
sequence of peer IDs which define the route from the source peer to
the destination peer. The sequence may not be complete, but at least
the first gateway SHOULD be present. The first gateway is sufficient
to initially route the messages. The remaining gateway sequence is
OPTIONAL.

---------------------------------------------------------------------

TABLES NOT CURRENTLY CONVERTED.

Endpoint Route

---------------------------------------------------------------------

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.

3.4.2.2 Route Query Request

This message is sent by a peer to a peer router to request 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.

Duigou & Project JXTA Expires December 20, 2002 [Page 46]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

---------------------------------------------------------------------

<?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>

Figure 19: Endpoint Router Query

---------------------------------------------------------------------

TABLES NOT CURRENTLY CONVERTED.

Endpoint Router Query

---------------------------------------------------------------------

3.4.2.3 Route Answer Request

This message is sent by a router peer to a peer in response to a
route information request.

Duigou & Project JXTA Expires December 20, 2002 [Page 47]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

---------------------------------------------------------------------

<?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>

Figure 21: Endpoint Router Response

---------------------------------------------------------------------

TABLES NOT CURRENTLY CONVERTED.

Endpoint Router Answer

---------------------------------------------------------------------

3.5 Core JXTA Transport Bindings

3.5.1 Endpoint Service

3.5.1.1 Description

The Endpoint Service is responsible for performing end-to-end
messaging between two JXTA peers, using one of the underlying JXTA
transport protocols, such as the JXTA TCP or HTTP bindings.

The Endpoint Service is primarily used by other services or
applications that need to have an understanding of the network
topology, such as the Resolver Service or the Propagation Service.

The Endpoint Service is not responsible for routing messages for
peers that are not directly connected to each other. This task is

Duigou & Project JXTA Expires December 20, 2002 [Page 48]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

performed by the Endpoint Router Transport Protocol (Section 3.5.2)
which provides the illusion that the source and destination peers are
directly connected.

3.5.1.2 Protocol

When the Endpoint Service transmits a message it MAY add a single
element to the message: the source peer ID.

The element name is : "jxta:EndpointHeaderSrcPeer" and its value is a
textual UTF-8 representation of the peer ID at the point of emission
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.

3.5.1.3 Behaviour

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.

3.5.2 Endpoint Router Transport Protocol

3.5.2.1 Description

The Endpoint Router is a logical JXTA Transport Protocol that sits
below the Endpoint Service and beside the other Transport Protocols
such as the JXTA TCP and HTTP Transport Protocols.

The Endpoint Router is responsible for exchanging messages between

Duigou & Project JXTA Expires December 20, 2002 [Page 49]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

peers that do not have a direct connection between each other. The
Endpoint Router provides a virtual direct connection to the peer's
Endpoint Service.

3.5.2.2 Protocol

The Endpoint Router protocol defines a set of queries and responses
used to communicate with instances of the Endpoint Router on other
peers.

o Route Query: when the Endpoint Router is requested to send a
message to a peer for which it does not have yet a route for, it
sends a Route Query request to other peers. Peers that have an
route for the given peer answers with Route Response.

o Route Response: a peer that desires inform another peer about a
give route sends a Route Response to the peer. A Route Response
is replied following up a Route Query.

o Ping Query: a Ping Query is sent to a peer in order to validate a
route. The peer receiving a Ping Query is requested to answer
with a Ping Response.

o Ping Response: a Ping Response is sent back to the originator of a
Ping Query.

In addition, the Endpoint Router defines an informational message
that requires no reply.

o NACK: a NACK is sent by any peer that detects that a route used by
another peer is not valid. Typically, this happens by a router
peer that are requested to route a message to peer for which it
does not have a route itself. NACK messages are optional: routers
are not required to send them, and while a NACK is typically sent
to the source peer of the message, peers can send NACK to other
peers of their choice.

Those messages are sent and received by the EndpointRouter using the
JXTA Resolver Service.

The Endpoint Router Transport Protocol appends its own message
element to each message it transports. The name of the message
element is "JxtaEndpointRouter" and contains an XML document
containing the following:

o Mandatory:

Duigou & Project JXTA Expires December 20, 2002 [Page 50]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

* Source: the original EndpointAddress of the source of the
message.

* Destination: the original EndpointAddress of the destination of
the message.

* LastHop: The EndpointRouter EndpointAddress of the last router
that processed the incoming message to route.

* NbOfHop: the number of the peers the incoming message to route
has already been through.

o Optional:

* ForwardRoute: the ordered list of EndpointRouter
EndpointAddresses of the peers the message is supposed to go
through in order to reach its destination. This list is
optional since each router can use the QueryRoute request in
order to find a route. However, JXTA EndpointRouter
implementation are strongly encouraged to use it: it decreases
the network traffic, by limiting the use of queries, which can
be expensive.

* ReverseRoute: the ordered list of EndpointRouter
EndpointAddresses of the peers the message is supposed to go
through in order to reach its source. This list is optional
since each router can use the QueryRoute request in order to
find a route. However, JXTA EndpointRouter implementation are
strongly encouraged to use it: it decreases the network
traffic, by limiting the use of queries, which can be
expensive.

3.5.2.3 Wire Format

3.5.2.3.1 Queries And Responses

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:

Duigou & Project JXTA Expires December 20, 2002 [Page 51]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

---------------------------------------------------------------------

<!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 >

Figure 23: JXTA Endpoint Router DTD

---------------------------------------------------------------------

While this DTD does not define the contents of the elements, the
following defines what each element is expected to be:

---------------------------------------------------------------------

TABLES NOT CURRENTLY CONVERTED.

Router Query

---------------------------------------------------------------------

Beside Version and Type, depending on the query or the response, only
a subset of tags are used:

o RouteQuery: DestPeer is set to the peer id (in its EndpointRouter
definition) of the peer for which a route is requested.

o RouteResponse: DestPeer is set to the peer id (in its
EndpointRouter definition) of the peer for which a route was
requested.

o RoutingPeer is set to the EndpointAddress of the peer that knows
how to route message to the destination peer.

o RoutingPeerAdv can be optionally contain the Peer Advertisement of

Duigou & Project JXTA Expires December 20, 2002 [Page 52]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

the routing peer. This allow the requesting peer to not have to
search for the advertisement later on (optimization).

o NbOfHops: is set to the number of hops of the route starting at
the routing peer.

o GatewayForward: contains the Endpoint Address of a routing peer
within the route. The ordered list of GatewayForward defines the
entire route to be used starting at the routing peer in order to
reach the destination. Endpoint Routers are not required to fill
up this list, however, this is required if the endpoint router
desire to use the optimization of embedding the forward route
within the message. JXTA Endpoint Routers implementations are
strongly encouraged to fill up the Gateway Forward list.

o PingQuery: DestPeer is set to the peer id (in its EndpointRouter
definition) of the peer for which a ping is requested.

o PingResponse: DestPeer is set to the peer id (in its
EndpointRouter definition) of the peer for which a ping was
requested.

o NACK: DestPeer is set to the peer id (in its EndpointRouter
definition) of the peer for which the route has failed.

o GatewayForward: if the message for which the route has failed
contained a list of GatewayForward, this list is included into the
NACK message.

3.5.2.3.2 EndpointRouter Message Element

The Endpoint Router transport protocol includes a message element
named JxtaEndpointRouter. The format of the message element is an
XML document defined as follows:

Duigou & Project JXTA Expires December 20, 2002 [Page 53]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

---------------------------------------------------------------------

<!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 >

Figure 25: JXTA Endpoint Router Message DTD

---------------------------------------------------------------------

While this DTD does not define the nature of contents of the tag, the
following defines was is expected to be each tag:

---------------------------------------------------------------------

TABLES NOT CURRENTLY CONVERTED.

Router Element In Messages

---------------------------------------------------------------------

The meaning of these elements is as follows:

o jxta:Src contains the EndpointAdress of the original source of the
message

o jxta:Dest contains the EndpointAdress of the original destination
of the message

o jxta:Last contains the EndpointAdress of immediate previous peer
that has received the message

o jxta:NBOH contains the number of hops of the reverse route. 0 if
there is no reverse route.

o GatewayForward: contains the Endpoint Address of a routing peer
within the forward route. The ordered list of GatewayForward

Duigou & Project JXTA Expires December 20, 2002 [Page 54]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

defines the entire route to be used in order to reach the
destination peer of the message. Endpoint Routers are not
required to fill up this list, however, JXTA Endpoint Routers
implementations are strongly encouraged to fill up the Gateway
Forward list since it is an important optimization in order to
decrease latency of communication between peers.

o GatewayReverse: contains the Endpoint Address of a routing peer
within the reverse route. The ordered list of GatewayForward
defines the entire route to be used in order to reach the source
peer of the message. Endpoint Routers are not required to fill up
this list, however, JXTA Endpoint Routers implementations are
strongly encouraged to fill up the Gateway Forward list since it
is an important optimization in order to decrease latency of
communication between peers.

3.5.2.3.3 EndpointRouter Endpoint Address format

Since the EndpointRouter is a transport protocol, it has its own
Endpoint Address format, which is:

---------------------------------------------------------------------

jxta://uuid-<PeerID unique value>

Figure 27: JXTA Endpoint Router Address Format

---------------------------------------------------------------------

3.6 Messages

Messages are the basic unit of data exchange between peers. Pipes
send and receive messages to and from services; any protocol
implemented by a service will send and receive messages. Messages
are encoded using "wire" representations for transmission. Each JXTA
transport will use the message representations most appropriate for
its characteristics and the peers' preferences. See JXTA Message
Wire Representations (Section 4.4) for information about
representations.

3.6.1 Message

A message is a set of named and typed contents called elements. Thus
a message is essentially a set of name/value pairs. The content can
be an arbitrary type. Many core services send XML advertisements as

Duigou & Project JXTA Expires December 20, 2002 [Page 55]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

message element contents.

As a message passes down a protocol stack (applications, services,
endpoint and transports), each level may add one or more named
elements to the message. As a message is passed back up the stack on
the receiving peer, the protocol handlers SHOULD remove those
elements.

A message is an ordered sequence of message elements. The most
recently added element appears at the end of the message.

3.6.2 Element

A message element contains a namespace, an optional name, an optional
type, an optional signature or digest and content.

3.6.2.1 Namespace

Every element is assigned to a namespace. Namespaces are used to
organize elements used by different message users and transports
within the same message.

Two namespaces names are considered equivalent if their
representation in canonical UTF8 (NFC) (see Unicode Standard Annex
#15 : Unicode Normalization Forms [USA15 [5]]) is byte-for-byte
identical.

Two message element namespaces are pre-defined, """" (empty string)
and "jxta". The """" namespace is reserved for user applications and
services--none of the JXTA protocols or services will use or modify
elements in this namespace.

The "jxta" namespace is reserved for internal use by the JXTA
protocols and services. Applications SHOULD NOT create, manipulate
or assume the interpretation of any of the content of elements in the
"jxta" namespace. In some bindings, applications MAY be forbidden
from accessing or creating elements in the "jxta" namespace.

Use of namespaces by services and applications other than the ""
namespace is OPTIONAL. Namespaces require no formal registration as
the protocols used need only be agreed upon by the participants.

3.6.2.2 Name

Elements may have an optional name. Elements in the same message MAY
have the same name.

Duigou & Project JXTA Expires December 20, 2002 [Page 56]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

3.6.2.3 Type

A type is specified as a MIME type. See [bib-RFC2046 [1]]. MIME
types are UTF8 strings. The type is used by the applications and
services that process the element. There is no restriction on the
set of MIME types that can be used by applications and services. In
addition to the applications and services which use the particular
element, the type of the element may also be examined by the JXTA
transport to determine how to format the message element to ensure
the most effcient transfer.

If the type is not specified for an element "application/octet-
stream" is assumed.

3.6.2.4 Content

The contents of the Element data are opaque to except to the
applications and services which use these elements.

Duigou & Project JXTA Expires December 20, 2002 [Page 57]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

4. JXTA Standard Services

4.1 Introduction

The JXTA Core Specification (Section 3) defines the required
components and behaviours for all JXTA implementations. In order to
create a complete JXTA implementation there are some additional
components which all implementation SHOULD provide.

The JXTA Standard Services are OPTIONAL JXTA components and
behaviours. Implementations are not required to provide these
services, but are strongly RECOMMENDED to do so. Implementing these
services will provide greater interoperability with other
implementations and broader functionality.

4.2 Standard Protocols

4.2.1 Peer Discovery Protocol

4.2.1.1 Introduction

The Peer Discovery Protocol is used to discover any published peer
resource. Resources are represented as advertisements. A resource
can be a peer, a peergroup, a pipe, a module, or any resource that
has an advertisement. Each resource MUST be represented by an
advertisement.

The Peer Discovery Protocol (PDP) enables a peer to find
advertisements in its group. The PDP protocol is the discovery
protocol of the world peergroup. Custom discovery services MAY
choose to leverage PDP. If a peer group does not need to define its
own discovery protocol, it may use the world peergroup PDP.

The intent is for PDP to provide the essential discovery
infrastructure for building and bootstrapping high-level discovery
services. In many situation, discovery information is better known
by a high-level service, because the service may have a better
knowledge of the group topology.

The PDP protocol provides a basic mechanism to discover
advertisements while providing hooks so high-level services and
applications can participate in the discovery process. Services
SHOULD be able to give hints to improve discovery (i.e. decide which
advertisements are the most valuable to cache).

The PDP protocol utilizes the resolver protocol to route queries and
responses.

Duigou & Project JXTA Expires December 20, 2002 [Page 58]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

4.2.1.2 Discovery Query Message

The discovery query message is used by peers to send discovery
requests when searching for advertisements.

---------------------------------------------------------------------

<xs:element name="DiscoveryQuery" type="jxta:DiscoveryQuery"/>

<xsd:simpleType name="DiscoveryQueryType">
<xsd:restriction base="xsd:string">

<xsd:enumeration value="0"/>

<xsd:enumeration value="1"/>

<xsd:enumeration value="2"/>
</xsd:restriction>
</xsd:simpleType>

<xs:complexType name="DiscoveryQuery">
<xs:sequence>
<xs:element name="Type" type="jxta:DiscoveryQueryType"/>
<xs:element name="Threshold" type="xs:unsignedInt" minOccurs="0"/>
<xs:element name="Attr" type="xs:string" minOccurs="0"/>
<xs:element name="Value" type="xs:string" minOccurs="0"/>

<xs:element name="PeerAdv" type="xs:string" minOccurs="0"/>
</xs:sequence>
</xs:complexType>

Figure 28: Discovery Query Schema

---------------------------------------------------------------------

<Type> : Only advertisements of requested type will be matched.
Possible values are:

&#10; "0"&#10; : Peer Advertisements

&#10; "1"&#10; : Peergroup Advertisements

&#10; "2"&#10; : Any Advertisements

<Threshold> : specifies the maximum number of advertisements that

Duigou & Project JXTA Expires December 20, 2002 [Page 59]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

each responding peer SHOULD provide. The total number of results
received depends on the number of peers that respond and the
advertisements they have. If <Type> is "0" (Peer Advertisements)
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, e ven though no
results are to be included.

<PeerAdv> : If present, the advertisement of the requestor.

<Attribute>, <Value> : Must either be both present or absent. If
absent, then each respondent should supply a random set of
advertisements of the appropriate type up to <Threshold> count.

Only advertisements containing an element who's name matches
<Attribute> and that also contains a value matching <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 choose not match any advertisement for <Value> "*".

Duigou & Project JXTA Expires December 20, 2002 [Page 60]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

---------------------------------------------------------------------

<?xml version="1.0" encoding="UTF-8"?>

<jxta:DiscoveryQuery>
<Type>2</Type>
<Threshold>1</Threshold>
<Attr>Name</Attr>
<Value>*sidus*</Value>
<PeerAdv>
&lt;?xml version="1.0"?>

&lt;!DOCTYPE jxta:PA>

&lt;jxta:PA xmlns:jxta="http://jxta.org">
&lt;PID>
urn:jxta:uuid-59616261646162614A7874615032503304BD268FA4764960AB93A53D7F15044503
&lt;/PID>
... REMAINDER OMITTED FOR BREVITY ...
&lt;/jxta:PA>
</PeerAdv>
</jxta:DiscoveryQuery>

Figure 29: Discovery Query

---------------------------------------------------------------------

4.2.1.3 Discovery Response Message

A Discovery response message is used by a peer to respond to a
discovery query message.

Duigou & Project JXTA Expires December 20, 2002 [Page 61]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

---------------------------------------------------------------------

<xs:element name="DiscoveryResponse" type="jxta:DiscoveryResponse"/>

<xs:complexType name="DiscoveryResponse">
<xs:sequence>
<xs:element name="Type" type="jxta:DiscoveryQueryType"/>
<xs:element name="Count" type="xs:unsignedInt" minOccurs="0"/>
<xs:element name="Attr" type="xs:string" minOccurs="0"/>
<xs:element name="Value" type="xs:string" minOccurs="0"/>

<xs:element name="PeerAdv" minOccurs="0">
<xs:complexType>
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute name="Expiration" type="xs:unsignedLong"/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
<xs:element name="Response" maxOccurs="unbounded">
<xs:complexType>
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute name="Expiration" type="xs:unsignedLong"/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>

Figure 30: Discovery Response Schema

---------------------------------------------------------------------

<Type> : The type of all the advertisements returned in the
<Response> element(s).

<Count> : If present, the number of <Response> element(s) included
in this response.

<PeerAdv> : If present, the advertisement of the respondent. The
"Expiration" attribute is the associated relative expiration time
in milliseconds.

<Attribute>, <Value> : If present, reflects that of the

Duigou & Project JXTA Expires December 20, 2002 [Page 62]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

DiscoveryQuery to which this is the response.

<Response> : An advertisement.The "Expiration" attribute is the
associated relative expiration time in milliseconds.

---------------------------------------------------------------------

<?xml version="1.0" encoding="UTF-8"?>

<jxta:DiscoveryResponse>
<Type>2</Type>
<Count>1</Count>
<Attr>Name</Attr>
<Value>*sidus*</Value>
<PeerAdv>
&lt;?xml version="1.0"?>

&lt;!DOCTYPE jxta:PA>

&lt;jxta:PA xmlns:jxta="http://jxta.org">
&lt;PID>
urn:jxta:uuid-59616261646162614A7874615032503304BD268FA4764960AB93A53D7F15044503
&lt;/PID>
... OMITTED ...
&lt;/jxta:PA>
</PeerAdv>
<Response Expiration="36000000">
&lt;?xml version="1.0"?>

&lt;!DOCTYPE jxta:PipeAdvertisement>

&lt;jxta:PipeAdvertisement xmlns:jxta="http://jxta.org">
&lt;Id>
urn:jxta:uuid-094AB61B99C14AB694D5BFD56C66E512FF7980EA1E6F4C238A26BB362B34D1F104
&lt;/Id>
&lt;Type>
JxtaUnicastSecure
&lt;/Type>
&lt;Name>
JxtaTalkUserName.sidus
&lt;/Name>
&lt;/jxta:PipeAdvertisement>
</Response>
</jxta:DiscoveryResponse>

Figure 31: Discovery Response

Duigou & Project JXTA Expires December 20, 2002 [Page 63]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

---------------------------------------------------------------------

4.2.1.4 Behaviour

4.2.1.4.1 Policies and Quality of Service

The PDP does not guarantee peers that receive a query will respond to
the query, nor does it mandate that the number of advertisements
requested will be honored. Only a best effort is made at matching
the query to results in the respondant's cache.

There is no guarantee that a response to a discovery query request
will be made. It is important to point out that responding to a
DiscoveryQuery request is OPTIONAL. A peer is not required to
respond to a DiscoveryQuery request.

A reliable transport is OPTIONAL with the PDP. Multiple Discovery
query messages may be sent. None, one, multiple or redundant
responses may be received.

A peer may receive a DiscoveryResponse that is not a response to any
DiscoveryQuery initiated by the peer, this mechanism provides the
ability to remote publish a resource.

The PDP provides a mechanism for services to query the network for
JXTA resources, and receive responses. As a service, the reference
implementation helps other services by taking care of all messaging
aspects, caching, and expiring advertisements.

The actual task of propagating, and re-propagating a query to the
next set of peers is delegated to the Resolver Service.

4.2.2 Rendezvous Protocol

4.2.2.1 Introduction

The Rendezvous Protocol (RVP) is responsible for propagating messages
within a JXTA Peergroup. While different Peergroups may have
different means to propagate messages, the Rendezvous Protocol
defines a simple protocol that allows:

o Enables peers to connect to services (propagates messages to other
peers and receive propagated messages from other peers)

o Control the propagation of the message (TTL, loopback detection,
etc.).

Duigou & Project JXTA Expires December 20, 2002 [Page 64]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

4.2.2.2 Rendezvous Advertisement

A Rendezvous advertisement describes a peer that acts as a rendezvous
peer for a given PeerGroup. Those advertisements can be published
and retrieved, so peers that are looking for rendezvous peers can
find them.

---------------------------------------------------------------------

<xs:element name="RdvAdvertisement" type="jxta:RdvAdvertisement"/>

<xs:complexType name="RdvAdvertisement">
<xs:sequence>
<xs:element name="Name" type="xs:string" minOccurs="0"/>
<xs:element name="RdvGroupId" type="jxta:JXTAID"/>
<xs:element name="RdvPeerId" type="jxta:JXTAID"/>
</xs:sequence>
</xs:complexType>

Figure 32: Rendezvous Advertisement Schema

---------------------------------------------------------------------

<Name> : This is an optional name that can be associated with the
rendezvous peer. Often the same as the peer name.

<RdvGroupId> : This is a required element that contains the JxtaID
of the PeerGroup for which the peer is a rendezvous.

<RdvPeerId> : This is a required element that contains the JxtaID of
the peer which is a rendezvous.

4.2.2.3 Behaviour

4.2.2.3.1 Peer connection

RVP introduces the notion of special peers, called Rendezvous peers,
which can be used to re-propagate messages they have received. A
peer can become dynamically a rendezvous peer and/or can dynamically
connect to a rendezvous peer. The connection between a peer to a
rendezvous peer is achieved by an explicit connection, associated to
a lease.

This connection is performed by sending messages using the JXTA
Endpoint Protocol. Each RVP is listening on an EndpointAddress with
the following Service Name and Service Param:

Duigou & Project JXTA Expires December 20, 2002 [Page 65]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

o service name: JxtaPropagate

o service param: PeerGroup ID

A set of queries and responses are defined by the Rendezvous Protocol
in order to establish connections:

o LEASEREQUEST This request is sent by a peer that desire to connect
to a given rendezvous. No indication of the amount of the lease:
the rendezvous will give whatever it feels is appropriate. A
lease can always be canceled by both parties at anytime if
necessary. A rendezvous that grants a lease returns LeaseGranted.

o LEASEGRANTED This message is sent by a rendezvous that is granted
a lease to a given client. The amount of time the lease is
granted for is included in the message.

o LEASECANCELREQUEST This message is sent by a client to its
rendezvous in order to cancel an existing lease. The rendezvous
is expected to reply with LeaseCancelled.

NOTE: the Peer Resolver protocol is not used to send those message:
the Rendezvous Protocol sits directly on top of the Endpoint Routing
Protocol (Section 3.4.2). The reason of this is layering: the Peer
Resolver Protocol itself sit on top of the Rendezvous Protocol.

4.2.2.3.2 Propagation control

The Rendezvous Protocol is responsible for controlling the
propagation of messages. The Rendezvous Protocol will propagate a
message unless of the following conditions is detected:

o Loop: if a propagated messages has already been processed on a
peer, it is discarded.

o TTL: propagated messages are associated with a Time To Live (TTL).
Each time a propagated message is received on a peer, its TTL is
decreased by one. When the TTL of a message drops to zero, the
message is discarded.

o Duplicate: each propagated message is associated with a unique
identifier. When a propagated message has been duplicated, and
has already been received on a peer, duplicates are discarded.

This control is performed by embedding a Message Element within each
propagated message that is defined as:

Duigou & Project JXTA Expires December 20, 2002 [Page 66]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

---------------------------------------------------------------------

<xs:element name="RendezVousPropagateMessage" type="jxta:RendezVousPropagateMessage"/>

<xs:complexType name="RendezVousPropagateMessage">
<xs:element name="MessageId" type="xs:string"/>

<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>

Figure 33: RendezVous Propagate Message Schema

---------------------------------------------------------------------

4.2.2.3.3 Lease Request Message

When a peer wants to connect to a Rendezvous Peer, it sends a message
with the a message element named jxta:Connect which contains its Peer
advertisement.

4.2.2.3.4 Lease Granted Message

When a rendezvous peer grants a lease (upon a lease request), it
sends a message to the source of the lease request, containing the
following message elements:

jxta:ConnectedLease : This message element contains (in a String
representation) the time in milliseconds the lease is granted for.
This message element is mandatory.

jxta:ConnectedPeer : This message element contains the PeerID of the
rendezvous peer that has granted the lease. This message element
is mandatory.

jxta:RdvAdvReply : This message element contains the Peer
Advertisement of the rendezvous peer that grants the lease. This
message element is optional.

4.2.2.3.5 Lease Cancel Message

When a peer wants to cancel a lease, it sends a message with the
following message element:

Duigou & Project JXTA Expires December 20, 2002 [Page 67]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

o "jxta:Disconnect": This message element contains the Peer
Advertisement of the peer which is requesting to cancel the lease.
This message element is mandatory.

4.2.3 Peer Information Protocol

Once a peer is located, its capabilities and status may be queried.
PIP provides a set of messages to obtain a peer status information.
PIP is an OPTIONAL JXTA protocol. Peers are not required to respond
to PIP requests.

A reliable transport is OPTIONAL for PIP. Multiple peer information
messages may be sent. None, one or multiple responses MAY be
received in response to any query.

The PIP is layered upon the Peer Resolver Protocol (Section 3.4.1).
The <QueryID> element is used to match PIP queries containing
<request> elements to the PIP Response Messages containing the
matching responses.

4.2.3.1 Obtaining PIP Responses

The PIP Query Message provides a REQUEST field that MAY be used to
encode a specific request. PIP does not dictate the format of the
REQUEST field and it is left up to the consumer to do so. Higher-
level services MAY utilize the request field to offer expanded
capabilities.

4.2.3.2 PIP Query Message

The query message is sent to a peer to query the current state of the
peer, and obtain other relevant information about the peer. A query
without a defined request field returns a default set of information
about a peer (i.e. uptime, message count, etc.).

Duigou & Project JXTA Expires December 20, 2002 [Page 68]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

---------------------------------------------------------------------

<xs:element name="PeerInfoQueryMessage" type="jxta:PeerInfoQueryMessage"/>

<xs:complexType name="PeerInfoQueryMessage">
<xs:sequence>
<xs:element name="sourcePid" type="jxta:JXTAID"/>
<xs:element name="targetPid" type="jxta:JXTAID"/>

<xs:element name="request" type="xs:anyType" minOccurs="0"/>
</xs:sequence>
</xs:complexType>

Figure 34: PIP Query Message

---------------------------------------------------------------------

<sourcePid> : The peer id of the requesting peer.

<targetPid> : The peer id of the peer being queried.

<request> : An optional Request structure.

4.2.3.3 PIP Response Message

The Peer Information Protocol Response Message provides specific
information about the current state of a peer, such as uptime,
inbound and outbound message count, time last message received, and
time last message sent.

---------------------------------------------------------------------

<xs:element name="PeerInfoResponse" type="jxta:PeerInfoResponse"/>

<xs:complexType name="PeerInfoResponseMessage">
<xs:sequence>
<xs:element name="sourcePid" type="jxta:JXTAID"/>
<xs:element name="targetPid" type="jxta:JXTAID"/>
<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:sequence>
</xs:complexType>

Duigou & Project JXTA Expires December 20, 2002 [Page 69]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

<xs:complexType name="piptraffic">
<xs:sequence>
<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:sequence>
</xs:complexType>

<xs:complexType name="piptrafficinfo">
<xs:sequence>
<xs:element name="transport" maxOccurs="unbounded">
<xs:complexType>
<xs:simpleContent>
<xs:extension base="xs:unsignedLong">
<xs:attribute name="Expiration" type="xs:anyURI"/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>

Figure 35: PIP Response Message

---------------------------------------------------------------------

<sourcePid> : The peer id of the requesting peer.

<targetPid> : The peer id of the peer being queried.

<uptime> : The relative time in milliseconds since the responding
Peer Information Service began execution. Peers SHOULD provide
this tag in all responses, but MAY chose to not implement it if
the information is unavailable or would represent a security
breach.

<timestamp> : The absolute time at which this response was
generated. Measured in milliseconds since "the epoch", namely
January 1, 1970, 00:00:00 GMT. Peers SHOULD provide this tag in
all responses, but MAY chose to not implement it if the
information is unavailable or would represent a security breach.

Duigou & Project JXTA Expires December 20, 2002 [Page 70]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

<response> : Potentially contains a response to a previous request
from a PIP Query. To match queries to responses the QUERYID
element of the Peer Resolver Protocol (Section 3.4.1) MUST match.
This field can contain any desired content.

<traffic> : Contains information about the network traffic performed
by the target peer. This element is OPTIONAL.

<lastIncomingMessageAt> : The absolute time at which this peer
last received a valid JXTA message on one of its transports.
Measured in milliseconds since "the epoch", namely January 1,
1970, 00:00:00 GMT. Peers SHOULD provide this tag in all
responses, but MAY chose to not implement it if the information
is unavailable or would represent a security breach.

<lastOutgoingMessageAt> : The absolute time at which this peer
last sent a valid JXTA message on one of its transports.
Measured in milliseconds since "the epoch", namely January 1,
1970, 00:00:00 GMT. Peers SHOULD provide this tag in all
responses, but MAY chose to not implement it if the information
is unavailable or would represent a security breach.

<in> : If present, contains elements which describe incoming
traffic from various endpoint addresses.

<transport> : Provides the number of bytes received by the
named endpoint address.

<out> : If present, contains elements which describe outgoing
traffic from various endpoint addresses.

<transport> : Provides the number of bytes transmitted by the
named endpoint address.

4.2.4 Pipe Binding Protocol

The Pipe Binding Protocol (PBP) is used by applications and services
in order to communicate with other peers. A pipe is a virtual
channel between two endpoints described in a Pipe Advertisement.
There are two ends of a Pipe: the Input Pipe (receiving end) and the
Output Pipe (sending end).

Duigou & Project JXTA Expires December 20, 2002 [Page 71]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

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:

o JXTAUNICAST Unicast, unsecure and unreliable. This type of pipe
is used to send one-to-one messages.

o JXTAUNICASTSECURE Unicast, secure (using TLS). This pipe is
equivalent to the UnicastType pipe, except that the data is
protected using a virtual TLS connection between the endpoints.

o JXTAPROPAGATE Diffusion pipes. This pipe type is used to send
one-to-many messages. Any peer that has enabled an Input Pipe on
a Propagate type pipe receives messages that are sent onto it.

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.

4.2.4.1 Pipe Advertisement

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 MAY include an optional symbolic name.

Each pipe advertisement MUST include a pipe type. The following
types are currently defined: unicast, propagate, unicast-secure.

Duigou & Project JXTA Expires December 20, 2002 [Page 72]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

---------------------------------------------------------------------

<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>

Figure 36: Pipe Advertisement Schema

---------------------------------------------------------------------

<Name> : This is an optional name that can be associated with a
pipe. The name is not required to be unique unless the name is
obtained from a centralized naming service that guarantee name
uniqueness.

<Id> : This is a required element that uniquely identifies the pipe.
Each pipe has a unique id. The pipe id representation is given in
the Id Chapter.

<Type> : This is an required element that defines the type of the
pipe. The following types are currently defined:

&#10; "JxtaUnicast"&#10; : may not arrive at the
destination, may be delivered more than once to the same
destination, may arrive in different order.

&#10; "JxtaUnicastSecure"&#10; : may not arrive at
the destination, may be delivered more than once to the same
destination, may arrive in different order, but is encrypted
using TLS.

&#10; "JxtaPropagate"&#10; : one to many pipe.

Duigou & Project JXTA Expires December 20, 2002 [Page 73]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

---------------------------------------------------------------------

<?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>

Figure 37: Pipe Advertisement

---------------------------------------------------------------------

4.2.4.2 Pipe Resolver Message

This message is used by the Pipe Resolver to find an Input Pipe
endpoint bound to the same pipe advertisement. The same message
schema is used for both the resolve query and for the response.

Duigou & Project JXTA Expires December 20, 2002 [Page 74]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

---------------------------------------------------------------------

<xs:element name="PipeResolver" type="jxta:PipeResolver"/>

<xs:complexType name="PipeResolver">

<xs:element name="MsgType" type="xs:string"/>
<xs:element name="PipeId" type="JXTAID"/>
<xs:element name="Type" type="xs:string"/>
<xs:element name="Peer" type="JXTAID" minOccurs="0"/>

<xs:element name="Cached" type="xs:boolean" default="false" minOccurs="0"/>

<xs:element name="Found" type="xs:boolean" minOccurs="0"/>

<xs:element name="PeerAdv" type="xs:string" minOccurs="0"/>
</xs:complexType>

Figure 38: Pipe Resolver Message Schema

---------------------------------------------------------------------

<MsgType> : Used to indicate if it is the Query or the Answer. May
be one of:

&#10; "Query"&#10; : This is a query.

&#10; "Answer"&#10; : This is a response.

<PipeId> : The Pipe ID which is being resolved.

<Type> : The type of pipe resolution being requested. This value
MUST match the value of <Type> from the Pipe Advertisement.

<Cached> : False if the answer MUST NOT come from the cache. The
requestor may ask that the information was not obtained from the
cache. This is to obtain the most up-to-date information from a
peer to address stale connection.

<Peer> : A peer id. In Queries, if present it specifies the Peer ID
of the only peer from which responses will be expected. Responses
from all other peers will be ignored. This does not guarantee a
response to the pipe binding request will be made by the peer.

Duigou & Project JXTA Expires December 20, 2002 [Page 75]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

Response to pipe binding requests is always OPTIONAL.

In Answer messages, all of the peers on which the Input Pipe is
known to be bound.

<Found> : Used to indicate if the Input Pipe was found on the
specified peer.

<PeerAdv> : Peer Advertisement of the peer which resolved the Input
Pipe. This peer MAY appear in the list of peer ids on which the
Input Pipe is bound, but this should not be assumed.

4.3 Standard JXTA Transport Bindings

JXTA defines several Transport Bindings for implementing JXTA on top
of existing networks.

4.3.1 TCP/IP Transport

This section describes the TCP/IP Transport Binding. This binding is
the most frequently used Transport Binding. It is designed to be the
most efficient. Unfortunately it can be adversely affected by the
partitioning of the Internet Address Space caused by Network Address
Translation, Firewalls, and conflicting use of Private IP Address
ranges.

4.3.1.1 TCP/IP Wire Format

This section defines the TCP/IP message wire format. Each TCP/IP
message is composed of a header and a body.

o Header

o Body

4.3.1.1.1 Header

The format of the header is:

Duigou & Project JXTA Expires December 20, 2002 [Page 76]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

---------------------------------------------------------------------

TABLES NOT CURRENTLY CONVERTED.

Figure 39: JXTA TCP/IP Binding Header

---------------------------------------------------------------------

The header fields are as follows:

Type: 1 byte. The byte info is used to either unicast or multicast
the request.

o 1 = this is a propagate message.

o 2 = this is a unicast message.

o 3 = This for ACK //unused

o 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.

o HANDCHECK = 1 not implemented yet (bi-directional)

o NONBLOCKING = 2 (unidirectional transfer)

Unused: 8 bytes

4.3.1.1.2 Body

The body of transmissions is a Messages (Section 3.6) and presented
as JXTA Message Wire Representations (Section 4.4).

Duigou & Project JXTA Expires December 20, 2002 [Page 77]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

4.3.1.2 Connection States

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.

4.3.1.3 Optional Optimizations

4.3.1.3.1 Keep Alive Optimization

If a receiving end decides to keep the connection active (socket
"keep alive"), it can return the value 1 (byte) to the sender to tell
the sending end that it is keeping the connection alive. The sending
end can reuse the same socket to send a new packet.

4.3.2 HTTP Transport

The HTTP transport is logically divided into two functions: the HTTP
"Message Receiver" and the HTTP "Message Relay". The Message
Receiver simply accepts JXTA messages over HTTP, while the Message
Relay implements a protocol that allows peers to connect to it for
message relay capabilities.

4.3.2.1 Message Receiver

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.

4.3.2.1.1 Send JXTA Message

4.3.2.1.1.1 Request

The HTTP request must adhere to the following rules:

o The request method must be POST

o The Content-Length must be specified

o The Content-Type must be "application/x-jxta-msg"

o The request body must a binary JXTA message

o No Transfer-Encoding may be specified

Duigou & Project JXTA Expires December 20, 2002 [Page 78]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

4.3.2.1.1.2 Response

If the request and the JXTA message was well-formed, 200 is returned.
Otherwise, an error code (4xx) will be returned. No other result
codes are permitted.

4.3.2.1.2 Ping

4.3.2.1.2.1 Request

The HTTP request must adhere to the following rules:

o The request method must be GET

o The request URI must be '/ping'

4.3.2.1.2.2 Response

The response must be 200 if the ping request was received. Another
appropriate HTTP response may be returned if the node is not
accepting messages.

4.3.2.2 Message Relay

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:

o obtainLease: Client requests a new lease with the relay server.

o renewLease: Client requests to renew an existing lease with the
relay server.

o block: Client requests to stay connected while waiting for a
message on the relay server.

o poll: Client requests to receive a queued message.

4.3.2.2.1 obtainLease

The obtainLease command instructs the relay server to issue a new
lease for a peer.

Duigou & Project JXTA Expires December 20, 2002 [Page 79]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

4.3.2.2.1.1 Request

The following querystring variables that must be set by the client
are as follows:

o command: Must be equal to 'obtainLease'

o peerId: The Peer ID of the client.

4.3.2.2.1.2 Response

The following querystring variables must be included by the relay
server in the response:

o 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.

---------------------------------------------------------------------

command=obtainLease&peerId=foobar

Figure 40: HTTP POST Request Body for "obtainLease" Command

---------------------------------------------------------------------

leaseId=1234

Figure 41: HTTP POST Request Body for "obtainLease" Command

---------------------------------------------------------------------

4.3.2.2.2 renewLease

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.

4.3.2.2.2.1 Request

The following querystring variables that must be set by the client

Duigou & Project JXTA Expires December 20, 2002 [Page 80]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

are as follows:

o leaseId: Must be set to the leaseId of the existing lease.

4.3.2.2.2.2 Response

The following querystring variables must be included by the relay
server in the response:

o 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.

---------------------------------------------------------------------

command=renewLease&leaseId=1234

Figure 42: HTTP POST Request Body for "renewLease" Command

---------------------------------------------------------------------

leaseId=5678

Figure 43: HTTP POST Request Body for "renewLease" Command

---------------------------------------------------------------------

4.3.2.2.3 block

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.

4.3.2.2.3.1 Request

The following querystring variables that must be set by the client
are as follows:

o leaseId: Must be set to the leaseId of the lease.

Duigou & Project JXTA Expires December 20, 2002 [Page 81]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

4.3.2.2.3.2 Response

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.

---------------------------------------------------------------------

command=block&leaseId=1234

Figure 44: HTTP POST Request Body for "Block" Command

---------------------------------------------------------------------

4.3.2.2.4 poll

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.

4.3.2.2.4.1 Request

The following querystring variables that must be set by the client
are as follows:

o leaseId: Must be set to the leaseId of the lease.

4.3.2.2.4.2 Response

If the leaseId is not valid (e.g. the lease is expired), the
response must be 400.

Duigou & Project JXTA Expires December 20, 2002 [Page 82]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

---------------------------------------------------------------------

command=poll&leaseId=1234

Figure 45: HTTP POST Request Body for "Poll" Command

---------------------------------------------------------------------

4.3.3 TLS Transport Binding

JXTA implements Transport Layer Security Version 1 (RFC 2246) on top
of a virtual connection protocol using JXTA messages transmitted
across one of the other Transport Bindings. This implementation
provides for secure message delivery between Endpoints even when
multiple hops across JXTA peers must be used.

This description of the TLS Transport Binding has yet to be written.

4.4 JXTA Message Wire Representations

There are two standard representations for JXTA Messages, XML and
binary. Each JXTA transport will use the representations most
appropriate.

4.4.1 Binary Message Format

Transports, such as TCP, which require a compact representation for a
message will use the binary format. This format is designed such
that all components are of declared size, no parsing is ever required
to determine lengths.

---------------------------------------------------------------------

msg ::= "jxmg"

version ; One byte. Currently binary "0".

namespaces

element_count ; two bytes (binary)

1* elm

namespaces ::= namespace_count ; two bytes (binary)

Duigou & Project JXTA Expires December 20, 2002 [Page 83]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

0* namespace ; Each namespace is a string

namespace ::= string

string ::= len2 ; two bytes (binary)

len2 * UTF8 chars ; characters

elm ::= "jxel" ; signature

namespaceid ; one byte (binary)

flags ; Indicates which parts follow (binary)

name ; element name

[type] ; Present if (flags & HAS_TYPE)

len4 ; Four byte binary length of content

content ;

[signature] ; associated signature element
; Present if (flags & HAS_SIGNATURE)
type ::= string

content ::= len4 * byte ; the bytes of the content.

signature ::= elm

flags ::= byte ; HAS_TYPE = 0x01;
; HAS_ENCODING = 0x02;
; HAS_SIGNATURE = 0x04;

Figure 46: JXTA Binary Message ABNF

---------------------------------------------------------------------

4.4.1.1 Conventions

Multi-byte lengths are sent with the high order byte first (also
known as "Big Endian" or "Network Byte Order"). All strings start
with a two byte length, followed by a UTF-8 string value. The
message format is specified using ABNF [bib-RFC2234 [4]]. ABNF is
normally used for ASCII grammars, but here we use it to define a byte
sequence for a binary message.

Duigou & Project JXTA Expires December 20, 2002 [Page 84]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

4.4.1.2 Message

Each message starts with the four byte UTF8 signature "jxmg". The
signature is used to aid in sanity checking a transport
implementation. This is followed by a one byte version number. At
present, the version number must be zero. Next is a list of
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.

4.4.1.3 Namespaces

Each message element name is part of a namespace. The namespaces of
all elements are placed into a list at the start of the message.
This is an ordered list. Each entry in the list is assigned an id.
The first entry in the list is assigned an id of 2. The id of each
successive id is one plus the id of the preceding namespace id. The
ids 0, and 1 are preassigned. 0 represents the empty namespace. 1
is the "jxta" namespace.

The namespaces part of a binary message starts with a two byte
namespace count. The count is followed by a sequence of namespace
names. It is permissible for this sequence to be empty.

4.4.1.4 Element

Each message starts with the four byte UTF8 signature "jxel". The
signature is used to aid in sanity checking a transport
implementation. Next is the namespace id byte. This byte indicates
which name space this element belongs to. The next byte is the flags
byte. Bits in this flag byte indicate which of the optional
components of an element are present. "HAS_ENCODING" is currently
unsupported.

The flags are followed by the simple name. The element name can be
reconstructed from the simple name and the namespace id as described
above. The mime type, if present follows next. If the type is not
specified for an element "application/octet-stream" is assumed. Last
but not least is the four byte length of the content, followed by the
content itself.

4.4.2 XML Message Format

The XML message format is used for transports which can transmit text
but not raw binary data. An effort is made to keep the message
elements as readable as possible. See the section on encoding.

Duigou & Project JXTA Expires December 20, 2002 [Page 85]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

4.4.2.1 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>

Figure 47: XML Message

---------------------------------------------------------------------

The top level XML element is the Message element. There is one
required attribute, version. The value of version must be zero "0".
The body of the Message element is a sequence of Element elements.

4.4.2.2 Element

Each Element must have a name and mime_type attribute. Optionally an
encoding attribute may be present.

4.4.2.2.1 Name

This a required attribute names the element. The name contains the
namespace, followed by a colon, followed by the simple name of the
element.

4.4.2.2.2 MIME type

A required attribute indicating the MIME type of the element. If the
MIME type was not specified in the message, a type of "application/
octet-stream" is used.

Duigou & Project JXTA Expires December 20, 2002 [Page 86]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

4.4.2.2.3 Encoding

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.

4.4.2.2.4 Content

The content data must not interfere with the syntax of the XML. To
prevent this, the content is escaped.

---------------------------------------------------------------------

TABLES NOT CURRENTLY CONVERTED.

Character mapping

---------------------------------------------------------------------

This will not change base64 encoded data.

Duigou & Project JXTA Expires December 20, 2002 [Page 87]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

5. JXTA Reference Implementations Information

5.1 Introduction

In order to deliver complete JXTA implementations, the developers of
the various JXTA Reference Bindings have produced a number of
components which implement parts of the JXTA specification, but are
either not required by the core specification or not specified. This
section describes some of these components. These implementations
may not be present in all JXTA Bindings and Binding developers are
not required to support them.

5.2 Java 2 SE Reference Implementation

5.2.1 JXTA ID Formats

These ID Formats have been defined for JXTA Language Binding
Reference Implementations.

5.2.1.1 JXTA ID Formats : uuid ID Format

The Java 2SE reference implementation of JXTA provides an
implementation of JXTA IDs based upon UUIDs. This OPTIONAL ID Format
is identified as the "uuid" format. In this implementation, UUIDs
are encoded as hex digits as the basis generating unique identifiers.
At the end of each UUID ID are two hex characters that identify the
type of JXTA ID. Currently, six ID Types have been defined.

Duigou & Project JXTA Expires December 20, 2002 [Page 88]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

---------------------------------------------------------------------

<JXTAUUIDFMT> ::= "uuid"

<CODATID> ::= "01"

<PEERGROUPID> ::= "02"

<PEERID> ::= "03"

<PIPEID> ::= "04"

<MODULECLASSID> ::= "05"

<MODULESPECID> ::= "06"

Figure 49: JXTA "uuid" ID Format ABNF

---------------------------------------------------------------------

The characters preceding the ID Type identifier are the encoded form
of the ID. The encoding consists of a variable number of characters
dependant upon the ID Type being encoded. To decode the ID the hex
characters are translated in order and placed into the elements of a
byte array from which the various ID components can be retrieved.
All of JXTA UUID IDs are currently manipulated as 64 byte arrays
although no ID Type currently requires all the full 64 bytes to
encode their contents. Position 63 always contains the UUID ID Type
value. The remainder of the ID fields are defined beginning at
Position 0 and increment towards Position 63.

To make the text presentation of JXTA UUID IDs as URNs more compact
implementations must not encode the value of unused Positions within
the array. Since they are irrelevant to the value of the ID they can
be assumed to be zero. Implementations must also omit from the
encoding the value of any Positions that precede the unused portion
and contain zero. The reference Java implementation accomplishes
this by scanning from Position 62 towards Position 0 searching for
the first non-zero value. It then encodes from position 0 to the
discovered location followed by the encoding for Position 63. The
text encoding of a JXTA ID must be canonical according to the URN

Duigou & Project JXTA Expires December 20, 2002 [Page 89]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

specification, thus this "zero-saving" technique MUST be present in
every implementation.

5.2.1.2 JXTA UUID Field Definitions

Each of the six JXTA ID Types has a specific definition for how its
fields are represented within the common 64-byte array structure.
Common between the four types is the definition of Position 63. This
location is reserved for the ID Type.

5.2.1.2.1 JXTA UUID Codat ID Fields

Each Codat is assigned a unique codat id that enables canonical
references to be made to the codat in the context of a specific peer
group. A CodatID is formed by the conjunction of a PeerGroupID, a
randomly chosen value that has a high probability of being unique,
and an optional SHA1 cryptographic hash of the codat contents.

---------------------------------------------------------------------

TABLES NOT CURRENTLY CONVERTED.

JXTA UUID Codat ID Fields

---------------------------------------------------------------------

5.2.1.2.2 JXTA UUID PeerGroup ID Fields

Each peer group is assigned a unique id that enables canonical
references to that peer group.

---------------------------------------------------------------------

TABLES NOT CURRENTLY CONVERTED.

JXTA UUID PeerGroup ID Fields

---------------------------------------------------------------------

5.2.1.2.3 JXTA UUID Peer ID Fields

Each peer is assigned a unique peer id that enables canonical
references to be made to the peer in the context of a specific peer
group.

Duigou & Project JXTA Expires December 20, 2002 [Page 90]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

---------------------------------------------------------------------

TABLES NOT CURRENTLY CONVERTED.

JXTA UUID Peer ID Fields

---------------------------------------------------------------------

5.2.1.2.4 JXTA UUID Pipe ID Fields

Each pipe is assigned a unique pipe id that enables canonical
references to be made to the pipe in the context of a specific peer
group.

---------------------------------------------------------------------

TABLES NOT CURRENTLY CONVERTED.

JXTA UUID Pipe ID Fields

---------------------------------------------------------------------

5.2.1.2.5 JXTA UUID Module Class ID Fields

Each Module is assigned a Module service id that enables canonical
references to be made to the service in the context of a specific
peer group and optionally within the context of a specific peer.

---------------------------------------------------------------------

TABLES NOT CURRENTLY CONVERTED.

JXTA UUID Module Class ID Fields

---------------------------------------------------------------------

5.2.1.2.6 JXTA UUID Module Spec ID Fields

Each Service is assigned a unique service id that enables canonical
references to be made to the service in the context of a specific
peer group and optionally within the context of a specific peer.

Duigou & Project JXTA Expires December 20, 2002 [Page 91]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

---------------------------------------------------------------------

TABLES NOT CURRENTLY CONVERTED.

JXTA UUID Module Spec ID Fields

---------------------------------------------------------------------

5.2.2 Advertisment Sub-Classes

These Advertisement Sub-classes have been defined for local
configuration of the peer and services. They are not published.

5.2.2.1 Platform Config Advertisement

This advertisment is used to manage local configuration parameters by
the peer. This advertisement is not published.

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.

A Platform Config 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).

5.2.2.2 J2SE JXTA Endpoint Router Implementation

This section describes the implementation of the Endpoint Router in
the J2SE implementation of JXTA. This is just an example of how the
EndpointRouter protocol can be implemented, but there is several
other manners the Endpoint Router could be implemented. Other
optimizations or robustness mechanisms could be added or changed in
other implementations of the Endpoint Router.

In this section, the term Endpoint Router refers to the J2SE Endpoint
Router implementation and not to the Endpoint Router protocol as the
term has been used in the previous sections.

Also, the current implementation does not yet implement the entire
protocol (pending tasks). What is not yet implemented is outlined in

Duigou & Project JXTA Expires December 20, 2002 [Page 92]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

this document.

The Endpoint Router manages a cache of routes to destination peers.

[PENDING TASK] Currently the cache does not associate a life time to
a route in the cache. This is needed as routes are dynamic and
constantly changing in a peer to peer network. A life time of 15-20
minutes is probably a good guess.

When the Endpoint Router is asked to send a message to a peer for
which it does not yet have a route, it sends out a RouteQuery, using
the Resolver Service. When the router is asked to route a message,
if the message contains the forward route, this route is used, even
if the router knows another route (the forward route within the
message takes precedence). If the forward route is not valid (the
next hop in the list is not reachable), or if the message does not
contain a forward route, the local route is then used. If there is
no local route, then the message is dropped.

[PENDING TASK] When a router is asked to route a message, and when no
route is available, it should search for a route (sending a
RouteQuery), and/or send a NACK message back to the source of the
message.

When the Endpoint Router receives a RouteQuery, if it knows a route,
it answer with a RouteResponse including the forward route.

[PENDING TASK] PingQuery and PingResponse are not yet implemented.
In particular, routes should be checked once in a while.

[PENDING TASK] NACK is not yet implemented.

When the Endpoint Router receives an incoming message, and when the
incoming message contains a reverse route, the reverse route is added
into the local cache of routes. Note that the Endpoint Router
detects loops and other errors both in reverse route and forward
route.

The Endpoint Router does not remove its message element, even when
routed message is eventually delivered locally to the destination
application. This allow the application to decide to forward the
message to another peer, while keeping the routing information,
especially the reverse route, allowing the final destination to
respond to the original source of the message without having to issue
a RouteQuery.

Duigou & Project JXTA Expires December 20, 2002 [Page 93]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

References

[1] "Multipurpose Internet Mail Extensions (MIME) Part Two: Media
Types", June 2002.

[2] "Key words for use in RFCs to Indicate Requirement Levels", June
2002.

[3] "URN Syntax", June 2002.

[4] "Augmented BNF for Syntax Specifications: ABNF", June 2002.

[5] "Unicode Standard Annex #15: Unicode Normalization Forms", June
2002.

[6] "XML Schema Part 1: Structures", June 2002.

[7] "XML Schema Part 2: Datatypes", June 2002.

Authors' Addresses

Michael J. Duigou, editor
Project JXTA

EMail: bondolo@jxta.org

JXTA Specification Project
Project JXTA

EMail: discuss@spec.jxta.org
URI: http://spec.jxta.org

Duigou & Project JXTA Expires December 20, 2002 [Page 94]

Internet-Draft JXTA v1.0 Protocols Specification June 2002

Full Copyright Statement

This document and translations of it may be copied and furnished to
others, and derivative works that comment on or otherwise explain it
or assist in its implementation may be prepared, copied, published
and distributed, in whole or in part, without restriction of any
kind, provided that the above copyright notice and this paragraph are
included on all such copies and derivative works. However, this
document itself may not be modified in any way, such as by removing
the copyright notice or references to the Internet Society or other
Internet organizations, except as needed for the purpose of
developing Internet standards in which case the procedures for
copyrights defined in the Internet Standards process must be
followed, or as required to translate it into languages other than
English.

The limited permissions granted above are perpetual and will not be
revoked by the Internet Society or its successors or assigns.

This document and the information contained herein is provided on an
"AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Acknowledgement

Funding for the RFC Editor function is currently provided by the
Internet Society.

Duigou & Project JXTA Expires December 20, 2002 [Page 95]