org.jgroups.blocks
Class RequestCorrelator

java.lang.Object
  org.jgroups.blocks.RequestCorrelator

Direct Known Subclasses:

MuxRequestCorrelator

public class RequestCorrelator
extends java.lang.Object

Framework to send requests and receive matching responses (matching on request ID). Multiple requests can be sent at a time. Whenever a response is received, the correct RspCollector is looked up (key = id) and its method receiveResponse() invoked. A caller may use done() to signal that no more responses are expected, and that the corresponding entry may be removed.

RequestCorrelator can be installed at both client and server sides, it can also switch roles dynamically; i.e., send a request and at the same time process an incoming request (when local delivery is enabled, this is actually the default).

Author:

Bela Ban

Nested Class Summary

static class	RequestCorrelator.Header The header for RequestCorrelator messages
static class	RequestCorrelator.MultiDestinationHeader

Field Summary

protected short	id makes the instance unique (together with IDs)
protected Address	local_addr The address of this group member
protected static Log	log
protected RpcDispatcher.Marshaller	marshaller Possibility for an external marshaller to marshal/unmarshal responses
protected RequestHandler	request_handler The handler for the incoming requests.
protected java.util.concurrent.ConcurrentMap<java.lang.Long,RspCollector>	requests The table of pending requests (keys=Long (request IDs), values=RequestEntry)
protected boolean	started
protected Protocol	transport The protocol layer to use to pass up/down messages.
protected View	view

Constructor Summary

RequestCorrelator(Protocol transport, RequestHandler handler, Address local_addr)

RequestCorrelator(short id, Protocol transport, RequestHandler handler, Address local_addr)
Constructor.

Method Summary

void	done(long id) Used to signal that a certain request may be garbage collected as all responses have been received.
Address	getLocalAddress()
RpcDispatcher.Marshaller	getMarshaller()
protected void	handleRequest(Message req, RequestCorrelator.Header hdr) Handle a request msg for this correlator
protected void	prepareResponse(Message rsp)
boolean	receive(Event evt) Callback.
boolean	receiveMessage(Message msg) Handles a message coming from a layer below
void	receiveSuspect(Address mbr) Event.SUSPECT event received from a layer below.
void	receiveView(View new_view) Event.VIEW_CHANGE event received from a layer below.
void	registerProbeHandler(TP transport)
void	sendRequest(long id, java.util.Collection<Address> dest_mbrs, Message msg, RspCollector coll, RequestOptions options) Sends a request to a group.
void	sendRequest(long id, java.util.List<Address> dest_mbrs, Message msg, RspCollector coll)
void	sendUnicastRequest(long id, Address target, Message msg, RspCollector coll) Sends a request to a single destination
void	setLocalAddress(Address local_addr)
void	setMarshaller(RpcDispatcher.Marshaller marshaller)
void	setRequestHandler(RequestHandler handler)
void	setSiteUnreachable(short site) An entire site is down; mark all requests that point to that site as unreachable (used by RELAY2)
void	start()
void	stop()
void	unregisterProbeHandler(TP transport)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

transport

protected Protocol transport

The protocol layer to use to pass up/down messages. Can be either a Protocol or a Transport

requests

protected final java.util.concurrent.ConcurrentMap<java.lang.Long,RspCollector> requests

The table of pending requests (keys=Long (request IDs), values=RequestEntry)

request_handler

protected RequestHandler request_handler

The handler for the incoming requests. It is called from inside the dispatcher thread

marshaller

protected RpcDispatcher.Marshaller marshaller

Possibility for an external marshaller to marshal/unmarshal responses

id

protected short id

makes the instance unique (together with IDs)

local_addr

protected Address local_addr

The address of this group member

view

protected volatile View view

started

protected boolean started

log

protected static final Log log

Constructor Detail

RequestCorrelator

public RequestCorrelator(short id,
                         Protocol transport,
                         RequestHandler handler,
                         Address local_addr)

Constructor. Uses transport to send messages. If handler is not null, all incoming requests will be dispatched to it (via handle(Message)).

Parameters:

id - Used to differentiate between different RequestCorrelators (e.g. in different protocol layers). Has to be unique if multiple request correlators are used.

transport - Used to send/pass up requests. Is a Protocol (up_prot.up()/down_prot.down() will be used)

handler - Request handler. Method handle(Message) will be called when a request is received.

RequestCorrelator

public RequestCorrelator(Protocol transport,
                         RequestHandler handler,
                         Address local_addr)

Method Detail

setRequestHandler

public void setRequestHandler(RequestHandler handler)

getMarshaller

public RpcDispatcher.Marshaller getMarshaller()

setMarshaller

public void setMarshaller(RpcDispatcher.Marshaller marshaller)

sendRequest

public void sendRequest(long id,
                        java.util.List<Address> dest_mbrs,
                        Message msg,
                        RspCollector coll)
                 throws java.lang.Exception

Throws:

java.lang.Exception

sendRequest

public void sendRequest(long id,
                        java.util.Collection<Address> dest_mbrs,
                        Message msg,
                        RspCollector coll,
                        RequestOptions options)
                 throws java.lang.Exception

Sends a request to a group. If no response collector is given, no responses are expected (making the call asynchronous)

Parameters:

id - The request ID. Must be unique for this JVM (e.g. current time in millisecs)

dest_mbrs - The list of members who should receive the call. Usually a group RPC is sent via multicast, but a receiver drops the request if its own address is not in this list. Will not be used if it is null.

msg - The request to be sent. The body of the message carries the request data

coll - A response collector (usually the object that invokes this method). Its methods receiveResponse() and suspect() will be invoked when a message has been received or a member is suspected, respectively.

Throws:

java.lang.Exception

sendUnicastRequest

public void sendUnicastRequest(long id,
                               Address target,
                               Message msg,
                               RspCollector coll)
                        throws java.lang.Exception

Sends a request to a single destination

Parameters:

id -

target -

msg -

coll -

Throws:

java.lang.Exception

done

public void done(long id)

Used to signal that a certain request may be garbage collected as all responses have been received.

receive

public boolean receive(Event evt)

Callback.

Called by the protocol below when a message has been received. The algorithm should test whether the message is destined for us and, if not, pass it up to the next layer. Otherwise, it should remove the header and check whether the message is a request or response. In the first case, the message will be delivered to the request handler registered (calling its handle() method), in the second case, the corresponding response collector is looked up and the message delivered.

Parameters:

evt - The event to be received

Returns:

Whether or not the event was consumed. If true, don't pass message up, else pass it up

start

public final void start()

stop

public void stop()

registerProbeHandler

public void registerProbeHandler(TP transport)

unregisterProbeHandler

public void unregisterProbeHandler(TP transport)

receiveSuspect

public void receiveSuspect(Address mbr)

Event.SUSPECT event received from a layer below.

All response collectors currently registered will be notified that mbr may have crashed, so they won't wait for its response.

setSiteUnreachable

public void setSiteUnreachable(short site)

An entire site is down; mark all requests that point to that site as unreachable (used by RELAY2)

receiveView

public void receiveView(View new_view)

Event.VIEW_CHANGE event received from a layer below.

Mark all responses from members that are not in new_view as NOT_RECEIVED.

receiveMessage

public boolean receiveMessage(Message msg)

Handles a message coming from a layer below

Returns:

true if the message was consumed, don't pass it further up, else false

getLocalAddress

public Address getLocalAddress()

setLocalAddress

public void setLocalAddress(Address local_addr)

handleRequest

protected void handleRequest(Message req,
                             RequestCorrelator.Header hdr)

Handle a request msg for this correlator

Parameters:

req - the request msg

prepareResponse

protected void prepareResponse(Message rsp)