router.txt

jxme的一些相关程序,主要是手机上程序开发以及手机和计算机通信的一些程序资料,程序编译需要Ant支持

		ENDPOINT ROUTER TRANSPORT PROTOCOL
		==================================


Description
-----------

The Endpoint Router is a JXTA Transport Protocol that seat under the
Endpoint Service, aside of the other Transport Protocols such as the
JXTA TCP and HTTP Transport Protocols.
The Endpoint Router is responsible for exchanging messages between peers
that do not have a direct connection between each other. The Endpoint Router
provides a virtual direction connection to the Endpoint Service.



Protocol
--------

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


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.

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.


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.

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


In addition to those queries and answer, the Endpoint Router defines an informational
message which does not need to be answered.

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 also includes its own message element in
each message it transports. The name of the message element is JxtaEndpointRouter
and contains an XML document containing the following:

Mandatory:

	Source: the orginal 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.
	
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.
               


Wire format
-----------

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

DOCTYPE: jxta:EndpointRouter

<!ELEMENT jxta:EndpointRouter (Version,
                               Type,
                               DestPeer?,
                               RoutingPeer?,
                               RoutingPeerAdv?,
                               NbOfHops?,
                               GatewayForward*) >
			       
<!ELEMENT Version #PCDATA >
<!ELEMENT Type #PCDATA >
<!ELEMENT DestPeer #PCDATA >
<!ELEMENT RoutingPeer #PCDATA >
<!ELEMENT RoutingPeerAdv #PCDATA >
<!ELEMENT NbOfHops #PCDATA >
<!ELEMENT GatewayForward #PCDATA >

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

Version: integer [current = 3]
Type: RouteQuery | RouteResponse | PingQuery | PingResponse | NACK
DestPeer: EndpointRouter EndpointAddress
RoutingPeer: EndpointRouter EndpointAddress
RoutingPeerAdv: Peer Advertisement
NbOfHops: integer [0-n]
GatewayForward: EndpointRouter EndpointAddress


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

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

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

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

	RoutingPeerAdv can be optionally contain the Peer Advertisement of the routing peer.
        This allow the requesting peer to not have to search for the advertisemetn later on
        (optimization).

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

	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.

PingQuery:
	. DestPeer is set to the peer id (in its EndpointRouter definition) of the peer
        for which a ping is requested.
	. RoutingPeerAdv is set with the local peer advertisement.
	
PingResponse:
	DestPeer is set to the peer id (in its EndpointRouter definition) of the peer
        for which a ping was requested.
	
NACK:
	DestPeer is set to the peer id (in its EndpointRouter definition) of the peer
        for which the route has failed.

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



B - 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 follow:

<!ELEMENT jxta:EndpointRouterMessage ( jxta:Src,
				       jxta:Dest,
                                       jxta:Last,
                                       jxta:NBOH,
                                       GatewayReverse*,
                                       GatewayForward* ) >
			       
<!ELEMENT jxta:Src #PCDATA >
<!ELEMENT jxta:Dest #PCDATA >
<!ELEMENT jxta:Last #PCDATA >
<!ELEMENT jxta:NBOH #PCDATA >
<!ELEMENT GatewayReverse #PCDATA >
<!ELEMENT GatewayForward #PCDATA >

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

jxta:Src : EndpointRouter EndpointAddress
jxta:Dest : EndpointRouter EndpointAddress
jxta:Last : EndpointRouter EndpointAddress
jxta:NBOH : integer [0-n]
GatewayForward: EndpointRouter EndpointAddress
GatewayReverse: EndpointRouter EndpointAddress

jxta:Src contains the EndpointAdress of the original source of the message
jxta:Dest contains the EndpointAdress of the original destination of the message
jxta:Last contains the EndpointAdress of immediate previous peer that has received the message
jxta:NBOH contains the number of hops of the reverse route. 0 if there is no reverse route.

GatewayForward: contains the Endpoint Address of a routing peer within the forward route.
The ordered list of GatewayForward 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 in the communication
between peers.

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 in the communication
between peers.


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


D - EndpointRouter listener

The EndpointRouter listens for queries coming from other EndpointRouter, registering
a Listener to the Endpoint Service. The name of the listener is:

          EndpointRouter<GroupID unique value>




J2SE JXTA Endpoint Router Implementation
----------------------------------------

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

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

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

The Endpoint Router manages a cache of routes to destination peers. 
[PENDING TASK] currentely the cache does not associate a life time to a route in the cache.
               This is needed since a P2P network, route are rather dynamic. A life time of 15-20
               minutes is probably a good guess.

When the Endpoint Router is asked to send a message to a peer for which it does not have
a route yet, it sends out, using the Resolver Service, a RouteQuery.

When the router is asked to route a message, if the message contains the forward route, this
route is used, even if the router knows another route (the forward route within the message
takes precedence). If the forward route is not valid (the next hop in the list is not reachable),
or if the message does not contain a forward route, the local route is then used. If there is
no local route, then the message is dropped.

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

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

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

[PENDING TASK] NACK is not yet implemented.

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

The Endpoint Router leaves its message element, even when routed messages are eventually
delivered 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.