org.jgroups.protocols

## Class RELAY

- java.lang.Object
- - org.jgroups.stack.Protocol
  - - org.jgroups.protocols.RELAY

-     public class RELAY
      extends Protocol

  Simple relaying protocol: RELAY is added to the top of the stack, creates a channel to a bridge cluster, and - if coordinator - relays all multicast messages via the bridge cluster to the remote cluster.

  This is not a big virtual cluster, e.g. consisting of {A,B,C,X,Y,Z}, but 2 autonomous clusters {A,B,C} and {X,Y,Z}, bridged together by RELAY. For example, when B multicasts a message M, A (if it happens to be the coord) relays M to X (which happens to be the other cluster's coordinator). X then re-broadcasts M, with M.src being a ProxyUUID(X,B). This means that the sender of M in the {X,Y,Z} cluster will be X for all practical purposes, but the original sender B is also recorded, for sending back a response.

  See [1] and [2] for details.

  [1] https://jira.jboss.org/browse/JGRP-747

  [2] doc/design/RELAY.txt
  Since:
    2.12
  Author:
    Bela Ban

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `protected class` | `RELAY.Receiver`
    `static class` | `RELAY.RelayHeader`
    `protected class` | `RELAY.RemoteViewFetcher`
    `protected static class` | `RELAY.ViewData` Contains local and remote views, and UUID information

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected JChannel` | `bridge` The bridge between the two local clusters, usually based on a TCP config
    `protected java.lang.String` | `bridge_name`
    `protected java.lang.String` | `bridge_props`
    `protected View` | `bridge_view` The view of the bridge cluster, usually consists of max 2 nodes
    `protected Address` | `coord`
    `protected View` | `global_view` The combined view of local and remote cluster
    `protected long` | `global_view_id` To generate new global views
    `protected boolean` | `is_coord`
    `protected Address` | `local_addr`
    `protected View` | `local_view` The view of the local cluster
    `protected boolean` | `present_global_views`
    `protected boolean` | `relay`
    `protected View` | `remote_view` The view of the remote cluster
    `protected java.util.concurrent.Future<?>` | `remote_view_fetcher_future`
    `protected java.lang.String` | `site`
    `protected TimeScheduler` | `timer`

    - ### Fields inherited from class org.jgroups.stack.Protocol

      `down_prot, ergonomics, id, log, name, stack, stats, up_prot`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `RELAY()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected void` | `createBridge()`
    `java.lang.Object` | `down(Event evt)` An event is to be sent down the stack.
    `protected void` | `forward(byte[] buffer, int offset, int length)` Forwards the message across the TCP link to the other local cluster
    `protected void` | `forwardToCoord(Message msg)` Wraps the message annd sends it to the current coordinator
    `protected View` | `generateGlobalView(View local_view, View remote_view)`
    `protected View` | `generateGlobalView(View local_view, View remote_view, boolean merge)`
    `java.lang.String` | `getBridgeView()`
    `java.lang.String` | `getGlobalView()`
    `java.lang.String` | `getLocalView()`
    `java.lang.String` | `getRemoteView()`
    `protected void` | `handleView(View view)`
    `void` | `init()` Called after instance has been created (null constructor) and before protocol is started.
    `protected java.lang.Object` | `installView(byte[] buf, int offset, int length)`
    `protected boolean` | `isLocal(Address dest)` Does the payload match the 'site' ID.
    `protected void` | `sendOnLocalCluster(byte[] buf, int offset, int length)`
    `protected void` | `sendViewOnLocalCluster(Address dest, RELAY.ViewData data, boolean use_seperate_thread)`
    `protected void` | `sendViewOnLocalCluster(Address dest, View remote_view, View global_view, boolean use_seperate_thread)`
    `protected void` | `sendViewToRemote(RELAY.ViewData view_data, boolean use_seperate_thread)`
    `void` | `setRelay(boolean relay)`
    `protected void` | `startRemoteViewFetcher()`
    `void` | `stop()` This method is called on a `Channel.disconnect()`.
    `protected void` | `stopRemoteViewFetcher()`
    `java.lang.Object` | `up(Event evt)` An event was received from the layer below.

    - ### Methods inherited from class org.jgroups.stack.Protocol

      `destroy, downThreadEnabled, dumpStats, enableStats, getConfigurableObjects, getDownProtocol, getId, getLevel, getName, getProperties, getProtocolStack, getSocketFactory, getThreadFactory, getTransport, getUpProtocol, getValue, isErgonomics, printStats, providedDownServices, providedUpServices, requiredDownServices, requiredUpServices, resetStats, setDownProtocol, setErgonomics, setId, setLevel, setProperties, setPropertiesInternal, setProperty, setProtocolStack, setSocketFactory, setUpProtocol, setValue, setValues, start, statsEnabled, upThreadEnabled`

    - ### 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

    - #### bridge_props

          protected java.lang.String bridge_props

    - #### bridge_name

          protected java.lang.String bridge_name

    - #### relay

          protected boolean relay

    - #### present_global_views

          protected boolean present_global_views

    - #### local_addr

          protected Address local_addr

    - #### is_coord

          protected volatile boolean is_coord

    - #### coord

          protected volatile Address coord

    - #### bridge

          protected JChannel bridge

      The bridge between the two local clusters, usually based on a TCP config

    - #### local_view

          protected View local_view

      The view of the local cluster

    - #### bridge_view

          protected View bridge_view

      The view of the bridge cluster, usually consists of max 2 nodes

    - #### remote_view

          protected View remote_view

      The view of the remote cluster

    - #### global_view

          protected View global_view

      The combined view of local and remote cluster

    - #### global_view_id

          protected long global_view_id

      To generate new global views

    - #### timer

          protected TimeScheduler timer

    - #### remote_view_fetcher_future

          protected java.util.concurrent.Future<?> remote_view_fetcher_future

  - ### Constructor Detail

    - #### RELAY

          public RELAY()

  - ### Method Detail

    - #### setRelay

          public void setRelay(boolean relay)

    - #### getLocalView

          public java.lang.String getLocalView()

    - #### getBridgeView

          public java.lang.String getBridgeView()

    - #### getRemoteView

          public java.lang.String getRemoteView()

    - #### getGlobalView

          public java.lang.String getGlobalView()

    - #### 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

    - #### 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`

    - #### 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`

    - #### handleView

          protected void handleView(View view)

    - #### installView

          protected java.lang.Object installView(byte[] buf,
                                     int offset,
                                     int length)

    - #### forward

          protected void forward(byte[] buffer,
                     int offset,
                     int length)

      Forwards the message across the TCP link to the other local cluster

    - #### forwardToCoord

          protected void forwardToCoord(Message msg)

      Wraps the message annd sends it to the current coordinator

    - #### sendViewToRemote

          protected void sendViewToRemote(RELAY.ViewData view_data,
                              boolean use_seperate_thread)

    - #### generateGlobalView

          protected View generateGlobalView(View local_view,
                                View remote_view)

    - #### generateGlobalView

          protected View generateGlobalView(View local_view,
                                View remote_view,
                                boolean merge)

    - #### createBridge

          protected void createBridge()

    - #### sendOnLocalCluster

          protected void sendOnLocalCluster(byte[] buf,
                                int offset,
                                int length)

    - #### sendViewOnLocalCluster

          protected void sendViewOnLocalCluster(Address dest,
                                    View remote_view,
                                    View global_view,
                                    boolean use_seperate_thread)

    - #### sendViewOnLocalCluster

          protected void sendViewOnLocalCluster(Address dest,
                                    RELAY.ViewData data,
                                    boolean use_seperate_thread)

    - #### isLocal

          protected boolean isLocal(Address dest)

      Does the payload match the 'site' ID. Checks only unicast destinations (multicast destinations return true)

    - #### startRemoteViewFetcher

          protected void startRemoteViewFetcher()

    - #### stopRemoteViewFetcher

          protected void stopRemoteViewFetcher()

Copyright © 1998-2009 Bela Ban / Red Hat. All Rights Reserved.