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 (on request ID). Multiple requests can be sent at a time. Whenever a response is received, the correct Request is looked up (key = id) and its method receiveResponse() invoked.

Author:

Bela Ban

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`RequestCorrelator.Header` The header for `RequestCorrelator` messages
`static class`	`RequestCorrelator.MultiDestinationHeader`
`protected class`	`RequestCorrelator.MyProbeHandler`
`protected class`	`RequestCorrelator.ResponseImpl`

Field Summary

Fields
Modifier and Type	Field and Description
`protected boolean`	`async_dispatching` Whether or not to use async dispatcher
`protected short`	`corr_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 RequestCorrelator.MyProbeHandler`	`probe_handler`
`protected RequestHandler`	`request_handler` The handler for the incoming requests.
`protected static java.util.concurrent.atomic.AtomicLong`	`REQUEST_ID` To generate unique request IDs
`protected java.util.concurrent.ConcurrentMap<java.lang.Long,Request>`	`requests` The table of pending requests (keys=Long (request IDs), values=`RequestEntry`)
`protected RpcStats`	`rpc_stats`
`protected boolean`	`started`
`protected Protocol`	`transport` The protocol layer to use to pass up/down messages.
`protected View`	`view`
`protected boolean`	`wrap_exceptions`

Constructor Summary

Constructors
Constructor and Description
`RequestCorrelator(Protocol transport, RequestHandler handler, Address local_addr)`
`RequestCorrelator(short corr_id, Protocol transport, RequestHandler handler, Address local_addr)` Constructor.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`boolean`	`asyncDispatching()`
`RequestCorrelator`	`asyncDispatching(boolean flag)`
`protected void`	`dispatch(Message msg, RequestCorrelator.Header hdr)`
`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`	`receiveMessageBatch(MessageBatch batch)`
`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)`
`protected RequestCorrelator`	`removeEntry(long id)`
`protected void`	`sendReply(Message req, long req_id, java.lang.Object reply, boolean is_exception)`
`void`	`sendRequest(java.util.Collection<Address> dest_mbrs, Message msg, Request req, RequestOptions options)` Sends a request to a group.
`void`	`sendRequest(java.util.List<Address> dest_mbrs, Message msg, Request req)`
`protected void`	`sendResponse(Message rsp, long req_id, boolean is_exception)`
`void`	`sendUnicastRequest(Address target, Message msg, Request req)` Sends a request to a single destination
`void`	`setLocalAddress(Address a)`
`void`	`setMarshaller(RpcDispatcher.Marshaller marshaller)`
`void`	`setRequestHandler(RequestHandler handler)`
`void`	`setSiteUnreachable(java.lang.String 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)`
`boolean`	`wrapExceptions()`
`RequestCorrelator`	`wrapExceptions(boolean flag)`

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,Request> requests
```
    The table of pending requests (keys=Long (request IDs), values=RequestEntry)
  - REQUEST_ID
```
protected static final java.util.concurrent.atomic.AtomicLong REQUEST_ID
```
    To generate unique request IDs
  - 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
  - corr_id
```
protected short corr_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
```
  - async_dispatching
```
protected boolean async_dispatching
```
    Whether or not to use async dispatcher
  - wrap_exceptions
```
protected boolean wrap_exceptions
```
  - probe_handler
```
protected final RequestCorrelator.MyProbeHandler probe_handler
```
  - rpc_stats
```
protected final RpcStats rpc_stats
```
  - log
```
protected static final Log log
```
- Constructor Detail
  - RequestCorrelator
```
public RequestCorrelator(short corr_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:
    
    corr_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.
    
    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)
```
  - getLocalAddress
```
public Address getLocalAddress()
```
  - setLocalAddress
```
public void setLocalAddress(Address a)
```
  - getMarshaller
```
public RpcDispatcher.Marshaller getMarshaller()
```
  - setMarshaller
```
public void setMarshaller(RpcDispatcher.Marshaller marshaller)
```
  - sendRequest
```
public void sendRequest(java.util.List<Address> dest_mbrs,
                        Message msg,
                        Request req)
                 throws java.lang.Exception
```
    Throws:
    
    java.lang.Exception
  - asyncDispatching
```
public boolean asyncDispatching()
```
  - asyncDispatching
```
public RequestCorrelator asyncDispatching(boolean flag)
```
  - wrapExceptions
```
public boolean wrapExceptions()
```
  - wrapExceptions
```
public RequestCorrelator wrapExceptions(boolean flag)
```
  - sendRequest
```
public void sendRequest(java.util.Collection<Address> dest_mbrs,
                        Message msg,
                        Request req,
                        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:
    
    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
    
    req - A request (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.
    
    Throws:
    
    java.lang.Exception
  - sendUnicastRequest
```
public void sendUnicastRequest(Address target,
                               Message msg,
                               Request req)
                        throws java.lang.Exception
```
    Sends a request to a single destination
    
    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(java.lang.String 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
  - receiveMessageBatch
```
public void receiveMessageBatch(MessageBatch batch)
```
  - removeEntry
```
protected RequestCorrelator removeEntry(long id)
```
  - dispatch
```
protected void dispatch(Message msg,
                        RequestCorrelator.Header hdr)
```
  - handleRequest
```
protected void handleRequest(Message req,
                             RequestCorrelator.Header hdr)
```
    Handle a request msg for this correlator
    
    Parameters:
    
    req - the request msg
  - sendReply
```
protected void sendReply(Message req,
                         long req_id,
                         java.lang.Object reply,
                         boolean is_exception)
```
  - sendResponse
```
protected void sendResponse(Message rsp,
                            long req_id,
                            boolean is_exception)
```
  - prepareResponse
```
protected void prepareResponse(Message rsp)
```

Class RequestCorrelator

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

transport

requests

REQUEST_ID

request_handler

marshaller

corr_id

local_addr

view

started

async_dispatching

wrap_exceptions

probe_handler

rpc_stats

log

Constructor Detail

RequestCorrelator

RequestCorrelator

Method Detail

setRequestHandler

getLocalAddress

setLocalAddress

getMarshaller

setMarshaller

sendRequest

asyncDispatching

asyncDispatching

wrapExceptions

wrapExceptions

sendRequest

sendUnicastRequest

done

receive

start

stop

registerProbeHandler

unregisterProbeHandler

receiveSuspect

setSiteUnreachable

receiveView

receiveMessage

receiveMessageBatch

removeEntry

dispatch

handleRequest

sendReply

sendResponse

prepareResponse