JXTA J2SE^? Reference Implementation Use Cases

These use cases, reverse-engineered from the implementation source code, are the work of Nicolas Théodoloz, and are reproduced here with his permission. They constitute Appendix A of his 2004 diploma project DHT-based Routing and Discovery in JXTA.

The original work on which this information is based was done using JXTA 2.1.1 (circa September 2003). There may have been significant changes to the implementation in the intervening time. I hope that by making these use cases available to the community, they can be updated and/or corrected on an ongoing basis.

If you see something incorrect or in need of updating and are unable to edit this page yourself, please send me a note about it at vwilliams@jxta.org. Any transcription errors from the original are entirely my fault.

Discovery Service

Publish an advertisement

1. The edge peer created a new advertisement and defines its expiration time (or affects a default value).
2. The discovery service saves the advertisement locally in the advertisements storage.
   The following steps are periodically executed by an active thread in the SRDI service in parallel with the steps (1-2).
3. A thread in the SRDI service (specific to the discovery service) asks the discovery service to index the new elements from its storage.
4. The discovery service gets from the storage the indexes of the new advertisements added since the last process activation.
5. The discovery service creates a SRDI Entries message containing all these indexes and a time-to-live of 1 (one step to reach the rendez-vous peer to which it is connected).
6. The discovery service asks the SRDI service to send a SRDI entries message. Use case terminates.

Top

Publish a remote advertisement

1. The edge peer provides the advertisement and its expiration time.
2. The discovery service creates a Discovery Response Message containing the advertisement and the expiration time.
3. The discovery service creates a Resolver Response Message containing the previous created message, the credential of the edge peer, the discovery service as handler name and the special query ID 0.
4. The discovery service uses the resolver service and invokes send a resolver response message. Use case terminates.

Top

Get a local advertisement

1. A peer asks the discovery service to get local advertisements specifying the type and an optional attribute/value pair (criteria).
2. The discovery service searches the matching advertisements in the storage.
3. The discovery service transmits the resulting advertisements to the peer. Use case terminates.

Top

Get a remote advertisement - Send a query message

1. A peer asks the discovery service to get advertisements specifying the type, an optional attribute/value element (criteria), a threshold (specifying the maximum number of advertisements transmitted by a single peer), an optional discovery listener (this listener will be notified when a response is received) and an optional destination peer ID.
2. The discovery service creates a Discovery Query Message specifying the parameters of the query.
3. The discovery service generates a unique ID for this query.
4. The discovery service registers the listener in relation with the query ID.
5. The discovery service creates a Resolver Query Message specifying as handler name the discovery service and adding the credential of the peer, the Discovery Query message and the query ID.
6. The peer is an edge peer.
7. The discovery service uses the resolver service and invokes send a resolver query message specifying the eventual destination peer and including the Resolver Query message. Use case terminates.

Extensions :

6a The peer is a rendez-vous peer
6a.1. The discovery service searches for the key of the query in its own SRDI index.
6a.2. The SRDI index returns at least one response (a set of peers).
6a.3. The discovery service increments the Resolver Query Message hop count.
6a.4. The discovery service asks the SRDI service to forward a query to all the peers included in the SRDI response.
6a.2a. The SRDI index finds nothing.
6a.2a.1. The discovery service asks the SRDI service to get a replica peer specifying the key of the query as expression.
6a.2a.2. A replica peer is returned.
6a.2a.3. The discovery service increments the Resolver Query Message hop count.
6a.2a.4. The discovery service asks the SRDI service to forward a query specifying the replica peer as destination peer. Use case terminates.
6a.2a.2a. No replica is returned.
6a.2a.2a.1. The discovery service uses the resolver service and invokes send a resolver query message without specifying a destination peer and including the Resolver Query Message. Use case terminates.

Top

Receive a discovery query message

1. The discovery service extracts the Discovery Query Message from the Resolver Query Message.
2. The query does not specify the peer advertisement type or specifies a threshold different from 0.
3. The discovery service looks for an advertisement matching the criteria of the query in the storage.
4. The storage returns a result.
5. The discovery service creates a Discovery Response Message including the advertisements found in the storage.
6. The discovery service creates a Resolver Response Message containing the previous created message, the credential of the edge peer, the discovery service as handler name and the query ID.
7. The discovery service uses the resolver service and invokes send a resolver response message. Use case terminates.

Extensions :

2a. The query specifies the peer advertisement type and a threshold of 0. This is a special case which means that the peer has to provide its own advertisement.
2a.1. The discovery service creates a Discovery Response Message including the local peer advertisement.
2a.2. The discovery service creates a Resolver Response Message containing the previous created message, the credential of the edge peer, the discovery service as handler name and the same query ID.
2a.3. The discovery service uses the resolver service and invokes send a resolver response message. Use case terminates.
4a. The storage does not find anything.
4a.1. The local peer is an edge peer. Use case terminates.
4a.1a. The local peer is a rendez-vous peer.
4a.1a.1. The discovery service searches the keys of the query in its own SRDI index.
4a.1a.2. The SRDI index returns at least one response (a set of peers).
4a.1a.3. The discovery service increments the hop count of the Resolver Query Message.
4a.1a.4. If the hopcount is smaller than 2, the discovery service increments the hopcount and asks the SRDI service to forward the query to all the peers included in the SRDI Index response. Use case terminates.
4a.1a.2a. The SRDI index finds nothing.
4a.1a.2a.1. If the hopcount of the Resolver Query Message is 0, the discovery service asks the resolver service to propagate the resolver request and the use case terminates.
4a.1a.2a.2. Otherwise, the discovery service asks the SRDI service to get a replica peer.
4a.1a.2a.3. A replica peer is returned.
4a.1a.2a.4. The discovery service asks the SRDI service to forward a query specifying the replica peer as destination peer. Use case terminates.
4a.1a.2a.3a. No replica is returned.
4a.1a.2a.3a.1. The discovery service increments the hop count of the Discovery Query Message and asks the resolver service to propagate the resolver request. Use case terminates.

Top

Receive a discovery response message

1. The discovery service extracts the Discovery Response Message from the Resolver Response Message.
   The step 2 is repeated for each advertisement contained in the Discovery Response Message
2. The discovery service publishes the advertisement.
3. The eventual listener related to the query ID is notified. Use case terminates.

Top

Process a SRDI resolver message (indexes) (only for rendez-vous peers)

1. The discovery service extracts the SRDI Entries Message from the Resolver SRDI Message.
   The step 2 is repeated for each entry contained in the SRDI Entries Message.
2. The discovery service adds the entry to its SRDI Index.
3. The discovery service asks the SRDI service to replicate SRDI entries from the SRDI Entries Message. Use case terminates.

Top

Notify a failure

1. A messenger failed to send a message to a destination peer.
2. The discovery service asks the SRDI service to remove all the entries related to this peer from the SRDI index. Use case terminates.

Top

Become a rendez-vous peer

1. The thread (to push entries to a rendez-vous peer) in the SRDI service is stopped.
2. A new SRDI index is created.
3. The SRDI service is reinitialized.

Top

Become an edge peer

1. The SRDI index is removed.
2. The SRDI service is reinitialized.
3. The thread (to push entries to a rendez-vous peer) in the SRDI service is started.

Top

SRDI Service

Send a SRDI entries message

1. The service transmits the SRDI Entries message to the SRDI service.
2. The SRDI service creates a SRDI Resolver Message specifying as handler name the service and containing the SRDI Entries message.
3. The SRDI service uses the resolver service and invokes send a SRDI message. Use case terminates.

Top

Get a replica peer

1. The SRDI service receives an expression.
2. The SRDI service asks the rendez-vous service to get the local peer view.
3. The SRDI service creates a digest of the expression received using SHA1.
4. The SRDI service gets the replica peer related to the digest using the algorithm 8.
5. The SRDI service returns the replica peer. Use case terminates.

Top

Forward a query

1. The SRDI service receives a Resolver Query Message and a list of destination peers.
2. The Resolver Query Message hop count is less than 3.
3. The SRDI service uses the resolver service to send the resolver query message to each destination peers of the list. Use case terminates.

Extensions :

2a. The Resolver Query Message hop count is greater or equal than 3.
2a.1 The message is not forwarded. Use case terminates.

Top

Replicate SRDI entries

1. The SRDI service asks the rendez-vous service to get the local peer view.
2. The SRDI Entries Message time-to-live is greater than 0.
   The steps (3-5) are repeated for each entry contained in the SRDI Entries Message.
3. The SRDI service gets a replica peer related to this entry.
4. A replica peer is returned and is different from the local peer.
5. A new SRDI Entries Message is created specifying the replica peer and containing the entry (only one SRDI Entries Message is created for each different destination peer)
   The step 6 is repeated for each SRDI Entries Message generated at step 5.
6. The SRDI Service sends a SRDI entries message. Use case terminates.

Extensions :

2a. The SRDI Entries Message time-to-live is 0.
2a.1. The entries are not replicated. Use case terminates.
4a. No replica peer is found or the replica peer is ourself.
4a.1. Use case continues at step 3 with the next entry.

Top

Remove the entries associated with a peer

1. The SRDI service removes all entries from the SRDI index associated with this peer ID. Use case terminates.

Top

Resolver Service

Send a SRDI message

1. A SRDI service asks the resolver service to send a SRDI Resolver Message optionally specifying a destination peer.
2. The resolver service creates an endpoint message.
3. The destination peer is defined.
4. The resolver service creates an endpoint address specifying the handler name (SRDI service) and the destination peer.
5. The resolver service looks for a messenger for this endpoint address in its local list of messengers.
6. A messenger is found.
7. The resolver service asks the messenger to send the message.
8. The resolver service is notified by the endpoint service when a message fails to be sent. In that case, the handlers are notified of this failure. If the handler is the discovery service, it is notified of this failure.

Extensions :

3a. The destination peer is not defined.
3a.1. The peer is an edge peer. The resolver service asks the rendez-vous service to walk the message with a time-to-live of 1 (just the time to reach the rendez-vous) and specifies the SRDI service as handler name. Use case terminates.
3a.1a. The peer is a rendez-vous peer. The resolver service asks the rendezvous service to walk the message and specifies the SRDI service as handler name. Use case terminates.
6a. No messenger is found.
6a.1. The resolver service asks the endpoint service to get a messenger for this destination address.
6a.2. Until the messenger is received (asynchronously), the message is kept in a sending queue.
6a.3. When the messenger is received, all the messages waiting in the queue are sent.

Top

Send a resolver query message

1. A service asks the resolver service to send a Resolver Query Message optionally specifying the destination peer.
2. The resolver service creates a new endpoint message.
3. The destination peer is defined.
4. The resolver service creates an endpoint address specifying the handler name and the destination peer.
5. The resolver service looks for a messenger for this endpoint address in its local list of messengers.
6. A messenger is found.
7. The resolver service asks the messenger to send the message.
8. The resolver service is notified by the endpoint service when a message fails to be sent. In that case, the handlers are notified of this failure. If the handler is the discovery service, it is notified of this failure.

Extensions :

3a. The destination peer is not defined.
3a.1. The time-to-live is defined as 1 for an edge peer and as the size of the list returned by get the local peer view for a rendez-vous peer.
3a.2. The resolver service asks the rendez-vous service to walk the message with the time-to-live and the Resolver Query Message handler as handler name. Use case terminates.
6a. No messenger is found.
6a.1. The resolver service asks the endpoint service to get a messenger for this destination address.
6a.2. Until the messenger is received (asynchronously), the message is kept in a sending queue.
6a.3. When the messenger is received, all the messages waiting to be sent in the queue are processed. The messenger is inserted in the local messengers list.

Top

Send a resolver response message

1. A service asks the resolver service to send a Resolver Response Message optionally specifying the destination peer.
2. The resolver service creates a new endpoint message.
3. The destination peer is defined.
4. The resolver service creates an endpoint address specifying the handler name and the destination peer.
5. The resolver service looks for a messenger for this endpoint address in its local list of messengers.
6. A messenger is found.
7. The resolver service asks the messenger to send the message.
8. The resolver service is notified by the endpoint service when a message fails to be sent. In that case, the handlers are notified of this failure. If the handler is the discovery service, it is notified of this failure.

Extensions :

3a. The destination peer is not defined.
3a.1. The resolver service asks the rendez-vous service to walk the message with a time-to-live of 1 and the Resolver Response Message handler as handler name. Use case terminates.
6a. No messenger is found.
6a.1. The resolver service asks the endpoint service to get a messenger for this destination address.
6a.2. Until the messenger is received (asynchronously), the message is kept in a sending queue.
6a.3. When the messenger is received, all the messages waiting to be sent in the queue are processed. The messenger is inserted in the local messengers list.

Top

Propagate a resolver query request

1. The resolver service is asked to propagate a Resolver Query Message.
2. The hop count of the message is not greater than 3.
3. The resolver service asks the rendez-vous service to get the local peer view.
4. The time-to-live is defined as the size of the peer view.
5. The resolver service asks the rendez-vous service to walk the message with the time-to-live and the resolver service as handler name. Use case terminates.

Extensions :

2a. The hop count of the message is greater than 3.
2a.1. The message is not propagated. Use case terminates.

Top

Receive a SRDI resolver message

1. The resolver service receives a SRDI Resolver Message.
2. The handler name is extracted from the SRDI Resolver Message.
3. The resolver service looks for this handler in the local map of SRDI handlers.
4. The handler is found.
5. The SRDI Resolver Message is sent to the SRDI handler.
6. The SRDI handler is the discovery service.
7. The discovery service (which is a SRDI handler) processes the SRDI resolver message.

Extensions :

4a. The handler is not found. Use case terminates.

Top

Receive a resolver query message

1. The resolver service receives a Resolver Query Message.
2. The handler name is extracted from the Resolver Query Message.
3. The resolver service looks for this handler in the local map of handlers.
4. The handler is found.
5. The Resolver Query Message is sent to the handler.
6. The handler is the discovery service.
7. The discovery service receives a discovery query message.

Extensions :

4a. The handler is not found. Use case terminates.
6a. The handler is the peer information service.
6a.1. The peer information service receives an information query message.

Top

Receive a resolver response message

1. The resolver service receives a Resolver Response Message.
2. The handler name is extracted from the Resolver Response Message.
3. The resolver service looks for this handler in the local map of handlers.
4. The handler is found.
5. The Resolver Response Message is sent to the handler.
6. The handler is the discovery service.
7. The discovery service receives a discovery query message.

Extensions :

4a. The handler is not found. Use case terminates.
6a. The handler is the peer information service.
6a.1. The peer information service receives an information response message.

Top

Pipe Service

Create an input pipe

1. The peer has an advertisement for the pipe.
2. The peer asks the pipe service to create an input pipe, according to the pipe advertisement and providing an optional listener.
3. The pipe service asks the endpoint service to register a listener for that pipe specifying as handler name the pipe service handler name and the pipe ID.
4. The pipe service adds the pipe in its local list of pipes.
5. The listener is specified.
6. The pipe service stores the listener in relation with the input pipe.
7. The pipe service creates a SRDI Entries message containing as entry the new input pipe key and a time-to-live of 1.
8. The pipe service asks the SRDI service to send a SRDI entries message. Use case terminates.

Extensions :

1a. The peer has no advertisement.
1a.1. The peer creates a pipe advertisement. Use case continues at step 2.
5a. No listener is defined.
5a.1. A queue is created for this input pipe. Use case continues at step 7.

Top

Create an output pipe

1. The peer has an advertisement for the pipe.
2. The peer asks the pipe service to create an output pipe, according to the pipe advertisement, providing an optional listener and specifying a timeout for the pipe binding process.
3. The pipe service searches the pipe ID in its local pipe ID list (local pipe: input and output on the same peer)
4. The pipe service does not find any pipe in its local list.
5. The pipe service searches the pipe ID in the local cache of pipes (found in a previous looking process).
6. The pipe service does not find any pipe in its pipes cache.
7. The pipe service tries to find a remote pipe.
8. The pipe service creates a Pipe Binding Query Message specifying the pipe ID and the type of pipe.
9. The pipe service generates a unique ID for this query.
10. The pipe service creates a Resolver Query Message specifying as handler name the pipe service and adding the credential of the peer, the Pipe Binding Query Message and the query ID.
11. The pipe service queries the SRDI service to get the peers related to the key of this pipe (get a replica peer).
12. No results are provided by the SRDI service.
13. The pipe service uses the resolver service and invokes send a resolver query message including the Resolver Query message.
    Steps 14-15 are repeated as long as the timeout defined in 2 is not reached.
14. The pipe service looks for the pipe in the local cache of pipes. If the pipe is found, the destination peer is now found. Use case continues at step 16.
15. The timeout is over. The binding failed. Use case terminates.
16. The pipe service asks the endpoint service to get a messenger (synchronously) for the destination peer.
17. The messenger is stored in relation with the output pipe. Use case terminates.

Extensions :

1a. The peer has no advertisement.
1a.1. The peer uses the discovery service to get a local advertisement or to get a remote advertisement. Use case continues at step 2.
4a. The pipe service finds a corresponding input pipe in its local list and consequently a destination peer for the pipe.
4a.1. The pipe service asks the endpoint service to get a messenger (synchronously) for the destination peer (in fact the local peer).
4a.2. The messenger (a loopback messenger) is stored in relation with the output pipe. Use case terminates.
6a. The pipe service finds a corresponding input pipe in its cache, and thus a destination peer for the pipe.
6a.1. The pipe service asks the endpoint service to get a messenger (synchronously) for the destination peer.
6a.2. The messenger is stored in relation with the output pipe. Use case terminates.
12a. The SRDI index returns at least one response (a set of peers).
12a.1. The pipe service increments the hop count of the Resolver Query Message.
12a.2. The pipe service asks the SRDI service to forward a SRDI query to all the peers included in the SRDI response. Use case continues at step 14.

Top

Maintain pipes cache

1. The pipes cache manager periodically (by default every 10 minutes) checks all the pipes in the cache.
   Steps 2-3 are repeated for each pipe in the cache.
2. The lifetime of the pipe is expired.
3. The pipe is removed from the cache.
4. Use case terminates.

Extensions :

2a. The lifetime is not expired. Use case continues with the next pipe at step 2.

Top

Receive a pipe binding query message

1. The pipe service extracts the Pipe Binding Request Message from the Resolver Request Message.
2. The pipe service searches the pipe ID in its local pipe ID list.
3. The pipe service does not find any pipe in its local list.
4. The pipe service searches the pipe ID in the local cache of pipes (found in a previous looking process).
5. The pipe service does not find any pipe in its pipes cache.
6. The local peer is a rendez-vous peer.
7. The pipe service searches for the ID of the pipe (the key) in its own SRDI index.
8. The SRDI index returns at least one response (a set of peers).
9. The pipe service asks the SRDI service to forward a query to all the peers included in the SRDI response.

Extensions :

3a. The pipe service finds a corresponding input pipe in its local list and consequently an input pipe for the pipe.
3a.1. The pipe service creates a Pipe Binding Response Message containing the information of the input pipe. The pipe service creates a Resolver Response Message containing the previous created message, the credential of the local peer, the pipe service as handler name and the query ID.
3a.2. The pipe service uses the resolver service and invokes send a resolver response message. Use case terminates.
5a. The pipe service finds a corresponding input pipe in its cache, and thus an input pipe for the pipe.
5a.1. The pipe service creates a Pipe Binding Response Message containing the information of the input pipe. The pipe service creates a Resolver Response Message containing the previous created message, the credential of the local peer, the pipe service as handler name and the query ID.
5a.2. The pipe service uses the resolver service and invokes send a resolver response message. Use case terminates.
6a. The local peer is an edge peer.
6a.1. The pipe binding fails. Use case terminates.
8a. The SRDI index finds nothing.
8a.1. The pipe service asks the resolver service to propagate the resolver request and the use case terminates.

Top

Receive a pipe binding response message

1. The pipe service extracts the Pipe Binding Response Message from the Resolver Response Message.
2. The pipe service inserts the pipe ID related to the binding (endpoint address) in the local cache of pipes.

Top

Reception of a message for a specific pipe

1. A listener is associated with this pipe.
2. An event is generated containing the message.
3. The listener is notified of this event.

Extensions :

1a. No listener is related to this pipe ID.
1a.1. The message is put in the queue. A method poll can then get the message from the queue of this input pipe.

Top

Sending of a message to a specific pipe

1. The peer invokes the method send to the output pipe and includes the message to send.
2. The pipe service looks for the messenger associated with this output pipe.
3. The pipe service asks the messenger to send the message.

Top

Peer Information Service

Add a monitor to a remote peer

1. A peer asks the peer information service to monitor a remote peer, specifying the remote peer ID, the rate of reports sending, a duration of the monitoring and a listener which will receive the reports.
2. The peer information service creates a unique query ID.
3. The peer information service creates a Peer Information Query Message specifying the elements enumerated in step 1 and adding the query ID.
4. The peer information service creates a Resolver Query Message specifying as handler name the peer information service and adding the credential of the peer, the Peer Information Query Message and the query ID.
5. The peer information service uses the resolver service to send the resolver query message specifying the remote peer it wants to monitor as destination peer. Use case terminates.

Top

Remove a monitor from a remote peer

1. A peer asks the peer information service to stop monitoring a remote peer, specifying the remote peer ID, the listener which receives actually the reports and a new timeout.
2. The peer information service creates a unique query ID.
3. The peer information service creates a Peer Information Query Message (the type of the Peer Information Query Message is specific for removing).
4. The peer information service creates a Resolver Query Message specifying as handler name the monitoring service and adding the credential of the peer, the Peer Information Query Message and the query ID.
5. The peer information service uses the resolver service to send the resolver query message specifying the remote peer it wants to stop monitoring. Use case terminates.

Top

Receive an information query message

1. The peer information service extracts the Peer Information Query Message from the Resolver Query Message.
2. The type of Peer Information Query Message is not specific for removing a monitoring.
3. The monitoring is registered in the list of monitoring processes of the monitoring manager. Use case terminates.

Extensions :

2a. The type of Peer Information Query Message is specific for removing a monitoring.
2a.1. The monitoring is removed from the list of monitoring processes of the monitoring manager. Use case terminates.

Top

Send information to monitoring listeners

1. A monitoring manager generates reports according to the defined rate of reports for each monitoring process.
2. The monitoring manager asks the peer information service to send the report.
3. The peer information service creates a Peer Information Response Message.
4. The peer information service creates a Resolver Response Message specifying as handler name the peer information service and adding the credential of the local peer (the monitored peer), the report and the query ID.
5. The peer information service uses the resolver service to send the resolver response message specifying the peer interested in the report as destination peer. Use case terminates.

Top

Receive an information response message

1. The peer information service extracts the Peer Information Response Message from the Resolver Response Message.
2. The peer information service looks for a listener for this report in its own list of listeners.
3. The peer information service forwards the message to the listener. Use case terminates.

Top

Rendez-vous Service

Maintain the rendez-vous peer view

Strategies :

The peer view maintenance uses different strategies to select an element from a list of elements (peers or advertisements):

• Random strategy (S1) : one element is selected randomly and remains in the list
• Sequential strategy (S2) : the list is traversed sequentially: each new invocation selects the following element

Main Success Scenario :

1. Seed process: as long as the peer view is empty (a peer view does not contain the local peer), the seed process does the following steps:
   1. The rendez-vous service gets the seed rendez-vous addresses (these seed addresses are configured during JXTA initialization) and the advertisement of the local peer is sent to all these rendez-vous peers. The process of sending uses the endpoint service and the messenger mechanism.
   2. The rendez-vous service uses the discovery service and the use case get a local advertisement specifying "rendez-vous peers" as the criteria. Then, the advertisement of the local peer is sent to all of these rendez-vous peers.
   3. The rendez-vous service asks the endpoint service to multicast the local peer advertisement using a multicast message transport (TCP multicast) if it is activated.
   4. The rendez-vous service sends the local peer advertisement using the wire output pipe specified in the peer group.
      Steps 2-5 are individually repeatable and can occur in any order
2. Recipient refresh process: periodically (by default every 15 minutes) a rendez-vous advertisement from the peer view is selected using the strategy S1 and a rendez-vous peer is selected from the peer view using also the strategy S1. The selected advertisement is sent to the selected rendez-vous peer:
   1. The rendez-vous service looks for a messenger in its local messenger map for the rendez-vous peer.
   2. A messenger is found. The rendez-vous service asks the messenger to send the message.
   3. No messenger is found. The rendez-vous service asks the endpoint service to get a messenger for this destination address. Until the messenger is received (asynchronously), the message is kept in a sending queue. When the messenger is received, all the messages waiting to be sent in the queue are processed. The messenger is inserted in the local messenger map.
   4. The resolver service is notified by the endpoint service when a message fails to be sent. In that case, the peer view is notified of this failure.
3. Own advertisement process: periodically (by default every 15 minutes), the advertisement of the local rendez-vous peer is sent to a rendez-vous peer selected from the list using the strategy S2. The process of sending is the same as the one described in step 1.
4. Incoming Message: if the originator of the message is a rendez-vous peer. Its advertisement is added to the peer view.
5. Failure notification by the endpoint service: the peer view is updated according to the event. The other rendez-vous peers are notified using the wire output pipe connected to all other peers. If the list becomes empty, the seed process starts again. The use case continues at step 1.

Top

Get the local peer view

1. A service on a rendez-vous peer needs the rendez-vous peer view in a routing process.
2. The rendez-vous service gets the local rendez-vous peer view.
3. The rendez-vous service returns the peer view. Use case terminates.

Top

Walk a message (rendez-vous peer)

1. A rendez-vous peer has to walk a message to an optional list of destination peers using a specified handler name.
2. The list is empty.
3. The direction is up or both up and down (if it has not yet been set, both is the default value).
4. The rendez-vous service gets the rendez-vous peer situated after the local peer (up peer) in the peer view.
5. The up peer is not null.
6. The rendez-vous service creates a Limited Range Rendezvous Message.
7. The rendez-vous service specifies the direction up to the Limited Range Rendezvous Message.
8. The rendez-vous service looks for a messenger in its local messenger map for the up peer destination.
9. A messenger is found.
10. The rendez-vous service asks the messenger to send the message.
11. The direction is down or both up and down.
12. The rendez-vous service gets the rendez-vous peer situated before the local peer (down peer) in the peer view.
13. The down peer is not null.
14. The rendez-vous service creates a Limited Range Rendezvous Message.
15. The rendez-vous service specifies the direction down to the Limited Range Rendezvous Message.
16. The rendez-vous service looks for a messenger in its local messenger map for the down peer destination.
17. A messenger is found.
18. The rendez-vous service asks the messenger to send the message. Use case terminates.

Extensions :

2a. The list contains destination peers.
Steps 2a.1. to 2a.3. are repeated for each destination peer of the list
2a.1. The rendez-vous service looks for a messenger in its local messenger map for the destination peer.
2a.2. A messenger is found.
2a.3. The rendez-vous service asks the messenger to send the message. Use case terminates.
2a.2a. No messenger is found.
2a.2a.1. The resolver service asks the endpoint service to get a messenger (synchronously) for the destination peer.
2a.2a.2. If a messenger is returned, the rendez-vous service asks the messenger to send the message. Otherwise, the peer view is notified of the failure (maintain peer view) and the destination peer is removed from the peer view. The next destination peer is processed. Use case continues at step 2a.1.
3a. The direction is down. Use case continues at step 11.
5a. The up peer is null.
5a.1. The message is not sent in the up direction. Use case continues at step 11.
9a. No messenger is found.
9a.1. The resolver service asks the endpoint service to get a messenger (synchronously) for the up peer.
9a.2. If a messenger is returned, the rendez-vous service asks the messenger to send the message. Otherwise, the peer view is notified of the failure (maintain peer view) and the up peer is removed from the peer view. Use case continues at step 11.
11a. The direction is up. Use case terminates.
13a. The down peer is null.
13a.1. The message is not sent down. Use case terminates.
17a. No messenger is found.
17a.1. The resolver service asks the endpoint service to get a messenger (synchronously) for the down peer.
17a.2. If a messenger is returned, the rendez-vous service asks the messenger to send the message. Otherwise, the peer view is notified of the failure (maintain peer view) and the down peer is removed from the peer view. Use case terminates.

Top

Walk a message (edge peer)

1. An edge peer has to walk a message.
2. The rendez-vous service sends the message to the rendez-vous to which the edge peer is connected: the rendez-vous service asks the endpoint service to get a messenger for the rendez-vous peer and then to send the message including the endpoint message to send and the rendez-vous service as handler.
3. The rendez-vous service asks the endpoint service to propagate the message to the network: this step is only executed if a multicast endpoint transport (TCP multicast) is available.

Top

Connect to a rendez-vous peer

1. The edge peer has the rendez-vous advertisement or the address of the rendez-vous on a specific message transport (TCP, HTTP, . . . ). Thus, the endpoint address of the rendez-vous peer is known.
2. The edge peer asks the rendez-vous service to connect to the rendezvous peer specified by the endpoint address.
3. The rendez-vous service creates a Lease Request Message containing the advertisement of the edge peer.
4. The rendez-vous service creates an endpoint message specifying the rendez-vous service as handler name and including the Lease Request Message.
5. The rendez-vous service asks the endpoint service to get a messenger (synchronously) for the rendez-vous peer endpoint.
6. If a messenger is returned, the rendez-vous service asks the messenger to send the message. Otherwise, the rendez-vous peer is not reachable. Use case terminates.

Extensions :

1a. The edge peer does not have the rendez-vous advertisement.
1a.1. The edge peer uses the discovery service to get a remote advertisement.
1a.2. The edge peer can now connect to the rendez-vous peer. Use case continues at step 2.

Top

Disconnect from a rendez-vous peer

1. The edge peer asks the rendez-vous service to disconnect from a rendezvous.
2. The rendez-vous service creates a Lease Cancel Message.
3. The rendez-vous service creates an endpoint message specifying the rendez-vous service as handler name and including the Lease Cancel Message.
4. The rendez-vous service asks the endpoint service to get a messenger (synchronously) for the rendez-vous peer.
5. If a messenger is returned, the rendez-vous service asks the messenger to send the message. Otherwise, the edge peer can either try again after a moment or become unreachable for the rendezvous peer after a period of time. Use case terminates.

Top

Receive a lease request message

1. The endpoint service received a generic message and the rendez-vous service is the handler.
2. The rendez-vous service extracts the Lease Request Message from the endpoint message.
3. The rendez-vous service defines a lease period for this peer (by default 20 minutes).
4. The rendez-vous service asks the discovery service to publish the advertisement of the peer.
5. The rendez-vous service creates a Lease Granted Message containing the lease period.
6. The rendez-vous service asks the endpoint service to get a messenger (synchronously) for the edge peer.
7. A messenger is returned.
8. The rendez-vous service asks the messenger to send the message.
9. The edge peer is added to the list of edge peers connected to the rendezvous peer. Use case terminates.

Extensions :

7a. No messenger is returned.
7a.1. The message is not sent. Use case terminates.

Top

Receive a cancel lease message

1. The endpoint service received an endpoint message and the rendezvous service is the handler.
2. The rendez-vous service extracts the Lease Cancel Message from the endpoint message.
3. The client is removed from the list of edge peers connected to the rendez-vous peer.
4. The rendez-vous service notifies all the srdi services to remove the entries associated with this peer (in particular for the discovery service). Use case terminates.

Top

Receive a granted lease message

1. The endpoint service of the edge peer received an endpoint message and the rendez-vous service is the handler.
2. The rendez-vous service extracts the Lease Granted Message from the generic message.
3. The rendez-vous service asks the discovery service to publish the advertisement of the rendez-vous peer.
4. The rendez-vous peer is stored as the connected rendez-vous.

Top

Maintain the list of connected peers

1. Periodically, the connections manager (by default every 2 minutes) checks the lease of each connected edge peer.
   Steps 2-4 are repeated for each edge peer connected to the rendez-vous peer.
2. The lease is no more valid.
3. The edge peer is removed from the list.
4. The rendez-vous service notifies all the SRDI services to remove the entries associated with this peer (in particular for the discovery service). Use case terminates.

Extensions :

2a. The lease is still valid. 2a.1. Use case continues with the next edge peer at step 2.

Top

Become a rendez-vous peer

1. The rendez-vous service disconnects from the rendez-vous peer.
2. The rendez-vous service creates an empty list of clients.
3. The rendez-vous service starts the connections manager.
4. The rendez-vous service creates a peer view and starts the peer view maintenance.
5. The edge peer is now a rendez-vous peer.
6. The rendez-vous service informs the discovery service that the peer is now a rendez-vous peer. Use case terminates.

Top

Become an edge peer

Steps 1-4 are repeated for each connected edge peer

1. The rendez-vous service asks the endpoint service to get a messenger (synchronously) for the edge peer.
2. A messenger is returned.
3. The rendez-vous service creates a message containing a specific disconnected request element.
4. The rendez-vous service asks the messenger to send the message.
5. The rendez-vous service stops the connections manager.
6. The rendez-vous service stops the peer view maintenance and notifies the other rendez-vous peers using the wire output pipe connected to all other rendez-vous peers.
7. The rendez-vous peer is now an edge peer.
8. The rendez-vous service informs the discovery service that the peer is now an edge peer. Use case terminates.

Extensions :

2a. No messenger is returned.
2a.1. The edge peer will not be informed. Use case continues at step 1 with the next connected edge peer.

Top

Endpoint Service

Get a messenger

1. A service asks the endpoint service to get a messenger for a specified endpoint address (which includes the protocol to use, the service name and the service parameter).
2. The invocation is done asynchronously using a listener.
3. The invocation is inserted in a queue of messenger requests which are processed by a specific process.
4. The messenger request is extracted from the queue by the process.
5. The endpoint service looks for a message transport corresponding to the protocol specified in the endpoint address.
6. A message transport is found.
7. The protocol is jxta://.
8. The message transport will be the endpoint router.
9. The endpoint service returns a virtual messenger which stores the destination endpoint address.

Extensions :

2a. The invocation is done synchronously.
2a.1. The messenger is created immediately. Use case continues at step 5.
6a. No message transport is found.
6a.1. The endpoint service asks the parent endpoint service to find a message transport. If it is found, a cross-group messenger is returned otherwise a failure is sent.
7a. The protocol is =tcp://=
7a.1. The message transport will be the TCP Message Transport. Use case continues at step 9.
7b. The protocol is =http://=
7b.1. The message transport will be the HTTP Message Transport. Use case continues at step 9.
7c. The protocol is =jxtatls://=
7c.1. The message transport will be the TLS Message Transport. Use case continues at step 9.
7d. The protocol is =relay://=
7d.1. The message transport will be the Relay Message Transport. Use case continues at step 9.

Top

Send a message

1. A service asks a messenger to send a message.
2. The messenger asks the endpoint service and more specifically the messenger pool to get a real messenger for the endpoint address.
3. The messenger pool looks for a message transport corresponding to the protocol specified in the endpoint address.
4. The messenger pool asks the message transport to get a messenger for the endpoint address.
5. The message transport is the endpoint router.
6. The endpoint address is not the local peer.
7. The endpoint router creates an endpoint router messenger.
8. The messenger pool asks the messenger to send the query.
9. The messenger asks the endpoint router to find a route to reach the destination peer.
10. The endpoint router asks the discovery service to get a local advertisement concerning a route advertisement to the destination peer.
11. No route advertisement is found.
12. The endpoint router creates a Route Query Message specifying the destination address.
13. The endpoint router creates a Resolver Query Message including the Route Query Message, the credential of the local peer, and a new generated query ID.
14. The local peer is a rendez-vous peer.
15. The endpoint router searches for a route to reach this destination peer in its own SRDI index.
16. The SRDI index returns at least one response (a set of peers).
17. The endpoint router increments the hop count of the Resolver Query Message.
18. The endpoint router asks the SRDI service to forward the query to all the peers included in the SRDI response.
19. The endpoint router waits at most during 15 seconds for the reception of a new route advertisement.
20. The messenger is used to send the message. Use case continues at step 5.

Extensions :

5a. The message transport is the TCP Message Transport.
5a.1. The messenger is asked to send the message. Use case terminates.
5b. The message transport is the HTTP Message Transport.
5b.1. The messenger is asked to send the message. Use case terminates.
5c. The message transport is the TLS Message Transport.
5c.1. The messenger is asked to send the message. Use case terminates.
5d. The message transport is the Relay Message Transport.
5d.1. The messenger is asked to send the message. Use case terminates.
6a. The endpoint address is the local peer.
6a.1. A loopback messenger is returned. The loopback messenger is asked to send the message (locally delivered). Use case terminates.
11a. A route advertisement is found.
11a.1. The messenger asks the endpoint service to send on local route, specifying the route. Use case terminates.
14a. The local peer is an edge peer.
14a.1. The edge peer asks the resolver service to send a resolver query message specifying the rendez-vous peer to which it is connected as destination peer. Use case terminates.
16a. The SRDI index did not return anything.
16a.1. The endpoint router asks the SRDI service to get a replica peer specifying the destination peer as key for the query.
16a.2. A replica peer is returned.
16a.3. The endpoint router asks the SRDI service to forward a query specifying the replica peer as destination peer.
16a.2a. No replica is returned.
16a.2a.1. No route is searched.

Top

Receive a route query message

1. The endpoint router extracts the Route Query Message from the Resolver Query Message.
2. The endpoint router extracts the destination peer ID from the Route Query Message.
3. The endpoint router searches a route for this destination peer in its local cache.
4. The endpoint router finds a route.
5. The endpoint router creates a Route Response Message including the route found and the local peer.
6. The endpoint router creates a Resolver Response Message containing the Route Response Message, the credential of the local peer, the endpoint router as handler name and the query ID of the Resolver Query Message received.
7. The endpoint router uses the resolver service and invokes send a resolver response message. Use case terminates.

Extensions :

4a. The endpoint router does not find a route.
4a.1. The Resolver Query Message hop count is smaller than 2.
4a.2. The endpoint router searches for the destination peer ID (key) in its own SRDI index.
4a.3. The SRDI index returns at least one response (a set of peers).
4a.4. The endpoint router increments the hop count of the Resolver Query Message.
4a.5. The endpoint router asks the SRDI service to forward a query to all the peers included in the SRDI response. Use case terminates.
4a.1a. The Resolver Query Message hop count is greater or equal than 2.
4a.1a.1. The Resolver Query Message is not forwarded. Use case terminates.
4a.3a. The SRDI index finds nothing.
4a.3a.1. The endpoint router asks the resolver service to propagate the resolver request and the use case terminates.

Top

Receive a route response message

1. The endpoint router extracts the Route Response Message from the Resolver Response Message.
2. The endpoint router creates a Route Advertisement containing the destination peer, the source peer and the sequence of hops to route a message from the source to the destination.
3. The Route Advertisement is inserted in the local routes cache.
4. The endpoint router asks the discovery service to publish the advertisement of the route.

-- vwilliams@jxta.org - 30 Dec 2005