ObjectGridLifecycleListener plug-in

An ObjectGridLifecycleListener plug-in receives notification of WebSphere® eXtreme Scale life cycle, state change events for the data grid.

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

Overview

An ObjectGridLifecycleListener plug-in is useful when an existing ObjectGrid plug-in needs to perform activities relative to activities in a related plug-in. As an example, a TransactionCallback plug-in might need to retrieve the configuration from a cooperating ObjectGridEventListener or ShardListener plug-in.

By implementing the ObjectGridLifecycleListener interface, and detecting the ObjectGridLifecycleListener.State.INITIALIZED event, the TransactionCallback plug-in can detect the state of other plug-ins in the ObjectGrid instance. The TransactionCallback plug-in can safely retrieve information from the cooperating ObjectGridEventListener plug-in or ShardListener plug-in, since the ObjectGrid is in the INITIALIZED state, which means that the other plug-in has had its initialize() method called.

You can add an ObjectGridLifecycleListener plug-in at any time, either before or after the ObjectGrid is initialized.

Write an ObjectGridLifecycleListener plug-in

An ObjectGridLifecycleListener plug-in must implement the ObjectGridLifecycleListener interface to receive notifications about significant eXtreme Scale events. Any ObjectGrid plug-in can implement the ObjectGridLifecycleListener interface and be automatically added as a listener when it is also added to the ObjectGrid.

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

Life cycle event and plug-in relationships

The ObjectGridLifecycleListener retrieves the life cycle state from the event in the objectgridStateChanged method; for example:

public void objectGridStateChanged(ObjectGrid grid, 
                                   LifecycleEvent event) 
throws LifecycleFailedException {
  switch(event.getState()) {
    case INITIALIZED: // All other plug-ins are initialized.
      // Retrieve reference to plug-in X for use from grid.
      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 ObjectGrid objects as life cycle events occur and are sent to a ObjectGridLifecycleListener plug-in.

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

ObjectGridLifecycleListener.State value	Description
INITIALIZING	The ObjectGrid initialization phase is starting. The ObjectGrid and ObjectGrid plug-ins are about to be initialized.
INITIALIZED	The ObjectGrid initialization phase is complete. All ObjectGrid plug-ins are initialized. The INITIALIZED state might recur when shard placement activities (promotion or demotion) occur. All BackingMap plug-ins in the BackingMap instances owned by this ObjectGrid instance have been initialized.
STARTING	The ObjectGrid 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. The STARTING state might recur when shard placement activities (promotion or demotion) occur.
PRELOAD	The ObjectGrid instance is set to the PRELOAD state by the StateManager API or other configuration.
ONLINE	The ObjectGrid instance is ready for work as a local instance, client instance, or as an instance in a primary or replica shard on the server. This steady state is typical of the ObjectGrid. The ONLINE state might recur when shard placement activities (promotion or demotion) occur.
QUIESCE	Work is stopping on the ObjectGrid as a result of the StateManager API or other event. No new work is allowed. End any existing work as soon as possible.
OFFLINE	All work is stopped on the ObjectGrid as a result of the StateManager API or other event. No new work is allowed.
DESTROYING	The ObjectGrid instance is starting the destroy phase. ObjectGrid plug-ins for the instance are about to be destroyed. During the destroy phase, all BackingMap instances owned by this ObjectGrid instance are also destroyed.
DESTROYED	The ObjectGrid instance, its BackingMap instances, and all ObjectGrid plug-ins have been destroyed.

Configure an ObjectGridLifecycleListener plug-in with XML

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

You can configure an ObjectGridLifecycleListener plug-in using XML. The following XML creates a configuration using the ObjectGridLifecycleListener. 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">
            <bean id="ObjectGridLifecycleListener" 
                  className="com.company.org.MyObjectGridLifecycleListener" />
            <backingMap name="Book"/>
        </objectGrid>
    </objectGrids>
</objectGridConfig>

Notice the bean declarations come before the backingMap declarations. Provide this file to the ObjectGridManager plug-in to facilitate the creation of this configuration.

Like the registered ObjectGridLifecycleListener in the previous example, other ObjectGrid plug-ins, CollisionArbiter or TransactionCallback for example, that you specify using XML that also implement the ObjectGridLifecycleListener interface, will automatically be added as life cycle listeners.