Administration guide > Operate the deployment environment

Manage ObjectGrid availability

The availability state of an ObjectGrid instance determines which requests can be processed at any particular time. Use the StateManager interface to set and retrieve the state of an ObjectGrid instance.

Four availability states exist for a given ObjectGrid instance.

Figure 1. Availability states of an ObjectGrid instance

Availability states include online, quiesce, offline, and preload


The ONLINE state is the default availability state for an ObjectGrid. An ONLINE ObjectGrid is able to process any requests from a typical eXtreme Scale client. However, requests from a preload client are rejected while the ObjectGrid is ONLINE.


The QUIESCE state is transitional. An ObjectGrid that is in QUIESCE is soon moved to the OFFLINE state. While in the QUIESCE state, an ObjectGrid is allowed to process outstanding transactions. However, any new transactions are rejected. An ObjectGrid can remain in QUIESCE for up to 30 seconds. After this time, the availability state is moved to OFFLINE.


The OFFLINE state results in the rejection of all transactions that are sent to the ObjectGrid.


The PRELOAD state can be used to load data into an ObjectGrid from a preload client. While the ObjectGrid is in the PRELOAD state, only a preload client can commit transactions against the ObjectGrid. All other transactions are rejected.

A request is rejected if an ObjectGrid is not in the appropriate availability state to support that request. An AvailabilityException exception results whenever a request is rejected.


  1. Set the initial state of an ObjectGrid with the ObjectGrid configuration XML file.

    Use the initialState attribute on an ObjectGrid to indicate its startup state. Normally, when an ObjectGrid completes initialization, it is available for routing. The state can later be changed to prevent traffic from routing to an ObjectGrid. If the ObjectGrid needs to be initialized, but not immediately available, you can use the initialState attribute.

    The initialState attribute is set on the ObjectGrid configuration XML file. The default state is ONLINE. Valid values include:

    • ONLINE (default)



    See ObjectGrid descriptor XML file for more information about the initialState attribute.

    If the initialState attribute is set on an ObjectGrid, the state must be explicitly set back to online or the ObjectGrid will remain unavailable. An AvailabilityException exception results if the ObjectGrid is not in the ONLINE state.

    See AvailabilityState API documentation for more information.

    Use the initialState attribute for preloading

    If the ObjectGrid is preloaded with data, there can be a period of time between when the ObjectGrid is available and switching to a preload state to block client traffic.

    To avoid this time period, the initial state on an ObjectGrid can be set to PRELOAD. The ObjectGrid still completes all the necessary initialization, but it blocks traffic until the state has changed and allows the preload to occur.

    The PRELOAD and OFFLINE states both block traffic, but use the PRELOAD state to initiate a preload.

    Failover and balancing behavior

    If a replica data grid is promoted to be a primary data grid, the replica does not use the initialState setting. If the primary data grid is moved for a rebalance, the initialState setting is not used because the data is copied to the new primary location before the move is completed. If replication is not configured, then the primary goes into the initialState setting if failover occurs, and a new primary must be placed.

  2. Change the availability state with the StateManager interface.

    Use the StateManager interface to set the availability state of an ObjectGrid.

    To set the availability state of an ObjectGrid running on the servers, pass a corresponding ObjectGrid client to the StateManager interface. The following code demonstrates how to change the availability state of an ObjectGrid.

    ClientClusterContext client = ogManager.connect("localhost:2809", null, null);
    ObjectGrid myObjectGrid = ogManager.getObjectGrid(client, "myObjectGrid");
    StateManager stateManager = StateManagerFactory.getStateManager();
    stateManager.setObjectGridState(AvailabilityState.OFFLINE, myObjectGrid);

    Each shard of the ObjectGrid transitions to the desired state when the setObjectGridState method is called on the StateManager interface. When the method returns, all shards within the ObjectGrid should be in the proper state.

    Use an ObjectGridEventListener plug-in to change the availability state of a server side ObjectGrid. Only change the availability state of a server-side ObjectGrid when the ObjectGrid has a single partition. If the ObjectGrid has multiple partitions, the shardActivated method is called on each primary, which results in superfluous calls to change the state of the ObjectGrid

    public class OGListener implements ObjectGridEventListener, 
                ObjectGridEventGroup.ShardEvents {
        public void shardActivated(ObjectGrid grid) {        
                StateManager stateManager = StateManagerFactory.getStateManager();
                stateManager.setObjectGridState(AvailabilityState.PRELOAD, grid);        

    Because QUIESCE is a transitional state, you cannot use the StateManager interface to put an ObjectGrid into the QUIESCE state. An ObjectGrid passes through this state on its way to the OFFLINE state.

  3. Retrieve the availability state.

    Use the getObjectGridState method of the StateManager interface to retrieve the availability state of a particular ObjectGrid.

    StateManager stateManager = StateManagerFactory.getStateManager();
    AvailabilityState state = stateManager.getObjectGridState(inventoryGrid);

    The getObjectGridState method chooses a random primary within the ObjectGrid and returns its AvailabilityState. Because all shards of an ObjectGrid should be in the same availability state or transitioning to the same availability state, this method provides an acceptable result for the current availability state of the ObjectGrid.

Parent topic:

Operate the deployment environment

Related tasks

Start and stop stand-alone servers

Start and stop servers in a WAS environment

Use the embedded server API to start and stop servers

Ovveride catalog service quorum

Related reference

Administer programmatically with Managed Beans (MBeans)