BackingMapLifecycleListener plug-in

A BackingMapLifecycleListener plug-in receives notification of WebSphere® eXtreme Scale life cycle state change events for the backing map.

The BackingMapLifecycleListener plug-in receives an event containing a BackingMapLifecycleListener.State object for each state change of the backing map. Any BackingMap plug-in that also implements the BackingMapLifecycleListener interface will automatically be added as a listener for the BackingMap instance where the plug-in is registered.

Overview

A BackingMapLifecycleListener plug-in is useful when an existing BackingMap plug-in needs to perform activities relative to activities in a related plugin. As an example, a loader plug-in might need to retrieve configuration from a cooperating MapIndexPlugin or DataSerializer plug-in.

By implementing the BackingMapLifecycleListener interface, and detecting the BackingMapLifecycleListener.State.INITIALIZED event, the loader can know about the state of other plug-ins in the BackingMap instance. The loader can safely retrieve information from the cooperating MapIndexPlugin or DataSerializer plug-in, since the BackingMap is in the INITIALIZED state, which means that the other plug-in has had its initialize() method called.

A BackingMapLifecycleListener can be added or removed at any time, either before or after the ObjectGrid and its BackingMaps are initialized.

Write a BackingMapLifecycleListener plug-in

A BackingMapLifecycleListener plug-in must implement the BackingMapLifecycleListener interface to receive notifications about significant eXtreme Scale events. Any BackingMap plug-in can implement the BackingMapLifecycleListener interface and be automatically added as a listener when it is also added to the backing map.

For more information about these interfaces, see the API documentation.

Life cycle event and plug-in relationships

The BackingMapLifecycleListener retrieves the life cycle state from the event in the backingMapStateChanged method; for example:

public void backingMapStateChanged(BackingMap map, 
                                   LifecycleEvent event) 
throws LifecycleFailedException {
  switch(event.getState()) {
    case INITIALIZED: // All other plug-ins are initialized.
      // Retrieve reference to plug-in X for use from map.
      break;
    case DESTROYING:  // Destroy phase is starting
      // Eliminate reference to plug-in X it may be destroyed before this plug-in
      break;
  }
}

The following illustration summarizes the states of the BackingMap objects as life cycle events occur and are sent to a BackingMapLifecycleListener plug-in.

The following table describes the relationship between life cycle events sent to a BackingMapLifecycleListener plug-in and the states of the BackingMap and other plug-in objects.

BackingMapLifecycleListener.State value	Description
INITIALIZING	The BackingMap initialization phase is starting. The BackingMap and BackingMap plug-ins are about to be initialized.
INITIALIZED	The BackingMap initialization phase is complete. All BackingMap plug-ins are initialized. The INITIALIZED state might recur when shard placement activities (promotion or demotion) occur.
STARTING	The BackingMap instance is being activated for use as a local instance, client instance or as an instance in a primary or replica shard on the server. All ObjectGrid plug-ins in the ObjectGrid instance owning this BackingMap instance have been initialized. The STARTING state might recur when shard placement activities (promotion or demotion) occur.
PRELOAD	The BackingMap instance is set to the PRELOAD state by the StateManager API for preloading, or the configured loader is preloading data into the backing map.
ONLINE	The BackingMap instance is ready for work as a local instance, client instance, or as an instance in a primary or replica shard on the server. All ObjectGrid plug-ins in the ObjectGrid instance owning this BackingMap instance have been initialized. This steady state is typical of the BackingMap. The ONLINE state might recur when shard placement activities (promotion or demotion) occur.
QUIESCE	Work is stopping on the BackingMap as a result of the StateManager API or other event. No new work is allowed. Your plug-in ends any existing work as soon as possible.
OFFLINE	All work is stopped on the BackingMap as a result of the StateManager API or another event. No new work is allowed.
DESTROYING	The BackingMap instance is starting the destroy phase. BackingMap plug-ins for the instance are about to be destroyed.
DESTROYED	The BackingMap instance and all BackingMap plug-ins have been destroyed.

Configure a BackingMapLifecycleListener plug-in with XML

Assume that the class name of the eXtreme Scale event listener is the com.company.org.MyBackingMapLifecycleListener class. This class implements the BackingMapLifecycleListener interface.

You can configure a BackingMapLifecycleListener plug-in using XML. The following text must be in the object grid XML file:

<?xml version="1.0" encoding="UTF-8" ?>
<objectGridconfig xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://ibm.com/ws/objectgrid/config../objectGrid.xsd" 
        xmlns="http://ibm.com/ws/objectgrid/config">
    <objectGrids>
        <objectGrid name="myGrid">
            <backingMap name="myMap" pluginCollectionRef="myPlugins" />
        </objectGrid>
    </objectGrids>
    <backingMapPluginCollections>
        <backingMapPluginCollection id="myPlugins">
            <bean id="BackingMapLifecycleListener"
                  className="com.company.org.MyBackingMapLifecycleListener" />
        </backingMapPluginCollection>
    </backingMapPluginCollections>
</objectGridConfig>

Provide this file to the ObjectGridManager plug-in to facilitate the creation of this configuration. The BackingMap instance that is created has a BackingMapLifecycleListener listener set on the myGrid ObjectGrid.

Like the BackingMapLifecycleListener, other BackingMap plug-ins, such as Loader or MapIndexPlugin, that you specify using XML that also implement the BackingMapLifecycleListener interface, will automatically be added as life cycle listeners.