Enterprise Integration Patterns
Conversation Patterns
ReferralConversation Patterns » Discovery

A participant wants to initiate a conversation.

The choice of conversation partner may depend on the context of a conversation or may change over time. How can an initiator discover the right conversation partner?

  • The choice of a conversation partner can depend on the context of a conversation. For example, a participant may be required to interact with the same partner that another participant is already interacting with.
  • Directories are generally context free, i.e. they do not keep track of existing conversations and when assigning an initiator to a partner. They may take workload or proximity information into account, e.g. to avoid overloading a single instance or unnecessary latency. This information tends to be based on lower-level network and server properties and is transparent to the initiator. This type of selection is therefore not based on a specific conversation that is already taking place. In contrast, some conversations require specific information to be passed to an additional partner or the identity of the partner depends on the course of the conversation.
  • Some participants may not want to be "discovered". However, "friends of friends" are allowed to interact with them.
  • Conversation partners can move. However, some initiators may still access the partner at a previous address.
  • Conversation partners may rely on third parties to perform some functions necessary to service the conversation. At some point in the conversation, a direct interaction between a requesting service and the third party may be desirable or necessary.

One participant provides a Referral to another, such that the two can start to interact.

The Referral conversation involves the following participants:

  • The Initiator initiates the conversation by sending a message to the Referrer.
  • The Referrer receives request messages from the Initiator and responds with a reference to the Referral.
  • The Referral accepts messages from the Initiator. The Referral does not have to be aware of the Referrer or the fact that a Referral is taking place.

The purpose of using a Referral can be to cross trust boundaries. If the Referral trusts the Referrer and the Referrer trusts the Initiator then the Referrer is permitted to pass a Referral to the Initiator to conduct a conversation with the Referral. This is sometimes referred to as the "Mafia approach" where connections are only made by introduction, i,e, Referral.

Consult Directory is a specialized case of Referral, where the sole purpose of the Referrer is to provide references. In the Referral conversation the Referrer can take part in the general conversation and only pass the Referral during certain points in the conversation. Consult Directory also relies on the Referral to be aware of the Referrer to register itself. However, in a Referral this may not be the case.

Like most Discovery conversations, Referral requires addressability, such as URI's, which can be embedded in a message from the Referrer to the Initiator. If trust and security are an concern, the Referrer may also pass additional information, such as a token, along to assure that the conversation between the Initiator and the Referral is legitimate. In such a setup the Referrer protects access to the Referral as in

Example: HTTP 302 and Location Header

The HTTP protocol includes a "302" status code which indicated "FOUND" and can include a location header element in the response to redirect the user agent to another resource. In HTTP/1.0, the 302 code was referred to as "temporary redirect".

A user agent may make the following request:
GET /ramblings HTTP/1.1
Host: www.eaipatterns.com
The Referrer responds with the following HTTP header.
HTTP/1.1 302 Found
Location: /ramblings.html
Subsequently the Initiator issues the following request:
GET /ramblings.html HTTP/1.1
Host: www.eaipatterns.com

Example: Supplier Refers Customer to Shipper

When a customer orders from an on-line supplier, such as Amazon, the supplier often refers the customer to the shipper's service, for example FedEx's or UPS's tracking service. This referral usually includes a token, so that the customer can retrieve the information from the shipper that is associated with his or her order.

Related patterns: Consult Directory, Discovery

Table of Contents
Describing Conversations
Hypermedia State
Conversation Vocabulary
Dynamic Discovery
Advertise Availability
Consult Directory
Leader Election
Starting a Conversation
Three-Way Hand Shake
Acquire Token First
Rotate Tokens
Verify Identity
User Grants Access
Basic Conversations
Asynchronous Request-Response
Request-Response with Retry
Quick Acknowledgment
Load Balancer
Managing Distributed Systems
Resource Management
Incremental State Build-up
Renewal Reminder
Ensuring Consistency
Ignore Error
Compensating Action
Tentative Operation
Coordinated Agreement