propagate.txt

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

			PROPAGATE SERVICE
			=================



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

The Propagate Service (previously known as the Rendezvous Service)
is responsible for propagating messages within a JXTA PeerGroup.
While different PeerGroups may have different means to propagate
messages, the JXTA Propagate Services defines a simple protocol that
allows:

	- peers to connect to service (be able to propagate messages
          and receive propagates messages)

        - control the propagation of the message (TTL, loopback
          detection...).

Protocol
--------

1 - Peer connection

The Propagate Service has the notion of special peers, called
Rendezvous, which can be used to re-propagate message they have
received. A peer can become dynamically a rendezvous and/or can
dynamically connect to a rendezvous. The connection between a peer
(named a client in this document) to a rendezvous is achieved
by an explicit connection, associated to a lease.

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

		 service name: JxtaPropagate
		service param: PeerGroup ID

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

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 cancelled by
              both parties at anytime if necessary. A rendezvous that
              grants a lease returns LeaseGranted.

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.

LeaseCancelRequest: This message is sent by a client to its rendezvous
              in order to cancel an existing lease. The rendezvous is
              expeted to reply with LeaseCancelled.

LeaseCancelled: This message is sent by a rendezvous in order to either
              cancel (on its own) an existing lease with a client, or
              as a response to a LeaseCancelRequest.


NOTE: the JXTA Resolver protocol is not used to send those message: the
      Propagate Service seats directely on top of the Endpoint. The reason
      of this is layering: the JXTA Resolver Protocol seats itself on top
      of the JXTA Propagate Service.


The JXTA Propagate Protocol also includes its own message element
in each message it transports. The name of the message element is
JxtaPropagate and contains an XML document containing the following:

Mandatory:

TTL: Time To Live. Each propagated messages is associated to a maximum
     number of peers it will go through. Passed that number, the message
     is dropped (not further propagated). Each instance of the Propagate
     Service is required to decrease the TTL by at least one before resending
     it (a peer can decide to actually decrease the TTL by more than one
     if that is the local policy).


Optional:

Path: the list of EndpointAddresses of the peers the message has already been
      through. This is used by the Propagate Service in order to filter
      out loopbacks.


ID: Each propagated message can be associated with a unique identifier
    which can be used by the Propagation Service in order to eliminate
    duplicated messages.



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

A - Queries and Responses

The messages are represented by an XML document:

DOCTYPE: jxta:PropagateMessage

<!ELEMENT jxta:PropagateLeaseMessage (Type,
				      Peer,
				      PeerAdv?
				      Lease?
<!ELEMENT Type #PCDATA >
<!ELEMENT Peer #PCDATA >
<!ELEMENT PeerAdv #PCDATA >
<!ELEMENT Lease #PCDATA >

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

Type: LeaseRequest |
      LeaseGranted |
      LeaseCancelRequest |
      LeaseCancelled

Peer: Peer Id
PeerAdv: XML Peer Advertisement
Lease: [0-n] (time in millisecond).

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

LeaseRequest:
	. Peer is set to the client PeerID (the peer that is
          requesting a lease. This is mandatory.
	. PeerAdv is optionally set with the requesting peer's advertisment.
          This is optional because the destination (rendezvous) peer
          can use either a cached advertisement if it already had any, or
          issue a Discovery query. However, setting the advertisement is
          a optimization that decrease the latency of getting a lease to
          a rendezvous.


LeaseGranted:
	. Peer is set to the rendezvous PeerId.
	. Lease is set to the time the rendezvous is granted the connection
          for. The time is expressed in millisecond.

LeaseCancelRequest:
	. Peer (client) that is requesting to cancel the lease.

LeaseCancelled:
	. Peer (rendezvous) that is cancelling the lease.




B - Message Element

The Propagate Service includes a message element named JxtaPropagate.
The format of the message element is an XML document defined as follow:


DOCTYPE: jxta:PropagateMessage

<!ELEMENT jxta:PropagateMessage (TTL,
				 Path*,
				 ID?) >
<!ELEMENT TTL #PCDATA >
<!ELEMENT Path #PCDATA >
<!ELEMENT ID #PCDATA >

TTL: integer [0-n]. This contains the current (remaining) TTL
     of the propagated message.

Path: Peer ID. The message contains several Path, each of them
      identifying a peer that has already processed the propagated message.

ID: unique identifier. This unique identfier needs to be unique in time
    and space.