RELAY2

java.lang.Object
- org.jgroups.stack.Protocol
- - org.jgroups.protocols.relay.RELAY2

```
public class RELAY2
extends Protocol
```
Design: ./doc/design/RELAY2.txt and at https://github.com/belaban/JGroups/blob/master/doc/design/RELAY2.txt.
JIRA: https://issues.jboss.org/browse/JGRP-1433

Since:

3.2

Author:

Bela Ban

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class RELAY2.Relay2Header

Nested Classes
Modifier and Type	Class and Description
`static class`	`RELAY2.Relay2Header`

Field Summary

Fields
Modifier and Type	Field and Description
`protected boolean`	`async_relay_creation`
`protected boolean`	`can_become_site_master`
`protected boolean`	`can_forward_local_cluster`
`protected java.lang.String`	`config`
`protected boolean`	`enable_address_tagging`
`protected java.util.concurrent.atomic.AtomicLong`	`forward_sm_time`
`protected java.util.concurrent.atomic.AtomicLong`	`forward_to_local_mbr` Number of messages (received from a remote Sitemaster and) delivered by the local SiteMaster to a local node
`protected java.util.concurrent.atomic.AtomicLong`	`forward_to_local_mbr_time`
`protected java.util.concurrent.atomic.AtomicLong`	`forward_to_site_master` Number of messages forwarded to the local SiteMaster
`protected boolean`	`forwarding_protocol_present` Whether or not FORWARD_TO_COORD is on the stack
`protected boolean`	`is_site_master`
`protected Address`	`local_addr`
`protected java.util.concurrent.atomic.AtomicLong`	`local_deliveries` Number of messages delivered locally, e.g.
`protected java.util.concurrent.atomic.AtomicLong`	`local_delivery_time` Total time (ms) for received messages that are delivered locally
`protected int`	`max_site_masters`
`protected java.util.List<Address>`	`members`
`protected short[]`	`prots_above`
`protected boolean`	`relay_multicasts`
`protected java.util.concurrent.atomic.AtomicLong`	`relayed` Number of messages relayed by the local SiteMaster to a remote SiteMaster
`protected java.util.concurrent.atomic.AtomicLong`	`relayed_time` Total time spent relaying messages from the local SiteMaster to remote SiteMasters (in ns)
`protected Relayer`	`relayer`
`protected RouteStatusListener`	`route_status_listener`
`protected java.lang.String`	`site`
`protected RelayConfig.SiteConfig`	`site_config`
`protected SiteMasterPicker`	`site_master_picker`
`protected java.lang.String`	`site_master_picker_impl`
`protected java.util.List<Address>`	`site_masters`
`protected java.util.Map<java.lang.String,RelayConfig.SiteConfig>`	`sites` A map containing site names (e.g.
`protected TimeScheduler`	`timer`
`protected boolean`	`warn_when_ftc_missing`

Fields inherited from class org.jgroups.stack.Protocol
after_creation_hook, down_prot, ergonomics, id, log, name, stack, stats, up_prot

Constructor Summary

Constructors
Constructor and Description

RELAY2()

Constructors
Constructor and Description
`RELAY2()`

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`RELAY2`	`addSite(java.lang.String site_name, RelayConfig.SiteConfig cfg)`
`void`	`addToRelayedTime(long delta)`
`boolean`	`asyncRelayCreation()`
`RELAY2`	`asyncRelayCreation(boolean flag)`
`boolean`	`canBecomeSiteMaster()`
`RELAY2`	`canBecomeSiteMaster(boolean flag)`
`java.lang.String`	`config()`
`RELAY2`	`config(java.lang.String cfg)`
`void`	`configure()`
`protected Message`	`copy(Message msg)` Copies the message, but only the headers above the current protocol (RELAY) (or RpcDispatcher related headers)
`protected void`	`deliver(Address dest, Address sender, Message msg)`
`protected void`	`deliverLocally(SiteAddress dest, SiteAddress sender, Message msg)`
`protected java.util.List<Address>`	`determineSiteMasters(View view)` Iterates over the list of members and adds every member if the member's rank is below max_site_masters.
`java.lang.Object`	`down(Event evt)` An event is to be sent down the stack.
`boolean`	`enableAddressTagging()`
`RELAY2`	`enableAddressTagging(boolean flag)`
`protected void`	`forwardTo(Address next_dest, SiteAddress final_dest, Address original_sender, Message msg, boolean forward_to_current_coord)`
`long`	`getAvgMsgsDeliveringLocally()`
`long`	`getAvgMsgsForwardingToLocalMbr()`
`long`	`getAvgMsgsForwardingToSM()`
`long`	`getAvgMsgsRelaying()`
`JChannel`	`getBridge(java.lang.String site_name)` Returns the bridge channel to a given site
`View`	`getBridgeView(java.lang.String cluster_name)`
`Address`	`getLocalAddress()`
`long`	`getNumForwardedToLocalMbr()`
`long`	`getNumForwardedToSiteMaster()`
`long`	`getNumLocalDeliveries()`
`long`	`getNumRelayed()`
`Route`	`getRoute(java.lang.String site_name)` Returns the route to a given site
`RouteStatusListener`	`getRouteStatusListener()`
`java.util.List<java.lang.String>`	`getSites()`
`long`	`getTimeDeliveringLocally()`
`long`	`getTimeForwardingToLocalMbr()`
`long`	`getTimeForwardingToSM()`
`TimeScheduler`	`getTimer()`
`long`	`getTimeRelaying()`
`protected void`	`handleMessage(RELAY2.Relay2Header hdr, Message msg)` Called to handle a message received by the transport
`protected void`	`handleRelayMessage(RELAY2.Relay2Header hdr, Message msg)` Called to handle a message received by the relayer
`void`	`handleView(View view)`
`void`	`incrementRelayed()`
`void`	`init()` Called after instance has been created (null constructor) and before protocol is started.
`boolean`	`isSiteMaster()`
`void`	`parse(org.w3c.dom.Node node)` Called by the XML parser when subelements are found in the configuration of a protocol.
`protected void`	`parseSiteConfiguration(java.util.Map<java.lang.String,RelayConfig.SiteConfig> map)` Parses the configuration by reading the config file.
`protected Address`	`pickSiteMaster(Address sender)` Returns a site master from site_masters
`java.lang.String`	`printRoutes()`
`boolean`	`relayMulticasts()`
`RELAY2`	`relayMulticasts(boolean flag)`
`void`	`resetStats()`
`protected void`	`route(SiteAddress dest, SiteAddress sender, Message msg)` Routes the message to the target destination, used by a site master (coordinator)
`protected void`	`sendSiteUnreachableTo(Address dest, java.lang.String target_site)` Sends a SITE-UNREACHABLE message to the sender of the message.
`protected void`	`sendToBridges(Address sender, Message msg, java.lang.String... excluded_sites)` Sends the message via all bridges excluding the excluded_sites bridges
`void`	`setRouteStatusListener(RouteStatusListener l)`
`java.lang.String`	`site()`
`RELAY2`	`site(java.lang.String site_name)`
`RELAY2`	`siteMasterPicker(SiteMasterPicker s)`
`java.util.List<java.lang.String>`	`siteNames()`
`protected void`	`startRelayer(Relayer rel, java.lang.String bridge_name)`
`void`	`stop()` This method is called on a `Channel.disconnect()`.
`java.lang.Object`	`up(Event evt)` An event was received from the layer below.
`void`	`up(MessageBatch batch)` Sends up a multiple messages in a `MessageBatch`.

Methods inherited from class org.jgroups.stack.Protocol
accept, afterCreationHook, destroy, dumpStats, enableStats, getConfigurableObjects, getDownProtocol, getDownServices, getId, getIdsAbove, getLevel, getLog, getName, getProtocolStack, getSocketFactory, getThreadFactory, getTransport, getUpProtocol, getUpServices, getValue, isErgonomics, level, printStats, providedDownServices, providedUpServices, requiredDownServices, requiredUpServices, resetStatistics, setDownProtocol, setErgonomics, setId, setLevel, setProtocolStack, setSocketFactory, setUpProtocol, setValue, setValues, start, statsEnabled

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - site
```
protected java.lang.String site
```
  - config
```
protected java.lang.String config
```
  - can_become_site_master
```
protected boolean can_become_site_master
```
  - max_site_masters
```
protected int max_site_masters
```
  - enable_address_tagging
```
protected boolean enable_address_tagging
```
  - relay_multicasts
```
protected boolean relay_multicasts
```
  - async_relay_creation
```
protected boolean async_relay_creation
```
  - warn_when_ftc_missing
```
protected boolean warn_when_ftc_missing
```
  - site_master_picker_impl
```
protected java.lang.String site_master_picker_impl
```
  - sites
```
protected final java.util.Map<java.lang.String,RelayConfig.SiteConfig> sites
```
    A map containing site names (e.g. "LON") as keys and SiteConfigs as values
  - site_config
```
protected RelayConfig.SiteConfig site_config
```
  - is_site_master
```
protected volatile boolean is_site_master
```
  - site_masters
```
protected volatile java.util.List<Address> site_masters
```
  - site_master_picker
```
protected SiteMasterPicker site_master_picker
```
  - relayer
```
protected volatile Relayer relayer
```
  - timer
```
protected TimeScheduler timer
```
  - local_addr
```
protected volatile Address local_addr
```
  - members
```
protected volatile java.util.List<Address> members
```
  - forwarding_protocol_present
```
protected boolean forwarding_protocol_present
```
    Whether or not FORWARD_TO_COORD is on the stack
  - can_forward_local_cluster
```
protected boolean can_forward_local_cluster
```
  - prots_above
```
protected short[] prots_above
```
  - route_status_listener
```
protected volatile RouteStatusListener route_status_listener
```
  - forward_to_site_master
```
protected final java.util.concurrent.atomic.AtomicLong forward_to_site_master
```
    Number of messages forwarded to the local SiteMaster
  - forward_sm_time
```
protected final java.util.concurrent.atomic.AtomicLong forward_sm_time
```
  - relayed
```
protected final java.util.concurrent.atomic.AtomicLong relayed
```
    Number of messages relayed by the local SiteMaster to a remote SiteMaster
  - relayed_time
```
protected final java.util.concurrent.atomic.AtomicLong relayed_time
```
    Total time spent relaying messages from the local SiteMaster to remote SiteMasters (in ns)
  - forward_to_local_mbr
```
protected final java.util.concurrent.atomic.AtomicLong forward_to_local_mbr
```
    Number of messages (received from a remote Sitemaster and) delivered by the local SiteMaster to a local node
  - forward_to_local_mbr_time
```
protected final java.util.concurrent.atomic.AtomicLong forward_to_local_mbr_time
```
  - local_deliveries
```
protected final java.util.concurrent.atomic.AtomicLong local_deliveries
```
    Number of messages delivered locally, e.g. received and delivered to self
  - local_delivery_time
```
protected final java.util.concurrent.atomic.AtomicLong local_delivery_time
```
    Total time (ms) for received messages that are delivered locally
- Constructor Detail
  - RELAY2
```
public RELAY2()
```
- Method Detail
  - site
```
public RELAY2 site(java.lang.String site_name)
```
  - config
```
public RELAY2 config(java.lang.String cfg)
```
  - canBecomeSiteMaster
```
public RELAY2 canBecomeSiteMaster(boolean flag)
```
  - enableAddressTagging
```
public RELAY2 enableAddressTagging(boolean flag)
```
  - relayMulticasts
```
public RELAY2 relayMulticasts(boolean flag)
```
  - asyncRelayCreation
```
public RELAY2 asyncRelayCreation(boolean flag)
```
  - siteMasterPicker
```
public RELAY2 siteMasterPicker(SiteMasterPicker s)
```
  - site
```
public java.lang.String site()
```
  - siteNames
```
public java.util.List<java.lang.String> siteNames()
```
  - config
```
public java.lang.String config()
```
  - canBecomeSiteMaster
```
public boolean canBecomeSiteMaster()
```
  - enableAddressTagging
```
public boolean enableAddressTagging()
```
  - relayMulticasts
```
public boolean relayMulticasts()
```
  - asyncRelayCreation
```
public boolean asyncRelayCreation()
```
  - getLocalAddress
```
public Address getLocalAddress()
```
  - getTimer
```
public TimeScheduler getTimer()
```
  - incrementRelayed
```
public void incrementRelayed()
```
  - addToRelayedTime
```
public void addToRelayedTime(long delta)
```
  - getRouteStatusListener
```
public RouteStatusListener getRouteStatusListener()
```
  - setRouteStatusListener
```
public void setRouteStatusListener(RouteStatusListener l)
```
  - getNumForwardedToSiteMaster
```
public long getNumForwardedToSiteMaster()
```
  - getTimeForwardingToSM
```
public long getTimeForwardingToSM()
```
  - getAvgMsgsForwardingToSM
```
public long getAvgMsgsForwardingToSM()
```
  - getNumRelayed
```
public long getNumRelayed()
```
  - getTimeRelaying
```
public long getTimeRelaying()
```
  - getAvgMsgsRelaying
```
public long getAvgMsgsRelaying()
```
  - getNumForwardedToLocalMbr
```
public long getNumForwardedToLocalMbr()
```
  - getTimeForwardingToLocalMbr
```
public long getTimeForwardingToLocalMbr()
```
  - getAvgMsgsForwardingToLocalMbr
```
public long getAvgMsgsForwardingToLocalMbr()
```
  - getNumLocalDeliveries
```
public long getNumLocalDeliveries()
```
  - getTimeDeliveringLocally
```
public long getTimeDeliveringLocally()
```
  - getAvgMsgsDeliveringLocally
```
public long getAvgMsgsDeliveringLocally()
```
  - isSiteMaster
```
public boolean isSiteMaster()
```
  - resetStats
```
public void resetStats()
```
    Overrides:
    
    resetStats in class Protocol
  - getBridgeView
```
public View getBridgeView(java.lang.String cluster_name)
```
  - addSite
```
public RELAY2 addSite(java.lang.String site_name,
                      RelayConfig.SiteConfig cfg)
```
  - getSites
```
public java.util.List<java.lang.String> getSites()
```
  - init
```
public void init()
          throws java.lang.Exception
```
    Description copied from class: Protocol
    
    Called after instance has been created (null constructor) and before protocol is started. Properties are already set. Other protocols are not yet connected and events cannot yet be sent.
    
    Overrides:
    
    init in class Protocol
    
    Throws:
    
    java.lang.Exception - Thrown if protocol cannot be initialized successfully. This will cause the ProtocolStack to fail, so the channel constructor will throw an exception
  - configure
```
public void configure()
               throws java.lang.Exception
```
    Throws:
    
    java.lang.Exception
  - stop
```
public void stop()
```
    Description copied from class: Protocol
    
    This method is called on a Channel.disconnect(). Stops work (e.g. by closing multicast socket). Will be called from top to bottom. This means that at the time of the method invocation the neighbor protocol below is still working. This method will replace the STOP, STOP_OK, CLEANUP and CLEANUP_OK events. The ProtocolStack guarantees that when this method is called all messages in the down queue will have been flushed
    
    Overrides:
    
    stop in class Protocol
  - parseSiteConfiguration
```
protected void parseSiteConfiguration(java.util.Map<java.lang.String,RelayConfig.SiteConfig> map)
                               throws java.lang.Exception
```
    Parses the configuration by reading the config file.
    
    Throws:
    
    java.lang.Exception
  - parse
```
public void parse(org.w3c.dom.Node node)
           throws java.lang.Exception
```
    Description copied from class: Protocol
    
    Called by the XML parser when subelements are found in the configuration of a protocol. This allows a protocol to define protocol-specific information and to parse it
    
    Overrides:
    
    parse in class Protocol
    
    Throws:
    
    java.lang.Exception
  - printRoutes
```
public java.lang.String printRoutes()
```
  - getBridge
```
public JChannel getBridge(java.lang.String site_name)
```
    Returns the bridge channel to a given site
    
    Parameters:
    
    site_name - The site name, e.g. "SFO"
    
    Returns:
    
    The JChannel to the given site, or null if no route was found or we're not the coordinator
  - getRoute
```
public Route getRoute(java.lang.String site_name)
```
    Returns the route to a given site
    
    Parameters:
    
    site_name - The site name, e.g. "SFO"
    
    Returns:
    
    The route to the given site, or null if no route was found or we're not the coordinator
  - down
```
public java.lang.Object down(Event evt)
```
    Description copied from class: Protocol
    
    An event is to be sent down the stack. The layer may want to examine its type and perform some action on it, depending on the event's type. If the event is a message MSG, then the layer may need to add a header to it (or do nothing at all) before sending it down the stack using down_prot.down(). In case of a GET_ADDRESS event (which tries to retrieve the stack's address from one of the bottom layers), the layer may need to send a new response event back up the stack using up_prot.up().
    
    Overrides:
    
    down in class Protocol
  - up
```
public java.lang.Object up(Event evt)
```
    Description copied from class: Protocol
    
    An event was received from the layer below. Usually the current layer will want to examine the event type and - depending on its type - perform some computation (e.g. removing headers from a MSG event type, or updating the internal membership list when receiving a VIEW_CHANGE event). Finally the event is either a) discarded, or b) an event is sent down the stack using down_prot.down() or c) the event (or another event) is sent up the stack using up_prot.up().
    
    Overrides:
    
    up in class Protocol
  - up
```
public void up(MessageBatch batch)
```
    Description copied from class: Protocol
    
    Sends up a multiple messages in a MessageBatch. The sender of the batch is always the same, and so is the destination (null == multicast messages). Messages in a batch can be OOB messages, regular messages, or mixed messages, although the transport itself will create initial MessageBatches that contain only either OOB or regular messages.
    The default processing below sends messages up the stack individually, based on a matching criteria (calling Protocol.accept(org.jgroups.Message)), and - if true - calls Protocol.up(org.jgroups.Event) for that message and removes the message. If the batch is not empty, it is passed up, or else it is dropped.
    Subclasses should check if there are any messages destined for them (e.g. using MessageBatch.getMatchingMessages(short,boolean)), then possibly remove and process them and finally pass the batch up to the next protocol. Protocols can also modify messages in place, e.g. ENCRYPT could decrypt all encrypted messages in the batch, not remove them, and pass the batch up when done.
    
    Overrides:
    
    up in class Protocol
    
    Parameters:
    
    batch - The message batch
  - handleRelayMessage
```
protected void handleRelayMessage(RELAY2.Relay2Header hdr,
                                  Message msg)
```
    Called to handle a message received by the relayer
  - handleMessage
```
protected void handleMessage(RELAY2.Relay2Header hdr,
                             Message msg)
```
    Called to handle a message received by the transport
  - route
```
protected void route(SiteAddress dest,
                     SiteAddress sender,
                     Message msg)
```
    Routes the message to the target destination, used by a site master (coordinator)
    
    Parameters:
    
    dest -
    
    sender - the address of the sender
    
    msg - The message
  - sendToBridges
```
protected void sendToBridges(Address sender,
                             Message msg,
                             java.lang.String... excluded_sites)
```
    Sends the message via all bridges excluding the excluded_sites bridges
  - sendSiteUnreachableTo
```
protected void sendSiteUnreachableTo(Address dest,
                                     java.lang.String target_site)
```
    Sends a SITE-UNREACHABLE message to the sender of the message. Because the sender is always local (we're the relayer), no routing needs to be done
    
    Parameters:
    
    dest -
    
    target_site -
  - forwardTo
```
protected void forwardTo(Address next_dest,
                         SiteAddress final_dest,
                         Address original_sender,
                         Message msg,
                         boolean forward_to_current_coord)
```
  - deliverLocally
```
protected void deliverLocally(SiteAddress dest,
                              SiteAddress sender,
                              Message msg)
```
  - deliver
```
protected void deliver(Address dest,
                       Address sender,
                       Message msg)
```
  - copy
```
protected Message copy(Message msg)
```
    Copies the message, but only the headers above the current protocol (RELAY) (or RpcDispatcher related headers)
  - handleView
```
public void handleView(View view)
```
  - startRelayer
```
protected void startRelayer(Relayer rel,
                            java.lang.String bridge_name)
```
  - determineSiteMasters
```
protected java.util.List<Address> determineSiteMasters(View view)
```
    Iterates over the list of members and adds every member if the member's rank is below max_site_masters. Skips members which cannot become site masters (can_become_site_master == false). If no site master can be found, the first member of the view will be returned (even if it has can_become_site_master == false)
  - pickSiteMaster
```
protected Address pickSiteMaster(Address sender)
```
    Returns a site master from site_masters

Class RELAY2

Nested Class Summary

Field Summary

Fields inherited from class org.jgroups.stack.Protocol

Constructor Summary

Method Summary

Methods inherited from class org.jgroups.stack.Protocol

Methods inherited from class java.lang.Object

Field Detail

site

config

can_become_site_master

max_site_masters

enable_address_tagging

relay_multicasts

async_relay_creation

warn_when_ftc_missing

site_master_picker_impl

sites

site_config

is_site_master

site_masters

site_master_picker

relayer

timer

local_addr

members

forwarding_protocol_present

can_forward_local_cluster

prots_above

route_status_listener

forward_to_site_master

forward_sm_time

relayed

relayed_time

forward_to_local_mbr

forward_to_local_mbr_time

local_deliveries

local_delivery_time

Constructor Detail

RELAY2

Method Detail

site

config

canBecomeSiteMaster

enableAddressTagging

relayMulticasts

asyncRelayCreation

siteMasterPicker

site

siteNames

config

canBecomeSiteMaster

enableAddressTagging

relayMulticasts

asyncRelayCreation

getLocalAddress

getTimer

incrementRelayed

addToRelayedTime

getRouteStatusListener

setRouteStatusListener

getNumForwardedToSiteMaster

getTimeForwardingToSM

getAvgMsgsForwardingToSM

getNumRelayed

getTimeRelaying

getAvgMsgsRelaying

getNumForwardedToLocalMbr

getTimeForwardingToLocalMbr

getAvgMsgsForwardingToLocalMbr

getNumLocalDeliveries

getTimeDeliveringLocally

getAvgMsgsDeliveringLocally

isSiteMaster

resetStats

getBridgeView

addSite

getSites

init