UniversalMembershipListenerAdapter (Apache Geode 1.10.0)
Date: 2019-09-19

org.apache.geode.management.membership

## Class UniversalMembershipListenerAdapter

- java.lang.Object
- - org.apache.geode.management.membership.UniversalMembershipListenerAdapter

- All Implemented Interfaces:
    MembershipListener

      public abstract class UniversalMembershipListenerAdapter
      extends Object
      implements MembershipListener

  The `UniversalMembershipListenerAdapter` is a wrapper for `MembershipListener` and `ClientMembershipListener`, providing a facade that makes both appear as a single `MembershipListener` . This includes adapting `ClientMembershipListener` events to appear as events for the `MembershipListener`.

  `UniversalMembershipListenerAdapter` implements `MembershipListener`, exposing the callback in that interface as methods to be overridden by implementing classes.

  An internal implementation of `ClientMembershipListener` is registered when this class is instantiated. This implementation creates a `MembershipEvent` and calls the corresponding `MembershipListener` public methods on `UniversalMembershipListenerAdapter`.The `ClientMembershipEvent`s are wrapped to appear as `MembershipEvent`s. In this way, both types of membership events appear as `MembershipEvent`s.

  Any CacheServer using the `UniversalMembershipListenerAdapter` will receive notifications of peer membership changes and client membership changes through a single listener.

  Any cache client using the `UniversalMembershipListenerAdapter` would receive notifications of cache server connection changes. If that cache client also creates a connection to the GemFire `DistributedSystem`, then it will also register the adapter for membership events. But it wont be an automatic process. User needs to register the UniversalMembershipListenerAdapter with ManagementService to receive membership events. How to register UniversalMembershipListenerAdapter with ManagementService is explained below.

  Subclasses of `UniversalMembershipListenerAdapter` may be registered as a `MembershipListener` using `ManagementService.addMembershipListener(org.apache.geode.management.membership.MembershipListener)` .It is best, however, to register the listener using `registerMembershipListener(org.apache.geode.management.ManagementService)` since this allows the adapter to prevent duplicate events for members that are both a peer member and a client.

  Simply constructing the `UniversalMembershipListenerAdapter` results in the underlying `ClientMembershipListener` also being registered.

  The following code illustrates how a CacheServer application would use `UniversalMembershipListenerAdapter`. The code in this example assumes that the class MyMembershipListenerImpl extends `UniversalMembershipListenerAdapter`:

       public class MyMembershipListenerImpl extends UniversalMembershipListenerAdapter {
         public void memberCrashed(MembershipEvent event) {
           // customer code
         }
         public void memberLeft(MembershipEvent event) {
           // customer code
         }
         public void memberJoined(MembershipEvent event) {
           // customer code
         }
       }

        Cache cache = //Get hold of GemFire Cache instance
        ManagementService service = ManagementService.getExistingManagementService(cache);

        MyMembershipListenerImpl myListener = new MyMembershipListenerImpl();
        myListener.registerMembershipListener(service);

  The callback on MyMembershipListenerImpl would then be invoked for all `MembershipEvent`s and `ClientMembershipEvent`s. The latter will appear to be `MembershipEvent`s.

  Similarly, the following code illustrates how a client application would use `UniversalMembershipListenerAdapter`, where MyMembershipListenerImpl is a subclass.Simply by constructing this subclass of `UniversalMembershipListenerAdapter` it is registering itself as a `ClientMembershipListener`:

       new MyMembershipListenerImpl();

  A client that also connects to the `DistributedSystem` could register with the`ManagementService` as shown above.

  It is recommended that subclasses register with the `ManagementService` using `registerMembershipListener(org.apache.geode.management.ManagementService)`, as this will prevent duplicate events for members that are both clients and peer members.If duplicate events are acceptable, you may register subclasses using `ManagementService#addMembershipListener`.

  Since:
    GemFire 8.0

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `UniversalMembershipListenerAdapter.AdaptedMembershipEvent` Adapts ClientMembershipEvent to look like a MembershipEvent

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `DEFAULT_HISTORY_SIZE` Default number of historical events to track in order to avoid duplicate events for members that are both clients and peer members; value is 100.
    `protected MembershipListener` | `membershipListener`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `UniversalMembershipListenerAdapter()` Constructs an instance of UniversalMembershipListenerAdapter.
    `UniversalMembershipListenerAdapter(int historySize)` Constructs an instance of UniversalMembershipListenerAdapter.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `memberCrashed(MembershipEvent event)` Invoked when a member has unexpectedly left the distributed system.
    `void` | `memberJoined(MembershipEvent event)` Invoked when a member has joined the distributed system.
    `void` | `memberLeft(MembershipEvent event)` Invoked when a member has gracefully left the distributed system.
    `void` | `registerClientMembershipListener()` Registers this adapter as a `ClientMembershipListener`.
    `void` | `registerMembershipListener(ManagementService service)` Registers this adapter with the `ManagementService`.
    `void` | `unregisterClientMembershipListener()` Unregisters this adapter as a `ClientMembershipListener`.
    `void` | `unregisterMembershipListener(ManagementService service)` Unregisters this adapter with the `ManagementService`.

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### DEFAULT_HISTORY_SIZE

          public static final int DEFAULT_HISTORY_SIZE

      Default number of historical events to track in order to avoid duplicate events for members that are both clients and peer members; value is 100.
      See Also:
        Constant Field Values

    - #### membershipListener

          protected final MembershipListener membershipListener

  - ### Constructor Detail

    - #### UniversalMembershipListenerAdapter

          public UniversalMembershipListenerAdapter()

      Constructs an instance of UniversalMembershipListenerAdapter.

    - #### UniversalMembershipListenerAdapter

          public UniversalMembershipListenerAdapter(int historySize)

      Constructs an instance of UniversalMembershipListenerAdapter.
      Parameters:
        `historySize` - number of historical events to track in order to avoid duplicate events for members that are both client and peer members; must a number between 10 and `Integer.MAX_INT`
      Throws:
        `IllegalArgumentException` - if historySize is less than 10

  - ### Method Detail

    - #### registerMembershipListener

          public void registerMembershipListener(ManagementService service)

      Registers this adapter with the `ManagementService`. Registering in this way allows the adapter to ensure that callback will not be invoked twice for members that have a client connection and a peer connection. If you register with `ManagementService.addMembershipListener(org.apache.geode.management.membership.MembershipListener)` then duplicate events may occur for members that are both client and peer.

    - #### unregisterMembershipListener

          public void unregisterMembershipListener(ManagementService service)

      Unregisters this adapter with the `ManagementService`. If registration is performed with `registerMembershipListener(org.apache.geode.management.ManagementService)` then this method must be used to successfully unregister the adapter.

    - #### registerClientMembershipListener

          public void registerClientMembershipListener()

      Registers this adapter as a `ClientMembershipListener`. Registration is automatic when constructing this adapter, so this call is not necessary unless it was previously unregistered by calling `unregisterClientMembershipListener()`.

    - #### unregisterClientMembershipListener

          public void unregisterClientMembershipListener()

      Unregisters this adapter as a `ClientMembershipListener`.
      See Also:
        `registerClientMembershipListener()`

    - #### memberJoined

          public void memberJoined(MembershipEvent event)

      Invoked when a member has joined the distributed system. Also invoked when a client has connected to this process or when this process has connected to a `CacheServer`.
      Specified by:
        `memberJoined` in interface `MembershipListener`

    - #### memberLeft

          public void memberLeft(MembershipEvent event)

      Invoked when a member has gracefully left the distributed system. Also invoked when a client has gracefully disconnected from this process. or when this process has gracefully disconnected from a `CacheServer`.
      Specified by:
        `memberLeft` in interface `MembershipListener`

    - #### memberCrashed

          public void memberCrashed(MembershipEvent event)

      Invoked when a member has unexpectedly left the distributed system. Also invoked when a client has unexpectedly disconnected from this process or when this process has unexpectedly disconnected from a `CacheServer`.
      Specified by:
        `memberCrashed` in interface `MembershipListener`